wlshiu / freertos-btf-trace

Generate BTF trace file for FreeRTOS

FreeRTOS-BTF-Trace

Generate BTF trace file or VCD waveform for FreeRTOS.

BTF (Best Trace Format) is a CSV-based format used to record and trace at the system level to analyze the timing, performance, and reliability of embedded real-time systems. The spec can be found here.

VCD (Value Change Dump) is an ASCII-based format for dumpfiles generated by EDA logic simulation tools, which can be opened by GTKWave tool.

Tracelyzer from Percepio is the best analysis tools to visualize the real-time execution of tasks and ISRs. However, sometimes we just need a simple solution to find the performance bottleneck. This project provides a simple and extensible framework for this, and most importantly, it is open source and free.

There's another related solution is using BareCTF and Trace Compass to trace FreeRTOS system in freerots-barectf.

Build

This is an example to test srv32 on FreeRTOS. The code can be run on the ISS (Instruction Set Simulator) of srv32 to generate trace data in BTF and VCD format. I use srv32 to run the test, and this can be easily ported to another platform.

Requirement: Install the toolchains. See details in srv32 Building toolchains section.

The file "trace.btf" and "trace.vcd" will be generated under tracedata folder. Open it by the Trace Compass (for trace.btf) or VCD viewer (for trace.vcd).

$ make run

Results

This is a screen shot of Trace Compass by reading the BTF trace file. Use the gentrace tool to convert the trace data into BTF format.

$ gentrace dump.bin trace.btf

This is the VCD waveform showing task switching. Use gentrace tool to generate trace data into VCD format.

$ gentrace -v dump.bin trace.vcd

Porting guide

1. Include FreeRTOS-Trace/FreeRTOS-Trace.h in your FreeRTOSConfig.h.
2. Provide xGetTime() macro in FreeRTOS-Trace/btf_port.h to report the system time in nanoseconds.
3. Keep HAVE_SYS_DUMP undefined in FreeRTOS-Trace/btf_port.h.
4. Compile the code FreeRTOS-Trace/btf_trace.c with your project.
5. Call traceSTART() in your application to enable trace log.

#if configUSE_TRACE_FACILITY
    traceSTART();
#endif

6. Call traceEND() in your application to disable trace log.

#if configUSE_TRACE_FACILITY
    traceEND();
#endif

7. After the application is built, use readelf to find the location of trace_data. Run the application and dump the memory to a binary file. In this example, you should dump 65572 bytes of data from address 0x21d44.

$ readelf -a task.elf
...
21: 00021d44 65572 OBJECT  LOCAL  DEFAULT    4 trace_data
...

8. Using gentrace tools to convert trace data to BTF file.

$ ../../tools/gentrace dump.bin trace.btf
814 events generated

9. Open the BTF file with Trace Compass to view the trace file.

License

MIT license