wiki:Developer/Projects/Open/TraceTool

Version 54 (modified by Cocanlucian, on Aug 10, 2009 at 8:33:17 PM) (diff)

/* API configuration file */

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 -m generate

-c path to the configuration file -g path to where the wrapping code should be saved

./rtems_trace.py --mode=generate

--genpath=path to where the wrapping code should be saved --config=path to the configuration file

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

./rtems_trace.py

Compile mode

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

./rtems_trace.py --mode=compile

--compiler=name of the compiler --genpath=path to the wrapping code --objpath=path to where the compiled wrapping code should be saved --lib=path to where the RTEMS libraries were installed

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/. <BR> Example:

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

Usage: ./rtems_trace.py -m link

-i name of the compiler -b RTEMS build path -o path to the compiled code (.o files) - list of comma separated object files that should be included in the final executable -l path to where the RTEMS libraries were installed

./rtems_trace.py --mode=link

--compiler=name of the compiler --build=RTEMS build path --objpath=path to the compiled code(.o files) --trace-o=list of comma separated object files that should be included in the final executable --lib=path to where the RTEMS libraries were installed

In this mode, the RTEMS trace tool will link all the object files from the specified directory (or from the default one if no directory is specified using the -o or --objpath option) if the --trace-o option it's not used. The user can specify only a subset of object files to be included in the final executable using the --trace-o option. The final executable file is placed into the same directory where the object files are found, under the wrapper.exe name. <BR> Example:

./rtems_trace.py --mode=link --compiler=i386-rtems4.10-gcc -build=/home/cocan/Faculta/RTEMS/build-i386-qemu-rtems

will link all the object files from cwd/objects, generating the final executable file cwd/objects/wrapper.exe

Decode mode

Usage: ./rtems_trace.py -m decode

-t path to the trace file -d where to save the final decoded data

./rtems_trace.py --mode=decode

--trace-file=path to the trace file --dec-file=where to save the final decoded data

In this mode, the RTEMS trace tool will read the input file, specified using the -t or --trace-file option and decode it, generating the final decoded data in the file specified by the -d or --dec-file option. If these options are not specified then the file cwd/log.txt will be used as input file and cwd/decoded.txt will be used as output file.

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

TBD

  1. manager_name-id: numeric value

TBD

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

TBD

  1. manager_name-libraries: set of libraries

TBD

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

API: name = classic, id = 1 <BR> # 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...

Tutorial

The following section will try to illustrate how to properly use the RTEMS trace tool in order to get the decoded file containing the information needed. The BSP used is i386 and the RTEMS version is 4.10.

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

./rtems_trace.py

  • Compile the wrapping and the application code (copy your application code in the cwd/wrappers directory).

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

  • Do the linking.

./rtems_trace.py --mode=link --compiler=i386-rtems4.10-gcc -build=/home/cocan/Faculta/RTEMS/build-i386-qemu-rtems

  • Run the final executable in QEMU in order to get the trace file needed for decoding.

TBD

  • Decode the trace file (copy the trace file in cwd).

./rtems_trace.py --mode=decode

This is it. All the tracing information it's now saved in the cwd/decoded.txt file.