ctrace initial development

.gitattributes

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

.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/codeql-analysis.yml

@@ -6,11 +6,22 @@ on:
     branches: [ main ]
     paths:
       - '.github/workflows/codeql-analysis.yml'
+      - '.github/codeql-config.yml'
+      - '.gitmodules'
       - '**/*.c'
+      - '**/*.cc'
       - '**/*.cpp'
       - '**/*.h'
+      - '**/*.hpp'
       - '**/*.in'
       - '**/CMakeLists.txt'
+      - '**/*.cmake'
+      - 'cmake/**'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - '!**/*.md'
   push:
     branches: [ main ]

.github/workflows/ctrace.yml

@@ -1,23 +1,40 @@
 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'
+      - '.gitmodules'
       - 'cmake/**'
       - 'CMakeLists.txt'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - 'tools/ctrace/**'
       - '!**/docs/**/*'
       - '!**/*.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'
+      - '.gitmodules'
       - 'cmake/**'
       - 'CMakeLists.txt'
+      - 'external/OpenCSD'
+      - 'external/cxxopts'
+      - 'external/cxxopts.patch'
+      - 'external/yaml-cpp'
+      - 'external/yaml-cpp.patch'
       - 'tools/ctrace/**'
       - '!**/docs/**/*'
       - '!**/*.md'
@@ -74,6 +91,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 +137,19 @@ 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
+            qemu-aarch64 -L /usr/aarch64-linux-gnu "$binary_path" --version
+          else
+            "$binary_path" --version
+          fi
+
       - name: Archive ctrace
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -116,11 +170,18 @@ jobs:
     steps:
       - name: Checkout devtools
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: true
 
       - name: Create distribution folders
         run: |
           mkdir -p tools/ctrace/distribution/bin
-          cp LICENSE tools/ctrace/distribution/
+          mkdir -p tools/ctrace/distribution/THIRD_PARTY_LICENSES
+          cp LICENSE tools/ctrace/distribution/LICENSE.txt
+          cp tools/ctrace/docs/THIRD_PARTY_NOTICES.md tools/ctrace/distribution/
+          cp external/cxxopts/LICENSE tools/ctrace/distribution/THIRD_PARTY_LICENSES/cxxopts.txt
+          cp external/yaml-cpp/LICENSE tools/ctrace/distribution/THIRD_PARTY_LICENSES/yaml-cpp.txt
+          cp external/OpenCSD/LICENSE tools/ctrace/distribution/THIRD_PARTY_LICENSES/OpenCSD.txt
 
       - name: Download ctrace linux-amd64
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -159,8 +220,13 @@ jobs:
           chmod +x bin/linux-arm64/ctrace
         working-directory: tools/ctrace/distribution
 
-      - name: Zip distribution folder
-        run: zip -r ctrace.zip *
+      - name: Verify and zip distribution
+        run: |
+          find bin THIRD_PARTY_LICENSES -type f -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
+          sha256sum LICENSE.txt THIRD_PARTY_NOTICES.md >> SHA256SUMS
+          sha256sum --check SHA256SUMS
+          zip -r ctrace.zip bin LICENSE.txt THIRD_PARTY_LICENSES THIRD_PARTY_NOTICES.md SHA256SUMS
+          sha256sum ctrace.zip > ctrace.zip.sha256
         working-directory: tools/ctrace/distribution
 
       - name: Attach zip archive to release assets
@@ -172,6 +238,15 @@ 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 ]
     name: unittest (${{ matrix.runs_on }}, ${{ matrix.arch }})
@@ -201,16 +276,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
 
@@ -252,8 +327,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,7 +345,7 @@ 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
 
@@ -279,7 +358,7 @@ jobs:
       - 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
+          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
           genhtml coverage_ctrace.info --output-directory coverage_ctrace --branch-coverage
         working-directory: ./build/tools/ctrace
 

.github/workflows/shared_matrix_prep.yml

@@ -39,6 +39,6 @@ jobs:
       - id: set-matrix
         run: |
           publicRepo=$(echo '${{ github.event.repository.private && 'privateRepo' || 'publicRepo' }}')
-          matrix=$(jq --arg publicRepo "$publicRepo" 'map(. | select((.runOn==$publicRepo) or (.runOn=="always")) )' matrix_includes_${{ inputs.workflow_name }}.json)
-          echo "matrix={\"include\":$(echo $matrix)}\"" >> $GITHUB_OUTPUT
+          matrix=$(jq -c --arg publicRepo "$publicRepo" '{include: map(select(.runOn == $publicRepo or .runOn == "always"))}' matrix_includes_${{ inputs.workflow_name }}.json)
+          echo "matrix=${matrix}" >> "$GITHUB_OUTPUT"
         working-directory: .github/

.github/workflows/shared_setup_env.yml

@@ -5,7 +5,6 @@ on:
     inputs:
       run_if:
         description: 'True if workflow needs to run'
-        default: false
         required: true
         type: boolean
     outputs:

.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
+if(NOT LIBS_ONLY)
+  include(tools/ctrace/cmake/dependencies/ConfigureOpenCSD.cmake)
+endif()
+
 # Google Test Framework
 set(INSTALL_GTEST OFF CACHE BOOL "" FORCE)
 add_subdirectory(external/googletest)

LICENSE.md

@@ -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 |
+|Google C++ Testing Framework|1.16.0|[BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)|https://github.com/google/googletest.git| Testing |
+|cxxopts|3.0.0|[MIT](https://opensource.org/licenses/MIT)|https://github.com/jarro2783/cxxopts.git| packgen, ctrace (statically incorporated) |
+|yaml-cpp|0.8.0|[MIT](https://opensource.org/licenses/MIT)|https://github.com/jbeder/yaml-cpp.git| packgen, ctrace (statically linked) |
+|OpenCSD|1.8.3|[BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause)|https://github.com/Linaro/OpenCSD.git| ctrace (statically linked) |
 |[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,17 @@
+---
+BasedOnStyle: LLVM
+IndentWidth: 2
+ContinuationIndentWidth: 4
+ConstructorInitializerIndentWidth: 2
+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

tools/ctrace/CMakeLists.txt

@@ -9,21 +9,34 @@ get_version_from_git_tag("tools/ctrace/")
 project(ctrace VERSION "${PROJECT_VERSION}")
 dump_cmake_project_version()
 
-set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT ctrace)
-
-# ctrace library
-add_library(ctracelib OBJECT src/CtraceMain.cpp include/CtraceMain.h)
-target_include_directories(ctracelib PUBLIC include)
+set(CTRACE_VERSION_FULL "${PROJECT_VERSION_FULL}")
+set(CTRACE_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
 
-set_property(TARGET ctracelib PROPERTY
-  MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
-
-# ctrace target
-add_executable(ctrace src/main.cpp)
-target_link_libraries(ctrace PRIVATE ctracelib)
+set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT ctrace)
 
-set_property(TARGET ctrace PROPERTY
-  MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+function(ctrace_configure_target target)
+  target_compile_definitions(${target} PRIVATE
+    $<$<PLATFORM_ID:Windows>:NOMINMAX>
+  )
+  target_compile_options(${target} PRIVATE
+    $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wall>
+    $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wextra>
+    $<$<CXX_COMPILER_ID:AppleClang,Clang,GNU>:-Wpedantic>
+    $<$<CXX_COMPILER_ID:MSVC>:/W4>
+  )
+endfunction()
+
+add_subdirectory(src)
+
+add_executable(ctrace
+  src/CtraceMain.cpp
+  src/CtraceMain.hpp
+  src/main.cpp
+)
+target_link_libraries(ctrace PRIVATE
+  ctrace::control
+)
+ctrace_configure_target(ctrace)
 
 if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" OR
    "${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")