rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-07-04 10:14:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

User: Improvements to some of the tools commands.

Browse Source
This commit is contained in:
Chris Johns 2017-05-31 20:59:36 +10:00
parent 7f89df83f3
commit d224b11688
3 changed files with 51 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
user/tools/exeinfo.rst
View File

@ -30,22 +30,21 @@ initialisation functions in specially named sections. The system initialisation
function's address is placed in a variable and the section attribute of the function's address is placed in a variable and the section attribute of the
variable is set to a special section name. The linker is instructed via a variable is set to a special section name. The linker is instructed via a
special linker command file to collect these variables together to create a special linker command file to collect these variables together to create a
table. The start-up code in RTEMS loops over the table of addresses and calls table. The start-up code in RTRMS loops over the table of addresses and calling
each address or system initialisation function. Th especial section names given each address or system initialisation function. Special section names given to
to the variables sort the table placing the initialisation calls in a specific the variables sorts the table placing the functions in a specific order.
and controlled order.
A user places a call to an API function in their application and the linker A user places a call to an API function in their application and the linker
pulls the API code from the RTEMS kernel library adding it to the pulls the API code from the RTEMS kernel library adding it to the
executable. The API code the linker loads references the variable containing executing. The API code the linker loads references the variable containing the
the address of that API's system initialisation function. The linker loads the address of the that API's system initialisation function. The linker loads the
API system initialisation code into the executable to resolve the external API system initialisation code into the executable to resolve the external
reference created by the variable. If the user does not reference the API the refernece created by the variable. If the user does not reference the API the
variable is not referenced and so not loaded into the executable resling in no variables is loaded into the executable and no reference to the API system
API initialisation. initialisation code is made so it is not linked into the executable.
The design automatically creates a unique system intialisation table for each The design automatically creates a unique system intialisation table for each
executable and the code in RTEMS does not change. There are no special build executable and the code in RTEMS does not change, there is no special build
system tricks, or stub libraries. system tricks, or stub libraries.
The RTEMS Execuable Information reports the tables created and you can use this The RTEMS Execuable Information reports the tables created and you can use this

21
user/tools/index.rst
View File

@ -3,18 +3,17 @@
.. comment: Copyright (c) 2017 Chris Johns <chrisj@rtems.org> .. comment: Copyright (c) 2017 Chris Johns <chrisj@rtems.org>
.. comment: All rights reserved. .. comment: All rights reserved.
Tools <<<<<<< Updated upstream
***** Host Tools
**********
The RTEMS kernel is developed on a host computer where the user's application The RTEMS kernel is developed on host computers cross-compiled and linking the
code is cross-compiled to the target hardware's processor instructions and kernel, language runtime libraries, 3rd party packages and application source
linked to the RTEMS kernel and language runtime libraries, and any 3rd party code so it can run on target hardware. RTEMS and some of the hardware it
packages. RTEMS is not a multiprocess operating system and self hosting the support cannot self-host so we need a range of tools to support the wide range
types of tools need to create executables is not feasable. As a result a range of avaliable host computers users wish to develop on. This section details the
of support tools are needed and they need run on the wide range of avaliable tools available on the host computers to help support RTEMS users and
host computers users wish to develop on. This section details the tools developers.
available on host computers RTEMS users and developers need to create RTEMS
executables.
.. include:: linker.rst .. include:: linker.rst
.. include:: symbols.rst .. include:: symbols.rst

61
user/tools/symbols.rst
View File

@ -8,35 +8,33 @@ RTEMS Symbols
.. index:: Tools, rtems-syms .. index:: Tools, rtems-syms
The RTEMS Symbols (:program:`rtems-syms`) command is an RTEMS Tool to generate 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 symbol tables used by the RTEMS Runtime Loader (RTL). The symbol table contains
loaded at run time with the exported base kernel image's symbols so dynamically the exported base kernel symbols user code dynamically loaded can reference.
loaded code can link to them.
The RTEMS Runtime Loader supports embedding of a symbol table in the base The RTEMS Runtime Loader supports two methods of loading a symbol table,
kernel image or loading the symbol table at runtime. Embedding the table embedded and runtime loading. Embedding the table requires linking the symbol
requires linking the symbol table with the base image and runtime loading loads table with the base image and runtime loading loads the table using the dynamic
the table using the dynamic loader when RTEMS is running. loader when RTEMS is running.
.. sidebar:: *Filtering Symbols* .. sidebar:: *Filtering Symbols*
Currently there is no filtering of symbols loaded into the symbol Currently there is no filtering of symbols in the symbol table. This means
table. This means all base kernel image symbols are present in the symbol all base kernel image symbols are present in the symbol table when only a
table when only a sub-set of the symbols may be referenced. sub-set of the symbols are referenced.
Embedding the symbol table creates self contained images. A target may not have 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 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 the management need to match the symbol table with the kernel base
images. Embedding the symbol table requires a 2-pass link process making the image. Embedding the symbol table requires a 2-pass link process making the
application's build system more complicated as well as lengthing the build application's build system more complicated.
time.
A dynamically loadable symbol table is simpler to create however the symbol 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 table and the kernel base image must match or the behaviour is undefined. There
:program:`rtems-syms` command is run against the base kernel image and the is currently no mechnanisum to ensure the symbol table and the kernel image
generated symbol table is installed on to the target hardware and loaded before match The :program:`rtems-syms` command is run against the base kernel image
any other modules. The symbol table object file contains a constructor that is and the generated symbol table is installed on to the target hardware and
called after being loaded and that code registers the symbol table. loaded before any other modules.
Symbol Table Symbol Table
------------ ------------
@ -44,17 +42,18 @@ Symbol Table
The symbol table is an ELF object file in the target's ELF format and is built 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 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 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 system path. If the target's C compiler is not located in either of these paths
to the compiler can be used. use the option ``-c`` or ``--cc`` to specify the path to the compiler.
The :program:`rtems-syms` command loads the base kernel image's ELF file The :program:`rtems-syms` command loads the base kernel image's ELF file and
reading the symbols then creates a temporary C file it compiles using the RTEMS reads the global or public symbols, creates a temporary C file and then
C compiler. The command automatically detects the architecture from the base compiles it using the target's RTEMS C compiler. The command automatically
kernel image's ELF file. The option ``-E`` or ``--exec-prefix`` can be used to detects the architecture from the base kernel image's ELF file and uses it to
override the executable prefix used. create the C compiler's name. 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 It is important to supply suitable C compiler flags (``cflags``) that match the
table can be linked or loaded. kernel image's so the symbol table can be linked or loaded.
2-Pass Linking 2-Pass Linking
-------------- --------------
@ -133,7 +132,11 @@ Examples
-------- --------
Create a dynamlically loaded symbol table for the ``minimum.exe`` sample Create a dynamlically loaded symbol table for the ``minimum.exe`` sample
<<<<<<< Updated upstream
program for the ``i386/pc686`` BSP: program for the ``i386/pc686`` BSP:
=======
program for the ``i386/pc686``:
>>>>>>> Stashed changes
.. code-block:: shell .. code-block:: shell