rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-31 09:01:36 +08:00
Code Issues Packages Projects Releases Wiki Activity

user: Add tool commands to the user manual.

Browse Source
This commit is contained in:
Chris Johns 2017-03-15 12:34:19 +11:00
parent 91d6c96b4c
commit 1accbe31a5
8 changed files with 621 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
common/_static/my-styles.css
View File

@ -110,6 +110,15 @@ table.rtems-table.docutils td {
color: #333333;
}
/*
* Option description name.
*/
.rst-content dl:not(.docutils) dt {
background: transparent;
color: #11111111;
border-top: 0px;
}
/*
* Nav side-bar in RTEMS colours.
*/

2
user/index.rst
View File

@ -28,6 +28,8 @@ Table of Contents
hardware/index
tools/index
support/index
additional/index
glossary/index

200
user/tools/bsp-builder.rst Normal file
View File

@ -0,0 +1,200 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
.. comment: Copyright (c) 2017 Chris Johns <chrisj@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.

17
user/tools/build.rst
View File

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

204
user/tools/exeinfo.rst Normal file
View File

@ -0,0 +1,204 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
.. comment: Copyright (c) 2017 Chris Johns <chrisj@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``.

24
user/tools/index.rst
View File

@ -1,11 +1,23 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
.. comment: Copyright (c) 2016 Chris Johns <chrisj@rtems.org>
.. comment: Copyright (c) 2017 Chris Johns <chrisj@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

14
user/tools/linker.rst Normal file
View File

@ -0,0 +1,14 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
.. comment: Copyright (c) 2017 Chris Johns <chrisj@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 ]

174
user/tools/symbols.rst Normal file
View File

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