[PATCH] user: Add tool commands to the user manual.

Chris Johns chrisj at rtems.org
Wed Mar 15 04:01:15 UTC 2017


---
 common/_static/my-styles.css |   9 ++
 user/index.rst               |   2 +
 user/tools/bsp-builder.rst   | 200 ++++++++++++++++++++++++++++++++++++++++++
 user/tools/build.rst         |  17 ----
 user/tools/exeinfo.rst       | 204 +++++++++++++++++++++++++++++++++++++++++++
 user/tools/index.rst         |  24 +++--
 user/tools/linker.rst        |  14 +++
 user/tools/symbols.rst       | 174 ++++++++++++++++++++++++++++++++++++
 8 files changed, 621 insertions(+), 23 deletions(-)
 create mode 100644 user/tools/bsp-builder.rst
 delete mode 100644 user/tools/build.rst
 create mode 100644 user/tools/exeinfo.rst
 create mode 100644 user/tools/linker.rst
 create mode 100644 user/tools/symbols.rst

diff --git a/common/_static/my-styles.css b/common/_static/my-styles.css
index 1fee616..3ab5cb0 100644
--- a/common/_static/my-styles.css
+++ b/common/_static/my-styles.css
@@ -111,6 +111,15 @@ table.rtems-table.docutils td {
 }
 
 /*
+ * Option description name.
+ */
+.rst-content dl:not(.docutils) dt {
+    background: transparent;
+    color: #11111111;
+    border-top: 0px;
+}
+
+/*
  * Nav side-bar in RTEMS colours.
  */
 .wy-nav-top, .wy-nav-top a {
diff --git a/user/index.rst b/user/index.rst
index 7241d3f..3363b17 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -28,6 +28,8 @@ Table of Contents
 
 	hardware/index
 
+	tools/index
+
 	support/index
 	additional/index
 	glossary/index
diff --git a/user/tools/bsp-builder.rst b/user/tools/bsp-builder.rst
new file mode 100644
index 0000000..f27cb68
--- /dev/null
+++ b/user/tools/bsp-builder.rst
@@ -0,0 +1,200 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. comment: Copyright (c) 2017 Chris Johns <chrisj at rtems.org>
+.. comment: All rights reserved.
+
+RTEMS BSP Builder
+=================
+
+.. index:: Tools, rtems-bsp-builder
+
+The RTEMS BSP Builder is an RTEMS developer tool to build RTEMS in ways users
+do not to test changes to RTEMS. RTEMS has large number of architectures, board
+support packages and configuration options. This tool provides a standard way
+to test a change.
+
+Developer Workflows
+-------------------
+
+There are a number of RTEMS developers each with a different view or expertise
+in RTEMS. Developer can work in the generic areas such as scheduling, file
+systems or the shell, then there are users turned developers adding a new BSP,
+or even a new port to a new architecture. A common approach for all these
+developers is to select a BSP and to work with that BSP. Developers working in
+a generic areas of RTEMS tend to select a BSP that has good simulator support
+with good debugging such as QEMU, while developers of a new BSP or a new port
+tend to work on target hardware. This type of development does not check the
+other architectures, BSP, and build options and a change may change the number
+of warnings or introduce build errors. It is important for the RTEMS project to
+have developers fix these issues before pushing the changes to master
+repository to avoid breaking the code for other developers. It is best for a
+developer to resolve as many issues as they work on changes because comming
+back to a problem often proves difficult.
+
+The RTEMS BSP Builder forms part of a developers workflow where patches are
+tested before being pushed to the repository.
+
+Build Characteristics
+---------------------
+
+Build characteristic are the various parts of a build that can varied changing
+what is built. RTEMS can vary builds based on:
+
+#. Architecture
+
+#. Board Support Package (BSP)
+
+#. Build Configuration options
+
+#. BSP Options
+
+The BSP Builder provides a template of build variation to try and reduce the
+possble combinations to something manageable. It is not realistic to build all
+possible combinations on a single machine in reasonible time.
+
+The RTEMS BSP Builder specifies it builds in terms of:
+
+#. Profiles
+
+#. Builds
+
+The RTEMS BSP Builder will build a list of builds for a profile of board
+support packages.
+
+Profiles
+^^^^^^^^
+
+A profile is named collection of architectures and board support packages. When
+the RTEMS BSP Builder is asked to build a specific profile it builds the BSPs
+in the specified architectures.
+
+The default configuration provides standard profiles based on
+:ref:`Tiers`. They are:
+
+#. ``tier-1`` (default)
+
+#. ``tier-2``
+
+#. ``tier-3``
+
+#. ``tier-4``
+
+Builds
+^^^^^^
+
+A build is a list of builds and each BSP in a profiles is built using each
+build in the builds list.
+
+The default configuration provides standard builds based around the commonly
+varied configure options.
+
+The builds are:
+
+#. ``all`` (default)
+
+#. ``basic``
+
+A ``basic`` build is the ``standard`` or default set configure options.
+
+The ``all`` build is:
+
+ +-----------------------+-----------------------------------------------------+
+ | Label                 | Configure Options                                   |
+ +-----------------------+-----------------------------------------------------+
+ | ``debug``             | ``--enable-debug``                                  |
+ +-----------------------+-----------------------------------------------------+
+ | ``profiling``         | ``--enable-profiling``                              |
+ +-----------------------+-----------------------------------------------------+
+ | ``smp``               | ``--enable-sm``                                     |
+ +-----------------------+-----------------------------------------------------+
+ | ``smp-debug``         | ``--enable-smp --enable-debug``                     |
+ +-----------------------+-----------------------------------------------------+
+ | ``posix``             | ``--enable-posix``                                  |
+ +-----------------------+-----------------------------------------------------+
+ | ``no-posix``          | ``--disable-posix``                                 |
+ +-----------------------+-----------------------------------------------------+
+ | ``posix-debug``       | ``--enable-posix --enable-debug``                   |
+ +-----------------------+-----------------------------------------------------+
+ | ``posix-profiling``   | ``--enable-posix --enable-profiling``               |
+ +-----------------------+-----------------------------------------------------+
+ | ``posix-smp``         | ``--enable-posix --enable-smp``                     |
+ +-----------------------+-----------------------------------------------------+
+ | ``network``           | ``--enable-networking``                             |
+ +-----------------------+-----------------------------------------------------+
+ | ``no-network``        | ``--disable-networking``                            |
+ +-----------------------+-----------------------------------------------------+
+ | ``network-debug``     | ``--disable-networking``                            |
+ +-----------------------+-----------------------------------------------------+
+ | ``network-debug``     | ``--enable-debug --enable-networking``              |
+ +-----------------------+-----------------------------------------------------+
+ | ``smp-network``       | ``--enable-smp --enable-networking``                |
+ +-----------------------+-----------------------------------------------------+
+ | ``smp-network-debug`` | ``--enable-smp --enable-debug --enable-networking`` |
+ +-----------------------+-----------------------------------------------------+
+
+Command
+-------
+
+:program:`rtems-bsp-builder` [options]
+
+.. option:: -?
+
+   Display a compact help.
+
+.. option:: -h, --help
+
+   Display the full help.
+
+.. option:: --prefix
+
+   Prefix to pass to configure then building a BSP.
+
+.. option:: --rtems-tools
+
+   The path the RTEMS tools such as the C compiler. This option avoid polluting
+   your path.
+
+.. option:: --rtems
+
+   The path the RTEMS source tree to build.
+
+.. option:: --build-path
+
+   The path to build the BSP and place the build output. This can be any path
+   and away from your current directory or the RTEMS source code. The storage
+   does not need to be fast like an SSD.
+
+.. option:: --log
+
+   The log file.
+
+.. option:: --stop-on-error
+
+   Stop the build on an error. The default is to build all the builds for a
+   profile.
+
+.. option:: --no-clean
+
+   Do not remove the build once finished. This option lets you inspect the
+   built output. The output of output can be large and disks can fill with this
+   option.
+
+.. option:: --profiles
+
+   Build the list of profiles. The default is ``tier-1``.
+
+.. option:: --build
+
+   The build to be used. The default is ``all``.
+
+.. option:: --arch
+
+   Specify an architecure for a BSP to build instead of using a profile.
+
+.. option:: --bsp
+
+   The a specific BSP to build instead of using a profile.
+
+.. option:: --dry-run
+
+   Do not do the actual builds just show what would be built.
diff --git a/user/tools/build.rst b/user/tools/build.rst
deleted file mode 100644
index 3482cc2..0000000
--- a/user/tools/build.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-Build Tools
-===========
-.. index:: Tools, rtems-config, rtems-cc
-
-
-rtems-config
-------------
-
-XXX: rtems-config
-
-
-rtems-cc
---------
-
-XXX: rtems-cc
diff --git a/user/tools/exeinfo.rst b/user/tools/exeinfo.rst
new file mode 100644
index 0000000..6eff10a
--- /dev/null
+++ b/user/tools/exeinfo.rst
@@ -0,0 +1,204 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. comment: Copyright (c) 2017 Chris Johns <chrisj at rtems.org>
+.. comment: All rights reserved.
+
+RTEMS Executable Infomation
+===========================
+
+.. index:: Tools, rtems-exeinfo
+
+The RTEMS Executable Information (:program:`rtems-exeinfo`) command is an RTEMS
+tool to display some important parts of an RTEMS executable. RTEMS uses ELF as
+the final linker output and this tool displays useful RTEMS specific
+information held in the ELF executable. The tool does not replace tools like
+`readelf`, rather it focuses on reporting specific information RTEMS builds
+into the executable.
+
+System Initialisation
+---------------------
+
+Linker based system initialisation automatically lets RTEMS only link into the
+executable the system initialisation code referenced by the user's application
+or indirectly by RTEMS. The technique is a varation of the system
+initialisation process used in the FreeBSD kernel. It is also similar to the
+process used by the C++ language to run static constructors before entering
+`main` and destructors after `exit` is called.
+
+Linker based system initialisation collects the address of referenced system
+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.
+
+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
+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.
+
+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
+system tricks, or stub libraries.
+
+The RTEMS Execuable Information reports the tables created and you can use this
+information to debug any initialisation issues.
+
+Command
+-------
+
+The :program:`rtems-exeinfo` tool reports RTEMS specific information about the
+executable. The ``init`` and ``fini`` tables print the symbol referenced for
+each table entry and if the symbol is from the C++ language it is demangled.
+
+:program:`rtems-exeinfo`
+
+.. option:: -V
+
+   Display the version information and then exit.
+
+.. option:: -v
+
+   Increase the verbose level by 1. The option can be used more than once to
+   get more detailed trace and debug information.
+
+.. option:: -a
+
+   Report all types of output data.
+
+.. option:: -I
+
+   Report the ``init`` or initialisation table.
+
+.. option:: -F
+
+   Report the ``fini`` or finialisation table.
+
+.. option:: -S
+
+   Report the sections.
+
+.. option:: -?, -h
+
+   Reort the usage help.
+
+Examples
+--------
+
+Prints all reports for the ``hello.exe`` for the ``i386/pc686`` BSP:
+
+.. code-block:: shell
+
+  $ rtems-exeinfo -a i386-rtems4.12/c/pc686/testsuites/samples/hello/hello.exe
+  RTEMS Executable Info 4.12.a72a462adc18
+   rtems-exeinfo -a i386-rtems4.12/c/pc686/testsuites/samples/hello/hello.exe
+  exe: i386-rtems4.12/c/pc686/testsuites/samples/hello/hello.exe
+  Sections: 23
+                    -------------- address: 0x00000000 0x00000000 size:       0 align:   0 relocs:    0
+    .bss            WA------------ address: 0x0013f340 0x00144d9c size:   23132 align:  32 relocs:    0
+    .comment        ---MS--------- address: 0x00000000 0x0000008f size:     143 align:   1 relocs:    0
+    .ctors          WA------------ address: 0x0013cc9c 0x0013cca4 size:       8 align:   4 relocs:    0
+    .data           WA------------ address: 0x0013ccc0 0x0013f32c size:    9836 align:  32 relocs:    0
+    .debug_abbrev   -------------- address: 0x00000000 0x0003ef4c size:  257868 align:   1 relocs:    0
+    .debug_aranges  -------------- address: 0x00000000 0x00003da8 size:   15784 align:   8 relocs:    0
+    .debug_info     -------------- address: 0x00000000 0x0036dd9e size: 3595678 align:   1 relocs:    0
+    .debug_line     -------------- address: 0x00000000 0x00072dca size:  470474 align:   1 relocs:    0
+    .debug_loc      -------------- address: 0x00000000 0x0003fd2c size:  261420 align:   1 relocs:    0
+    .debug_ranges   -------------- address: 0x00000000 0x00009738 size:   38712 align:   1 relocs:    0
+    .debug_str      ---MS--------- address: 0x00000000 0x0001bf78 size:  114552 align:   1 relocs:    0
+    .dtors          WA------------ address: 0x0013cca4 0x0013ccac size:       8 align:   4 relocs:    0
+    .eh_frame       -A------------ address: 0x00134340 0x0013bc9c size:   31068 align:   4 relocs:    0
+    .fini           -AE----------- address: 0x0012d8a9 0x0012d8b1 size:       8 align:   1 relocs:    0
+    .init           -AE----------- address: 0x0012d89c 0x0012d8a9 size:      13 align:   1 relocs:    0
+    .jcr            WA------------ address: 0x0013ccac 0x0013ccb0 size:       4 align:   4 relocs:    0
+    .rodata         -A------------ address: 0x0012d8c0 0x0013433d size:   27261 align:  32 relocs:    0
+    .rtemsroset     WA------------ address: 0x0012d860 0x0012d89c size:      60 align:   4 relocs:    0
+    .shstrtab       -------------- address: 0x00000000 0x000000cb size:     203 align:   1 relocs:    0
+    .strtab         -------------- address: 0x00000000 0x0000772a size:   30506 align:   1 relocs:    0
+    .symtab         -------------- address: 0x00000000 0x00007120 size:   28960 align:   4 relocs:    0
+    .text           WAE----------- address: 0x00100000 0x0012d860 size:  186464 align:  16 relocs:    0
+
+  Init sections: 2
+   .ctors
+    0xffffffff RamSize
+    0x00000000 _TLS_Data_size
+   .rtemsroset
+    0x00100280 bsp_work_area_initialize
+    0x001003b0 bsp_start_default
+    0x0011ace0 _User_extensions_Handler_initialization
+    0x00113040 rtems_initialize_data_structures
+    0x00112ec0 _RTEMS_tasks_Manager_initialization
+    0x0011df30 _Message_queue_Manager_initialization
+    0x0011cfa0 _Semaphore_Manager_initialization
+    0x0011ce70 _POSIX_Keys_Manager_initialization
+    0x00117360 _Thread_Create_idle
+    0x0010c8d0 rtems_libio_init
+    0x0010c7c0 rtems_filesystem_initialize
+    0x00100390 bsp_predriver_hook
+    0x001130f0 _IO_Initialize_all_drivers
+    0x00112d90 _RTEMS_tasks_Initialize_user_tasks_body
+    0x0010d520 rtems_libio_post_driver
+
+  Fini sections: 1
+   .dtors
+    0xffffffff RamSize
+    0x00000000 _TLS_Data_size
+
+The Init section ``.rtemsroset`` shows the initialisation call order for the
+``hello.exe`` sample application. The order is initialise the BSP work area,
+call the BSP start up, initialise the User extensions, initialise the RTEMS
+data structures, then call the various Classic API managers that have been
+linked into the application. Next any POSIX managers are initialisations, in
+this case the POSIX Keys manager which is used by the thread local storage
+(TLS) support. Finally the IO and file system is initialise followed by the
+drivers.
+
+Print the ``Init`` section data for the ``cdtest.exe`` for the ``i386/pc686`` BSP:
+
+.. code-block:: shell
+
+  $ rtems-exeinfo -I i386-rtems4.12/c/pc686/testsuites/samples/cdtest/cdtest.exe
+  RTEMS Executable Info 4.12.a72a462adc18
+   rtems-exeinfo -I i386-rtems4.12/c/pc686/testsuites/samples/cdtest/cdtest.exe
+  exe: i386-rtems4.12/c/pc686/testsuites/samples/cdtest/cdtest.exe
+  Init sections: 2
+   .ctors
+    0xffffffff RamSize
+    0x00100e90 rtems_test_name
+    0x001014b0 __gnu_cxx::__freeres()
+    0x001017c0 __cxa_get_globals_fast
+    0x001024e0 __cxxabiv1::__terminate(void (*)())
+    0x001030a0 std::_V2::error_category::~error_category()
+    0x0010cfa0 std::ctype_byname<char>::ctype_byname(std::string const&, unsigned long)
+    0x0010d070 std::ctype_byname<wchar_t>::ctype_byname(std::string const&, unsigned long)
+    0x0010d210 std::nothrow
+    0x0010d230 std::ctype_byname<char>::ctype_byname(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, unsigned long)
+    0x0010d2c0 std::ctype_byname<wchar_t>::ctype_byname(std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > const&, unsigned long)
+    0x00000000 _TLS_Data_size
+   .rtemsroset
+    0x00111210 bsp_work_area_initialize
+    0x00111340 bsp_start_default
+    0x0012c560 _User_extensions_Handler_initialization
+    0x001244d0 rtems_initialize_data_structures
+    0x00124350 _RTEMS_tasks_Manager_initialization
+    0x0012f790 _Message_queue_Manager_initialization
+    0x0012e7c0 _Semaphore_Manager_initialization
+    0x0013ccc0 _POSIX_signals_Manager_Initialization
+    0x0012e650 _POSIX_Keys_Manager_initialization
+    0x00128be0 _Thread_Create_idle
+    0x0011d9d0 rtems_libio_init
+    0x0011d8c0 rtems_filesystem_initialize
+    0x00111320 bsp_predriver_hook
+    0x00124580 _IO_Initialize_all_drivers
+    0x00124220 _RTEMS_tasks_Initialize_user_tasks_body
+    0x0011e620 rtems_libio_post_driver
+
+The C++ constructor section ``.ctors`` shows you the C++ static objects the
+RTEMS kernel will construct before calling ``main``.
diff --git a/user/tools/index.rst b/user/tools/index.rst
index 5441d76..d77a7ca 100644
--- a/user/tools/index.rst
+++ b/user/tools/index.rst
@@ -1,11 +1,23 @@
 .. comment SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. comment: Copyright (c) 2016 Chris Johns <chrisj at rtems.org>
+.. comment: Copyright (c) 2017 Chris Johns <chrisj at rtems.org>
 .. comment: All rights reserved.
 
-RTEMS Tools
-***********
+Tools
+*****
 
-The RTEMS kernel is cross-compiled on host computers and linked to 3rd party
-packages and application code and run on target hardware. This section details
-how to build asuitable cross-compiler and how to use the 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.
+
+.. include:: linker.rst
+.. include:: symbols.rst
+.. include:: exeinfo.rst
+.. include:: trace-linker.rst
+.. include:: bsp-builder.rst
diff --git a/user/tools/linker.rst b/user/tools/linker.rst
new file mode 100644
index 0000000..56286a8
--- /dev/null
+++ b/user/tools/linker.rst
@@ -0,0 +1,14 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. comment: Copyright (c) 2017 Chris Johns <chrisj at rtems.org>
+.. comment: All rights reserved.
+
+RTEMS Linker
+============
+
+.. index:: Tools, rtems-ld, linker
+
+The RTEMS Linker is an RTEMS tool to help build RTEMS application that
+dynamically loader code into a running RTEMS system.
+
+[ NOT COMPLETE ]
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 at 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
-- 
2.11.0



More information about the devel mailing list