Changes between Version 10 and Version 11 of Developer/Tracing/Trace_Linker


Ignore:
Timestamp:
Mar 24, 2015, 12:37:04 AM (5 years ago)
Author:
Chris Johns
Comment:

Update.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Tracing/Trace_Linker

    v10 v11  
    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 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.
     7The RTEMS Trace Linker is a post link tool that performs a re-link of your application to produce a ''trace executable''. A ''trace executable'' has been instrumented by the RTEMS Trace Linker with additional code that implements software tracing. A key requirement of the trace process in RTEMS is to take existing code in a compiled format (ELF) and instrument it without rebuilding that code from source and without annotating that source 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.
     8
     9The RTEMS Trace Linker is controlled using configuration files in a flexible way and can be configured to implement a number of tracing schemes.
    810
    911The [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.
     
    3133 -W wrapper  : wrapper file name without ext (also --wrapper)
    3234 -C ini      : user configuration INI file (also --config)
     35 -P path     : user configuration INI file search path (also --path)
    3336}}}
    3437
    3538There 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.
    3639
    37 The 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 
    39 The 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 If you are working with new configuration files and you want to view the files the trace linker generates add the `-k` option to keep the temporary files, and `-W` to specify an explicit wrapper C file name.
     40The trace linker generates 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. If the functions you are tracing use types from you code add the include path to the `CFLAGS`.
     41
     42The trace linker requires you provide a configuration file using the `-C` or `--config`  option. This is an INI format file detailed in the Configuration section. You can also provide an INI file search path using the `-P` option.
     43
     44If you are working with new configuration files and you want to view the files the trace linker generates add the `-k` option to keep the temporary files, and `-W` to specify an explicit wrapper C file name. If you set the `dump-on-error` option in the configuration `options` section you will get a dump of the configuration on an error.
    4245
    4346== Wrapping ==
    4447
    45 The 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:
    46 
    47   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.
     48The 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. The trace is provided by the `generator` configuration. The wrapping function uses a GNU linker option called `--wrap=symbol`. The GNU Ld manual states:
     49
     50  ''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.''
    4851
    4952The 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.
     
    5558== Configuration ==
    5659
    57 The 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.
     60The 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 trace executable that meets their needs.
     61
     62There are 3 types of configurations:
     63
     641. User configurations. These are specific to an application and are typically kept with the application.
     651. Tracer configurations. These are like a library of common or base trace functions that can be referenced by an application. These files tend to hold the details needed to wrap a specific set of functions. Examples provided with the RTEMS Linker are the RTEMS API and Libc.
     661. Generator configurations. These encapsulate a specific method of tracing. The RTEMS Linker provides ''buffer tracer'', ''printk'' and ''printf'' generators.
     67
     68The break down into these types of files promotes reuse. You could combine all the files into a single configuration file.
    5869
    5970=== INI Files ===
    6071
    61 [http://en.wikipedia.org/wiki/INI_file INI files format] consist of sections with a section name that groups keys A key has a name and value used as `name=value`. An example format is:
     72[http://en.wikipedia.org/wiki/INI_file INI file format] consists of ''sections'' with a ''section name'' that groups ''keys''. A key has a ''name'' and ''value'' used as `name=value`. An example format is:
    6273
    6374{{{
     
    7586}}}
    7687
    77 The trace linker also uses values in key to specify other sections. In this example the `functions` name lists `test-trace-funcs` and that section a `headers` key that references a further section `test-headers`:
     88The trace linker also uses values in keys to specify other sections. In this example the `functions` name lists `test-trace-funcs` and that section contains a `headers` key that references a further section `test-headers`:
    7889
    7990{{{
     
    91102The ability to include INI files and have key lists reference sections lets the trace linker provide base functionality a user can specialise.
    92103
    93 === Tracer Section ===
     104== Tracer Section ==
    94105
    95106The top level section is `[tracer]`. The tracer section can contain the following keys:
    96107
    97  name:: A user defined name for the trace.
    98  bsp:: The BSP as an RTEMS standard `arch/bsp` pair. Currently not used.
    99  options:: Various trace linker defined options. Currently not used.
    100  traces:: List of trace sections. A trace section defines how functions are to be instrumented.
    101  functions:: List function sections. Function sections list the functions to be instrumented.
     108  name:: The name of trace being linked.
     109  options:: A list of option sections.
     110  defines:: A list of sections containing defines or define record.
     111  define:: A list of define string that are single or double quoted.
     112  enables:: The list of sections containing enabled functions to trace.
     113  triggers:: The list of sections containing enabled functions to trigger trace on.
     114  traces:: The list of sections containing function lists to trace.
     115  functions:: The list of sections containing function details.
     116  include:: The list of files to include.
     117
     118=== Options ===
     119
     120The following options are available:
     121
     122  dump-on-error:: Dump the parsed configuration data on error. The value can be `true` or `false`.
     123  verbose:: Set the ''verbose'' level. The value can be `true` or a number value.
     124  prefix:: The prefix for the tools and an install RTEMS if `rtems-path` is not set.
     125  cc:: The compiler used to compile the generated wrapper code. Overrides the BSP configuration value if a BSP is specified.
     126  ld:: The linker used to link the application. The default is the `cc` value as read from the BSP configuration if specificed. If your application contains C++ code use this setting to the change the linker to `g++`.
     127  cflags:: Set the `CFLAGS` used to compiler the wrapper. These flags are pre-pended to the BSP read flags if a BSP is specified. This option is used to provide extra include paths to header files in your application that contain ''types'' any functions being traced reference.
     128  rtems-path:: The path to an install RTEMS if not installed under the `prefix`.
     129  rtems-bsp:: The BSP we are building the trace executable for. The is an `arch` and `bsp` pair. For example `arm/xilinx_zynq_zc706`.
    102130
    103131An example tracer section is:
     
    122150; Options can be defined here or on the command line.
    123151;
    124 options = all-funcs, verbose
     152options = test-options
    125153;
    126154; Functions to trace.
     
    136164;
    137165include = rtems.ini, rtld-base.ini
     166
     167[test-options]
     168verbose = true
     169prefix = /opt/rtems/4.11
    138170}}}
    139171
     
    186218A trace section can reference other trace sections of a specific type. This allows a trace sections to build on other trace sections.
    187219
    188 Function signatures are specified with the function being the key's name and the key's value being the return value and a list of function arguments.
     220=== Function Sections ===
     221
     222Function sections define functions that can be traced. The provide any required defines, header files, and the function signatures. Defining a function so it can be traced does not mean it is traced. The function has to be added to a `trace` list to be traced.
     223
     224  headers:: A list of sections containing headers or header records.
     225  header:: A list of include string that are single or double quoted.
     226  defines:: A list of sections containing defines or define record.
     227  defines:: A list of define string that are single or double quoted.
     228  signatures:: A list of section names of signatures.
     229  includes:: A list of files to include.
     230
     231Function `signatures` are specified with the function name being the key's name and the key's value being the return value and a list of function arguments. You need to provide `void` if the function uses `void`. Variable argument list are currently not supported. There is no way to determine statically a variable argument list.
    189232
    190233=== Generators ===
    191234
    192 Generators sections specify how to generate trace wrapping code. The section's name specifies the generator and can be listed in a `generator` key in a `tracer` or `trace` section.
     235Generators sections specify how to generate trace wrapping code. The trace linker and generator section must match to work. The trace linker expects a some things to be present when wrapping functions. The section's name specifies the generator and can be listed in a `generator` key in a `tracer` or `trace` section.
    193236
    194237A generator specifies the code generated when:
    195238
    196 * Entering a trace function (`entry-trace`)
    197 * Entry argument of a trace function (`arg-trace`), called once per argument
    198 * Return value of a trace function (`ret-trace`), called if not `void`.
    199 * Exit value of a trace function (`exit-trace`)
    200 
     239  headers:: A list of sections containing headers or header records.
     240  header:: A list of include string that are single or double quoted.
     241   defines:: A list of sections containing defines or define record.
     242  define:: A list of define string that are single or double quoted.
     243  entry-trace:: The wrapper call made on a function's entry.  Returns `bool where `true` is the function is being traced. This call is made  without the lock being held if a lock is defined.
     244  arg-trace:: The wrapper call made for each argument to the trace function if the function is being traced. This call is made without the lock being held if a lock is defined.
     245  exit-trace:: The wrapper call made after a function's exit. Returns `bool where `true` is the function is being traced. This call is made without the lock being held if a lock is defined.
     246  ret-trace:: The wrapper call made to log the return value if the function is being traced. This call is made without the lock being held if a lock is defined.
     247  lock:: The name of an RTEMS `rtems_interrupt_lock` variable.
     248  buffer-alloc:: The wrapper call made with a lock held if defined to allocate buffer space to hold the trace data. A suitable 32bit buffer index is returned. If there is no space an invalid index is returned. The generator must handle any overhead space needed. the generator needs to make sure the space is available before making the alloc all.
     249  code-blocks:: A list of code block section names.
     250  code:: A code block in `<<CODE ... CODE` (without the single quote).
     251  includes:: A list of files to include.
     252
     253The `entry-trace` and `exit-trace` can be transformed using the following macros:
     254
     255  @FUNC_NAME@:: The trace function name as a quote C string.
     256  @FUNC_INDEX@:: The trace function index as a held in the sorted list of trace functions by teh trace linker. It can be used to index the `names`, `enables` and `triggers` data.
     257  @FUNC_LABEL@:: The trace function name as a C label that can be referenced. You can take the address of the label.
     258
     259The `arg-trace` can be transformed using the following macros:
     260
     261  @ARG_NUM@:: The argument number to the trace function.
     262  @ARG_TYPE@:: The type of the argument as a C string.
     263  @ARG_SIZE@:: The size of the type of the argument in bytes.
     264  @ARG_LABEL@:: The argument as a C label that can be referenced.
     265
     266The `ret-trace` can be transformed using the following macros:
     267
     268  @RET_TYPE@:: The type of the return value as a C string.
     269  @RET_SIZE@ :: The size of the type of the return value in bytes.
     270  @RET_LABEL@:: The return value as a C label that can be referenced.
     271 
    201272The the generator is not interested in a specific phase it does not need to define and nothing will be generated. For example code to profile specific function may only provide the `entry-trace` and `exit-trace` code where a nano-second time stamp is taken.
    202 
    203 The section supports:
    204 
    205  headers:: List of header sections.
    206  header:: A header key. Typically the include code.
    207  entry-trace: The code or call made on entry to a function.
    208  arg-trace:: The code or call made for each argument to a function.
    209  ret-trace:: The code or call made with the return value if not `void`.
    210  exit-trace:: The code or call made after the trace function has exited.
    211  code:: Code to be added into the trace file. The code is tagged between `<<<CODE` and `CODE` markers.
    212273
    213274An example generator section is:
     
    259320}}}
    260321
    261 The generator code can use a number of token's that are expanded when generating trace functions. They are:
    262 
    263  @FUNC_NAME@:: The name of the function being wrapped.
    264  @FUNC_LABEL@:: The C label of the function being wrapped. You can take the address of this label.
    265  @ARG_NUM@:: The argument number bring processed.
    266  @ARG_TYPE@:: The type of the argument.
    267  @ARG_SIZE@::  The size of the argument in bytes.
    268  @ARG_LABEL@:: The C label of the argument. You can take the address of this label.
    269  @RET_TYPE@:: The type of the return value.
    270  @RET_SIZE@:: The size of the return value in bytes.
    271  @RET_LABEL@:: The C label of the return value as held in the wrapping code.
    272 
    273322== Limitation ==
    274323