diff options
| -rw-r--r-- | user/tools/exeinfo.rst | 19 | ||||
| -rw-r--r-- | user/tools/index.rst | 21 | ||||
| -rw-r--r-- | user/tools/symbols.rst | 61 |
3 files changed, 51 insertions, 50 deletions
diff --git a/user/tools/exeinfo.rst b/user/tools/exeinfo.rst index 6eff10a..522c6e5 100644 --- a/user/tools/exeinfo.rst +++ b/user/tools/exeinfo.rst @@ -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 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 -table. The start-up code in RTEMS loops over the table of addresses and calls -each address or system initialisation function. Th especial section names given -to the variables sort the table placing the initialisation calls in a specific -and controlled order. +table. The start-up code in RTRMS loops over the table of addresses and calling +each address or system initialisation function. Special section names given to +the variables sorts the table placing the functions in a specific order. 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 -executable. The API code the linker loads references the variable containing -the address of that API's system initialisation function. The linker loads the +executing. The API code the linker loads references the variable containing 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 -reference 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 -API initialisation. +refernece created by the variable. If the user does not reference the API the +variables is loaded into the executable and no reference to the API system +initialisation code is made so it is not linked into the executable. 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. The RTEMS Execuable Information reports the tables created and you can use this diff --git a/user/tools/index.rst b/user/tools/index.rst index d77a7ca..feb3d31 100644 --- a/user/tools/index.rst +++ b/user/tools/index.rst @@ -3,18 +3,17 @@ .. comment: Copyright (c) 2017 Chris Johns <chrisj@rtems.org> .. comment: All rights reserved. -Tools -***** +<<<<<<< Updated upstream +Host Tools +********** -The RTEMS kernel is developed on a host computer where the user's application -code is cross-compiled to the target hardware's processor instructions and -linked to the RTEMS kernel and language runtime libraries, and any 3rd party -packages. RTEMS is not a multiprocess operating system and self hosting the -types of tools need to create executables is not feasable. As a result a range -of support tools are needed and they need run on the wide range of avaliable -host computers users wish to develop on. This section details the tools -available on host computers RTEMS users and developers need to create RTEMS -executables. +The RTEMS kernel is developed on host computers cross-compiled and linking the +kernel, language runtime libraries, 3rd party packages and application source +code so it can run on target hardware. RTEMS and some of the hardware it +support cannot self-host so we need a range of tools to support the wide range +of avaliable host computers users wish to develop on. This section details the +tools available on the host computers to help support RTEMS users and +developers. .. include:: linker.rst .. include:: symbols.rst diff --git a/user/tools/symbols.rst b/user/tools/symbols.rst index 1cd545f..f4a95ff 100644 --- a/user/tools/symbols.rst +++ b/user/tools/symbols.rst @@ -8,35 +8,33 @@ 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 Symbols (:program:`rtems-syms`) command is an RTEMS tool to generate +symbol tables used by the RTEMS Runtime Loader (RTL). The symbol table contains +the exported base kernel symbols user code dynamically loaded can reference. -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. +The RTEMS Runtime Loader supports two methods of loading a symbol table, +embedded and runtime loading. 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. + Currently there is no filtering of symbols in the symbol table. This means + all base kernel image symbols are present in the symbol table when only a + sub-set of the symbols are 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. +the management need to match the symbol table with the kernel base +image. Embedding the symbol table requires a 2-pass link process making the +application's build system more complicated. 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. +table and the kernel base image must match or the behaviour is undefined. There +is currently no mechnanisum to ensure the symbol table and the kernel image +match 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. 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 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. +system path. If the target's C compiler is not located in either of these paths +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 -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. +The :program:`rtems-syms` command loads the base kernel image's ELF file and +reads the global or public symbols, creates a temporary C file and then +compiles it using the target's RTEMS C compiler. The command automatically +detects the architecture from the base kernel image's ELF file and uses it to +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 -table can be linked or loaded. +It is important to supply suitable C compiler flags (``cflags``) that match the +kernel image's so the symbol table can be linked or loaded. 2-Pass Linking -------------- @@ -133,7 +132,11 @@ Examples -------- Create a dynamlically loaded symbol table for the ``minimum.exe`` sample +<<<<<<< Updated upstream program for the ``i386/pc686`` BSP: +======= +program for the ``i386/pc686``: +>>>>>>> Stashed changes .. code-block:: shell |