From 9ec0107573f38c4961f1507c3163e49c9c2c0e50 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 21 Mar 2019 13:20:32 +1100 Subject: shell/dl: Add dynamic loader commands --- shell/dl_commands.rst | 724 ++++++++++++++++++++++++++++++++++++++++++++++++++ shell/index.rst | 3 +- 2 files changed, 726 insertions(+), 1 deletion(-) create mode 100644 shell/dl_commands.rst (limited to 'shell') diff --git a/shell/dl_commands.rst b/shell/dl_commands.rst new file mode 100644 index 0000000..182736b --- /dev/null +++ b/shell/dl_commands.rst @@ -0,0 +1,724 @@ +.. SPDX-License-Identifier: CC-BY-SA-4.0 + +.. Copyright (C) 2019 Chris Johns + +Dynamic Loader +************** + +Introduction +============ + +The RTEMS shell has the following dynamic loader commands: + +- rtl_ - Manage the Run-Time Loader (RTL) + +Commands +======== + +This section details the Dynamic Loader Commands available. A subsection is +dedicated to each of the commands and describes the behavior and configuration +of that command as well as providing an example usage. + +.. raw:: latex + + \clearpage + +.. _rtl: + +rtl - Manager the RTL +--------------------- +.. index:: rtl + +SYNOPSYS: + .. code-block:: none + + rtl [-l] -[h] command [...] + +DESCRIPTION: + This command manages the Run-time Loader (RTL) using a series of + sub-commands. The sub-command selected determines what is displayed or the + action taken. Sub-commands can have options that modified the behaviour of + the specific command. + + The ``-l`` option lists the available commands and ``-h`` displays + a simple help message. + + The commands are: + + - `list `_ : Listings + - `sym `_ : Symbols + - `obj `_ : Object files + - `ar `_ : Archive files + - `call `_ : Call symbols + - `trace `_ : Link-editor trace debugging + + .. index:: rtl list + .. _rtl-list: + + ``list``: + List the loaded object files. The executable object file's full path is + displayed. If the executable object file is loaded from an archive the + archive is include in the path. If no options are provided only a list of + the object file names is displayed. + + The command is: + + .. code-block:: none + + rtl list [-nlmsdb] [name] + + The options are: + + ``-n`` + Display all the name fields. + + ``-l`` + Long display the RTL's fields: + + - ``unresolved`` - number of unresolved symbols + - ``users`` - number of users, ie times loaded + - ``references`` - number of referencs to symbols + - ``symbols`` - number of symbols + - ``symbol memory`` - amount of symbol memory + + ``-m`` + Display the memory map. The sections listed are: + + - ``exec`` - total memory allocated + - ``text`` - size of the executable code resident + - ``const`` - size of the constants or read-only memory + - ``data`` - size of the initialised data memory + - ``bss`` - size of the uninitialised data memory + + ``-s`` + Display the local symbols present in the listed object file's symbol + table. List the symbol's value. + + ``-d`` + Display the loaded object files that depend on symbols provided by this + object file. The object file cannot be unloaded while there are + references. + + ``-b`` + Include the base kernel image in the list of object modules. It is not + included by default. If this option is included the base kernel module + name of ``rtems-kernel`` can be used as a ``name``. + + ``name`` + The optional ``name`` argument is a regular expression filter for the + object files to list. The match is partial. If no name argument is + provided all object modules are listed. + + .. index:: rtl sym + .. _rtl-sym: + + ``sym``: + List symbols in the symbol table with their value. Symbols are grouped by + the object file they reside in. + + The command is: + + .. code-block:: none + + rtl sym [-bu] [-o name] [symbol] + + The options are: + + ``-u`` + List the system wide unresolved externals. Symbols are not displayed + when displaying unresolved externals. + + ``-o name`` + Display the symbols for the matching object files. The name is a + regular expression and it is a partial match. + + ``-b`` + Include the base kernel image in the list of object modules. It is not + included by default. If this option is included the base kernel module + name of ``rtems-kernel`` can be used as a ``name``. + + ``symbol`` + The optional ``symbol`` argument is a regular expression filter for the + symbols. The match is partial. If no symbol argument is provided all + symbols and their values are displayed. + + .. index:: rtl obj + .. _rtl-obj: + + ``obj``: + Manage object files. The sub-commands control the operation this command + performs. + + The command is: + + .. code-block:: none + + rtl obj [command] [...] + + ``load `` + Load the executable object file specificed by the ```` + argument. The ``file`` argument can be a file or it can be resided in + archive file. The format is ``archive:file``. The ``archive`` is file + name of the archive and ``file`` is the file in the archive. + + If the ```` references symbols in known archive dependent object + files in the available archives they are loaded. + + ``unload `` + Unload the executable object file specificed by the ```` + argument. The ```` argument can be the object files' name or it + can be a complete name including the archive. + + .. index:: rtl ar + .. _rtl-ar: + + ``ar``: + Display details about archives known to the link editor. + + The command is: + + .. code-block:: none + + rtl ar [-lsd] [name] + + The options are: + + ``-l`` + Long display the RTL's archive fields: + + - ``size`` - size of the archive in the file system + - ``symbols`` - number of symbols in the archive's symbol search table + - ``refs`` - number of referencs to object files in the archive + - ``flags`` - RTL specific flags + + ``-s`` + Display the symbols in the archive symbol tables + + ``-d`` + Display any duplicate symbols in any archives with the archive the + instance of the symbol. + + ``name`` + The optional ``name`` argument is a regular expression filter for the + archive files to list. The match is partial. If no name argument is + provided all archives known to the link editor are listed. + + .. index:: rtl call + .. _rtl-call: + + ``call``: + Call a symbol that resides in a code (``text``) section of an object + file. Arguments can be passed and there is no return value support. + + There are no checks made on the signature of a symbol being called. The + argument signature used needs to match the symbol being called or + unpredictable behaviour may result. + + The reference count of the object file containing the symbol is + increased while the call is active. The ``-l`` option locks the object + by not lowering the reference count once the call completes. This is + useful if the call starts a thread in the object file. The reference + count cannot be lowered by the shell and the object file remains locked + in memory. + + The call occurs on the stack of the shell so it is important to make + sure there is sufficient space available to meet the needs of the call + when configuring your shell. + + The call blocks the shell while it is active. There is no ability to + background the call. + + If no arguments are provided the call signature is: + + .. code-block:: none + + void call (void); + + If no options to specify a format are provided and there are arguments + the call signature is the standard ``argc/argv`` call signature: + + .. code-block:: none + + void call (int argc, const char* argv[]); + + + The command is: + + .. code-block:: none + + rtl call [-lsui] name [args] + + The options are: + + ``-l`` + Leave the object file the symbol resides in locked after the call + returns. + + ``-s`` + Concatenate the ``[args]`` into a single string and pass as a single + ``const char*`` argument. Quoted arguments are stripped or quotes and + merged into the single string. The call signature is: + + .. code-block:: none + + void call (const char* str); + + ``-u`` + Pass up to four unsigned integer ``[args]`` arguments. The symbol's + call signature can have fewer than four arguments, the unreferenced + arguments are ignored. The call signature is: + + .. code-block:: none + + void call (unsigned int u1, + unsigned int u2, + unsigned int u3, + unsigned int u4); + + ``-i`` + Pass up to four integer ``[args]`` arguments. The symbol's call + signature can have fewer than four arguments, the unreferenced + arguments are ignored. The call signature is: + + .. code-block:: none + + void call (int i1, int i2, int i3, int i4); + + ``name`` + The ``name`` argument is symbol name to find and call. + + .. index:: rtl trace + .. _rtl-trace: + + ``trace``: + Clear or set trace flags. The trace flags provide details trace + information from the link editor and can aid debugging. Note, some + options can produce a large volume or output. + + The command is: + + .. code-block:: none + + rtl trace [-l] [-h] [set/clear] flags... + + The options are: + + ``-l`` + List the available flags that can be cleared or set. + + ``-?`` + A ``trace`` command specific help + + The flags are: + + - ``all`` + - ``detail`` + - ``warning`` + - ``load`` + - ``unload`` + - ``section`` + - ``symbol`` + - ``reloc`` + - ``global-sym`` + - ``load-sect`` + - ``allocator`` + - ``unresolved`` + - ``cache`` + - ``archives`` + - ``archive-syms`` + - ``dependency`` + - ``bit-alloc`` + +EXIT STATUS: + This command returns 0 to indicate success else it returns 1. + +NOTES: + - Using this command may initialise the RTL manager if has not been used + and initialised before now. + + - A base kernel image symbol file has to be present for base kernel symbols + to be viewed and searched. + +EXAMPLES: + The following examples can be used with the testsuite's ``dl10`` test. + + Attempt to load an object file that not exist then load an object file that + exists: + + .. code-block:: none + + SHLL [/] # rtl obj load /foo.o + error: load: /foo.o: file not found + SHLL [/] $ rtl obj load /dl10-o1.o + + List the object files: + + .. code-block:: none + + SHLL [/] # rtl list + /dl10-o1.o + /libdl10_1.a:dl10-o2.o + /libdl10_2.a:dl10-o5.o + /libdl10_2.a:dl10-o3.o + /libdl10_1.a:dl10-o4.o + + The list shows the referenced archive object files that have been + loaded. Show the details for the library object file ``dl10-o2.o``: + + .. code-block:: none + + SHLL [/] # rtl list -l dl10-o4.o + /libdl10_1.a:dl10-o4.o + unresolved : 0 + users : 0 + references : 1 + symbols : 7 + symbol memory : 250 + + The object file has one reference, 7 symbols and uses 250 bytes of + memory. List the symbols: + + .. code-block:: none + + SHLL [/] # rtl list -s dl10-o4.o + /libdl10_1.a:dl10-o4.o + rtems_main_o4 = 0x20de818 + dl04_unresolv_1 = 0x20dead0 + dl04_unresolv_2 = 0x20dead4 + dl04_unresolv_3 = 0x20dead8 + dl04_unresolv_4 = 0x20deadc + dl04_unresolv_5 = 0x20deaa0 + dl04_unresolv_6 = 0x20deac0 + + The dependents of a group of object files can be listed using a regular + expression: + + .. code-block:: none + + SHLL [/] # rtl list -d dl10-o[234].o + /libdl10_1.a:dl10-o2.o + dependencies : dl10-o3.o + /libdl10_2.a:dl10-o3.o + dependencies : dl10-o4.o + : dl10-o5.o + /libdl10_1.a:dl10-o4.o + dependencies : dl10-o5.o + + A number of flags can be selected at once: + + .. code-block:: none + + SHLL [/] # rtl list -lmsd dl10-o1.o + /dl10-o1.o + exec size : 1086 + text base : 0x20dbec0 (352) + const base : 0x20dc028 (452) + data base : 0x20dc208 (12) + bss base : 0x20dc220 (266) + unresolved : 0 + users : 1 + references : 0 + symbols : 9 + symbol memory : 281 + dl01_func1 = 0x20dbec0 + rtems_main_o1 = 0x20dbec8 + dl01_bss1 = 0x20dc220 + dl01_bss2 = 0x20dc224 + dl01_bss3 = 0x20dc2a0 + dl01_data1 = 0x20dc20c + dl01_data2 = 0x20dc208 + dl01_const1 = 0x20dc1e8 + dl01_const2 = 0x20dc1e4 + dependencies : dl10-o2.o + + List all symbols that contain ``main``: + + .. code-block:: none + + SHLL [/] # rtl sym main + /dl10-o1.o + rtems_main_o1 = 0x20dbec8 + /libdl10_1.a:dl10-o2.o + rtems_main_o2 = 0x20dd1a0 + /libdl10_2.a:dl10-o5.o + rtems_main_o5 = 0x20df280 + /libdl10_2.a:dl10-o3.o + rtems_main_o3 = 0x20ddc40 + /libdl10_1.a:dl10-o4.o + rtems_main_o4 = 0x20de818 + + Include the base kernel image in the search: + + .. code-block:: none + + SHLL [/] # rtl sym -b main + rtems-kernel + rtems_shell_main_cp = 0x2015e9c + rtems_shell_main_loop = 0x201c2bc + rtems_shell_main_monitor = 0x203f070 + rtems_shell_main_mv = 0x201a11c + rtems_shell_main_rm = 0x201ad38 + /dl10-o1.o + rtems_main_o1 = 0x20dbec8 + /libdl10_1.a:dl10-o2.o + rtems_main_o2 = 0x20dd1a0 + /libdl10_2.a:dl10-o5.o + rtems_main_o5 = 0x20df280 + /libdl10_2.a:dl10-o3.o + rtems_main_o3 = 0x20ddc40 + /libdl10_1.a:dl10-o4.o + rtems_main_o4 = 0x20de818 + + The filter is a regular expression: + + .. code-block:: none + + SHLL [/] # rtl sym -b ^rtems_task + rtems-kernel + rtems_task_create = 0x2008934 + rtems_task_delete = 0x20386b8 + rtems_task_exit = 0x2008a98 + rtems_task_ident = 0x2038738 + rtems_task_iterate = 0x2038798 + rtems_task_self = 0x20387b8 + rtems_task_set_priority = 0x20387c4 + rtems_task_start = 0x2008b7c + rtems_task_wake_after = 0x2008bd0 + + The search can be limited to a selection of object files: + + .. code-block:: none + + SHLL [/] # rtl sym -o dl10-o[12].o dl01_b + /dl10-o1.o + dl01_bss1 = 0x20dc220 + dl01_bss2 = 0x20dc224 + dl01_bss3 = 0x20dc2a0 + SHLL [/] # rtl sym -o dl10-o[12].o dl0[12]_b + /dl10-o1.o + dl01_bss1 = 0x20dc220 + dl01_bss2 = 0x20dc224 + dl01_bss3 = 0x20dc2a0 + /libdl10_1.a:dl10-o2.o + dl02_bss1 = 0x20dd400 + dl02_bss2 = 0x20dd404 + dl02_bss3 = 0x20dd420 + + List the archives known to the link editor: + + .. code-block:: none + + SHLL [/] # rtl ar + /libdl10_1.a + /libdl10_2.a + + A long listing of the archives provides the link editor details: + + .. code-block:: none + + SHLL [/] # rtl ar -l + /libdl10_1.a: + size : 37132 + symbols : 13 + refs : 0 + flags : 0 + /libdl10_2.a: + size : 53050 + symbols : 8 + refs : 0 + flags : 0 + + + .. index:: list archive symbols + + List the symbols an archive provides using the ``-s`` option: + + .. code-block:: none + + SHLL [/] # rtl ar -s libdl10_1.a + /libdl10_1.a: + symbols : dl02_bss1 + dl02_bss2 + dl02_bss3 + dl02_data1 + dl02_data2 + dl04_unresolv_1 + dl04_unresolv_2 + dl04_unresolv_3 + dl04_unresolv_4 + dl04_unresolv_5 + dl04_unresolv_6 + rtems_main_o2 + rtems_main_o4 + + .. index:: duplicate symbols + + List the duplicate symbols in the archives using the ``-d`` option: + + .. code-block:: none + + SHLL [/] # rtl ar -d + /libdl10_1.a: + dups : + /libdl10_2.a: + dups : rtems_main_o5 (/libdl10_2.a) + + The link editor will list the first archive if finds that has the duplicate + symbol. + + Call the symbol ``rtems_main_o4`` with no options: + + .. code-block:: none + + SHLL [/] # rtl call rtems_main_o4 + dlo4: module: testsuites/libtests/dl10/dl-o4.c + dlo4: dl04_unresolv_1: 4: 0x20dee68: 0 + dlo4: dl04_unresolv_2: 4: 0x20dee6c: %f + dlo4: dl04_unresolv_3: 1: 0x20dee70: 00 + dlo4: dl04_unresolv_4: 4: 0x20dee74: 0 + dlo4: dl04_unresolv_5: 4: 0x20dee38: 4 + dlo4: dl04_unresolv_6: 4: 0x20dee58: dl-O4 + dlo5: module: testsuites/libtests/dl10/dl-o5.c + dlo5: dl05_unresolv_1: 8: 0x20df860: 0 + dlo5: dl05_unresolv_2: 2: 0x20df868: 0 + dlo5: dl05_unresolv_3: 4: 0x20df86c: 0 + dlo5: dl05_unresolv_4: 1: 0x20df870: 0 + dlo5: dl05_unresolv_5: 8: 0x20df878: 0 + + Call a symbol in a data section of an object file: + + .. code-block:: none + + SHLL [/] # rtl call dl04_unresolv_3 + error: symbol not in obj text: dl04_unresolv_3 + + Call the symbol ``rtems_main_o5`` with a single string: + + .. code-block:: none + + SHLL [/] # rtl call -s rtems_main_o5 arg1 arg2 "arg3 and still arg3" arg4 + dlo5: module: testsuites/libtests/dl10/dl-o5.c + dlo5: dl05_unresolv_1: 8: 0x20df860: 0 + dlo5: dl05_unresolv_2: 2: 0x20df868: 0 + dlo5: dl05_unresolv_3: 4: 0x20df86c: 0 + dlo5: dl05_unresolv_4: 1: 0x20df870: 0 + dlo5: dl05_unresolv_5: 8: 0x20df878: 0 + + Note, the call does not have any argument and the strin passed is + ignored. + + Call the symbol ``rtems_main_o5`` with three integer arguments: + + .. code-block:: none + + SHLL [/] # rtl call -i rtems_main_o5 1 22 333 + dlo5: module: testsuites/libtests/dl10/dl-o5.c + dlo5: dl05_unresolv_1: 8: 0x20df860: 0 + dlo5: dl05_unresolv_2: 2: 0x20df868: 0 + dlo5: dl05_unresolv_3: 4: 0x20df86c: 0 + dlo5: dl05_unresolv_4: 1: 0x20df870: 0 + dlo5: dl05_unresolv_5: 8: 0x20df878: 0 + +.. index:: rtems_rtl_shell_command + +CONFIGURATION: + This command is not included in the default shell command set. The command + needs to be added with the shell's ``rtems_shell_add_cmd``. + + .. code-block:: c + + #include + #include + + rtems_shell_init_environment (); + + if (rtems_shell_add_cmd ("rtl", + "rtl", + "rtl -?", + rtems_rtl_shell_command) == NULL) + printf("error: command add failed\n"); + +PROGRAMMING INFORMATION: + The ``rtl`` commanf is implemented by a C language function which has the + following prototype: + + .. code-block:: c + + int rtems_rtl_shell_command( + int argc, + char **argv + ); + + The sub-command parts of the ``rtl`` command can be called directly. These + calls all use the RTEMS Printer interface and as a result can be redirected + and captured. + + .. index:: rtems_rtl_shell_list + ``list`` + The RTL list command. + + .. code-block:: c + + #include + + int rtems_rtl_shell_list ( + const rtems_printer* printer, + int argc, + char* argv[] + ); + + .. index:: rtems_rtl_shell_object + ``sym`` + The RTL symbol command. + + .. code-block:: c + + #include + + int rtems_rtl_shell_sym ( + const rtems_printer* printer, + int argc, + char* argv[] + ); + + .. index:: rtems_rtl_shell_object + ``sym`` + The RTL object command. + + .. code-block:: c + + #include + + int rtems_rtl_shell_object ( + const rtems_printer* printer, + int argc, + char* argv[] + ); + + .. index:: rtems_rtl_shell_archive + ``ar`` + The RTL object command. + + .. code-block:: c + + #include + + int rtems_rtl_shell_archive ( + const rtems_printer* printer, + int argc, + char* argv[] + ); + + .. index:: rtems_rtl_shell_call + ``call`` + The RTL object command. + + .. code-block:: c + + #include + + int rtems_rtl_shell_call ( + const rtems_printer* printer, + int argc, + char* argv[] + ); diff --git a/shell/index.rst b/shell/index.rst index c7efff7..0338807 100644 --- a/shell/index.rst +++ b/shell/index.rst @@ -10,7 +10,7 @@ RTEMS Shell Guide (|version|). .. topic:: Copyrights and License - | |copy| 2016, 2018 Chris Johns + | |copy| 2016, 2019 Chris Johns | |copy| 2016, 2017 embedded brains GmbH | |copy| 2016, 2017 Sebastian Huber | |copy| 1988, 2017 On-Line Applications Research Corporation (OAR) @@ -29,6 +29,7 @@ RTEMS Shell Guide (|version|). file_and_directory memory_commands rtems_specific_commands + dl_commands network_commands function_and_variable concept -- cgit v1.2.3