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

Introduction

TBD

Command line interface

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

Usage: ./rtems_trace.py --mode=generate (this is by default) --genpath=path to where the wrapping code should be saved (the default is the wrappers directory from the cwd - current working directory).

• compile mode
• link mode
• decode mode

To call the RTEMS Trace Tool a user should do this (from the directory where the tool it's installed):

./rtems_trace.py

This will cause the tool to work These are the following options that the user can add when

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.

2. 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.

3. 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

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

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

5. 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

TBD

2. manager_name-id: numeric value

TBD

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

TBD

4. manager_name-libraries: set of libraries

TBD

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:

./rtems_trace.py --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