user: Add tool commands to the user manual.

1 files changed, 174 insertions, 0 deletions

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 <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