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

5
Last change on this file since 3605600 was 9ec0107, checked in by Chris Johns <chrisj@…>, on 03/21/19 at 02:20:32

shell/dl: Add dynamic loader commands

  • Property mode set to 100644
File size: 20.0 KB
RevLine 
[9ec0107]1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2019 Chris Johns <chrisj@rtems.org>
4
5Dynamic Loader
6**************
7
8Introduction
9============
10
11The RTEMS shell has the following dynamic loader commands:
12
13- rtl_ - Manage the Run-Time Loader (RTL)
14
15Commands
16========
17
18This section details the Dynamic Loader Commands available. A subsection is
19dedicated to each of the commands and describes the behavior and configuration
20of that command as well as providing an example usage.
21
22.. raw:: latex
23
24   \clearpage
25
26.. _rtl:
27
28rtl - Manager the RTL
29---------------------
30.. index:: rtl
31
32SYNOPSYS:
33    .. code-block:: none
34
35        rtl [-l] -[h] command [...]
36
37DESCRIPTION:
38    This command manages the Run-time Loader (RTL) using a series of
39    sub-commands. The sub-command selected determines what is displayed or the
40    action taken. Sub-commands can have options that modified the behaviour of
41    the specific command.
42
43    The ``-l`` option lists the available commands and ``-h`` displays
44    a simple help message.
45
46    The commands are:
47
48     - `list <rtl-list_>`_ : Listings
49     - `sym <rtl-sym_>`_ : Symbols
50     - `obj <rtl-obj_>`_ : Object files
51     - `ar <rtl-ar_>`_ : Archive files
52     - `call <rtl-call_>`_ : Call symbols
53     - `trace <rtl-trace_>`_ : Link-editor trace debugging
54
55    .. index:: rtl list
56    .. _rtl-list:
57
58    ``list``:
59      List the loaded object files. The executable object file's full path is
60      displayed. If the executable object file is loaded from an archive the
61      archive is include in the path. If no options are provided only a list of
62      the object file names is displayed.
63
64      The command is:
65
66      .. code-block:: none
67
68        rtl list [-nlmsdb] [name]
69
70      The options are:
71
72      ``-n``
73        Display all the name fields.
74
75      ``-l``
76        Long display the RTL's fields:
77
78        - ``unresolved`` - number of unresolved symbols
79        - ``users`` - number of users, ie times loaded
80        - ``references`` - number of referencs to symbols
81        - ``symbols`` - number of symbols
82        - ``symbol memory`` - amount of symbol memory
83
84      ``-m``
85        Display the memory map. The sections listed are:
86
87        - ``exec`` - total memory allocated
88        - ``text`` - size of the executable code resident
89        - ``const`` - size of the constants or read-only memory
90        - ``data`` - size of the initialised data memory
91        - ``bss`` - size of the uninitialised data memory
92
93      ``-s``
94        Display the local symbols present in the listed object file's symbol
95        table. List the symbol's value.
96
97      ``-d``
98        Display the loaded object files that depend on symbols provided by this
99        object file. The object file cannot be unloaded while there are
100        references.
101
102      ``-b``
103        Include the base kernel image in the list of object modules. It is not
104        included by default. If this option is included the base kernel module
105        name of ``rtems-kernel`` can be used as a ``name``.
106
107      ``name``
108        The optional ``name`` argument is a regular expression filter for the
109        object files to list. The match is partial. If no name argument is
110        provided all object modules are listed.
111
112    .. index:: rtl sym
113    .. _rtl-sym:
114
115    ``sym``:
116      List symbols in the symbol table with their value. Symbols are grouped by
117      the object file they reside in.
118
119      The command is:
120
121      .. code-block:: none
122
123        rtl sym [-bu] [-o name] [symbol]
124
125      The options are:
126
127      ``-u``
128        List the system wide unresolved externals. Symbols are not displayed
129        when displaying unresolved externals.
130
131      ``-o name``
132        Display the symbols for the matching object files. The name is a
133        regular expression and it is a partial match.
134
135      ``-b``
136        Include the base kernel image in the list of object modules. It is not
137        included by default. If this option is included the base kernel module
138        name of ``rtems-kernel`` can be used as a ``name``.
139
140      ``symbol``
141        The optional ``symbol`` argument is a regular expression filter for the
142        symbols. The match is partial. If no symbol argument is provided all
143        symbols and their values are displayed.
144
145    .. index:: rtl obj
146    .. _rtl-obj:
147
148    ``obj``:
149      Manage object files. The sub-commands control the operation this command
150      performs.
151
152      The command is:
153
154      .. code-block:: none
155
156        rtl obj [command] [...]
157
158      ``load <file>``
159        Load the executable object file specificed by the ``<file>``
160        argument. The ``file`` argument can be a file or it can be resided in
161        archive file. The format is ``archive:file``. The ``archive`` is file
162        name of the archive and ``file`` is the file in the archive.
163
164        If the ``<file>`` references symbols in known archive dependent object
165        files in the available archives they are loaded.
166
167      ``unload <file>``
168        Unload the executable object file specificed by the ``<file>``
169        argument. The ``<file>`` argument can be the object files' name or it
170        can be a complete name including the archive.
171
172    .. index:: rtl ar
173    .. _rtl-ar:
174
175    ``ar``:
176      Display details about archives known to the link editor.
177
178      The command is:
179
180      .. code-block:: none
181
182        rtl ar [-lsd] [name]
183
184      The options are:
185
186      ``-l``
187        Long display the RTL's archive fields:
188
189        - ``size`` - size of the archive in the file system
190        - ``symbols`` - number of symbols in the archive's symbol search table
191        - ``refs`` - number of referencs to object files in the archive
192        - ``flags`` - RTL specific flags
193
194      ``-s``
195        Display the symbols in the archive symbol tables
196
197      ``-d``
198        Display any duplicate symbols in any archives with the archive the
199        instance of the symbol.
200
201      ``name``
202        The optional ``name`` argument is a regular expression filter for the
203        archive files to list. The match is partial. If no name argument is
204        provided all archives known to the link editor  are listed.
205
206    .. index:: rtl call
207    .. _rtl-call:
208
209    ``call``:
210      Call a symbol that resides in a code (``text``) section of an object
211      file. Arguments can be passed and there is no return value support.
212
213      There are no checks made on the signature of a symbol being called. The
214      argument signature used needs to match the symbol being called or
215      unpredictable behaviour may result.
216
217      The reference count of the object file containing the symbol is
218      increased while the call is active. The ``-l`` option locks the object
219      by not lowering the reference count once the call completes. This is
220      useful if the call starts a thread in the object file. The reference
221      count cannot be lowered by the shell and the object file remains locked
222      in memory.
223
224      The call occurs on the stack of the shell so it is important to make
225      sure there is sufficient space available to meet the needs of the call
226      when configuring your shell.
227
228      The call blocks the shell while it is active. There is no ability to
229      background the call.
230
231      If no arguments are provided the call signature is:
232
233      .. code-block:: none
234
235        void call (void);
236
237      If no options to specify a format are provided and there are arguments
238      the call signature is the standard ``argc/argv`` call signature:
239
240      .. code-block:: none
241
242        void call (int argc, const char* argv[]);
243
244
245      The command is:
246
247      .. code-block:: none
248
249        rtl call [-lsui] name [args]
250
251      The options are:
252
253      ``-l``
254        Leave the object file the symbol resides in locked after the call
255        returns.
256
257      ``-s``
258        Concatenate the ``[args]`` into a single string and pass as a single
259        ``const char*`` argument. Quoted arguments are stripped or quotes and
260        merged into the single string. The call signature is:
261
262        .. code-block:: none
263
264          void call (const char* str);
265
266      ``-u``
267        Pass up to four unsigned integer ``[args]`` arguments. The symbol's
268        call signature can have fewer than four arguments, the unreferenced
269        arguments are ignored. The call signature is:
270
271        .. code-block:: none
272
273          void call (unsigned int u1,
274                     unsigned int u2,
275                     unsigned int u3,
276                     unsigned int u4);
277
278      ``-i``
279        Pass up to four integer ``[args]`` arguments. The symbol's call
280        signature can have fewer than four arguments, the unreferenced
281        arguments are ignored. The call signature is:
282
283        .. code-block:: none
284
285          void call (int i1, int i2, int i3, int i4);
286
287      ``name``
288        The ``name`` argument is symbol name to find and call.
289
290    .. index:: rtl trace
291    .. _rtl-trace:
292
293    ``trace``:
294      Clear or set trace flags. The trace flags provide details trace
295      information from the link editor and can aid debugging. Note, some
296      options can produce a large volume or output.
297
298      The command is:
299
300      .. code-block:: none
301
302        rtl trace [-l] [-h] [set/clear] flags...
303
304      The options are:
305
306      ``-l``
307        List the available flags that can be cleared or set.
308
309      ``-?``
310        A ``trace`` command specific help
311
312      The flags are:
313
314      - ``all``
315      - ``detail``
316      - ``warning``
317      - ``load``
318      - ``unload``
319      - ``section``
320      - ``symbol``
321      - ``reloc``
322      - ``global-sym``
323      - ``load-sect``
324      - ``allocator``
325      - ``unresolved``
326      - ``cache``
327      - ``archives``
328      - ``archive-syms``
329      - ``dependency``
330      - ``bit-alloc``
331
332EXIT STATUS:
333    This command returns 0 to indicate success else it returns 1.
334
335NOTES:
336    - Using this command may initialise the RTL manager if has not been used
337      and initialised before now.
338
339    - A base kernel image symbol file has to be present for base kernel symbols
340      to be viewed and searched.
341
342EXAMPLES:
343    The following examples can be used with the testsuite's ``dl10`` test.
344
345    Attempt to load an object file that not exist then load an object file that
346    exists:
347
348    .. code-block:: none
349
350      SHLL [/] # rtl obj load /foo.o
351      error: load: /foo.o: file not found
352      SHLL [/] $ rtl obj load /dl10-o1.o
353
354    List the object files:
355
356    .. code-block:: none
357
358      SHLL [/] # rtl list
359       /dl10-o1.o
360       /libdl10_1.a:dl10-o2.o
361       /libdl10_2.a:dl10-o5.o
362       /libdl10_2.a:dl10-o3.o
363       /libdl10_1.a:dl10-o4.o
364
365    The list shows the referenced archive object files that have been
366    loaded. Show the details for the library object file ``dl10-o2.o``:
367
368    .. code-block:: none
369
370      SHLL [/] # rtl list -l dl10-o4.o
371       /libdl10_1.a:dl10-o4.o
372        unresolved    : 0
373        users         : 0
374        references    : 1
375        symbols       : 7
376        symbol memory : 250
377
378    The object file has one reference, 7 symbols and uses 250 bytes of
379    memory. List the symbols:
380
381    .. code-block:: none
382
383      SHLL [/] # rtl list -s dl10-o4.o
384       /libdl10_1.a:dl10-o4.o
385         rtems_main_o4   = 0x20de818
386         dl04_unresolv_1 = 0x20dead0
387         dl04_unresolv_2 = 0x20dead4
388         dl04_unresolv_3 = 0x20dead8
389         dl04_unresolv_4 = 0x20deadc
390         dl04_unresolv_5 = 0x20deaa0
391         dl04_unresolv_6 = 0x20deac0
392
393    The dependents of a group of object files can be listed using a regular
394    expression:
395
396    .. code-block:: none
397
398     SHLL [/] # rtl list -d dl10-o[234].o
399      /libdl10_1.a:dl10-o2.o
400       dependencies  : dl10-o3.o
401      /libdl10_2.a:dl10-o3.o
402       dependencies  : dl10-o4.o
403                     : dl10-o5.o
404      /libdl10_1.a:dl10-o4.o
405       dependencies  : dl10-o5.o
406
407    A number of flags can be selected at once:
408
409    .. code-block:: none
410
411     SHLL [/] # rtl list -lmsd dl10-o1.o
412      /dl10-o1.o
413       exec size     : 1086
414       text base     : 0x20dbec0 (352)
415       const base    : 0x20dc028 (452)
416       data base     : 0x20dc208 (12)
417       bss base      : 0x20dc220 (266)
418       unresolved    : 0
419       users         : 1
420       references    : 0
421       symbols       : 9
422       symbol memory : 281
423         dl01_func1    = 0x20dbec0
424         rtems_main_o1 = 0x20dbec8
425         dl01_bss1     = 0x20dc220
426         dl01_bss2     = 0x20dc224
427         dl01_bss3     = 0x20dc2a0
428         dl01_data1    = 0x20dc20c
429         dl01_data2    = 0x20dc208
430         dl01_const1   = 0x20dc1e8
431         dl01_const2   = 0x20dc1e4
432       dependencies  : dl10-o2.o
433
434    List all symbols that contain ``main``:
435
436    .. code-block:: none
437
438     SHLL [/] # rtl sym main
439      /dl10-o1.o
440         rtems_main_o1 = 0x20dbec8
441      /libdl10_1.a:dl10-o2.o
442         rtems_main_o2 = 0x20dd1a0
443      /libdl10_2.a:dl10-o5.o
444         rtems_main_o5 = 0x20df280
445      /libdl10_2.a:dl10-o3.o
446         rtems_main_o3 = 0x20ddc40
447      /libdl10_1.a:dl10-o4.o
448         rtems_main_o4 = 0x20de818
449
450    Include the base kernel image in the search:
451
452    .. code-block:: none
453
454     SHLL [/] # rtl sym -b main
455      rtems-kernel
456         rtems_shell_main_cp      = 0x2015e9c
457         rtems_shell_main_loop    = 0x201c2bc
458         rtems_shell_main_monitor = 0x203f070
459         rtems_shell_main_mv      = 0x201a11c
460         rtems_shell_main_rm      = 0x201ad38
461      /dl10-o1.o
462         rtems_main_o1 = 0x20dbec8
463      /libdl10_1.a:dl10-o2.o
464         rtems_main_o2 = 0x20dd1a0
465      /libdl10_2.a:dl10-o5.o
466         rtems_main_o5 = 0x20df280
467      /libdl10_2.a:dl10-o3.o
468         rtems_main_o3 = 0x20ddc40
469      /libdl10_1.a:dl10-o4.o
470         rtems_main_o4 = 0x20de818
471
472    The filter is a regular expression:
473
474    .. code-block:: none
475
476     SHLL [/] # rtl sym -b ^rtems_task
477      rtems-kernel
478         rtems_task_create       = 0x2008934
479         rtems_task_delete       = 0x20386b8
480         rtems_task_exit         = 0x2008a98
481         rtems_task_ident        = 0x2038738
482         rtems_task_iterate      = 0x2038798
483         rtems_task_self         = 0x20387b8
484         rtems_task_set_priority = 0x20387c4
485         rtems_task_start        = 0x2008b7c
486         rtems_task_wake_after   = 0x2008bd0
487
488    The search can be limited to a selection of object files:
489
490    .. code-block:: none
491
492     SHLL [/] # rtl sym -o dl10-o[12].o dl01_b
493      /dl10-o1.o
494         dl01_bss1 = 0x20dc220
495         dl01_bss2 = 0x20dc224
496         dl01_bss3 = 0x20dc2a0
497     SHLL [/] # rtl sym -o dl10-o[12].o dl0[12]_b
498      /dl10-o1.o
499         dl01_bss1 = 0x20dc220
500         dl01_bss2 = 0x20dc224
501         dl01_bss3 = 0x20dc2a0
502      /libdl10_1.a:dl10-o2.o
503         dl02_bss1 = 0x20dd400
504         dl02_bss2 = 0x20dd404
505         dl02_bss3 = 0x20dd420
506
507    List the archives known to the link editor:
508
509    .. code-block:: none
510
511     SHLL [/] # rtl ar
512     /libdl10_1.a
513     /libdl10_2.a
514
515    A long listing of the archives provides the link editor details:
516
517    .. code-block:: none
518
519     SHLL [/] # rtl ar -l
520     /libdl10_1.a:
521       size    : 37132
522       symbols : 13
523       refs    : 0
524       flags   : 0
525     /libdl10_2.a:
526       size    : 53050
527       symbols : 8
528       refs    : 0
529       flags   : 0
530
531
532    .. index:: list archive symbols
533
534    List the symbols an archive provides using the ``-s`` option:
535
536    .. code-block:: none
537
538     SHLL [/] # rtl ar -s libdl10_1.a
539     /libdl10_1.a:
540       symbols : dl02_bss1
541            dl02_bss2
542            dl02_bss3
543            dl02_data1
544            dl02_data2
545            dl04_unresolv_1
546            dl04_unresolv_2
547            dl04_unresolv_3
548            dl04_unresolv_4
549            dl04_unresolv_5
550            dl04_unresolv_6
551            rtems_main_o2
552            rtems_main_o4
553
554    .. index:: duplicate symbols
555
556    List the duplicate symbols in the archives using the ``-d`` option:
557
558    .. code-block:: none
559
560     SHLL [/] # rtl ar -d
561     /libdl10_1.a:
562       dups    :
563     /libdl10_2.a:
564       dups    : rtems_main_o5 (/libdl10_2.a)
565
566    The link editor will list the first archive if finds that has the duplicate
567    symbol.
568
569    Call the symbol ``rtems_main_o4`` with no options:
570
571    .. code-block:: none
572
573     SHLL [/] # rtl call rtems_main_o4
574     dlo4: module: testsuites/libtests/dl10/dl-o4.c
575     dlo4:   dl04_unresolv_1:    4: 0x20dee68: 0
576     dlo4:   dl04_unresolv_2:    4: 0x20dee6c: %f
577     dlo4:   dl04_unresolv_3:    1: 0x20dee70: 00
578     dlo4:   dl04_unresolv_4:    4: 0x20dee74: 0
579     dlo4:   dl04_unresolv_5:    4: 0x20dee38: 4
580     dlo4:   dl04_unresolv_6:    4: 0x20dee58: dl-O4
581     dlo5: module: testsuites/libtests/dl10/dl-o5.c
582     dlo5:   dl05_unresolv_1:    8: 0x20df860: 0
583     dlo5:   dl05_unresolv_2:    2: 0x20df868: 0
584     dlo5:   dl05_unresolv_3:    4: 0x20df86c: 0
585     dlo5:   dl05_unresolv_4:    1: 0x20df870: 0
586     dlo5:   dl05_unresolv_5:    8: 0x20df878: 0
587
588    Call a symbol in a data section of an object file:
589
590    .. code-block:: none
591
592     SHLL [/] # rtl call dl04_unresolv_3
593     error: symbol not in obj text: dl04_unresolv_3
594
595    Call the symbol ``rtems_main_o5`` with a single string:
596
597    .. code-block:: none
598
599     SHLL [/] # rtl call -s rtems_main_o5 arg1 arg2 "arg3 and still arg3" arg4
600     dlo5: module: testsuites/libtests/dl10/dl-o5.c
601     dlo5:   dl05_unresolv_1:    8: 0x20df860: 0
602     dlo5:   dl05_unresolv_2:    2: 0x20df868: 0
603     dlo5:   dl05_unresolv_3:    4: 0x20df86c: 0
604     dlo5:   dl05_unresolv_4:    1: 0x20df870: 0
605     dlo5:   dl05_unresolv_5:    8: 0x20df878: 0
606
607    Note, the call does not have any argument and the strin passed is
608    ignored.
609
610    Call the symbol ``rtems_main_o5`` with three integer arguments:
611
612    .. code-block:: none
613
614     SHLL [/] # rtl call -i rtems_main_o5 1 22 333
615     dlo5: module: testsuites/libtests/dl10/dl-o5.c
616     dlo5:   dl05_unresolv_1:    8: 0x20df860: 0
617     dlo5:   dl05_unresolv_2:    2: 0x20df868: 0
618     dlo5:   dl05_unresolv_3:    4: 0x20df86c: 0
619     dlo5:   dl05_unresolv_4:    1: 0x20df870: 0
620     dlo5:   dl05_unresolv_5:    8: 0x20df878: 0
621
622.. index:: rtems_rtl_shell_command
623
624CONFIGURATION:
625    This command is not included in the default shell command set. The command
626    needs to be added with the shell's ``rtems_shell_add_cmd``.
627
628    .. code-block:: c
629
630       #include <rtems/rtl/rtl-shell.h>
631       #include <rtems/shell.h>
632
633       rtems_shell_init_environment ();
634
635       if (rtems_shell_add_cmd ("rtl",
636                                "rtl",
637                                "rtl -?",
638                                rtems_rtl_shell_command) == NULL)
639         printf("error: command add failed\n");
640
641PROGRAMMING INFORMATION:
642    The ``rtl`` commanf is implemented by a C language function which has the
643    following prototype:
644
645    .. code-block:: c
646
647        int rtems_rtl_shell_command(
648            int    argc,
649            char **argv
650        );
651
652    The sub-command parts of the ``rtl`` command can be called directly. These
653    calls all use the RTEMS Printer interface and as a result can be redirected
654    and captured.
655
656    .. index:: rtems_rtl_shell_list
657    ``list``
658      The RTL list command.
659
660      .. code-block:: c
661
662         #include <rtems/rtl/rtl-shell.h>
663
664         int rtems_rtl_shell_list (
665             const rtems_printer* printer,
666             int                  argc,
667             char*                argv[]
668         );
669
670    .. index:: rtems_rtl_shell_object
671    ``sym``
672      The RTL symbol command.
673
674      .. code-block:: c
675
676         #include <rtems/rtl/rtl-shell.h>
677
678         int rtems_rtl_shell_sym (
679             const rtems_printer* printer,
680             int                  argc,
681             char*                argv[]
682         );
683
684    .. index:: rtems_rtl_shell_object
685    ``sym``
686      The RTL object command.
687
688      .. code-block:: c
689
690         #include <rtems/rtl/rtl-shell.h>
691
692         int rtems_rtl_shell_object (
693             const rtems_printer* printer,
694             int                  argc,
695             char*                argv[]
696         );
697
698    .. index:: rtems_rtl_shell_archive
699    ``ar``
700      The RTL object command.
701
702      .. code-block:: c
703
704         #include <rtems/rtl/rtl-archive.h>
705
706         int rtems_rtl_shell_archive (
707             const rtems_printer* printer,
708             int                  argc,
709             char*                argv[]
710         );
711
712    .. index:: rtems_rtl_shell_call
713    ``call``
714      The RTL object command.
715
716      .. code-block:: c
717
718         #include <rtems/rtl/rtl-archive.h>
719
720         int rtems_rtl_shell_call (
721             const rtems_printer* printer,
722             int                  argc,
723             char*                argv[]
724         );
Note: See TracBrowser for help on using the repository browser.