J-Trace - Getting started
J-Trace is SEGGER's dedicated debug and trace probe for capturing and analyzing program execution at instruction level, including continuous streaming trace for supported target architectures.
Why would I need tracing?
Traditional debugging is based on stopping the CPU, inspecting its state, and stepping through the program. This can make timing-dependent problems difficult to reproduce because stopping or stepping changes the system's real-time behavior.
Tracing provides visibility into what the CPU actually did while the application was running. Depending on the trace method, it can be used to:
- Find the instruction sequence that led to a crash or fault.
- Investigate intermittent or timing-dependent problems.
- Analyze interrupt behavior and execution flow.
- Identify unexpected program paths.
- Measure and optimize application behavior.
- Perform code coverage and profiling based on instruction execution.
- Record rare problems that are difficult to reproduce.
J-Trace is particularly useful when the application enters a fault state due to unforeseen or rarely occurring conditions and events, which might be hard to reproduce in an isolated test. Streaming trace allows complete execution traces to be captured over long periods without being limited by the size of the probe's trace buffer. This allows diagnosing the complete program flow leading up to any rarely occurring issue.
Types of tracing
There are several ways to get information out of an embedded system. They differ significantly in the amount of information they provide, their impact on the application, and the hardware required.
The following table lists all types of trace methods, trace components and trace-related diagnostic methods supported by SEGGER tools.
For more information on each trace component type and tracing in general, see General information about tracing and each component's dedicated KB page.
| Trace method/component | Output channel | J-Link | J-Trace | Information source | Intrusiveness | Pin requirements | Supported cores |
|---|---|---|---|---|---|---|---|
| ETM or PTM | Trace buffer (MTB/ETB/ETF/TMC) |  |
|
Instruction trace | None | None | ARM Cortex |
| Trace pins (TPIU) |  |
|
None | Trace clock + 1, 2 or 4 trace data pins | |||
| N-Trace Encoder | Trace buffer (RISC-V SRAM Sink) | |
|
Instruction trace | None | None | RISC-V |
| Trace pins (RISC-V PIB Sink) | |
|
None | Trace clock + 1, 2 or 4 trace data pins | |||
| Trace pins (TPIU) | |
|
None | Trace clock + 1, 2 or 4 trace data pins | RISC-V core in heterogeneous ARM + RISC-V SoCs | ||
| ITM | Trace pins (TPIU) | |
|
Code instrumentation | Low | None | ARM Cortex |
| SWO pin | |
|
Low | SWO pin | |||
| STM | Trace buffer (MTB/ETB/ETF/TMC) | |
|
Code instrumentation | Low | None | ARM Cortex |
| Trace pins (TPIU) | |
|
Low | Trace clock + 1, 2 or 4 trace data pins | |||
| Semihosting | Debug interface | |
|
Code instrumentation | High | None | All |
| RTT | Debug interface | |
|
Code instrumentation | Low | None | All |
The exact capabilities depend on the target device, trace architecture, and probe model. J-Link supports features such as buffer trace, PC sampling, SWO, SystemView, and J-Scope, while J-Trace adds dedicated high-speed pin trace capture.
Getting started with a trace example
The easiest way to get started is to use one of the trace examples supplied by SEGGER. SEGGER provides tested trace examples for selected target devices and evaluation boards. These examples are designed to demonstrate a working trace setup and can be used as a reference when bringing up tracing on custom hardware.
1. Select a trace example
Start by finding your device in the Tested Devices for J-Trace PRO list.
Each tested device comes with a linked knowledge base article, which includes all the files required the run the example.
2. Set up the hardware
Connect the trace reference board or supported evaluation board to the J-Trace using the appropriate debug and trace connector.
Make sure that:
- The target is powered correctly.
- The debug connection is established.
- The trace signals are connected.
- The trace clock and trace pins are configured as required by the example.
3. Run the example
Open the supplied project in Ozone or another supported debugging environment and start the application.
For the best J-Trace experience, SEGGER recommends using Ozone, which provides instruction tracing as well as live code profiling and code coverage features.
4. Start tracing
Start the trace session and verify that instructions are being decoded correctly.
For streaming trace, the application should normally be downloaded in the same debug session because the trace analysis uses a cached copy of the downloaded application to resolve execution addresses.
Troubleshooting a trace example
If the supplied example does not produce valid trace data, first verify the known-good setup before modifying the project.
Check:
- The J-Trace model and hardware revision.
- The J-Link Software and Documentation Package version.
- The selected target device.
- The trace connector and cable.
- Trace pin configuration.
- Target voltage.
- Trace clock configuration.
- Device-specific trace registers.
- Whether required peripheral clocks are enabled.
- Whether registers need to be unlocked before configuration.
For a detailed list of common problems and diagnostic steps, see the Trace Troubleshooting page.
The SEGGER Knowledge Base also contains model-specific troubleshooting, as well as information about J-Trace overflow errors and unknown addresses in instruction trace.
Moving from the trace example to custom hardware
Once the supplied example works, the next step is usually to move the setup to your own PCB.
The trace example should be treated as a reference rather than copied blindly. Evaluation boards may contain device-specific clock configuration, pin routing, pull-ups, level shifting, or other hardware features that are not present on the custom board.
When designing or reviewing a custom PCB, pay particular attention to:
- Trace pin availability and pin multiplexing.
- Trace connector pinout.
- Trace signal routing.
- Signal integrity and trace impedance.
- Trace clock frequency.
- Target I/O voltage.
- Required pull-ups or pull-downs.
- Whether the trace pins are shared with other peripherals.
- Whether device-specific registers are required to enable trace.
See Trace board design recommendations for the hardware requirements and recommendations.
SEGGER also notes that supplied example projects are often designed for specific evaluation boards, so initialization such as PLL configuration may need to be adapted for custom hardware.
No supplied trace example for your device
A device does not necessarily need to have a SEGGER trace example in order to support tracing.
If the target implements the required trace components and is otherwise supported, trace can often be enabled by configuring the device-specific pins and registers.
For Arm targets, J-Link software automatically configures the generic CoreSight trace components where possible. Device-specific initialization, such enabling peripheral clocks, configuring trace pins, or writing device-specific trace registers can be implemented in a J-Link Script.
The usual approach is:
- Create a .JLinkScript file. See J-Link Script files for more info.
- Implement OnTraceStart().
- Identify the trace pins from the device documentation and schematic.
- Enable the required peripheral clocks.
- Configure the trace pins for their trace alternate function.
- Configure any device-specific trace registers.
- Should the auto-detection of trace components from the ROM table fail, specify the base addresses manually. See How to configure JLinkScript files to enable tracing - Adding missing ROM table entries for more info.
- Select the script in the debugger or IDE.
- Connect the J-Trace and start tracing.
SEGGER provides a complete walkthrough, including an STM32F407 example, in How to configure JLinkScript files to enable tracing.
For general information about J-Link Script files, their available functions, and the OnTraceStart() function, see the J-Link Script Files documentation.