Merge pull request #3 from accemic/albert/ctxp-daq-events

Albert/ctxp daq events

Author: accemic

.github/workflows/pdf.yml

@@ -0,0 +1,40 @@
+name: spec-pdf
+
+on:
+  push:
+    paths:
+      - 'spec/**'
+      - '.github/workflows/pdf.yml'
+  pull_request:
+    paths:
+      - 'spec/**'
+      - '.github/workflows/pdf.yml'
+  workflow_dispatch:
+
+jobs:
+  build-pdf:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+
+      - name: Install asciidoctor-pdf
+        run: gem install --no-document asciidoctor-pdf rouge
+
+      - name: Build CTXP spec PDF
+        run: |
+          asciidoctor-pdf \
+            -a git-commit="${GITHUB_SHA::8}" \
+            -a attribute-missing=warn \
+            --failure-level=ERROR \
+            spec/tn-ctxp-format.adoc \
+            -o spec/tn-ctxp-format.pdf
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: tn-ctxp-format-pdf
+          path: spec/tn-ctxp-format.pdf
+          if-no-files-found: error

README.adoc

@@ -48,6 +48,27 @@ for the full set of curated example traces and explanations.
 
 The authoritative format specification is in link:spec/tn-ctxp-format.pdf[`spec/tn-ctxp-format.pdf`].
 
+Its AsciiDoc source lives in link:spec/[`spec/`] (link:spec/tn-ctxp-format.adoc[`tn-ctxp-format.adoc`]
++ link:spec/ctxp-format.adoc[`ctxp-format.adoc`] + diagrams under link:spec/images/[`spec/images/`]).
+The PDF is regenerated by the `spec-pdf` GitHub Action on every change under `spec/`; to build it
+locally:
+
+[source,sh]
+----
+gem install asciidoctor-pdf rouge
+asciidoctor-pdf spec/tn-ctxp-format.adoc -o spec/tn-ctxp-format.pdf
+----
+
+Diagrams: the editable sources are the `*.drawio.svg` files (drawn with https://draw.io[draw.io]).
+The PDF embeds the `*.drawio.png` next to them, because asciidoctor-pdf does not render the
+draw.io SVG format cleanly. Regenerate the PNGs after editing a diagram, e.g.:
+
+[source,sh]
+----
+inkscape spec/images/<name>.drawio.svg --export-type=png \
+  --export-filename=spec/images/<name>.drawio.png --export-dpi=192
+----
+
 == Tooling (Accemic)
 
 Accemic provides a CTXP exporter/decoder tool for converting native hardware trace formats to CTXP and

spec/ctxp-format.adoc

@@ -0,0 +1,42 @@
+= Technical Note: CTXP Format
+:title-page:
+:toc: left
+:sectnums:
+:source-highlighter: rouge
+:icons: font
+:xrefstyle: short
+:latest: 1.1.0
+ifndef::git-commit[:git-commit: dev]
+Version {latest} ~ Build {git-commit}
+{localdate}
+
+:sectnums!:
+== Revision History
+[cols=",,",options="header"]
+|===
+| Version  | Date       | Changes
+| {latest} | 2026-05-21 | Add instrumentation / DAQ events (`DAQ_DATA`, `DAQ_COUNTER`, `DAQ_LAST_PC`) and the ACT-CAP/DAQ native-mapping table. Make the address optional on the sized memory events (value-only accesses).
+| 1.0.0    | 2026-01-12 | Initial release.
+|===
+:sectnums:
+
+== Licensing and Usage
+This document is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). 
+You are free to share (copy and redistribute the material in any medium or format) and adapt (remix, transform, and build upon the material) for any purpose, including commercial use, provided that appropriate credit is given, a link to the license is provided, and any changes made are indicated.
+
+Usage of this document is subject to the following conditions:
+
+* Attribution is required. Any use or distribution of this document, or derivatives thereof, must include clear attribution to the original authors and source.
+* Commercial use is allowed, but the authorship and source must always be referenced in any publication or product that incorporates this material.
+* No additional restrictions. You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits.
+
+The full license text is available at: https://creativecommons.org/licenses/by/4.0/
+
+== Disclaimer
+This document is provided “as is”. The authors and publishers make no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability, or availability of this document or the information contained herein. Any reliance you place on such information is strictly at your own risk. The authors and publishers do not accept any liability for any loss or damage, including without limitation, indirect or consequential loss or damage, arising from the use of this document.
+
+include::ctxp-format.adoc[leveloffset=+1]
+
+== Acknowledgment
+
+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.