C-Trace eXPort (CTXP)

Table of Contents

• Quick start
• Event types (excerpt)
• Examples
• Documentation
• Tooling (Accemic)
• License / attribution / acknowledgement

CTXP is a unified trace format for exporting processor trace data (control-flow, memory accesses, and timing) from single- and multi-core systems.

This repository aims to be a publication-quality reference for the CTXP format:

• A readable overview and quick reference

• Canonical, curated examples

• A small linter to keep examples consistent

Specification (PDF): download the latest release — tn-ctxp-format.pdf. The AsciiDoc source lives in spec/.

Quick start

The text format (.ctxp.txt) is intended to be grep-able and diff-able.

HDR:format=accemic//ctxp-txt,ver=1
META:#0="CPU0"
#0:SYNC::0x80000000                      @ 0
#0:BRANCH_NOTTAKEN:0x80000014:0x80000018 @ 3
#0:CALL:0x8000001c:0x8000004c            @ 5
#0:RETURN:0x80000050:0x80000020          @ 17

Event types (excerpt)

• Control-flow: SYNC, BRANCH_TAKEN, BRANCH_NOTTAKEN, CALL, RETURN, INTERRUPT, RFI

• Memory: MEMREAD_0/1/2/4/8, MEMWRITE_0/1/2/4/8 (the address is optional on the sized variants — omit it for a value-only capture)

• Other: OVERFLOW, CONTEXT, WALLCLOCK

• Instrumentation / DAQ (user-generated): DAQ_DATA (DirectData tag), DAQ_COUNTER, DAQ_LAST_PC

Examples

The list below is a small excerpt. See examples/ for the full set of curated example traces and explanations.

• examples/basic.ctxp.txt (+ explanation)

• examples/dualcore.ctxp.txt (+ explanation)

• examples/overflow.ctxp.txt (+ explanation)

• examples/daq.ctxp.txt (+ explanation)

Documentation

The authoritative format specification is the PDF published as a GitHub Release asset: tn-ctxp-format.pdf (latest release).

Its AsciiDoc source lives in spec/ (tn-ctxp-format.adoc + ctxp-format.adoc + diagrams under spec/images/). The spec-pdf GitHub Action builds and validates the PDF on every change under spec/, and publishes it as a release asset when a v* tag is pushed. To build it locally:

gem install asciidoctor-pdf rouge
asciidoctor-pdf spec/tn-ctxp-format.adoc -o tn-ctxp-format.pdf

Diagrams are the *.drawio.png files under spec/images/, exported from draw.io (asciidoctor-pdf does not render the draw.io SVG format cleanly).

Tooling (Accemic)

Accemic provides a CTXP exporter/decoder tool for converting native hardware trace formats to CTXP and consuming CTXP in analyzers.

Common native trace formats supported include:

• RISC-V Nexus traces

• Arm CoreSight ETMv4

• Arm CoreSight PFT

• Infineon TriCore MCDS (TC2/TC3/TC4)

Accemic also has a NexRv adaptation (based on https://github.com/riscv-non-isa/tg-nexus-trace/tree/main/refcode/c) that supports CTXP output; it will be published soon.

If you want to evaluate or integrate CTXP tooling, please contact us:

• https://accemic.com/contact/

License / attribution / acknowledgement

The CTXP technical note states it is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). See the spec for details.

The CTXP format was developed as part of the TRISTAN project, a European Union research initiative involving 46 partners to advance the RISC-V ecosystem. See https://tristan-project.eu/ for more information.