[ctrace] Trace decoder utility development

[thorstendb-ARM]

Purpose

ctrace combines a CMSIS trace-run configuration with raw CoreSight trace data. It decodes the trace into backend-independent events and can produce CSV or CTF output for further analysis, including Trace Compass.

Architecture

Architecture description

Supported today

• Raw SWO stream decoding through OpenCSD
• ITM software trace packets
• DWT data and address trace
• Exception, timestamp, overflow and decoder-error events
• CSV, CTF and Trace Compass XML output
• Target, event-type and Trace Bus ID filtering
• Validation without generating output files
• Processing of multiple solution sets
• ITM stimulus port 0 is excluded from CSV and CTF output
• Integration tests for regular SWO input and recovery after a reset-like discontinuity

The selectors event, pmu and pcsample are accepted as specified. DWT event-counter and PMU packets are retained internally but are not emitted yet. Periodic DWT PC-sample packets are currently suppressed because no backend-independent PC-sample event exists yet. Formatted *.TB.raw input is discovered but currently skipped.

OpenCSD error handling

Invalid ITM packet sequences and packet headers are treated as recoverable stream errors:

1. Events before the reported raw offset are retained.
2. Events at or after the failing offset are discarded.
3. The OpenCSD decoder is reset.
4. Decoding resumes only after OpenCSD finds a real hardware ITM sync.
5. The lost byte range is emitted as an ordered error/data-loss event.
6. Pending DWT correlation is cleared and timestamp quality is marked unreliable.

Recoverable trace corruption is reported as [error] and causes a non-zero exit status, but decoding continues after the next valid synchronization point.

A non-recoverable OpenCSD failure aborts the current raw input and removes incomplete output artifacts. Other solution sets can still be processed.

Current development

• Initial ctrace implementation – devtools PR #2548

Remaining work

• Select and document the supported trace-run revision and define the architecture, comparator-role, grouped-source and symbol metadata required for complete decoding
• Preserve logical references, processor bindings, grouped resources and exact trace-route context in the normalized metadata
• Complete Armv7-M DWT comparator-role semantics, including linked comparators, address ranges and value matches
• Add architecture-aware Armv8-M and Armv8.1-M DWT decoding, including match, PC+offset, compressed address/PC packets and linked-pair reconstruction
• Finalize DWT event-counter semantics and implement event output
• Finalize PMU event semantics and implement pmu output
• Add a backend-independent DWT PC-sample event, retain periodic PC-sample packets in the decoder and implement pcsample output
• Add formatted Trace Bus decoding for *.TB.raw
• Add ETM instruction-trace decoding with target-image access
• Add MTB instruction-trace decoding
• Add multi-core support, including processor identity and trace-route bindings
• Add support for multiple trace clocks and cross-stream time synchronization
• tbd...

References

• CMSIS-Toolbox Trace specification
• OpenCSD CoreSight trace decoder
• Eclipse Trace Compass documentation
• Common Trace Format 1.8.3 specification
• https://github.com/ReinhardKeil/cmsis-toolbox/blob/main/docs/Experimental-Features.md#trace

Issues

• [Feature Request]: Trace and Live Debug Capablities vscode-cmsis-debugger#315
• Trace Architecture for Review vscode-cmsis-debugger#983
• Trace Architecture for Review: Common Trace Format (CTF) file contents vscode-cmsis-debugger#996