| 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. |
| | 40 | The 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 | |
| | 42 | The 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 | |
| | 44 | 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. If you set the `dump-on-error` option in the configuration `options` section you will get a dump of the configuration on an error. |
| 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. |
| | 60 | 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 trace executable that meets their needs. |
| | 61 | |
| | 62 | There are 3 types of configurations: |
| | 63 | |
| | 64 | 1. User configurations. These are specific to an application and are typically kept with the application. |
| | 65 | 1. 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. |
| | 66 | 1. Generator configurations. These encapsulate a specific method of tracing. The RTEMS Linker provides ''buffer tracer'', ''printk'' and ''printf'' generators. |
| | 67 | |
| | 68 | The break down into these types of files promotes reuse. You could combine all the files into a single configuration file. |
| 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 | |
| | 120 | The 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`. |
| 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 | |
| | 222 | Function 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 | |
| | 231 | Function `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. |
| 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 | |
| | 253 | The `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 | |
| | 259 | The `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 | |
| | 266 | The `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 | |
| 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 | | |
![[RTEMS Logo]](/images/logo.png){kind=logo}
