Version 38 (modified by Cocanlucian, on Aug 10, 2009 at 5:47:55 PM) (diff)

/* Compile mode */

RTEMS Trace Tool

RTEMS Trace Tool - trace your application in RTEMS

The RTEMS trace tool it's a tool that allows users to integrate tracing into their applications. TBD



Command line interface

The RTEMS Trace Tool can currently work in 4 modes:= Generate mode =

Usage: ./ -m generate -g path to where the wrapping code should be saved

./ --mode=generate --genpath=path to where the wrapping code should be saved

Using this mode the user will generate the wrapping code, which is a set of files corresponding to the functions that he specified in the configuration file. If the --mode option it's not specified then the default mode chosen by the tool will be generate. So if the user wants to generate and save the wrapping code in a directory named wrappers from the current working directory (cwd) which is the default path, then he can simply do this:


Compile mode

Usage: ./ -m compile -i name of the compiler -g path to the wrapping code

-o path to where the compiled wrapping code should be saved -l path to where the RTEMS libraries were installed

./ --mode=compile --compiler=name of the compiler

--genpath=path to the wrapping code --objpath=path to where the compiled wrapping code should be saved

Using this mode the user can compile all the .c files from a directory (usually the .c files from the wrapping code directory) and save the resulted files (.o files) in the directory specified by the -o option. If the -g and -o options are not specified then the rtems_trace tool will look in the wrappers directory located in cwd and save the .o files in a directory named objects also from cwd. Also, if the -l option it's not specified than the tool will choose this path by default: /opt/rtems-4.10/i386-rtems4.10/pc386/lib/. Example:

./ --mode=compile --compiler=i386-rtems4.10-gcc

will compile all the .c files from the cwd/wrappers using the gcc compiler for the i386 BSP and the 4.10 rtems version. The .o files will be saved in cwd/objects.

Link mode

Decode mode

Configuration files

There can be two types of configuration files: the main configuration file, where the user specifies the functions that he wants to trace and the API configuration file. Both of these two types of configuration files are presented in the next subsections.

Main configuration file – default: rtems-trace.cfg

In order for the rtems-trace tool to function correctly the user must provide a configuration file which should have the following format and include the following sections:

  1. include "path_to_an_API_config_file"

This section specifies paths to other configuration files (called API configuration files) which contain information that is needed for the encoding of data and generation of ID's (functions ID, manager ID, API id etc). The section “API configuration files” explains what these configuration files should contain. Check this for an example.

  1. rtems-functions: list of comma separated function names

This section should contain a list of comma separated function names that the user wants to trace. Check this for an example.

  1. rtems-managers: list of comma separated manager names

This section should contain a list of comma separated manager names. The manager names should be specified like this: API_name-manager_name. This is to help the user to specify more easily hole sets of functions. Example: If the user wants to trace all the functions from the task manager from the Classic API then he could do this:

rtems-managers: classic-task

Rather than doing this:

rtems-functions: rtems_task_create, rtems_task_ident

rtems_task_self, rtems_task_start rtems_task_restart, rtems_task_delete rtems_task_suspend, rtems_task_resume rtems_task_is_suspended, rtems_task_set_priority rtems_task_mode, rtems_task_get_note rtems_task_set_note, rtems_task_wake_after rtems_task_wake_when, rtems_iterate_over_all_threads rtems_task_variable_add, rtems_task_variable_get rtems_task_variable_delete

  1. rtems-libraries: list of comma separated library names

This section should contain a list of comma separated library names. Check this for an example.

  1. rtems-symbols-path: path to the folder containing the symbols files

This section should contain a valid path to a directory containing the symbols files. The symbols files (functions.sym, structs.sym, typedefs.sym, unions.sym) contain information, as their name suggest, about functions signature, struct, typedef and union definition. These files are specific to a library and should be found in a directory that has the same name as the library from which the files resulted.

Below is a sample configuration file.

# This is a comment. # Sample configuration file # Include section include "rtems_trace_classic.cfg" include "rtems_trace_posix.cfg" <BR> # The user can specify just some functions specific to an API to trace # or a hole set of functions specific to a manager from an API. # Specify some functions. rtems-functions: rtems_task_create, rtems_task_delete <BR> # Specify a manager from an API. # API_name-manager_name <BR> rtems-managers: classic-task, classic-interrupt, classic-clock, classic-timer, classic-semaphore,

classic-message, classic-event, classic-signal, classic-io, classic-init, posix-mutex, posix-semaphore, posix-clock, posix-timer, posix-condvar, posix-scheduler, posix-message

# Specify a path <BR> # The path to the symbols files. rtems-symbols-path: /home/cocan/Faculta/RTEMS/gsoc_2009/branch-rtems-trace/rtems-trace/bin/rtems-trace/symbols/librtems/

API configuration file

An API configuration file should contain the following sections:

  1. API: name = name_of_API, id = numeric value


  1. manager_name-id: numeric value


  1. manager_name-functions-id: name = name_of_function, class = class_type, id = numeric_value


  1. manager_name-libraries: set of libraries


The following is an example of an API configuration file, for the classic API:

# Task manager task-id: 1 task-functions-id: name = rtems_task_create, class = API, id = 1

name = rtems_task_ident, class = API, id = 2 name = rtems_task_self, class = API, id = 3 name = rtems_task_start, class = API, id = 4 name = rtems_task_restart, class = API, id = 5 name = rtems_task_delete, class = API, id = 6 name = rtems_task_suspend, class = API, id = 7 name = rtems_task_resume, class = API, id = 8 name = rtems_task_is_suspended, class = API, id = 9 name = rtems_task_set_priority, class = API, id = 10 name = rtems_task_mode, class = API, id = 11 name = rtems_task_get_note, class = API, id = 12 name = rtems_task_set_note, class = API, id = 13 name = rtems_task_wake_after, class = API, id = 14 name = rtems_task_wake_when, class = API, id = 15 name = rtems_iterate_over_all_threads, class = API, id = 16 name = rtems_task_variable_add, class = API, id = 17 name = rtems_task_variable_get, class = API, id = 18 name = rtems_task_variable_delete, class = API, id = 19

task-libraries: librtems.a <BR> # Initialization manager init-id: 2 init-functions-id: name = rtems_initialize_data_structures, class = API, id = 1

name = rtems_initialize_before_drivers, class = API, id = 2 name = rtems_initialize_device_drivers, class = API, id = 3 name = rtems_initialize_start_multitasking, class = API, id = 4 name = rtems_shutdown_executive, class = API, id = 5

init-libraries: librtemscpu.a <BR> # Interrrupt manager interrupt-id: 3 interrupt-functions-id: name = rtems_interrupt_catch, class = API, id = 1

name = rtems_interrupt_disable, class = API, id = 2 name = rtems_interrupt_enable, class = API, id = 3 name = rtems_interrupt_flash, class = API, id = 4 name = rtems_interrupt_is_in_progress class = API, id = 5

interrupt-libraries: librtemscpu.a # And so on...

How to use it

  • Set up the configuration file as explained here.
  • Generate the wrapping code:

./ --mode=generate

If the -c (--config) option it's not specified, then the tool will always look for the default configuration file rtems-trace.cfg from your current working directory. Also, if the