Skip to content
Merged
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
10 changes: 10 additions & 0 deletions .bazelrc
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,16 @@ build:ubsan --copt=-fsanitize-trap=undefined
test:ubsan --build_tests_only
test:ubsan --test_tag_filters=-firmware_size

# Host tests under AddressSanitizer: out-of-bounds access, use after free and
# leaks fail the test with a report. Host tests only, like ubsan. See
# tools/asan/README.md. The toolchain's own flag, not a raw -fsanitize: it
# also puts the ASan runtime among the link inputs, which plain --linkopt
# can't, so remote links fail to find libclang_rt.asan*.a.
build:asan --@llvm//config:asan=true
build:asan --copt=-fno-omit-frame-pointer
test:asan --build_tests_only
test:asan --test_tag_filters=-firmware_size

# Line coverage of host C++ tests, with LLVM's source-based coverage (the
# hermetic toolchain ships llvm-cov and llvm-profdata). Only firmware code is
# instrumented; tests and generated code are left out. The combined lcov
Expand Down
8 changes: 8 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,14 @@ jobs:
bazel test --config=ubsan
//boards/... //drivers/... //lib/codegen/cpp/... //tools/ubsan:trap_test

# And under ASan for memory errors; overflow_test is its canary
# (tools/asan/README.md).
- name: Test host C++ under ASan
if: ${{ !cancelled() }}
run: >-
bazel test --config=asan
//boards/... //drivers/... //lib/codegen/cpp/... //tools/asan:overflow_test

# Firmware line coverage from the host tests on the lines this PR
# changes, reported on the summary page and never failing the build
# (tools/coverage/README.md). The checkout is the PR merged into its
Expand Down
1 change: 1 addition & 0 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ except coverage, which is reported, not enforced.
| Network off in tests | A unit test that reaches the internet or a service | `bazel test //tools/hermetic:network_off_test` |
| Changed-line coverage (report only) | How many firmware lines a PR adds or changes run under a host test, on the run's summary page | `bazel coverage //boards/... //drivers/...`, then diff-cover ([how](../tools/coverage/README.md)) |
| UBSan | Undefined behavior in host C++ (overflow, bad shifts, misaligned access) | `bazel test --config=ubsan //boards/... //drivers/... //lib/codegen/cpp/...` |
| ASan | Memory errors in host C++ (out of bounds, use after free, leaks) | `bazel test --config=asan //boards/... //drivers/... //lib/codegen/cpp/... //tools/asan:overflow_test` |
| Firmware warnings as errors | Shadowed variables, `float` silently widened to `double` (slow on the M4F), unchecked format strings, fallthrough, `#if` on undefined macros, in app and longhorn code ([list](../tools/firmware/README.md#warnings)) | part of `bazel build //...` |
| Format | Unformatted C/C++ | `bazel run //tools/format:check` |
| Lint: Python (ruff) | Undefined names, unused imports, swallowed exceptions, unchecked subprocesses, unsafe calls. Stale `noqa` fails. | `uv run --group lint ruff check` |
Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ nav:
- IDE Setup: tools/ide/README.md
- Serial Monitor: tools/monitor/README.md
- UBSan: tools/ubsan/README.md
- ASan: tools/asan/README.md
- Hermetic Tests: tools/hermetic/README.md
- Coverage: tools/coverage/README.md
- Prebuilt protoc: tools/protoc/README.md
Expand Down
1 change: 1 addition & 0 deletions tools/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ Build and dev tooling. Each package documents itself:
| [hermetic/](hermetic/README.md) | Tests run without network; `:network_off_test` is the canary that proves it. |
| [coverage/](coverage/README.md) | Firmware line coverage from the host tests on the lines a PR changes, reported on every PR (no enforced percent). |
| [ubsan/](ubsan/README.md) | `--config=ubsan`: host tests with undefined behavior trapping, plus the canary that proves it's on. |
| [asan/](asan/README.md) | `--config=asan`: host tests under AddressSanitizer, with its canary. |

`new_board.py` (`bazel run //tools:new_board -- boards/<Name>/<Name>.ioc`)
scaffolds a whole working board from its CubeMX `.ioc`, so new boards
Expand Down
13 changes: 13 additions & 0 deletions tools/asan/BUILD.bazel
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
load("@rules_cc//cc:cc_test.bzl", "cc_test")

# Passes only when --config=asan really instruments the build: it reads past
# a heap buffer on purpose and expects ASan to stop the process. Without the
# sanitizer that read is silent, so `manual` keeps it out of wildcards and
# presubmit's ASan step names it explicitly, like //tools/ubsan:trap_test.
cc_test(
name = "overflow_test",
size = "small",
srcs = ["overflow_test.cpp"],
tags = ["manual"],
deps = ["@googletest//:gtest_main"],
)
26 changes: 26 additions & 0 deletions tools/asan/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# ASan

`--config=asan` builds host C++ with AddressSanitizer: out-of-bounds reads
and writes, use after free, double free and leaks stop the test with a
report naming the line. UBSan ([tools/ubsan](../ubsan/README.md)) covers
arithmetic; this covers memory, which matters for the ring buffers, frame
packing and fixed arrays in firmware code that the host tests drive.

```bash
bazel test --config=asan //boards/... //drivers/... //lib/codegen/cpp/... //tools/asan:overflow_test
```

That is the command presubmit runs. Gotchas:

- **Host tests only**, like UBSan: the config sets `--build_tests_only` and
skips the firmware size tests (tag `firmware_size`).
- **`:overflow_test` is the canary.** It reads past a heap buffer and
passes only if ASan reports it, so the ASan step can't go green because
the flags stopped reaching the compiler. Tagged `manual`; name it.
- **Turn it on with the toolchain's flag**, `--@llvm//config:asan=true`,
as the config does. hermetic-llvm adds `-fsanitize=address` and puts the
`libclang_rt.asan*` runtimes in the link's inputs only when that flag is
set. A raw `--copt`/`--linkopt=-fsanitize=address` compiles fine and then
fails to link with "cannot open libclang_rt.asan_static.a".
- ASan and UBSan are separate configs because each one recompiles
everything it touches; the remote cache keeps repeats cheap.
23 changes: 23 additions & 0 deletions tools/asan/overflow_test.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
// Canary for --config=asan (see README.md): if the sanitizer flags ever stop
// reaching the compiler or linker, the ASan CI step would still pass on clean
// code. This test fails instead.

#include <gtest/gtest.h>

#include <memory>

namespace {

int ReadPastTheEnd() {
auto buffer = std::make_unique<int[]>(4);
// Both volatile: the index so the compiler can't prove it out of range,
// and the load so optimization (-c opt) can't drop it as dead.
volatile int index = 4;
return static_cast<const volatile int*>(buffer.get())[index];
}

TEST(AsanOverflowTest, HeapOverflowIsCaught) {
EXPECT_DEATH(static_cast<void>(ReadPastTheEnd()), "heap-buffer-overflow");
}

} // namespace
3 changes: 1 addition & 2 deletions tools/ubsan/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,7 @@ That is the command presubmit runs. Gotchas:
- **Trap mode, so no report.** The hermetic LLVM ships no sanitizer
runtime, so there is nothing to print which check fired. A trapped test
dies with `SIGILL`. Rerun it under a debugger to find the faulting
line. ASan is not possible for the
same reason.
line. Memory errors are [ASan's](../asan/README.md) job.
- **Host tests only.** Firmware images can't take the flags, so the config
sets `--build_tests_only` and skips each image's `{image}_size_test`
(tag `firmware_size`, see [tools/firmware](../firmware/README.md)). Don't
Expand Down
Loading