Changes between Version 13 and Version 14 of Developer/Tracing/Trace_Linker


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

Update the generator documentation.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Tracing/Trace_Linker

    v13 v14  
    235235Generators 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. If the generator is not interested in a specific phase it does not need do not define it and nothing will be generated. For example code to profile specific functions may only provide the `entry-trace` and `exit-trace` code where a nano-second time stamp is taken.
    236236
    237 A generator specifies the code generated when:
     237The generate code will create an entry and exit calls and the generator code block can be used to allocate buffer space for each with the lock held. The entry call and argument copy is performed with the lock released. The buffer space having been allocated will cause the trace events to be in order. The same goes for the exit call. Space is allocated in separate buffer allocate calls so the blocking calls will have the exit event appear in the correct location in the buffer.
     238
     239A generator specifies the code generated:
    238240
    239241  headers:: A list of sections containing headers or header records.
    240242  header:: A list of include string that are single or double quoted.
    241    defines:: A list of sections containing defines or define record.
     243  defines:: A list of sections containing defines or define record.
    242244  define:: A list of define string that are single or double quoted.
    243245  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.
     
    245247  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.
    246248  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.
     249  lock-local:: The wrapper code to declare a local lock variable.
     250  lock-acquire:: The wrapper code to acquire the lock.
     251  lock-release:: The wrapper code to release the lock.
     252  buffer-local:: The wrapper code to declare a buffer index local variable.
    248253  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.
    249254  code-blocks:: A list of code block section names.
     
    251256  includes:: A list of files to include.
    252257
    253 The `entry-trace` and `exit-trace` can be transformed using the following macros:
     258The following macros can be used in specific wrapper calls. The lists of where you can use them is listed before. The macros are:
    254259
    255260  @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.
     261  @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.
    257262  @FUNC_LABEL@:: The trace function name as a C label that can be referenced. You can take the address of the label.
    258 
    259 The `arg-trace` can be transformed using the following macros:
    260 
     263  @FUNC_DATA_SIZE@:: The size of the data in bytes.
     264  @FUNC_DATA_ENTRY_SIZE@:: The size of the entry data in bytes.
     265  @FUNC_DATA_RET_SIZE@:: The size of the return data in bytes.
    261266  @ARG_NUM@:: The argument number to the trace function.
    262267  @ARG_TYPE@:: The type of the argument as a C string.
    263268  @ARG_SIZE@:: The size of the type of the argument in bytes.
    264269  @ARG_LABEL@:: The argument as a C label that can be referenced.
     270  @RET_TYPE@:: The type of the return value as a C string.
     271  @RET_SIZE@:: The size of the type of the return value in bytes.
     272  @RET_LABEL@:: The return value as a C label that can be referenced.
     273
     274The `buffer-alloc`, `entry-trace` and `exit-trace` can be transformed using  the following  macros:
     275
     276  * '''@FUNC_NAME@'''
     277  * '''@FUNC_INDEX@'''
     278  * '''@FUNC_LABEL@'''
     279  * '''@FUNC_DATA_SZIE@'''
     280  * '''@FUNC_DATA_ENTRY_SZIE@'''
     281  * '''@FUNC_DATA_EXIT_SZIE@'''
     282
     283The `arg-trace` can be transformed using the following macros:
     284
     285  * '''@ARG_NUM@'''
     286  * '''@ARG_TYPE@'''
     287  * '''@ARG_SIZE@'''
     288  * '''@ARG_LABEL@'''
    265289
    266290The `ret-trace` can be transformed using the following macros:
    267291
    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  
     292   * '''@RET_TYPE@'''
     293   * '''@RET_SIZE@'''
     294   * '''@RET_LABEL@'''
     295
    272296An example generator section is:
    273297