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

@@ -108,19 +108,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 +149,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,9 +161,9 @@ 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:
@@ -200,17 +189,25 @@ jobs:
           build_type: Debug
           arch: ${{ matrix.arch }}
 
-      - name: Run ctrace unit tests
-        if: (matrix.arch != 'arm64')
-        run: ctest -C Debug -R CtraceUnitTests
+      - name: Build ctrace integration target
+        uses: Open-CMSIS-Pack/devtools-build-action@5b24a2b5145eb406a664269b3704bb983c19242d # arm64
+        with:
+          target: ctrace
+          build_type: Debug
+          arch: ${{ matrix.arch }}
+
+      - name: Run ctrace tests
+        if: matrix.arch != 'arm64'
+        run: ctest -V -C Debug -R '^(CtraceUnitTests|ctrace-)'
         working-directory: ./build
 
       - name: Archive unit tests results
+        # Keep the report available when test execution fails.
         if: always() && (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
 
@@ -222,8 +219,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 +231,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 +245,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,21 +263,24 @@ 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
+          # 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 +289,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 +304,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 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)

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,20 +30,25 @@ 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 (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 |
 |json-schema-validator|2.1.0|[MIT](https://opensource.org/licenses/MIT)|https://github.com/pboettch/json-schema-validator| yml-schema-checker |
 
 <!-- markdownlint-restore -->
+
+Dependency modifications incorporated into ctrace are documented in its
+[third-party notices](tools/ctrace/docs/THIRD_PARTY_NOTICES.md). Compiler and operating-system runtime obligations are
+artifact-specific and must be verified before publishing a ctrace release.

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

tools/ctrace/CMakeLists.txt

@@ -9,26 +9,40 @@ 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(CTRACE_GENERATED_INCLUDE_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated")
+configure_file(
+  src/cli/ProductInfo.h.in
+  "${CTRACE_GENERATED_INCLUDE_DIR}/ProductInfo.h"
+  @ONLY
+)
 
-set_property(TARGET ctracelib PROPERTY
-  MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT ctrace)
 
-# ctrace target
-add_executable(ctrace src/main.cpp)
-target_link_libraries(ctrace PRIVATE ctracelib)
+add_subdirectory(src)
 
-set_property(TARGET ctrace PROPERTY
-  MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+set(CTRACE_HEADER_FILES
+  src/CtraceMain.h
+)
+source_group("Header Files" FILES ${CTRACE_HEADER_FILES})
 
-if("${CMAKE_CXX_COMPILER_ID}" STREQUAL "GNU" OR
-   "${CMAKE_CXX_COMPILER_ID}" STREQUAL "Clang")
-  target_link_options(ctrace PUBLIC "-static")
+add_executable(ctrace
+  src/CtraceMain.cpp
+  src/main.cpp
+  ${CTRACE_HEADER_FILES}
+)
+if(CMAKE_SYSTEM_NAME STREQUAL "Windows")
+  target_sources(ctrace PRIVATE src/ctrace.manifest)
+endif()
+target_link_libraries(ctrace PRIVATE
+  ctrace::control
+)
+
+if(CMAKE_SYSTEM_NAME STREQUAL "Linux" AND
+   (CMAKE_CXX_COMPILER_ID STREQUAL "GNU" OR
+    CMAKE_CXX_COMPILER_ID STREQUAL "Clang"))
+  target_link_options(ctrace PRIVATE "-static")
 endif()
 
-enable_testing()
 add_subdirectory(test)