Changes between Version 3 and Version 4 of Developer/Tracing/Trace_Linker


Ignore:
Timestamp:
Mar 15, 2015, 11:09:25 PM (4 years ago)
Author:
Chris Johns
Comment:

Update.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Tracing/Trace_Linker

    v3 v4  
    55The RTEMS Trace Linker is a tool that is part of the [wiki:Developer/Tools RTEMS Tool Project] and is central in the [wiki:Developer/Tracing RTEMS Tracing] framework.
    66
    7 The RTEMS Trace Linker is a post link tool that performs a link which produces a trace executable. A trace executable has been instrumented with addition code that provides software tracing capabilities.
     7The RTEMS Trace Linker is a post link tool that performs a link which produces a trace executable. A trace executable has been instrumented with additional code that provides software tracing capabilities. A key requirement of the trace process in RTEMS is to take existing code in a compiled format and to instrument it without rebuilding that code from source annotating it with trace code. The code being trace may be from a 3rd party or already certified or in the process of being certified and the trace testing is part of that process.
    88
     9The [wiki:Developer/Tools/RSB RTEMS Source Builder] builds and installs the [wiki:Developer/Tools RTEMS Tools] package so the RTEMS Trace Linker is available for you to use.
     10
     11== Command Line ==
     12
     13The current command line for the trace linker is:
     14
     15{{{
     16$ rtems-tld -h
     17rtems-trace-ld [options] objects
     18Options and arguments:
     19 -h          : help (also --help)
     20 -V          : print linker version number and exit (also --version)
     21 -v          : verbose (trace import parts), can supply multiple times
     22               to increase verbosity (also --verbose)
     23 -w          : generate warnings (also --warn)
     24 -k          : keep temporary files (also --keep)
     25 -c compiler : target compiler is not standard (also --compiler)
     26 -l linker   : target linker is not standard (also --linker)
     27 -E prefix   : the RTEMS tool prefix (also --exec-prefix)
     28 -f cflags   : C compiler flags (also --cflags)
     29 -r path     : RTEMS path (also --rtems)
     30 -B bsp      : RTEMS arch/bsp (also --rtems-bsp)
     31 -W wrapper  : wrapper file name without ext (also --wrapper)
     32 -C ini      : user configuration INI file (also --config)
     33}}}
     34
     35There are two parts to the command line passed to the trace linker. The first part controls the trace linker and provides the various options it needs and the second part is a standard linker command line you would use to link an RTEMS application. The first and second parts are separated by `--` the command line option escape sequence.
     36
     37The trace linker generate code that needs to be compiled and linked your standard executable so it needs to know the target compiler and `CFLAGS`. There are a couple of ways to do this. The simplest is to provide the path to RTEMS using the `-r` option and the architecture and BSP name in the standard RTEMS format of `arch/bsp`. The trace linker will extract the compiler and flags used to build RTEMS and will use them. If you require specific options you can use the `-f`, `-c`, `-l` and `-E` options to provide them.
     38
     39The trace linker requires you provide a configuration file using the `-C` or `--config`  option. This is an INI detailed in the Configuration section.
     40
     41== Configuration ==
     42
     43The trace linker uses the INI file format for configuration files. Users provide a top level configuration that defines the trace executable created.  The trace linker comes with a number of standard configurations that provide a range of functionality. A user can use those configurations or they can define a completely new set and produce a localised specific form or trace executable.
     44
     45== Wrapping ==
     46
     47The trace linker's main role is to wrap functions in the existing executable with trace code. The trace linker executable does not know about the trace code added. That is provided by the `generator` configuration. The wrapping function uses a GNU linker option called `--wrap=symbol`. The GNU Ld manual states:
     48
     49  Use a wrapper function for symbol. Any undefined reference to symbol will be resolved to !__wrap_symbol. Any undefined reference to !__real_symbol will be resolved to symbol.
     50
     51The trace linker generates C code with a wrapper for each function to be instrumented. The trace code generated is driven by the configuration INI files.