summaryrefslogtreecommitdiffstats
path: root/shell/dl_commands.rst
diff options
context:
space:
mode:
Diffstat (limited to 'shell/dl_commands.rst')
-rw-r--r--shell/dl_commands.rst724
1 files changed, 724 insertions, 0 deletions
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 <chrisj@rtems.org>
+
+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 <rtl-list_>`_ : Listings
+ - `sym <rtl-sym_>`_ : Symbols
+ - `obj <rtl-obj_>`_ : Object files
+ - `ar <rtl-ar_>`_ : Archive files
+ - `call <rtl-call_>`_ : Call symbols
+ - `trace <rtl-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 <file>``
+ Load the executable object file specificed by the ``<file>``
+ 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 ``<file>`` references symbols in known archive dependent object
+ files in the available archives they are loaded.
+
+ ``unload <file>``
+ Unload the executable object file specificed by the ``<file>``
+ argument. The ``<file>`` 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 <rtems/rtl/rtl-shell.h>
+ #include <rtems/shell.h>
+
+ 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 <rtems/rtl/rtl-shell.h>
+
+ 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 <rtems/rtl/rtl-shell.h>
+
+ 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 <rtems/rtl/rtl-shell.h>
+
+ 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 <rtems/rtl/rtl-archive.h>
+
+ 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 <rtems/rtl/rtl-archive.h>
+
+ int rtems_rtl_shell_call (
+ const rtems_printer* printer,
+ int argc,
+ char* argv[]
+ );
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-24 18:45:20 +0000