Getting Started with Percepio Profile for Zephyr
Percepio Profile relies on Percepio TraceRecorder to provide trace data. This library is provided as a Zephyr submodule and is easy to enable via the Zephyr kconfig system. Percepio Profile supports trace streaming via SEGGER J-Link RTT, which allows for recording long traces (several minutes), e.g. for profiling and debugging. Snapshot tracing is also supported, as described in the Percepio View guide. Percepio Profile supports x86-64 computers running Windows or Linux. Arm-based host computers are not yet supported.
If you prefer a different method for trace streaming, or want to record very long traces, please consider upgrading to Percepio Tracealyzer.
Installing the application
- Windows: Download and run the installer.
- Linux: Download the archive. The standalone version is recommended for most users. Then refer to the Running Tracealyzer on Linux guide. Start the application by running ./launch-tz.sh.
Adding TraceRecorder in your project
1. Enable TraceRecorder and configure it for SEGGER RTT streaming by applying the following settings, for example in prj.conf:
CONFIG_TRACING=y
CONFIG_PERCEPIO_TRACERECORDER=y
CONFIG_PERCEPIO_TRC_START_MODE_START_FROM_HOST=y
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT=y
Build and flash the device.
2. Open Percepio Profile and select File -> Settings -> Project Settings -> J-Link Settings. Update as described below.
- J-Link speed: start with the default (4000 KHz), but can be increased if needed.
- Debugger Interface: Set JTAG or SWD. If another debug tool is used at the same time, make sure to use the same setting in both tools.
- Target Device: Specify the target device. Note that the list of devices comes from the J-Link driver.
- Enable logging: Disabled.
3. Open File -> Settings -> Project Settings -> PSF Streaming Settings and update as described below.
- Target Connection: SEGGER RTT
- RTT Control Block Address: “auto-detect” (= 0)
- Target RTT Up Buffer Index: 1
- Target RTT Down Buffer Index: 1
- Reset Target on Connect: Disabled
- Target Starts Tracing: Disabled
- Use separate receiver thread: Enabled (may improve throughput)
4. Finally, open File -> Settings -> Project Settings -> Definition File Paths and add the path to your Zephyr build folder.
This folder should contain a file “syscalls-[version].xml” created during build.
Note that more settings are available for tweaking the tracing setup, for example event filtering. For details, please refer to the Percepio Tracealyzer guide for Zephyr.
Recording Traces
Make sure the device is running, for example by starting a debug session.
Open File -> Trace -> Open Live Stream Tool.
Click Connect and then Start Session. The live visualization should begin, unless disabled by the checkbox. Disabling the live visualization reduces the load on the host system.
Record your test case. You can use your debugger and set breakpoints as usual during the tracing. Halting the device won’t affect the trace, as time effectively ‘pauses’ when the debugger halts the core.
Select Stop Session to finalize the trace file and enable all views.
Make sure to check for “Missed Events”. If you see a notice in red (like in the below screenshot), some events have been lost during the trace streaming. In that case, make sure to resolve such issues before studying the trace in detail. A complete trace is needed for accurate display.
Missed events can sometimes be avoided or decreased by increasing the RTT buffer size.
You can override the default RTT buffer size by adding:
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RTT_UP_BUFFER_SIZE=(size in bytes)
Troubleshooting
In case of issues with the J-Link streaming, please consult the troubleshooting guide. More troubleshooting tips are found in the Percepio Profile User Manual (Help menu) under “Creating and Loading Traces” -> “Percepio TraceRecorder” -> “Troubleshooting”.
Questions
If you have issues getting started, please refer to Zephyr Github Discussions page and search for Percepio.