Changes between Version 5 and Version 6 of Developer/Tracing/Trace_Linker


Ignore:
Timestamp:
Mar 16, 2015, 1:29:26 AM (5 years ago)
Author:
Chris Johns
Comment:

Update.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Tracing/Trace_Linker

    v5 v6  
    3838
    3939The 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== Wrapping ==
     42
     43The 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:
     44
     45  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.
     46
     47The 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.
    4048
    4149== Configuration ==
     
    8492 functions:: List function sections. Function sections list the functions to be instrumented.
    8593
     94An example tracer section is:
     95
     96{{{
     97;
     98; RTEMS Trace Linker Test Configuration.
     99;
     100; We must provide a top level trace section.
     101;                                                                                                                                                                                                                                                                                                                         
     102[tracer]
     103;
     104; Name of the trace.
     105;
     106name = RTEMS Trace Linker Test
     107;
     108; The BSP.
     109;
     110bsp = sparc/sis
     111;
     112; Options can be defined here or on the command line.
     113;
     114options = all-funcs, verbose
     115;
     116; Functions to trace.
     117;
     118traces = test-trace, test-trace-funcs, rtems-api-task
     119;
     120; Define the function sets. These are the function's that can be
     121; added to the trace lists.
     122;
     123functions = test-trace-funcs, rtems-api
     124;
     125; Include RTEMS Trace support.
     126;
     127include = rtems.ini, rtld-base.ini
     128}}}
     129
    86130=== Trace Section ===
    87131
    88 A trace section defines how trace wrapper functions are built.
     132A trace section defines how trace wrapper functions are built. To build a trace function that wraps an existing function in an ELF object file or library archive we need to have the function's ''signature''. A ''signature'' is the function's declaration with any ''types'' used. The the signature has specific types we need access to those types which means the wrapper code needs to include header files that define those types. There may also be specific defines needed to access those types.
    89133
    90 == Wrapping ==
     134 generator:: The generator defines the type of tracing being used.
     135 headers:: List of sections that contain header files keys.
     136 header:: A header key. Typically the include code.
     137 defines:: List of sections that contain defines.
     138 define:: A define key. Typically the define code.
     139 signatures:: List of function signature sections.
     140 trace:: Functions that are instrumented with trace code.
    91141
    92 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:
     142An example trace section is:
    93143
    94   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.
     144{{{
     145;
     146; User application trace example.
     147;
     148[test-trace]
     149generator = printf-generator
     150; Just here for testing.                                                                                                                                                                                                                                                                                                 
     151trace = test_trace_3
    95152
    96 The 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.
     153[test-trace-funcs]
     154; Parsed via the 'function-set', not parse as a 'trace'.                                                                                                                                                                                                                                                                 
     155headers = test-headers
     156header = '#include "test-trace-2.h"'
     157defines = test-defines
     158define = "#define TEST_TRACE_2 2"
     159signatures = test-signatures
     160; Parsed via the 'trace', not parsed as a function-set                                                                                                                                                                                                                                                                   
     161trace = test_trace_1, test_trace_2
     162
     163[test-headers]
     164header = '#include "test-trace-1.h"'
     165
     166[test-defines]
     167define = "#define TEST_TRACE_1 1"
     168
     169[test-signatures]
     170test_trace_1 = void, int
     171test_trace_2 = test_type_2, test_type_1
     172test_trace_3 = float, float*
     173}}}
     174
     175A trace section can reference other trace sections of a specific type. This allows a trace sections to build on other trace sections.
     176
     177Function signatures are specified with the function being the key's name and they key's value is return value and a list of function arguments.
     178
     179=== Generators ===
     180
     181Generators sections specify how to generate trace wrapping code.