feat(ctrace): support formatted multi-route ITM/DWT trace

.github/matrix_includes_ctrace.json

@@ -3,34 +3,39 @@
         "runs_on":"macos-14",
         "target":"darwin",
         "arch": "arm64",
+        "run_tests": true,
         "binary": "ctrace",
         "runOn": "publicRepo"
     },
     {
         "runs_on":"ubuntu-24.04",
         "target":"linux",
         "arch": "amd64",
+        "run_tests": true,
         "binary": "ctrace",
         "runOn": "always"
     },
     {
         "runs_on":"ubuntu-24.04",
         "target":"linux",
         "arch": "arm64",
+        "run_tests": false,
         "binary": "ctrace",
         "runOn": "always"
     },
     {
         "runs_on":"windows-2022",
         "target":"windows",
         "arch": "amd64",
+        "run_tests": true,
         "binary": "ctrace.exe",
         "runOn": "always"
     },
     {
         "runs_on":"windows-2022",
         "target":"windows",
         "arch": "arm64",
+        "run_tests": false,
         "binary": "ctrace.exe",
         "runOn": "always"
     }

.github/workflows/ctrace.yml

@@ -33,6 +33,7 @@ permissions:
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  BABELTRACE2_DEB_VERSION: 2.0.5-3build2
 
 jobs:
   setup:
@@ -181,6 +182,14 @@ jobs:
         with:
           submodules: true
 
+      - name: Install pinned Babeltrace consumer
+        if: matrix.run_tests && matrix.target == 'linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            babeltrace2=${{ env.BABELTRACE2_DEB_VERSION }} \
+            libbabeltrace2-0=${{ env.BABELTRACE2_DEB_VERSION }}
+
       # https://github.com/Open-CMSIS-Pack/devtools-build-action
       - name: Build CtraceUnitTests
         id: build_unit_tests
@@ -201,19 +210,26 @@ jobs:
 
       - name: Run ctrace unit tests
         id: run_unit_tests
-        if: always() && (matrix.arch != 'arm64') && (steps.build_unit_tests.outcome == 'success')
+        if: always() && matrix.run_tests && (steps.build_unit_tests.outcome == 'success')
         run: ctest -V -C Debug -R '^CtraceUnitTests$'
         working-directory: ./build
 
       - name: Run ctrace integration tests
         id: run_integration_tests
-        if: always() && (matrix.arch != 'arm64') && (steps.build_integration_target.outcome == 'success')
-        run: ctest -V -C Debug -R '^(CtraceIntegTests|ctrace-)'
+        if: always() && matrix.run_tests && (steps.build_integration_target.outcome == 'success')
+        run: ctest -V -C Debug -R '^(CtraceIntegTests|CtraceFixtureIntegrity|ctrace-)'
+        working-directory: ./build
+
+      - name: Run pinned Babeltrace consumer test
+        if: |
+          always() && matrix.run_tests && matrix.target == 'linux' &&
+          (steps.build_integration_target.outcome == 'success')
+        run: ctest -V -C Debug --no-tests=error -L '^linux-consumer$'
         working-directory: ./build
 
       - name: Archive unit test results
         # Keep the report available when test execution fails.
-        if: always() && (matrix.arch != 'arm64') && (steps.run_unit_tests.outcome != 'skipped')
+        if: always() && matrix.run_tests && (steps.run_unit_tests.outcome != 'skipped')
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: unit_test_result_ctrace-${{ matrix.target }}-${{ matrix.arch }}
@@ -223,7 +239,7 @@ jobs:
 
       - name: Archive integration test results
         # Keep the report available when test execution fails.
-        if: always() && (matrix.arch != 'arm64') && (steps.run_integration_tests.outcome != 'skipped')
+        if: always() && matrix.run_tests && (steps.run_integration_tests.outcome != 'skipped')
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: integ_test_result_ctrace-${{ matrix.target }}-${{ matrix.arch }}
@@ -256,6 +272,13 @@ jobs:
         with:
           submodules: true
 
+      - name: Install pinned Babeltrace consumer
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            babeltrace2=${{ env.BABELTRACE2_DEB_VERSION }} \
+            libbabeltrace2-0=${{ env.BABELTRACE2_DEB_VERSION }}
+
       # https://github.com/Open-CMSIS-Pack/devtools-build-action
       - name: Build CtraceUnitTests
         uses: Open-CMSIS-Pack/devtools-build-action@5b24a2b5145eb406a664269b3704bb983c19242d # arm64
@@ -276,7 +299,11 @@ jobs:
         working-directory: ./build
 
       - name: Run ctrace integration tests
-        run: ctest -V -C Debug -R '^(CtraceIntegTests|ctrace-)'
+        run: ctest -V -C Debug -R '^(CtraceIntegTests|CtraceFixtureIntegrity|ctrace-)'
+        working-directory: ./build
+
+      - name: Run pinned Babeltrace consumer test
+        run: ctest -V -C Debug --no-tests=error -L '^linux-consumer$'
         working-directory: ./build
 
       - name: Get retention days
@@ -310,6 +337,7 @@ jobs:
         working-directory: ./build/tools/ctrace
 
       - name: Generate coverage report
+        id: generate_coverage_report
         run: |
           lcov-1.15/bin/lcov --rc lcov_branch_coverage=1 --rc geninfo_no_exception_branch=1 -c --directory . --output-file full_coverage.info
           lcov-1.15/bin/lcov --rc lcov_branch_coverage=1 --rc geninfo_no_exception_branch=1 -e full_coverage.info '*/tools/ctrace/src/*' -o coverage_ctrace.info
@@ -318,6 +346,36 @@ jobs:
           lcov-1.15/bin/genhtml coverage_ctrace.info --output-directory coverage_ctrace --branch-coverage
         working-directory: ./build/tools/ctrace
 
+      - name: Enforce 100% ctrace source-line coverage
+        run: |
+          awk '
+            /^SF:/ {
+              source = substr($0, 4)
+              files += 1
+              next
+            }
+            /^DA:/ {
+              split(substr($0, 4), fields, ",")
+              lines += 1
+              if ((fields[2] + 0) == 0) {
+                printf "uncovered source line: %s:%s\n", source, fields[1]
+                missed += 1
+              }
+            }
+            END {
+              if (files == 0 || lines == 0) {
+                print "coverage gate failed: no ctrace source-line records found" > "/dev/stderr"
+                exit 2
+              }
+              printf "ctrace source-line coverage: %d/%d lines\n", lines - missed, lines
+              if (missed != 0) {
+                printf "coverage gate failed: %d source lines are uncovered\n", missed > "/dev/stderr"
+                exit 1
+              }
+            }
+          ' coverage_ctrace_codecov.info
+        working-directory: ./build/tools/ctrace
+
       - name: Upload Report to Codecov
         if: ${{ !github.event.repository.private }}
         uses: Wandalen/wretry.action@e68c23e6309f2871ca8ae4763e7629b9c258e1ea # v3.8.0
@@ -333,6 +391,7 @@ jobs:
           attempt_delay: 5000
 
       - name: Archive coverage report
+        if: ${{ always() && steps.generate_coverage_report.outcome == 'success' }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: coverage-report-ctrace

tools/ctrace/CMakeLists.txt

@@ -39,6 +39,26 @@ target_link_libraries(ctrace PRIVATE
   ctracelib
 )
 
+# GCC/gcov attributes optional NRVO cleanup and return epilogues to otherwise
+# covered source lines. Stabilize that attribution only in coverage-instrumented
+# ctrace objects; release, debug, and external-dependency builds stay unchanged.
+if(COVERAGE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+  set(CTRACE_COVERAGE_TARGETS
+    ctrace-model
+    ctrace-cli
+    ctrace-trace-run
+    ctrace-diagnostics
+    ctrace-decode
+    ctrace-output
+    ctrace-control
+    ctracelib
+    ctrace
+  )
+  foreach(target IN LISTS CTRACE_COVERAGE_TARGETS)
+    target_compile_options(${target} PRIVATE -fno-elide-constructors)
+  endforeach()
+endif()
+
 if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND
    (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR
     CMAKE_CXX_COMPILER_ID STREQUAL "Clang"))

tools/ctrace/README.md

@@ -14,7 +14,7 @@ ctrace <trace-dir> [options]
       --ctf                 Generate CTF and Trace Compass XML output
   -a, --all                 Generate all output formats
       --type <type ...>     Select event types
-      --stream <id ...>     Select CoreSight Trace Bus IDs (0 to 111)
+      --stream <id ...>     Select streams (0 for unformatted; ATB IDs 1 to 111)
   -h, --help                Print command-line help
   -V, --version             Print the version
 ```
@@ -32,7 +32,7 @@ Input and output files share a solution-set base name:
 .trace/
   Board.ctrace-run.yml
   Board.SWO.raw
-  Board.TB.raw              # optional Trace Bus input
+  Board.TB.raw              # optional Trace Buffer input
 ```
 
 For `ctrace .trace --target Board --all`, the supported input produces:
@@ -43,9 +43,19 @@ For `ctrace .trace --target Board --all`, the supported input produces:
   Board.ctf/
     metadata
     stream_0
-  Board.SWO.traceanalysis.xml
+  Board.SWO.traceanalysis.xml  # when retained streams use one clock domain; views are data-driven
 ```
 
+Without an explicit format declaration, ctrace preserves the legacy SWO-only
+selection and decodes `Board.SWO.raw` as unformatted ITM. The ctrace-private
+provisional root field `trace-format: unformatted | formatted` makes SWO, TB,
+and named-TB inputs eligible under the declared byte format; discovery then
+requires exactly one eligible input. The field does not identify a particular
+file. Formatted input currently requires complete 16-byte memory-aligned
+CoreSight frames; there is no public `trace-framing` field yet. See the
+[constraints](docs/constraints.md) for the full discovery, routing, and
+compatibility contract.
+
 ## Build and test
 
 Initialize all dependencies and configure the repository from its root:
@@ -59,9 +69,20 @@ cmake --build build --target ctrace CtraceUnitTests CtraceIntegTests
 Run the GoogleTest unit and integration suites plus the executable smoke tests:
 
 ```bash
-ctest --test-dir build -C Debug -R '^(CtraceUnitTests|CtraceIntegTests|ctrace-)'
+ctest --test-dir build -C Debug -R '^(CtraceUnitTests|CtraceIntegTests|CtraceFixtureIntegrity|ctrace-)'
+```
+
+On native Linux, installing exactly Babeltrace `2.0.5` before configuration
+also registers the external consumer gate:
+
+```bash
+ctest --test-dir build -C Debug --no-tests=error -L '^linux-consumer$'
 ```
 
+CI installs the pinned consumer and treats a missing labelled test as a
+failure. The separate versioned Trace Compass acceptance record is documented
+with the [integration tests](test/integration/README.md).
+
 Editors using `clangd` should open the devtools repository root and configure into `build`. The tool-local
 `.clangd` file points clangd at that compilation database.
 

tools/ctrace/docs/OpenCSD-NOTICE.txt

@@ -2,9 +2,8 @@ OpenCSD 1.8.3
 https://github.com/Linaro/OpenCSD
 
 The ctrace executable incorporates unmodified OpenCSD source code from the
-pinned revision. The following copyright notices are retained from the
-incorporated OpenCSD source files (capitalization and punctuation are
-preserved):
+pinned revision. The following copyright notices are retained from the pinned
+OpenCSD source tree (capitalization and punctuation are preserved):
 
 Copyright (c) 2015, ARM Limited. All Rights Reserved.
 Copyright (c) 2015, 2019 ARM Limited. All Rights Reserved.