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/.cppcheck_suppressions

@@ -4,3 +4,34 @@ unusedFunction:libs/xmltree/src/XMLTree.cpp:47
 unusedFunction:libs/xmlschemachecker/src/XmlErrorHandler.cpp:27
 unusedFunction:libs/xmlschemachecker/src/XmlErrorHandler.cpp:32
 unusedFunction:tools/projmgr/src/ProjMgrRpcServer.cpp
+
+# OpenCSD invokes these ITraceErrorLog overrides through its external library.
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:295
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:306
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:315
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:327
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:336
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:341
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:350
+unusedFunction:tools/ctrace/src/decode/OpenCsdErrorController.cpp:355
+
+# This public metadata query is used by consumers and tests excluded from the cppcheck scan.
+unusedFunction:tools/ctrace/src/tracerun/CtraceRunMeta.cpp:542
+
+# cppcheck 2.7 treats lightweight std::string_view parameters as expensive copies.
+passedByValue:tools/ctrace/src/model/TraceSelection.cpp:84
+passedByValue:tools/ctrace/src/model/TraceSelection.cpp:96
+passedByValue:tools/ctrace/src/output/ctf/CtfMetadataWriter.cpp:148
+passedByValue:tools/ctrace/src/output/ctf/CtfSchema.hpp:87
+passedByValue:tools/ctrace/src/tracerun/TraceRunConfig.hpp:48
+passedByValue:tools/ctrace/src/tracerun/TraceRunConfig.hpp:58
+passedByValue:tools/ctrace/src/tracerun/TraceRunConfig.hpp:63
+passedByValue:tools/ctrace/src/tracerun/TraceRunConfig.hpp:68
+passedByValue:tools/ctrace/src/tracerun/TraceRunDiscovery.cpp:30
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:63
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:76
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:81
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:87
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:147
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:157
+passedByValue:tools/ctrace/src/tracerun/YmlTraceRunConfigReader.cpp:169

.github/matrix_includes_ctrace.json

@@ -1,6 +1,6 @@
 [
     {
-        "runs_on":"macos-14",
+        "runs_on":"macos-15",
         "target":"darwin",
         "arch": "arm64",
         "binary": "ctrace",

.github/workflows/ctrace.yml

@@ -1,26 +1,51 @@
 name: ctrace
 on:
   workflow_call:
+  workflow_dispatch:
   push:
     branches:
       - main
     paths:
       - '.github/workflows/ctrace.yml'
+      - '.github/workflows/shared_matrix_prep.yml'
+      - '.github/workflows/shared_setup_env.yml'
       - '.github/matrix_includes_ctrace.json'
       - 'cmake/**'
       - 'CMakeLists.txt'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/googletest'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - 'tools/ctrace/**'
       - '!**/docs/**/*'
       - '!**/*.md'
+      - 'LICENSE'
+      - 'tools/ctrace/docs/OpenCSD-NOTICE.txt'
+      - 'tools/ctrace/docs/RUNTIME_COMPONENTS.md'
+      - 'tools/ctrace/docs/THIRD_PARTY_NOTICES.md'
   pull_request:
     paths:
       - '.github/workflows/ctrace.yml'
+      - '.github/workflows/shared_matrix_prep.yml'
+      - '.github/workflows/shared_setup_env.yml'
       - '.github/matrix_includes_ctrace.json'
       - 'cmake/**'
       - 'CMakeLists.txt'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/googletest'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - 'tools/ctrace/**'
       - '!**/docs/**/*'
       - '!**/*.md'
+      - 'LICENSE'
+      - 'tools/ctrace/docs/OpenCSD-NOTICE.txt'
+      - 'tools/ctrace/docs/RUNTIME_COMPONENTS.md'
+      - 'tools/ctrace/docs/THIRD_PARTY_NOTICES.md'
   release:
     types: [published]
 
@@ -35,6 +60,31 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
+  release_metadata:
+    name: Validate ctrace release tag
+    runs-on: ubuntu-22.04
+    outputs:
+      version: ${{ steps.release_tag.outputs.version }}
+    steps:
+      - name: Harden Runner
+        if: ${{ !github.event.repository.private }}
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Validate release tag
+        id: release_tag
+        shell: bash
+        run: |
+          if [[ "${GITHUB_EVENT_NAME}" != "release" || "${GITHUB_REF_NAME}" != tools/ctrace/* ]]; then
+            exit 0
+          fi
+          if [[ ! "${GITHUB_REF_NAME}" =~ ^tools/ctrace/(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]; then
+            echo "Expected a stable SemVer tag named tools/ctrace/<major>.<minor>.<patch>, got '${GITHUB_REF_NAME}'" >&2
+            exit 1
+          fi
+          echo "version=${GITHUB_REF_NAME#tools/ctrace/}" >> "${GITHUB_OUTPUT}"
+
   setup:
     uses: ./.github/workflows/shared_setup_env.yml
     with:
@@ -47,7 +97,7 @@ jobs:
       workflow_name: ctrace
 
   build:
-    needs: [ setup, matrix_prep ]
+    needs: [ release_metadata, setup, matrix_prep ]
     runs-on: ${{ matrix.runs_on }}
     name: build (${{ matrix.runs_on }}, ${{ matrix.arch }})
     timeout-minutes: 25
@@ -74,6 +124,30 @@ jobs:
           target: ctrace
           arch: ${{ matrix.arch }}
 
+      - name: Run ctrace integration tests
+        if: (matrix.target != 'windows' || matrix.arch != 'arm64')
+        run: ctest -V -C Release -R '^ctrace-'
+        working-directory: ./build
+
+      - name: Verify Windows Arm64 binary architecture
+        if: (matrix.target == 'windows' && matrix.arch == 'arm64')
+        shell: pwsh
+        run: |
+          $binaryPath = "./build/tools/ctrace/${{ matrix.target }}-${{ matrix.arch }}/Release/${{ matrix.binary }}"
+          $bytes = [System.IO.File]::ReadAllBytes($binaryPath)
+          if ($bytes.Length -lt 64) {
+            throw "ctrace.exe is too short to contain a valid PE header"
+          }
+          $peOffset = [System.BitConverter]::ToUInt32($bytes, 0x3c)
+          if ($peOffset + 6 -gt $bytes.Length) {
+            throw "ctrace.exe contains an invalid PE header offset"
+          }
+          $signature = [System.Text.Encoding]::ASCII.GetString($bytes, $peOffset, 4)
+          $machine = [System.BitConverter]::ToUInt16($bytes, $peOffset + 4)
+          if ($signature -ne "PE`0`0" -or $machine -ne 0xAA64) {
+            throw "ctrace.exe is not an Arm64 PE binary (machine 0x$($machine.ToString('X4')))"
+          }
+
       - name: Install strip tools
         if: |
           github.event_name == 'release' &&
@@ -96,6 +170,38 @@ jobs:
             strip "$binary_path"
           fi
 
+      - name: Smoke-test release binary
+        if: |
+          github.event_name == 'release' &&
+          (matrix.target != 'windows' || matrix.arch != 'arm64')
+        shell: bash
+        run: |
+          binary_path="./build/tools/ctrace/${{ matrix.target }}-${{ matrix.arch }}/Release/${{ matrix.binary }}"
+          if [[ "${{ matrix.target }}" == "linux" && "${{ matrix.arch }}" == "arm64" ]]; then
+            actual_version="$(qemu-aarch64 -L /usr/aarch64-linux-gnu "$binary_path" --version)"
+          else
+            actual_version="$("$binary_path" --version)"
+          fi
+          actual_version="${actual_version%$'\r'}"
+          expected_version="ctrace ${{ needs.release_metadata.outputs.version }}"
+          if [[ "$actual_version" != "$expected_version" ]]; then
+            echo "Expected '$expected_version', got '$actual_version'" >&2
+            exit 1
+          fi
+
+      - name: Dry-run ctrace package assembly
+        if: matrix.target == 'linux' && matrix.arch == 'amd64'
+        shell: bash
+        run: |
+          binary_path="${GITHUB_WORKSPACE}/build/tools/ctrace/${{ matrix.target }}-${{ matrix.arch }}/Release/${{ matrix.binary }}"
+          cmake \
+            -DCTRACE_SOURCE_DIR="${GITHUB_WORKSPACE}" \
+            -DCTRACE_DISTRIBUTION_DIR="${RUNNER_TEMP}/ctrace-package-dry-run" \
+            -DCTRACE_STAGE_BINARY="$binary_path" \
+            -DCTRACE_STAGE_PATH="bin/${{ matrix.target }}-${{ matrix.arch }}/${{ matrix.binary }}" \
+            -DCTRACE_EXPECTED_BINARIES="bin/${{ matrix.target }}-${{ matrix.arch }}/${{ matrix.binary }}" \
+            -P tools/ctrace/cmake/PackageCtrace.cmake
+
       - name: Archive ctrace
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -108,19 +214,22 @@ jobs:
     if: |
       github.event_name == 'release' &&
       startsWith(github.ref, 'refs/tags/tools/ctrace/')
-    needs: [ build, unittest, coverage ]
+    needs: [ build, unittest, coverage, release_metadata ]
     runs-on: ubuntu-22.04
     timeout-minutes: 25
     permissions:
       contents: write
     steps:
+      - name: Harden Runner
+        if: ${{ !github.event.repository.private }}
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
       - 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 +261,13 @@ jobs:
           name: ctrace-windows-arm64
           path: tools/ctrace/distribution/bin/windows-arm64/
 
-      - name: Set Unix executable permissions
+      - name: Verify and package distribution
         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
+          cmake \
+            -DCTRACE_SOURCE_DIR="${GITHUB_WORKSPACE}" \
+            -DCTRACE_DISTRIBUTION_DIR="${GITHUB_WORKSPACE}/tools/ctrace/distribution" \
+            -DCTRACE_EXPECTED_BINARIES="bin/darwin-arm64/ctrace|bin/linux-amd64/ctrace|bin/linux-arm64/ctrace|bin/windows-amd64/ctrace.exe|bin/windows-arm64/ctrace.exe" \
+            -P tools/ctrace/cmake/PackageCtrace.cmake
 
       - name: Attach zip archive to release assets
         uses: svenstaro/upload-release-action@29e53e917877a24fad85510ded594ab3c9ca12de # v2
@@ -172,8 +278,17 @@ jobs:
           overwrite: true
           asset_name: ctrace.zip
 
+      - name: Attach archive checksum to release assets
+        uses: svenstaro/upload-release-action@29e53e917877a24fad85510ded594ab3c9ca12de # v2
+        with:
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          file: tools/ctrace/distribution/ctrace.zip.sha256
+          tag: ${{ github.ref }}
+          overwrite: true
+          asset_name: ctrace.zip.sha256
+
   unittest:
-    needs: [ setup, matrix_prep ]
+    needs: [ release_metadata, setup, matrix_prep ]
     name: unittest (${{ matrix.runs_on }}, ${{ matrix.arch }})
     runs-on: ${{ matrix.runs_on }}
     timeout-minutes: 25
@@ -201,16 +316,16 @@ jobs:
           arch: ${{ matrix.arch }}
 
       - name: Run ctrace unit tests
-        if: (matrix.arch != 'arm64')
+        if: (matrix.target != 'windows' || matrix.arch != 'arm64')
         run: ctest -C Debug -R CtraceUnitTests
         working-directory: ./build
 
       - name: Archive unit tests results
-        if: always() && (matrix.arch != 'arm64')
+        if: always() && (matrix.target != 'windows' || matrix.arch != 'arm64')
         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.*.xml
           retention-days: ${{ needs.setup.outputs.retention_days }}
           if-no-files-found: error
 
@@ -221,9 +336,11 @@ jobs:
       (github.event_name == 'push') ||
       (github.event_name == 'release' && startsWith(github.ref, 'refs/tags/tools/ctrace/')) ||
       ((github.event.schedule != '') && (!github.event.repository.private))
+    needs: [ release_metadata ]
     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 +350,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,8 +364,12 @@ 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 tests
+        run: ctest -V -C Debug -R '^(CtraceUnitTests|ctrace-)'
         working-directory: ./build
 
       - name: Get retention days
@@ -266,28 +382,29 @@ jobs:
         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.*.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
+          lcov-1.15/bin/genhtml coverage_ctrace.info --output-directory coverage_ctrace --branch-coverage
         working-directory: ./build/tools/ctrace
 
       - name: Upload Report to Codecov
         if: ${{ !github.event.repository.private }}
         uses: Wandalen/wretry.action@e68c23e6309f2871ca8ae4763e7629b9c258e1ea # v3.8.0
         with:
-          action: codecov/codecov-action@v4
+          action: codecov/codecov-action@b9fd7d16f6d7d1b5d2bec1a2887e65ceed900238 # v4.6.0
           with: |
             files: ./build/tools/ctrace/coverage_ctrace.info
             fail_ci_if_error: true

.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 private 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)