Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .cppreportcard.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
],
"tidy_checks": "-*,clang-analyzer-*,bugprone-*",
"format_style": "LLVM",
"timeout_seconds": 300,
"timeout_seconds": 400,
"jobs": 4,
"tools": {
"clang-format": "clang-format-18",
Expand Down
96 changes: 93 additions & 3 deletions .github/workflows/sanitizers.yml
Original file line number Diff line number Diff line change
Expand Up @@ -62,13 +62,14 @@ jobs:
--compiler g++-13

sanitizers:
name: ASan and UBSan
name: ASan, UBSan and LSan
runs-on: ubuntu-24.04
timeout-minutes: 30
env:
CC: gcc-13
CXX: g++-13
ASAN_OPTIONS: detect_leaks=0:halt_on_error=1:strict_string_checks=1
ASAN_OPTIONS: detect_leaks=1:halt_on_error=1:strict_string_checks=1
LSAN_OPTIONS: exitcode=23
UBSAN_OPTIONS: print_stacktrace=1:halt_on_error=1

steps:
Expand Down Expand Up @@ -116,4 +117,93 @@ jobs:

- name: Run sanitizer tests
working-directory: hand-cpp
run: ctest --test-dir build-sanitized --output-on-failure --timeout 180
run: |
ctest --test-dir build-sanitized --output-on-failure --no-tests=error \
--timeout 180 --output-junit "$PWD/build-sanitized/sanitizer-tests.xml"

- name: Upload sanitizer diagnostics
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: asan-ubsan-lsan-diagnostics
if-no-files-found: warn
path: |
hand-cpp/build-sanitized/sanitizer-tests.xml
hand-cpp/build-sanitized/Testing/Temporary/

thread-sanitizer:
name: TSan
runs-on: ubuntu-24.04
timeout-minutes: 45
env:
CC: clang-18
CXX: clang++-18
TSAN_OPTIONS: halt_on_error=1:exitcode=66:second_deadlock_stack=1:external_symbolizer_path=/usr/bin/llvm-symbolizer-18

steps:
- name: Set offline configuration directory
run: echo "XDG_CONFIG_HOME=${RUNNER_TEMP}/xdg-config" >> "$GITHUB_ENV"

- name: Check out hand SDK
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
path: hand-cpp

- name: Check out communication library
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
repository: ${{ env.COMM_REPOSITORY }}
ref: ${{ env.COMM_REF }}
path: linkerbot-transport-cpp
token: ${{ secrets.LINKERBOT_COMM_TOKEN || github.token }}

- name: Install build tools
run: |
sudo apt-get update
sudo apt-get install -y --no-install-recommends \
cmake ninja-build gcc-13 g++-13 clang-18 libclang-rt-18-dev llvm-18

- name: Configure TSan address space
# TSan needs a compatible shadow-memory layout with Ubuntu 24.04's ASLR.
# This setting affects only this ephemeral runner.
run: sudo sysctl -w vm.mmap_rnd_bits=28

- name: Configure TSan build
working-directory: hand-cpp
run: |
# Clang otherwise selects the runner's newest GCC installation, which
# can have incompatible timed-mutex headers. Match the tested GCC 13 baseline.
gcc_install_dir="$(dirname "$(gcc-13 -print-libgcc-file-name)")"
cmake -S . -B build-tsan -G Ninja \
-DCMAKE_BUILD_TYPE=Debug \
-DCMAKE_CXX_FLAGS="--gcc-install-dir=${gcc_install_dir} -O1 -fsanitize=thread -fno-omit-frame-pointer" \
-DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread" \
-DCMAKE_SHARED_LINKER_FLAGS="-fsanitize=thread" \
-DLINKERBOT_COMM_SOURCE_DIR="${GITHUB_WORKSPACE}/linkerbot-transport-cpp" \
-DLINKERBOT_BUILD_EXAMPLES=OFF \
-DLINKERBOT_BUILD_TESTS=ON \
-DLINKERBOT_ISOLATE_OFFLINE_TESTS=ON \
-DLINKERBOT_BUILD_TOOLS=ON \
-DLINKERBOT_COMM_BUILD_TESTS=OFF

- name: Build TSan test targets
working-directory: hand-cpp
run: |
cmake --build build-tsan --parallel 4 --target \
tests protocol-tests l6_read_version l6_frequency_benchmark

- name: Run TSan tests
working-directory: hand-cpp
run: |
ctest --test-dir build-tsan --output-on-failure --no-tests=error \
--timeout 300 --output-junit "$PWD/build-tsan/tsan-tests.xml"

- name: Upload TSan diagnostics
if: always()
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: tsan-diagnostics
if-no-files-found: warn
path: |
hand-cpp/build-tsan/tsan-tests.xml
hand-cpp/build-tsan/Testing/Temporary/
29 changes: 29 additions & 0 deletions docs/en/guides/quality.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,35 @@

[English](quality.md) | [简体中文](../../zh/guides/quality.md)

## Runtime sanitizers

The `Sanitizers` workflow runs two independent Linux Debug builds against the pinned
transport source. `ASan, UBSan and LSan` checks memory access, undefined behavior and
leaks (`detect_leaks=1`); `TSan` checks data races in a separate Clang 18 build using
`-fsanitize=thread`. Both run the registered offline CTest suite, including communication,
Python-policy, discovery and protocol regressions. They do not open real CAN devices.
SDK and paired transport sources are instrumented together. Findings fail the job;
CTest logs and JUnit results are uploaded even after failures.

The TSan build enables `LINKERBOT_ISOLATE_OFFLINE_TESTS`: Catch2 discovers every
`[comm]` and `[discovery]` case and CTest runs each test name in its own process.
Cases sharing a name remain selected together by Catch2. This prevents
libstdc++'s trivial mutex destruction and stack-address reuse between cases from
creating stale lock-order cycles. Data-race and deadlock detection remain enabled
within each case. The normal ASan/UBSan/LSan build keeps the grouped test layout.

The TSan job explicitly selects the GCC 13 libstdc++ headers and libraries with
Clang's `--gcc-install-dir`; runner image updates must not silently select a newer
GCC installation. Clang 18 with the runner's GCC 14 headers fails to compile the
SDK's timed-mutex calls, before sanitizer tests can run.

Clang 18 TSan recognizes the `pthread_mutex_clocklock` calls used by libstdc++ timed
mutexes; the GCC runtime on Ubuntu 24.04 reports false unlock errors for these calls.
TSan also needs a compatible shadow-memory layout. Its job sets `vm.mmap_rnd_bits=28`
on the ephemeral Ubuntu runner before testing. Local environments need a compatible
layout too; an initialization failure is not a clean race check. Runtime sanitizers
cover only executed paths and do not replace static analysis or hardware acceptance.

## Report Card

The `C++ Report Card` workflow runs on PRs, main/master pushes and manual dispatch.
Expand Down
25 changes: 25 additions & 0 deletions docs/zh/guides/quality.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,31 @@

[English](../../en/guides/quality.md) | [简体中文](quality.md)

## 运行时检测

`Sanitizers` 工作流基于固定的 transport 源码,运行两套独立的 Linux Debug 构建。
`ASan, UBSan and LSan` 检查内存访问、未定义行为和泄漏(`detect_leaks=1`);
`TSan` 使用独立的 Clang 18 `-fsanitize=thread` 构建检查数据竞争。两者都运行已注册的离线
CTest 测试,包括通信、Python 策略、发现和协议回归,不打开真实 CAN 设备。
SDK 与配套 transport 源码一起插桩。检测到问题会使任务失败;失败后仍上传
CTest 日志和 JUnit 测试结果。

TSan 构建开启 `LINKERBOT_ISOLATE_OFFLINE_TESTS`:Catch2 发现全部 `[comm]` 和
`[discovery]` 用例,CTest 按用例名称启动独立进程,同名用例仍由 Catch2 一起匹配。
这样可避免 libstdc++ 互斥锁的平凡析构和
跨用例栈地址复用形成过期的锁顺序环。每个用例内的数据竞争和死锁检测仍保持开启;
常规 ASan/UBSan/LSan 构建继续按原有分组运行测试。

TSan 任务通过 Clang 的 `--gcc-install-dir` 显式选择 GCC 13 的 libstdc++ 头文件与库,
避免 runner 镜像更新后自动选择更高版本的 GCC。Clang 18 搭配 runner 的 GCC 14
头文件时,SDK 的定时互斥锁调用会在编译阶段失败,检测测试尚未开始。

Clang 18 TSan 能识别 libstdc++ 定时互斥锁使用的 `pthread_mutex_clocklock`;
Ubuntu 24.04 的 GCC 检测运行库会对此误报解锁错误。
TSan 还需要兼容的影子内存布局,因此该任务在临时 Ubuntu runner 上先设置
`vm.mmap_rnd_bits=28`。本地环境也需要兼容的布局;初始化失败不代表没有数据竞争。
运行时检测只覆盖实际执行的路径,不能替代静态分析或实机验收。

## Report Card

`C++ Report Card` 工作流在 PR、main/master 推送和手动触发时运行。
Expand Down
Loading
Loading