[rtems-docs commit] user: Add tool commands to the user manual.
Chris Johns
chrisj at rtems.org
Thu Mar 16 03:14:57 UTC 2017
Module: rtems-docs
Branch: master
Commit: 1accbe31a5358b17731e5245294995a6e97b224f
Changeset: http://git.rtems.org/rtems-docs/commit/?id=1accbe31a5358b17731e5245294995a6e97b224f
Author: Chris Johns <chrisj at rtems.org>
Date: Wed Mar 15 12:34:19 2017 +1100
user: Add tool commands to the user manual.
---
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(-)
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
More information about the vc
mailing list