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

This repository uses two licenses:

• Specification (spec/): the CTXP technical note is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). See the spec for details.

• Tooling and examples (tools/, examples/): licensed under the ISC License. See the LICENSE file at the repository root.

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.