source: rtems-docs/shell/dl_commands.rst @ 3605600

Last change on this file since 3605600 was 9ec0107, checked in by Chris Johns <chrisj@…>, on Mar 21, 2019 at 2:20:32 AM

shell/dl: Add dynamic loader commands

  • Property mode set to 100644
File size: 20.0 KB

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 - Manager the RTL

?
.. index:: rtl
SYNOPSYS:
Error: Failed to load processor none
No macro or processor named 'none' found
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
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:

Error: Failed to load processor none
No macro or processor named 'none' found

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
sym:

List symbols in the symbol table with their value. Symbols are grouped by the object file they reside in.

The command is:

Error: Failed to load processor none
No macro or processor named 'none' found

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
obj:

Manage object files. The sub-commands control the operation this command performs.

The command is:

Error: Failed to load processor none
No macro or processor named 'none' found
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
ar:

Display details about archives known to the link editor.

The command is:

Error: Failed to load processor none
No macro or processor named 'none' found

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

Error: Failed to load processor none
No macro or processor named 'none' found

If no options to specify a format are provided and there are arguments the call signature is the standard argc/argv call signature:

Error: Failed to load processor none
No macro or processor named 'none' found

The command is:

Error: Failed to load processor none
No macro or processor named 'none' found

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:

Error: Failed to load processor none
No macro or processor named 'none' found
-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:

Error: Failed to load processor none
No macro or processor named 'none' found
-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:

Error: Failed to load processor none
No macro or processor named 'none' found
name
The name argument is symbol name to find and call.
?
.. index:: 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:

Error: Failed to load processor none
No macro or processor named 'none' found

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:

Error: Failed to load processor none
No macro or processor named 'none' found

List the object files:

Error: Failed to load processor none
No macro or processor named 'none' found

The list shows the referenced archive object files that have been loaded. Show the details for the library object file dl10-o2.o:

Error: Failed to load processor none
No macro or processor named 'none' found

The object file has one reference, 7 symbols and uses 250 bytes of memory. List the symbols:

Error: Failed to load processor none
No macro or processor named 'none' found

The dependents of a group of object files can be listed using a regular expression:

Error: Failed to load processor none
No macro or processor named 'none' found

A number of flags can be selected at once:

Error: Failed to load processor none
No macro or processor named 'none' found

List all symbols that contain main:

Error: Failed to load processor none
No macro or processor named 'none' found

Include the base kernel image in the search:

Error: Failed to load processor none
No macro or processor named 'none' found

The filter is a regular expression:

Error: Failed to load processor none
No macro or processor named 'none' found

The search can be limited to a selection of object files:

Error: Failed to load processor none
No macro or processor named 'none' found

List the archives known to the link editor:

Error: Failed to load processor none
No macro or processor named 'none' found

A long listing of the archives provides the link editor details:

Error: Failed to load processor none
No macro or processor named 'none' found
?
.. index:: list archive symbols

List the symbols an archive provides using the -s option:

Error: Failed to load processor none
No macro or processor named 'none' found
?
.. index:: duplicate symbols

List the duplicate symbols in the archives using the -d option:

Error: Failed to load processor none
No macro or processor named 'none' found

The link editor will list the first archive if finds that has the duplicate symbol.

Call the symbol rtems_main_o4 with no options:

Error: Failed to load processor none
No macro or processor named 'none' found

Call a symbol in a data section of an object file:

Error: Failed to load processor none
No macro or processor named 'none' found

Call the symbol rtems_main_o5 with a single string:

Error: Failed to load processor none
No macro or processor named 'none' found

Note, the call does not have any argument and the strin passed is ignored.

Call the symbol rtems_main_o5 with three integer arguments:

Error: Failed to load processor none
No macro or processor named 'none' found
?
.. 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.

#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:

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.

#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.

#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.

#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.

#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.

#include <rtems/rtl/rtl-archive.h>

int rtems_rtl_shell_call (
    const rtems_printer* printer,
    int                  argc,
    char*                argv[]
);
Note: See TracBrowser for help on using the repository browser.