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.
| 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 |
- FreeRTOS trace hooks record events in a RAM ring buffer.
- The application exports the buffer as
trace.bin. gentraceconvertstrace.binto BTF and VCD.- 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 |
The included demo runs on the RISC-V RV64 simulator in sim/.
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-make run # single core
make CORES=2 run # 2-core SMP
make CORES=8 run # 8-core SMPOn the first run, the build clones FreeRTOS-Kernel V11.3.1. After the simulator exits, gentrace creates:
tracedata/trace.btf
tracedata/trace.vcd
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.patchBuild the dedicated 128-core synchronization workload without running it:
make -C Demo/examples CORES=128 \
../../build/demo/examples/cores128-tickless0/stress_128.elfBuild the simulator, rebuild the ELF, and start 128 simulated harts:
make clean && make CORES=128 -C Demo/examples stress_128The 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-bitportTASK_CORE_AFFINITY_TYPEsupplied 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_settrace 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.
Install the Desktop application requirements and open the trace:
pip install -r BTFViewer/requirements.txt
python BTFViewer/builds/btf_viewer.py tracedata/trace.btfBTFViewer 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/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.
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.gzFor 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.
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.
SMP traces also support task-migration and migration-corridor analysis.
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.
| 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 |
freertos-barectf provides a related BareCTF and Trace Compass implementation.
MIT


