= RTEMS Trace Tool = RTEMS Trace Tool - trace your application in RTEMS = Introduction = 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: ./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/''.
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.
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. 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"
# 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
# Specify a manager from an API. # API_name-manager_name
'''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
# 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: '''API''': name = classic, id = 1
# 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
# 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
# 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 in this example is i386 and the RTEMS version is 4.10. * Set up the configuration files as explained [http://www.rtems.org/wiki/index.php/RTEMS_Trace_Tool#Configuration_files 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'' and name it ''log.txt'' if it has a different name). ./rtems_trace.py --mode=decode This is it. All the tracing information it's now saved in the ''cwd/decoded.txt'' file.