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

Timestamp:

03/16/15 01:29:26 (9 years ago)

Author:

Chris Johns

Comment:

Update.

Developer/Tracing/Trace_Linker

@@ -38 +38 @@
 
 The trace linker requires you provide a configuration file using the `-C` or `--config`  option. This is an INI detailed in the Configuration section.
+
+== Wrapping ==
+
+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:
+
+  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.
+
+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.
 
 == Configuration ==
@@ -84 +92 @@
  functions:: List function sections. Function sections list the functions to be instrumented.
 
+An example tracer section is:
+
+{{{
+;
+; RTEMS Trace Linker Test Configuration.
+;
+; We must provide a top level trace section.
+;                                                                                                                                                                                                                                                                                                                         
+[tracer]
+;
+; Name of the trace.
+;
+name = RTEMS Trace Linker Test
+;
+; The BSP.
+;
+bsp = sparc/sis
+;
+; Options can be defined here or on the command line.
+;
+options = all-funcs, verbose
+;
+; Functions to trace.
+;
+traces = test-trace, test-trace-funcs, rtems-api-task
+;
+; Define the function sets. These are the function's that can be
+; added to the trace lists.
+;
+functions = test-trace-funcs, rtems-api
+;
+; Include RTEMS Trace support.
+;
+include = rtems.ini, rtld-base.ini
+}}}
+
 === Trace Section ===
 
-A trace section defines how trace wrapper functions are built.
+A 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.
 
-== Wrapping ==
+ generator:: The generator defines the type of tracing being used.
+ headers:: List of sections that contain header files keys.
+ header:: A header key. Typically the include code.
+ defines:: List of sections that contain defines.
+ define:: A define key. Typically the define code.
+ signatures:: List of function signature sections.
+ trace:: Functions that are instrumented with trace code.
 
-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:
+An example trace section is:
 
-  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.
+{{{
+;
+; User application trace example.
+;
+[test-trace]
+generator = printf-generator
+; Just here for testing.                                                                                                                                                                                                                                                                                                  
+trace = test_trace_3
 
-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.
+[test-trace-funcs]
+; Parsed via the 'function-set', not parse as a 'trace'.                                                                                                                                                                                                                                                                  
+headers = test-headers
+header = '#include "test-trace-2.h"'
+defines = test-defines
+define = "#define TEST_TRACE_2 2"
+signatures = test-signatures
+; Parsed via the 'trace', not parsed as a function-set                                                                                                                                                                                                                                                                    
+trace = test_trace_1, test_trace_2
+
+[test-headers]
+header = '#include "test-trace-1.h"'
+
+[test-defines]
+define = "#define TEST_TRACE_1 1"
+
+[test-signatures]
+test_trace_1 = void, int
+test_trace_2 = test_type_2, test_type_1
+test_trace_3 = float, float*
+}}}
+
+A trace section can reference other trace sections of a specific type. This allows a trace sections to build on other trace sections.
+
+Function 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.
+
+=== Generators ===
+
+Generators sections specify how to generate trace wrapping code.