1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
.. comment: Copyright (c) 2017 Chris Johns <chrisj@rtems.org>
.. comment: All rights reserved.
RTEMS Symbols
=============
.. index:: Tools, rtems-syms
The RTEMS Symbols (:program:`rtems-syms`) command is an RTEMS Tool to generate
symbol tables used by the RTEMS Runtime Loader (RTL). The symbol table is
loaded at run time with the exported base kernel image's symbols so dynamically
loaded code can link to them.
The RTEMS Runtime Loader supports embedding of a symbol table in the base
kernel image or loading the symbol table at runtime. Embedding the table
requires linking the symbol table with the base image and runtime loading loads
the table using the dynamic loader when RTEMS is running.
.. sidebar:: *Filtering Symbols*
Currently there is no filtering of symbols loaded into the symbol
table. This means all base kernel image symbols are present in the symbol
table when only a sub-set of the symbols may be referenced.
Embedding the symbol table creates self contained images. A target may not have
any external media, for example RTEMS tests, or there is a requirement to avoid
the overhead of maintaining matching the symbol table files and kernel base
images. Embedding the symbol table requires a 2-pass link process making the
application's build system more complicated as well as lengthing the build
time.
A dynamically loadable symbol table is simpler to create however the symbol
table and the kernel base image must match or the behaviour is undefined. The
:program:`rtems-syms` command is run against the base kernel image and the
generated symbol table is installed on to the target hardware and loaded before
any other modules. The symbol table object file contains a constructor that is
called after being loaded and that code registers the symbol table.
Symbol Table
------------
The symbol table is an ELF object file in the target's ELF format and is built
using the target's RTEMS C compiler. The :program:`rtems-syms` command searches
for the C compller under the prefix this command is installed under or the
system path. If this fails the option ``-c`` or ``--cc`` to override the path
to the compiler can be used.
The :program:`rtems-syms` command loads the base kernel image's ELF file
reading the symbols then creates a temporary C file it compiles using the RTEMS
C compiler. The command automatically detects the architecture from the base
kernel image's ELF file. The option ``-E`` or ``--exec-prefix`` can be used to
override the executable prefix used.
It is important to supply suitable C compiler flags (cflags) so the symbol
table can be linked or loaded.
2-Pass Linking
--------------
2-Pass linking is used to embed a symbol table in a base kernel image. The
first link pass is a normal RTEMS kernel link process. The link output is
passed to the :program:`rtems-syms` command and the ``-e`` or ``--embed``
option is used. The symbol table object file created by :program:`rtems-syms`
is added to the linker command used in the first pass to create the second
pass. The address map will change between the first pass and second pass
without causing a problem, the symbol table embedded in the second link pass
will adjust the symbol addresses to match.
Command
-------
:program:`rtems-syms` [options] kernel
.. option:: -V, --version
Display the version information and then exit.
.. option:: -v, --verbose
Increase the verbose level by 1. The option can be used more than once to
get more detailed trace and debug information.
.. option:: -w, --warn
Enable build warnings. This is useful when debugging symbol table
generation.
.. option:: -k, --keep
Do not delete temporary files on exit, keep them.
.. option:: -e, --embed
Create a symbol table that can be embedded in the base kernel image using a
2-pass link process.
.. option:: -S, --symc
Specify the symbol's C source file. The defautl is to use a temporary file
name.
.. option:: -o, --output
Specify the ELF output file name.
.. option:: -m, --map
Create a map file using the provided file name.
.. option:: -C, --cc
Specify the C compile executable file name. The file can be absolute and no
path is search or relative and the environment's path is searched.
.. option:: -E, --exec-prefix
Specify the RTEMS tool prefix. For example for RTEMS 4.12 and the SPARC
architecture the prefix is ``sparc-rtems4.12``.
.. option:: -c, --cflags
Specify the C compiler flags used to build the symbol table with. These
should be the same or compatible with the flags used to build the RTEMS
kernel.
.. option:: -?, -h
Reort the usage help.
Examples
--------
Create a dynamlically loaded symbol table for the ``minimum.exe`` sample
program for the ``i386/pc686`` BSP:
.. code-block:: shell
$ rtems-syms -o ms.o i386-rtems4.12/c/pc686/testsuites/samples/minimum/minimum.exe
$ file ms.o
ms.o: ELF 32-bit LSB relocatable, Intel 80386, version 1 (SYSV), not stripped
Run the same command, this time create a map file:
.. code-block:: shell
$ rtems-syms -o ms.o -m ms.map i386-rtems4.12/c/pc686/testsuites/samples/minimum/minimum.exe
$ head -10 ms.map
RTEMS Kernel Symbols Map
kernel: i386-rtems4.12/c/pc686/testsuites/samples/minimum/minimum.exe
Globals:
No. Index Scope Type SHNDX Address Size Name
0 931 STB_GLOBAL STT_OBJECT 11 0x0012df08 4 BSPBaseBaud (minimum.exe)
1 1124 STB_GLOBAL STT_OBJECT 11 0x0012d894 4 BSPPrintkPort (minimum.exe)
2 836 STB_GLOBAL STT_FUNC 1 0x00104b00 302 BSP_dispatch_isr (minimum.exe)
3 1156 STB_GLOBAL STT_FUNC 1 0x001082d0 92 BSP_install_rtems_shared_irq_handler (minimum.exe)
4 876 STB_GLOBAL STT_FUNC 1 0x00106500 138 BSP_outch (minimum.exe)
Run the same command with a raise verbose level to observe the stages the
command performs:
.. code-block:: shell
$ rtems-syms -vvv -o ms.o i386-rtems4.12/c/pc686/testsuites/samples/minimum/minimum.exe
RTEMS Kernel Symbols 4.12.a72a462adc18
kernel: i386-rtems4.12/c/pc686/testsuites/samples/minimum/minimum.exe
cache:load-sym: object files: 1
cache:load-sym: symbols: 1043
symbol C file: /tmp/rld--X7paaa.c
symbol O file: ms.o
execute: i386-rtems4.12-gcc -O2 -c -o ms.o /tmp/rld--X7paaa.c
execute: status: 0
|
