[9ec0107] | 1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
| 2 | |
---|
| 3 | .. Copyright (C) 2019 Chris Johns <chrisj@rtems.org> |
---|
| 4 | |
---|
| 5 | Dynamic Loader |
---|
| 6 | ************** |
---|
| 7 | |
---|
| 8 | Introduction |
---|
| 9 | ============ |
---|
| 10 | |
---|
| 11 | The RTEMS shell has the following dynamic loader commands: |
---|
| 12 | |
---|
| 13 | - rtl_ - Manage the Run-Time Loader (RTL) |
---|
| 14 | |
---|
| 15 | Commands |
---|
| 16 | ======== |
---|
| 17 | |
---|
| 18 | This section details the Dynamic Loader Commands available. A subsection is |
---|
| 19 | dedicated to each of the commands and describes the behavior and configuration |
---|
| 20 | of that command as well as providing an example usage. |
---|
| 21 | |
---|
| 22 | .. raw:: latex |
---|
| 23 | |
---|
| 24 | \clearpage |
---|
| 25 | |
---|
| 26 | .. _rtl: |
---|
| 27 | |
---|
| 28 | rtl - Manager the RTL |
---|
| 29 | --------------------- |
---|
| 30 | .. index:: rtl |
---|
| 31 | |
---|
| 32 | SYNOPSYS: |
---|
| 33 | .. code-block:: none |
---|
| 34 | |
---|
| 35 | rtl [-l] -[h] command [...] |
---|
| 36 | |
---|
| 37 | DESCRIPTION: |
---|
| 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 | |
---|
| 332 | EXIT STATUS: |
---|
| 333 | This command returns 0 to indicate success else it returns 1. |
---|
| 334 | |
---|
| 335 | NOTES: |
---|
| 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 | |
---|
| 342 | EXAMPLES: |
---|
| 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 | |
---|
| 624 | CONFIGURATION: |
---|
| 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 | |
---|
| 641 | PROGRAMMING 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 | ); |
---|