Crate rtsan_standalone

Source
Expand description

§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:

[dependencies]
rtsan-standalone = "0.2.0"

To run your project with sanitizing enabled, execute:

RTSAN_ENABLE=1 cargo run

§Pre-built Libraries

By default this crate downloads pre-built libraries from the repo rtsan-libs. This requires curl to be installed.

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 RTSAN_ENABLE=1 cargo run

§Features

The prebuilt-libs feature enables automatic downloading of libraries from rtsan-libs and is activated by default, eliminating the need for local compilation. This requires curl to be installed.

§Examples

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

RTSAN_ENABLE=1 cargo run --example vector

§RTSan Options

You can set different options in RTSan like this:

RTSAN_OPTIONS=halt_on_error=false RTSAN_ENABLE=1 cargo run --example mutex

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!

Macros§

scoped_disabler
Disable all RTSan error reporting in an otherwise real-time context.

Structs§

ScopedDisabler
Disable all RTSan error reporting in an otherwise real-time context, for the lifetime of the object. Corresponds to a scoped_disabler or no_sanitize_realtime macro.
ScopedSanitizeRealtime
Enter real-time context for the lifetime of the object. When in a real-time context, RTSan interceptors will error if realtime violations are detected. Corresponds to a nonblocking macro.

Functions§

disable
Disable all RTSan error reporting in an otherwise real-time context. Must be paired with a call to enable. Corresponds to a scoped_disabler or no_sanitize_realtime macro.
enable
Re-enable all RTSan error reporting. Must follow a call to disable. Corresponds to a scoped_disabler or no_sanitize_realtime macro.
ensure_initialized
Initializes rtsan if it has not been initialized yet. Used by the RTSan runtime to ensure that rtsan is initialized before any other rtsan functions are called.
notify_blocking_call
Allows the user to specify a function as not-real-time-safe Including this in the first line of a function definition is analogous to marking a function with the blocking macro.
realtime_enter
Enter real-time context. When in a real-time context, RTSan interceptors will error if realtime violations are detected. Calls to this method are injected at the code generation stage when RTSan is enabled. Corresponds to a nonblocking macro.
realtime_exit
Exit the real-time context. When not in a real-time context, RTSan interceptors will simply forward intercepted method calls to the real methods. Corresponds to a nonblocking macro.

Attribute Macros§

blocking
Allows the user to specify a function as not-real-time-safe.
no_sanitize_realtime
Disable all RTSan error reporting in an otherwise real-time context.
nonblocking
Enter real-time context in your function. When in a real-time context, RTSan interceptors will error if realtime violations are detected. Calls to this method are injected at the code generation stage when RTSan is enabled.