Skip to content

About

Generate BTF trace file for FreeRTOS

Resources

Stars

29 stars

Watchers

1 watching

Forks

Repository files navigation

FreeRTOS-BTF-Trace

FreeRTOS-BTF-Trace records scheduling and synchronization events in a compact RAM ring buffer. The included tools convert the captured data to:

  • BTF (Best Trace Format) for BTFViewer and Eclipse Trace Compass.
  • VCD (Value Change Dump) for GTKWave.

BTF trace overview

Documentation

Document Purpose
README.md Build the demo, capture events, and open a trace
PORTING.md Integrate the trace library with another FreeRTOS target
TRACE_FORMAT.md Understand the trace.bin layout and BTF event mapping
BTFViewer/README.md Install and use BTFViewer
BTFViewer/WORKFLOWS.md Follow RTOS analysis procedures
BTFViewer/AI.md Configure and use the BTFViewer AI Assistant

How it works

  1. FreeRTOS trace hooks record events in a RAM ring buffer.
  2. The application exports the buffer as trace.bin.
  3. gentrace converts trace.bin to BTF and VCD.
  4. Open the converted trace in the appropriate viewer.
Output Use
.btf Scheduling, timing, synchronization, and SMP analysis in BTFViewer or Trace Compass
.vcd Signal-style waveform inspection in GTKWave

BTFViewer

Open the BTFViewer live demo

Quick start

The included demo runs on the RISC-V RV64 simulator in sim/.

1. Install the toolchain

Install xPack RISC-V GCC. The default compiler path is:

/opt/xpack-riscv-none-elf-gcc-15.2.0-1/bin/riscv-none-elf-gcc

To use another installation, set RISCV_PREFIX:

make run RISCV_PREFIX=/path/to/riscv-none-elf-

2. Build and capture

make run            # single core
make CORES=2 run    # 2-core SMP
make CORES=8 run    # 8-core SMP

On the first run, the build clones FreeRTOS-Kernel V11.3.1. After the simulator exits, gentrace creates:

tracedata/trace.btf
tracedata/trace.vcd

Experimental 128-core build

FreeRTOS-Kernel V11.3.1 and current upstream main store task affinity in UBaseType_t; upstream therefore does not provide a portable 128-core affinity API. This repository carries an experimental patch that replaces that field and the existing affinity API parameters with TaskCoreAffinityMask_t and adds taskCORE_AFFINITY_BIT(core).

Apply the patch only when starting from a clean official V11.3.1 checkout:

git -C FreeRTOS-Kernel checkout V11.3.1
git -C FreeRTOS-Kernel apply \
  ../patches/freertos-kernel-v11.3.1-128-core-affinity.patch

Build the dedicated 128-core synchronization workload without running it:

make -C Demo/examples CORES=128 \
  ../../build/demo/examples/cores128-tickless0/stress_128.elf

Build the simulator, rebuild the ELF, and start 128 simulated harts:

make clean && make CORES=128 -C Demo/examples stress_128

The stress program creates one affinity-pinned worker per core and exercises queues, mutex pairs, a counting semaphore, and event-group barriers. See Demo/examples/stress_128/README.md.

Current limitations:

  • This is a local experimental patch, not an official FreeRTOS feature.
  • Above 64 cores it requires GCC/Clang __int128, or an integer-like 128-bit portTASK_CORE_AFFINITY_TYPE supplied by the port.
  • The affinity API/TCB ABI changes above 32 cores; all kernel, application, trace-hook, debugger, and port objects must be rebuilt together.
  • The BTF v1.4 affinity event stores only 32 mask bits. Core IDs 0–127 and scheduling events can be recorded, but affinity bits 32–127 are truncated in affinity_set trace events and cannot yet be verified by BTFViewer.
  • The bundled simulator now accepts 128 harts, but simulation is extremely slow. The ELF compiles and links; completion of all stress rounds is not currently a fast CI test and has not been qualified as production-grade 128-core runtime support.
  • Kernel algorithms still scan core arrays in several scheduler paths, so their latency and lock contention grow significantly at 128 cores.

See patches/README.md for API and integration details.

3. Open the BTF trace

Install the Desktop application requirements and open the trace:

pip install -r BTFViewer/requirements.txt
python BTFViewer/builds/btf_viewer.py tracedata/trace.btf

BTFViewer Desktop and Web support .btf, .gz, .bz2, and .zip files.

Sample captures are available in tracedata/:

example.btf.gz
example-2cores.btf.gz
example-4cores.btf.gz
example-8cores.btf.gz
example-16cores.btf.gz

Demo workload

Demo/examples/freertos_test/ contains 11 tests. Tests 1–10 use task yields to keep the workload active. Test 11 uses vTaskDelay to compare normal tick operation with tickless idle.

Enable tickless idle with:

make TICKLESS=1 run
# Test Purpose
1 Context-switch stress Generate rapid voluntary yields across cores
2 Mutex contention Exercise a priority-inheritance mutex under load
3 Counting semaphore and mutex Combine synchronization primitives
4 Task notifications Exercise direct-to-task notifications
5 Event groups Exercise multi-bit event synchronization
6 Queue stress Run producer and consumer queues
7 Task priority change Exercise vTaskPrioritySet and traceTASK_PRIORITY_SET
8 Priority inversion Run low-, medium-, and high-priority tasks on one core for T8_ROUNDS
9 Task suspend and resume Suspend blocked or running tasks for T9_SUBJECTS × T9_ROUNDS
10 Core affinity Pin and migrate tasks with vTaskCoreAffinitySet
11 Tickless idle Compare TICK and TICKLESS behavior during vTaskDelay windows

Interval ID 0 covers each complete test. IDs 1–11 identify individual tests.

Trace viewers

BTFViewer

BTFViewer provides task and core timelines, measurement cursors, Statistics, Analysis Findings, migration inspection, trace comparison, optional AI-assisted investigation, and export.

python BTFViewer/builds/btf_viewer.py tracedata/example-8cores.btf.gz

For the Web application, open BTFViewer/builds/btf_viewer.html in a browser.

Desktop requirements: Python 3.8+ and PySide6 6.4 or later.

See BTFViewer/WORKFLOWS.md for analysis procedures.

Custom instrumentation

The demo records heap usage on every tick:

btf_traceTAG(0, ...);

The value appears in BTF as the STI channel tag0_event. Interval start and stop events mark individual test regions.

Heap usage tag

SMP traces also support task-migration and migration-corridor analysis.

Migration inspector

Porting

A port requires:

  • FreeRTOS trace-hook integration.
  • A free-running 32-bit cycle counter.
  • One supported trace-dump mode.

Call traceSTART() to begin capture and traceEND() to stop it.

See PORTING.md for configuration, time-source requirements, dump modes, tags, intervals, and SMP locking.

See TRACE_FORMAT.md for the binary layout, event encoding, BTF mapping, and trace-quality flags.

Repository layout

Path Contents
FreeRTOS-Trace/ FreeRTOS hooks, ring buffer, and trace dump support
tools/ gentrace converter for BTF and VCD output
sim/ RISC-V RV64 SMP simulator
Demo/ FreeRTOS SMP demo workloads
BTFViewer/ Desktop and Web trace-analysis applications
tracedata/ Sample BTF and VCD traces

Related project

freertos-barectf provides a related BareCTF and Trace Compass implementation.

License

MIT

About

Generate BTF trace file for FreeRTOS

Resources

Stars

29 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages