ctrace initial development

.gitattributes

@@ -46,3 +46,4 @@
 # Denote all files that are truly binary and should not be modified.
 *.png binary
 *.jpg binary
+tools/ctrace/test/data/**/*.raw binary

.github/workflows/ctrace.yml

@@ -7,17 +7,31 @@ on:
     paths:
       - '.github/workflows/ctrace.yml'
       - '.github/matrix_includes_ctrace.json'
+      - '.gitmodules'
       - 'cmake/**'
       - 'CMakeLists.txt'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/googletest'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - 'tools/ctrace/**'
       - '!**/docs/**/*'
       - '!**/*.md'
   pull_request:
     paths:
       - '.github/workflows/ctrace.yml'
       - '.github/matrix_includes_ctrace.json'
+      - '.gitmodules'
       - 'cmake/**'
       - 'CMakeLists.txt'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/googletest'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - 'tools/ctrace/**'
       - '!**/docs/**/*'
       - '!**/*.md'
@@ -108,19 +122,16 @@ jobs:
     if: |
       github.event_name == 'release' &&
       startsWith(github.ref, 'refs/tags/tools/ctrace/')
-    needs: [ build, unittest, coverage ]
+    needs: [ build, test, coverage ]
     runs-on: ubuntu-22.04
     timeout-minutes: 25
     permissions:
       contents: write
     steps:
       - name: Checkout devtools
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-
-      - name: Create distribution folders
-        run: |
-          mkdir -p tools/ctrace/distribution/bin
-          cp LICENSE tools/ctrace/distribution/
+        with:
+          submodules: true
 
       - name: Download ctrace linux-amd64
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -152,16 +163,8 @@ jobs:
           name: ctrace-windows-arm64
           path: tools/ctrace/distribution/bin/windows-arm64/
 
-      - name: Set Unix executable permissions
-        run: |
-          chmod +x bin/darwin-arm64/ctrace
-          chmod +x bin/linux-amd64/ctrace
-          chmod +x bin/linux-arm64/ctrace
-        working-directory: tools/ctrace/distribution
-
-      - name: Zip distribution folder
-        run: zip -r ctrace.zip *
-        working-directory: tools/ctrace/distribution
+      - name: Verify and package distribution
+        run: tools/ctrace/scripts/package-release.sh
 
       - name: Attach zip archive to release assets
         uses: svenstaro/upload-release-action@29e53e917877a24fad85510ded594ab3c9ca12de # v2
@@ -172,13 +175,13 @@ jobs:
           overwrite: true
           asset_name: ctrace.zip
 
-  unittest:
+  test:
     needs: [ setup, matrix_prep ]
-    name: unittest (${{ matrix.runs_on }}, ${{ matrix.arch }})
+    name: test (${{ matrix.runs_on }}, ${{ matrix.arch }})
     runs-on: ${{ matrix.runs_on }}
     timeout-minutes: 25
     strategy:
-      fail-fast: true
+      fail-fast: false
       matrix: ${{ fromJson(needs.matrix_prep.outputs.matrix) }}
     steps:
       - name: Harden Runner
@@ -194,23 +197,47 @@ jobs:
 
       # https://github.com/Open-CMSIS-Pack/devtools-build-action
       - name: Build CtraceUnitTests
+        id: build_unit_tests
         uses: Open-CMSIS-Pack/devtools-build-action@5b24a2b5145eb406a664269b3704bb983c19242d # arm64
         with:
           target: CtraceUnitTests
           build_type: Debug
           arch: ${{ matrix.arch }}
 
+      - name: Build ctrace integration target
+        id: build_integration_target
+        run: cmake --build . --target ctrace
+        working-directory: ./build
+
       - name: Run ctrace unit tests
-        if: (matrix.arch != 'arm64')
-        run: ctest -C Debug -R CtraceUnitTests
+        id: run_unit_tests
+        if: always() && (matrix.arch != 'arm64') && (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 '^ctrace-' --output-junit test_reports/ctraceintegtests-report-${{ matrix.target }}-${{ matrix.arch }}.xml
         working-directory: ./build
 
-      - name: Archive unit tests results
-        if: always() && (matrix.arch != 'arm64')
+      - name: Archive unit test results
+        # Keep the report available when test execution fails.
+        if: always() && (matrix.arch != 'arm64') && (steps.run_unit_tests.outcome != 'skipped')
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: unit_test_result_ctrace-${{ matrix.target }}-${{ matrix.arch }}
-          path: ./build/test_reports/ctraceunittests-*.xml
+          path: ./build/test_reports/ctraceunittests-report-${{ matrix.target }}-${{ matrix.arch }}.xml
+          retention-days: ${{ needs.setup.outputs.retention_days }}
+          if-no-files-found: error
+
+      - name: Archive integration test results
+        # Keep the report available when test execution fails.
+        if: always() && (matrix.arch != 'arm64') && (steps.run_integration_tests.outcome != 'skipped')
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: integ_test_result_ctrace-${{ matrix.target }}-${{ matrix.arch }}
+          path: ./build/test_reports/ctraceintegtests-report-${{ matrix.target }}-${{ matrix.arch }}.xml
           retention-days: ${{ needs.setup.outputs.retention_days }}
           if-no-files-found: error
 
@@ -222,8 +249,9 @@ jobs:
       (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/tools/ctrace/')) ||
       ((github.event.schedule != '') && (!github.event.repository.private))
     env:
-      lcov_base: https://github.com/linux-test-project/lcov/releases/download/v1.15/
+      lcov_base: https://github.com/linux-test-project/lcov/releases/download/v1.15
       lcov_installer: lcov-1.15.tar.gz
+      lcov_sha256: c1cda2fa33bec9aa2c2c73c87226cfe97de0831887176b45ee523c5e30f8053a
     runs-on: ubuntu-22.04
     timeout-minutes: 25
     steps:
@@ -233,11 +261,6 @@ jobs:
         with:
           egress-policy: audit
 
-      - name: Install linux deps
-        run: |
-          sudo apt-get update
-          sudo apt-get install lcov
-
       - name: Checkout devtools
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -252,35 +275,55 @@ jobs:
           build_type: Debug
           target: CtraceUnitTests
 
-      - name: Run CtraceUnitTests
-        run: ctest -V -C Debug -R CtraceUnitTests
+      - name: Build ctrace integration target
+        run: cmake --build . --target ctrace
+        working-directory: ./build
+
+      - name: Run ctrace unit tests
+        run: ctest -V -C Debug -R '^CtraceUnitTests$'
+        working-directory: ./build
+
+      - name: Run ctrace integration tests
+        run: ctest -V -C Debug -R '^ctrace-' --output-junit test_reports/ctraceintegtests-report-linux-amd64.xml
         working-directory: ./build
 
       - name: Get retention days
         id: var
         run: |
           echo "retention_days=$(echo '${{ (!github.event.repository.private && (github.event_name == 'push' || github.event.schedule != '')) && '7' || '1' }}')" >> $GITHUB_OUTPUT
 
-      - name: Archive unit tests results
+      - name: Archive unit test results
         if: (github.event_name == 'push')
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: unit_test_result_ctrace-linux-amd64
-          path: ./build/test_reports/ctraceunittests-*.xml
+          path: ./build/test_reports/ctraceunittests-report-linux-amd64.xml
+          retention-days: ${{ steps.var.outputs.retention_days }}
+          if-no-files-found: error
+
+      - name: Archive integration test results
+        if: (github.event_name == 'push')
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: integ_test_result_ctrace-linux-amd64
+          path: ./build/test_reports/ctraceintegtests-report-linux-amd64.xml
           retention-days: ${{ steps.var.outputs.retention_days }}
           if-no-files-found: error
 
       - name: Setup lcov1.15
         run: |
           wget -q ${{ env.lcov_base }}/${{ env.lcov_installer }}
+          echo "${{ env.lcov_sha256 }}  ${{ env.lcov_installer }}" | sha256sum --check --strict
           tar -xvf ${{ env.lcov_installer }}
         working-directory: ./build/tools/ctrace
 
       - name: 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/include/*' '*/tools/ctrace/src/*' -o coverage_ctrace.info
-          genhtml coverage_ctrace.info --output-directory coverage_ctrace --branch-coverage
+          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
+          # Preserve unfiltered branch data for review, but gate on portable source-line coverage.
+          lcov-1.15/bin/lcov --rc lcov_branch_coverage=0 -e full_coverage.info '*/tools/ctrace/src/*' -o coverage_ctrace_codecov.info
+          lcov-1.15/bin/genhtml coverage_ctrace.info --output-directory coverage_ctrace --branch-coverage
         working-directory: ./build/tools/ctrace
 
       - name: Upload Report to Codecov
@@ -289,7 +332,7 @@ jobs:
         with:
           action: codecov/codecov-action@v4
           with: |
-            files: ./build/tools/ctrace/coverage_ctrace.info
+            files: ./build/tools/ctrace/coverage_ctrace_codecov.info
             fail_ci_if_error: true
             flags: ctrace-cov
             token: ${{ secrets.CODECOV_TOKEN }}
@@ -304,13 +347,15 @@ jobs:
           path: |
             ./build/tools/ctrace/coverage_ctrace/
             ./build/tools/ctrace/coverage_ctrace.info
+            ./build/tools/ctrace/coverage_ctrace_codecov.info
           retention-days: ${{ steps.var.outputs.retention_days }}
           if-no-files-found: error
 
   test-results-preparation:
     name: "Publish Tests Results"
+    # A dependent reporting job is otherwise skipped after a test failure.
     if: ${{ always() }}
-    needs: [ unittest ]
+    needs: [ test ]
     runs-on: ubuntu-22.04
     steps:
       - name: Harden Runner

.gitmodules

@@ -32,3 +32,6 @@
 [submodule "external/json-rpc-cxx"]
 	path = external/json-rpc-cxx
 	url = https://github.com/jsonrpcx/json-rpc-cxx.git
+[submodule "external/OpenCSD"]
+	path = external/OpenCSD
+	url = https://github.com/Linaro/OpenCSD.git

CMakeLists.txt

@@ -158,6 +158,11 @@ apply_patch(${CMAKE_CURRENT_SOURCE_DIR}/external/cxxopts)
 apply_patch(${CMAKE_CURRENT_SOURCE_DIR}/external/xerces-c)
 apply_patch(${CMAKE_CURRENT_SOURCE_DIR}/external/yaml-cpp)
 
+# OpenCSD is a build dependency of ctrace.
+if(TARGET ctrace)
+  include(tools/ctrace/cmake/dependencies/ConfigureOpenCSD.cmake)
+endif()
+
 # Google Test Framework
 set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
 add_subdirectory(external/googletest)

LICENSE.md

@@ -1,6 +1,6 @@
 # License Terms
 
-Copyright 2020-2021 Arm Limited. All rights reserved.
+Copyright 2020-2026 Arm Limited. All rights reserved.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -30,17 +30,18 @@ from https://github.com/ARM-software/CMSIS_5/tree/develop/Device/ARM.
 
 ## External Dependencies
 
-The components listed below are not redistributed with the project but are used internally for building, development,
-or testing purposes.
+The components listed below are used for building, development, testing, or are incorporated into distributed tool
+binaries as indicated by the Usage column.
 
 <!-- markdownlint-capture -->
 <!-- markdownlint-disable MD013 -->
 
 | Component | Version | License | Origin | Usage |
 | --------- | ------- | ------- | ------ | ----- |
 |Google C++ Testing Framework|1.11.0|[BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)|https://github.com/google/googletest.git| Testing |
-|cxxopts|2.2.1|[MIT](https://opensource.org/licenses/MIT)|https://github.com/jarro2783/cxxopts.git| packgen |
-|yaml-cpp|0.7.0|[MIT](https://opensource.org/licenses/MIT)|https://github.com/jbeder/yaml-cpp.git| packgen |
+|cxxopts|3.0.0|[MIT](https://opensource.org/licenses/MIT)|https://github.com/jarro2783/cxxopts.git| packgen, ctrace |
+|yaml-cpp|0.8.0|[MIT](https://opensource.org/licenses/MIT)|https://github.com/jbeder/yaml-cpp.git| packgen, ctrace |
+|OpenCSD|1.8.3|[BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)|https://github.com/Linaro/OpenCSD.git| ctrace |
 |[GetGitRevisionDescription.cmake](./cmake/GetGitRevisionDescription.cmake)||[Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt)||Continuous integration|
 |[GetGitRevisionDescription.cmake.in](./cmake/GetGitRevisionDescription.cmake.in)||[Boost Software License, Version 1.0](http://www.boost.org/LICENSE_1_0.txt)||Continuous integration|
 |json|3.10.5|[MIT](https://opensource.org/licenses/MIT)|https://github.com/nlohmann/json| yml-schema-checker |

external/CONTENT.md

@@ -6,6 +6,7 @@ should be committed into this folder.
 
 ```txt
     📂external
+    ┣ 📂OpenCSD
     ┣ 📂cxxopts
     ┣ 📂fmt
     ┣ 📂googletest
@@ -14,6 +15,13 @@ should be committed into this folder.
     ┗ 📂yaml-cpp
 ```
 
+## OpenCSD
+
+<!-- markdown-link-check-disable-next-line -->
+The [OpenCSD](./OpenCSD) directory contains the CoreSight trace decode library
+used by ctrace and is fetched from
+[here](https://github.com/Linaro/OpenCSD).
+
 ## cxxopts
 
 <!-- markdown-link-check-disable-next-line -->

tools/ctrace/.clang-format

@@ -0,0 +1,18 @@
+---
+BasedOnStyle: LLVM
+IndentWidth: 2
+ContinuationIndentWidth: 4
+ConstructorInitializerIndentWidth: 2
+PackConstructorInitializers: Never
+TabWidth: 2
+UseTab: Never
+ColumnLimit: 120
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterFunction: true
+PointerAlignment: Left
+DerivePointerAlignment: false
+SortIncludes: Never
+SpaceBeforeParens: ControlStatements
+AllowShortFunctionsOnASingleLine: Empty
+...

tools/ctrace/.clangd

@@ -0,0 +1,5 @@
+CompileFlags:
+  CompilationDatabase: ../../build
+Diagnostics:
+  UnusedIncludes: Strict
+  MissingIncludes: Strict