> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Coverage and trace
> Record structured RTT or ITM debug events, capture ETM instruction traces, and measure firmware source coverage from an attached target.
Choose the trace path by the question you need to answer. RTT and ITM carry firmware-generated events. ETM records executed instruction addresses. Coverage derives function and source-line execution from ETM statistics.
## Compare the capture types
| Question | Use | Target behavior |
| ------------------------------------------------------------ | ----------------------------- | ----------------------------------------------- |
| What RTOS or application events occurred over time? | `trace_start` with RTT or ITM | Runs while firmware emits compact trace packets |
| What instructions executed in the most recent window? | `instruction_trace` | Resets, runs for a bounded duration, then halts |
| Which functions and source lines executed? | `coverage_run` | Resets, runs for a bounded duration, then halts |
| How does an instruction stream grow from the moment I start? | `trace_start` with ETM | Repeatedly runs and halts the target in slices |
RTT and ITM sessions contain decoded events. ETM sessions contain instructions. Event query and summary tools do not interpret an ETM session as an event log.
## Record RTT events
Select a J-Link target in the serial view before you start. Without an explicit transport, Embedder chooses:
* A discovered RTT up channel marked `ctf` or `binary`
* A discovered RTT down channel for control
* Data channel 2 and control channel 1 as fallbacks
```text theme={"system"}
Start an RTT trace recording on the selected J-Link. Use data channel 2,
control channel 1, and an 8192-byte buffer. Return the session ID.
```
The target firmware must emit Embedder compact trace packets on the data channel. At start, Embedder sends an `ETRC` control request on the down channel and waits for the firmware's trace descriptor.
Plain RTT log text is not a trace event stream. Use the [serial transport](/debug-mode/serial-transports) workflow for ordinary logs.
Stop the session when you have reproduced the behavior:
```text theme={"system"}
Stop the active trace session, report dropped records and resynchronizations,
then summarize the top tasks and events.
```
## Record ITM events
ITM event recording uses one stimulus port as a binary packet stream:
```text theme={"system"}
Start an ITM trace session at 2 MHz SWO with a 168 MHz CPU clock. Read compact
trace packets from stimulus port 1.
```
Configure OpenOCD and the target before you start. The firmware must emit compact trace packets, not line-oriented `ITM_SendChar` text, on the selected port.
Use the ITM serial monitor when you want human-readable stimulus output. Use trace recording only when the firmware implements the packet format and descriptor expected by the decoder.
## Capture an ETM instruction window
`instruction_trace` requires:
* A SEGGER J-Trace, not a plain J-Link
* SEGGER J-Link host software
* A fine-pitch CoreSight-20 trace cable
* A target that exposes and drives its ETM trace pins
* The matching ELF and SEGGER device name
```text theme={"system"}
Capture three seconds of ETM instruction trace from build/firmware.elf, print
the newest 500 instructions, and open the session in the Trace tab.
```
The tool stops active GDB and RTT sessions before it takes the probe. It resets and runs the target, then reads the probe's full 65,536-instruction window. The print limit changes only the returned table.
The window is usually the tail of a longer run. ETM gives instruction order,
not elapsed time. A CPU frequency can produce an estimate, but it does not add
real timestamps to the trace.
The stored session includes symbolized instructions and reconstructed call frames. Open frames indicate that the function entry or exit fell outside the retained window.
## Stream ETM from a known start
Use `trace_start` with `transport.kind="etm"` when the capture must begin at a known point and continue until you stop it. Pass `firmware.elfPath` at start; addresses are symbolized as they arrive and cannot be resolved from an ELF attached later.
```text theme={"system"}
Start an ETM trace session with build/firmware.elf and retain a rolling window
of 200000 instructions. Stop after I reproduce the startup fault.
```
Streaming runs the target in short slices and halts it between slices to drain the probe. This changes wall-clock timing and can break interrupts, timeouts, and peripheral handshakes. Do not use a sliced stream to draw timing conclusions.
Check the session's continuity summary. Gaps or lost instructions mean the probe buffer overran; call-frame reconstruction across a gap is incomplete.
## Run source coverage
`coverage_run` uses J-Trace instruction statistics for the whole bounded run:
```text theme={"system"}
Run five seconds of coverage for build/firmware.elf and include function and
source-line rows. Show the least-covered functions.
```
The report contains:
* Covered and total functions
* Covered and total source lines
* Covered and total instructions
* Function entry run counts
* Per-line rows when you request `funcs+lines`
Coverage counts describe the whole run even when the readable instruction window contains only its tail.
Reports persist and appear in the Coverage tab. List or load an existing report instead of rerunning the target when you only need a different view.
## Inspect and export sessions
Trace sessions persist under `.embedder/traces//`.
Use:
* `trace_status` to find the active or latest session
* `trace_list_sessions` to compare RTT, ITM, and ETM sessions
* Event query and summary tools for RTT or ITM sessions
* The Trace tab or `instruction_trace` output for ETM instructions
* `trace_export` with `raw` to copy a complete session
NDJSON export contains event data and applies only to RTT and ITM sessions. ETM instructions live in `instructions.json`; export the raw session directory so you do not drop them.
## Interpret capture quality
Every trace result reports provenance:
* Firmware match state and ELF hash when available
* Resolved and unresolved symbols
* Dropped records, resynchronizations, and transport errors
* Trace format and confidence
Treat a firmware mismatch or dropped records as low-confidence evidence. A resynchronization or unresolved symbol count makes the result partial.
## Fix trace problems
Confirm the data and control channel indexes and the firmware's compact trace integration. Plain RTT logging does not answer the trace-start control request.
Verify OpenOCD, SWO clocks, the stimulus port, and firmware packet output. Test human-readable ITM separately in the serial view.
Confirm that the probe is J-Trace, the target drives TRACECLK, and the fine-pitch CoreSight-20 cable carries the trace signals.
Stop active hardware scripts and trace sessions. The coverage tool already stops managed GDB and RTT connections during its handoff.
Check continuity, window truncation, and the matching ELF. Do not reconstruct across reported gaps.
Check the probe, cable, target, and scripted SDK path.
Configure RTT and ITM before recording events.