From 1accbe31a5358b17731e5245294995a6e97b224f Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Wed, 15 Mar 2017 12:34:19 +1100 Subject: user: Add tool commands to the user manual. --- user/tools/symbols.rst | 174 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 174 insertions(+) create mode 100644 user/tools/symbols.rst (limited to 'user/tools/symbols.rst') diff --git a/user/tools/symbols.rst b/user/tools/symbols.rst new file mode 100644 index 0000000..1cd545f --- /dev/null +++ b/user/tools/symbols.rst @@ -0,0 +1,174 @@ +.. comment SPDX-License-Identifier: CC-BY-SA-4.0 + +.. comment: Copyright (c) 2017 Chris Johns +.. 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 -- cgit v1.2.3