mirror of
https://github.com/PX4/PX4-Autopilot.git
synced 2026-07-26 16:28:06 +08:00
docs: document building SITL with sanitizers (ASan/TSan)
Add a test_and_ci page covering the PX4_ASAN / PX4_TSAN / PX4_MSAN / PX4_UBSAN build variables, the Linux `sudo sysctl vm.mmap_rnd_bits=28` workaround for the sanitizer runtime's startup memory mapping, and the TSan suppressions file (test/sitl_tsan.supp) for the Gazebo simulation transport. Linked from SUMMARY.md and the test_and_ci index.
This commit is contained in:
@@ -7,6 +7,7 @@ Test topics include:
|
||||
|
||||
- [Test Flights](../test_and_ci/test_flights.md) - How to make test flights (e.g. to [test PRs](../contribute/code.md#pull-requests))
|
||||
- [Unit Tests](../test_and_ci/unit_tests.md)
|
||||
- [Sanitizers](../test_and_ci/sanitizers.md) - Build SITL with ASan/TSan to catch memory errors and data races
|
||||
- [Continuous Integration (CI)](../test_and_ci/continous_integration.md)
|
||||
- [Integration Testing](../test_and_ci/integration_testing.md)
|
||||
- [MAVSDK Integration Testing](../test_and_ci/integration_testing_mavsdk.md)
|
||||
|
||||
73
docs/en/test_and_ci/sanitizers.md
Normal file
73
docs/en/test_and_ci/sanitizers.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# Sanitizers
|
||||
|
||||
[Sanitizers](https://github.com/google/sanitizers) are compiler-instrumentation tools that detect whole classes of bugs at runtime. PX4 can build [SITL](../simulation/index.md) with them to catch problems that are otherwise hard to reproduce:
|
||||
|
||||
- **AddressSanitizer (ASan)** — out-of-bounds accesses, use-after-free, memory leaks.
|
||||
- **ThreadSanitizer (TSan)** — data races and lock-order inversions.
|
||||
- **MemorySanitizer (MSan)** — reads of uninitialized memory (Clang only).
|
||||
- **UndefinedBehaviorSanitizer (UBSan)** — undefined behaviour (signed overflow, misaligned access, …).
|
||||
|
||||
:::info
|
||||
Sanitizers are only available for POSIX/SITL builds, where the host compiler instruments the code. They are not used on the NuttX flight-controller targets.
|
||||
:::
|
||||
|
||||
## Building and running
|
||||
|
||||
Set the matching environment variable when building SITL. It selects the corresponding `CMAKE_BUILD_TYPE`:
|
||||
|
||||
| Variable | Sanitizer |
|
||||
| ------------ | ----------------------------- |
|
||||
| `PX4_ASAN` | AddressSanitizer |
|
||||
| `PX4_TSAN` | ThreadSanitizer |
|
||||
| `PX4_MSAN` | MemorySanitizer |
|
||||
| `PX4_UBSAN` | UndefinedBehaviorSanitizer |
|
||||
|
||||
For example, to build and run SITL under ThreadSanitizer:
|
||||
|
||||
```sh
|
||||
PX4_TSAN=1 make px4_sitl_default
|
||||
```
|
||||
|
||||
To build and run the unit and integration test suite under a sanitizer:
|
||||
|
||||
```sh
|
||||
PX4_TSAN=1 make tests
|
||||
```
|
||||
|
||||
:::warning
|
||||
A sanitizer is a distinct `CMAKE_BUILD_TYPE`, so switching to or from one rebuilds from scratch. Sanitized binaries are larger and run several times slower (ASan/TSan roughly 2–5×), and lockstep timing changes, so expect tests to take longer.
|
||||
:::
|
||||
|
||||
## Linux: ASLR fix
|
||||
|
||||
On recent Linux kernels the default address-space-layout randomization entropy is too high for the sanitizer runtimes' shadow-memory mapping, and the process aborts at startup with e.g.:
|
||||
|
||||
```
|
||||
FATAL: ThreadSanitizer: unexpected memory mapping 0x... - 0x...
|
||||
```
|
||||
|
||||
Lower the mmap randomization (needed for both ASan and TSan), once per boot:
|
||||
|
||||
```sh
|
||||
sudo sysctl vm.mmap_rnd_bits=28
|
||||
```
|
||||
|
||||
To make it persistent across reboots:
|
||||
|
||||
```sh
|
||||
echo 'vm.mmap_rnd_bits=28' | sudo tee /etc/sysctl.d/99-sanitizers.conf
|
||||
```
|
||||
|
||||
If `28` still fails on your kernel, try `26`.
|
||||
|
||||
## ThreadSanitizer suppressions
|
||||
|
||||
Running SITL with the Gazebo bridge under TSan reports many data races inside the third-party simulation transport (ZeroMQ and gz-transport) and the PX4↔Gazebo bridge glue. None of this is in the flight code path or the SIH-based CI, and it can't be fixed here, so it is filtered with a suppressions file at `test/sitl_tsan.supp`:
|
||||
|
||||
```sh
|
||||
TSAN_OPTIONS="suppressions=$PWD/test/sitl_tsan.supp" PX4_TSAN=1 make px4_sitl_default gz_x500
|
||||
```
|
||||
|
||||
:::warning
|
||||
Only add third-party / simulation symbols to the suppressions file — never flight-code symbols. A race detector is only useful at zero reports; suppressing your own code blinds it to real bugs.
|
||||
:::
|
||||
Reference in New Issue
Block a user