rtsan-standalone-rs

This is a wrapper for the standalone version of RealtimeSanitizer (RTSan) to detect real-time violations in Rust applications. You can find more information in the Official Clang Docs and the RTSan Repository.

⚠️ Warning: Currently, this sanitizer only works on Linux, macOS and iOS.

Usage

Mark a real-time function with the #[nonblocking] macro:

use rtsan_standalone::nonblocking;

#[nonblocking]
fn process(data: &mut [f32]) {
    let _ = vec![0.0; 16]; // oops!
}

At runtime, real-time violations are presented with a stack trace:

==283082==ERROR: RealtimeSanitizer: unsafe-library-call
Intercepted call to real-time unsafe function `calloc` in real-time context!
    #0 0x55c0c3be8cf2 in calloc /tmp/.tmp6Qb4u2/llvm-project/compiler-rt/lib/rtsan/rtsan_interceptors_posix.cpp:470:34
    #1 0x55c0c3be4e69 in alloc::alloc::alloc_zeroed::hf760e6484fdf32c8 /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/alloc/src/alloc.rs:170:14
    #2 0x55c0c3be4e69 in alloc::alloc::Global::alloc_impl::hc0e9b7c86f5cad5c /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/alloc/src/alloc.rs:181:43
    #3 0x55c0c3be56fb in _$LT$alloc..alloc..Global$u20$as$u20$core..alloc..Allocator$GT$::allocate_zeroed::h8f75ff921b519af6 /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/alloc/src/alloc.rs:246:9
    ...
    #27 0x55c0c3be2ab4 in _start (target/debug/examples/vector+0x2ab4) (BuildId: adb992a7e560cd00ef533c9333d3c033fb4a7c42)
SUMMARY: RealtimeSanitizer: unsafe-library-call /rustc/f6e511eec7342f59a25f7c0534f1dbea00d01b14/library/alloc/src/alloc.rs:170:14 in alloc::alloc::alloc_zeroed::hf760e6484fdf32c8

Setup

RTSan currently supports Linux, macOS and iOS.

To use RTSan, add it as a dependency in your Cargo.toml file and conditionally add the enable feature:

[dependencies]
rtsan-standalone = "0.1.0"

[features]
rtsan = ["rtsan-standalone/enable"]

To run your project with sanitizing enabled, execute:

cargo run --features rtsan

For more help, refer to the integration example README.

Pre-built Libraries

By default this crate downloads pre-built libraries from the repo rtsan-libs.

If you do not wish to use the pre-built libraries you can disable the default features and either let the build script build the library automatically or provide a custom build of rtsan.

Building locally

Ensure you have the following tools installed: git, make, and cmake (version 3.20.0 or higher). Disable default features when adding rtsan-standalone to your project. The initial build of rtsan-standalone-sys may take a few minutes to compile the LLVM libraries. After building the crate for the first time, the library is located at:

target/debug/build/rtsan-standalone-sys-*/out/

Using Custom-Built RTSan Libraries

To use a custom-built library, you need to set the RTSAN_LIBRARY_PATH environment variable. When a library gets provided like this it will always be prioritized.

# Linux
RTSAN_LIBRARY_PATH=/path/to/libclang_rt.rtsan-x86_64.a cargo run --features enable

Features

The enable feature allows you to enable or disable sanitizing for your project. This ensures that all RTSan functions and macros can remain in your production code without impacting performance when the feature is disabled.

The prebuilt-libs feature enables automatic downloading of libraries from our repository and is activated by default, eliminating the need for local compilation.

Examples

Explore the various possibilities with RTSan through the provided examples. For instance, to run the vector example, execute:

cargo run --example vector --features enable

The integration example demonstrates how to conditionally build the sanitizer into your project:

cargo run --package integration-example --features rtsan

RTSan Options

You can set different options in RTSan like this:

RTSAN_OPTIONS=halt_on_error=false cargo run --example mutex --features enable

For a full list of options see here: https://clang.llvm.org/docs/RealtimeSanitizer.html#run-time-flags.

Contact

RTSan was invented by David Trevelyan and Ali Barker. The C++ upstream implementation was authored by David Trevelyan and Chris Apple, while the Rust wrapper was developed by Stephan Eckes. Feedback and contributions are welcome!

• Discord: RealtimeSanitizer (RTSan) Discord Channel
• Email: realtime.sanitizer@gmail.com
• GitHub Issues: Submit your queries or suggestions directly to this repository.