diff --git a/src/doc/unstable-book/src/compiler-flags/sanitizer.md b/src/doc/unstable-book/src/compiler-flags/sanitizer.md index 493256de99d52..5073d9d733730 100644 --- a/src/doc/unstable-book/src/compiler-flags/sanitizer.md +++ b/src/doc/unstable-book/src/compiler-flags/sanitizer.md @@ -24,6 +24,8 @@ This feature allows for use of one of following sanitizers: AddressSanitizer, but based on partial hardware assistance. * [LeakSanitizer](#leaksanitizer) a run-time memory leak detector. * [MemorySanitizer](#memorysanitizer) a detector of uninitialized reads. + * [RealtimeSanitizer](#realtimesanitizer) a detector of functions with + non-deterministic execution time in realtime contexts. * [ThreadSanitizer](#threadsanitizer) a fast data race detector. * Those that apart from testing, may be used in production: @@ -43,11 +45,11 @@ This feature allows for use of one of following sanitizers: To enable a sanitizer compile with `-Zsanitizer=address`, `-Zsanitizer=cfi`, `-Zsanitizer=dataflow`,`-Zsanitizer=hwaddress`, `-Zsanitizer=leak`, -`-Zsanitizer=memory`, `-Zsanitizer=memtag`, `-Zsanitizer=shadow-call-stack`, or -`-Zsanitizer=thread`. You might also need the `--target` and `build-std` flags. -If you're working with other languages that are also instrumented with sanitizers, -you might need the `external-clangrt` flag. See the section on -[working with other languages](#working-with-other-languages). +`-Zsanitizer=memory`, `-Zsanitizer=memtag`, `-Zsanitizer=realtime`, +`-Zsanitizer=shadow-call-stack` or `-Zsanitizer=thread`. You might also need the +`--target` and `build-std` flags. If you're working with other languages that are also +instrumented with sanitizers, you might need the `external-clangrt` flag. See +the section on [working with other languages](#working-with-other-languages). Example: ```shell @@ -865,6 +867,58 @@ WARNING: ThreadSanitizer: data race (pid=10574) Location is global 'example::A::h43ac149ddf992709' of size 8 at 0x5632dfe3d030 (example+0x000000bd9030) ``` +# RealtimeSanitizer +RealtimeSanitizer detects non-deterministic execution time calls in real-time contexts. +Function marked with the `#[sanitize(realtime = "nonblocking")]` attribute are considered real-time functions. +When RTSan detects a call to a function with non-deterministic execution time, like `malloc` or `free` +while in a real-time context, it reports an error. + +Besides "nonblocking" the attribute can also be used with "blocking" and "caller". +- "blocking" marks the function as having a non-deterministic execution time. When reaching such +a function while in a real-time context a violation will be reported. +- "caller" is the default if no attribute is present, but can also be set explicitly. These functions +will be sanitized if called from a function that was being sanitized and will not be sanitized if called +from a function not sanitized. So a function could be both sanitized and not sanitized in one program execution. + +The sanitizer can be disabled using the external function `__rtsan_disable()`. It can be enabled again using +`__rtsan_enable()`. + +```rust +unsafe extern "C" { + fn __rtsan_disable(); + fn __rtsan_enable(); +} +``` + +See the [Clang RealtimeSanitizer documentation][clang-rtsan] for more details. + +## Example + +```rust +#[sanitize(realtime = "nonblocking")] +fn main() { + let vec = vec![0, 1, 2]; // call to alloc is detected and reported as an error +} +``` + +```shell +==8670==ERROR: RealtimeSanitizer: unsafe-library-call +Intercepted call to real-time unsafe function `malloc` in real-time context! + #0 0x00010107b0d8 in malloc rtsan_interceptors_posix.cpp:792 + #1 0x000100d94e70 in alloc::alloc::Global::alloc_impl::h9e1fc3206c868eea+0xa0 (realtime_vec:arm64+0x100000e70) + #2 0x000100d94d90 in alloc::alloc::exchange_malloc::hd45b5788339eb5c8+0x48 (realtime_vec:arm64+0x100000d90) + #3 0x000100d95020 in realtime_vec::main::hea6bd69b03eb9ca1+0x24 (realtime_vec:arm64+0x100001020) + #4 0x000100d94a28 in core::ops::function::FnOnce::call_once::h493b6cb9dd87d87c+0xc (realtime_vec:arm64+0x100000a28) + #5 0x000100d949b8 in std::sys::backtrace::__rust_begin_short_backtrace::hfcddb06c73c19eea+0x8 (realtime_vec:arm64+0x1000009b8) + #6 0x000100d9499c in std::rt::lang_start::_$u7b$$u7b$closure$u7d$$u7d$::h202288c05a2064f0+0xc (realtime_vec:arm64+0x10000099c) + #7 0x000100d9fa34 in std::rt::lang_start_internal::h6c763158a05ac05f+0x6c (realtime_vec:arm64+0x10000ba34) + #8 0x000100d94980 in std::rt::lang_start::h1c29cc56df0598b4+0x38 (realtime_vec:arm64+0x100000980) + #9 0x000100d95118 in main+0x20 (realtime_vec:arm64+0x100001118) + #10 0x000183a46b94 in start+0x17b8 (dyld:arm64+0xfffffffffff3ab94) + +SUMMARY: RealtimeSanitizer: unsafe-library-call rtsan_interceptors_posix.cpp:792 in malloc +``` + # Instrumentation of external dependencies and std The sanitizers to varying degrees work correctly with partially instrumented @@ -918,6 +972,7 @@ Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PAT * [MemorySanitizer in Clang][clang-msan] * [MemTagSanitizer in LLVM][llvm-memtag] * [ThreadSanitizer in Clang][clang-tsan] +* [RealtimeSanitizer in Clang][clang-rtsan] [clang-asan]: https://clang.llvm.org/docs/AddressSanitizer.html [clang-cfi]: https://clang.llvm.org/docs/ControlFlowIntegrity.html @@ -926,6 +981,7 @@ Sanitizers produce symbolized stacktraces when llvm-symbolizer binary is in `PAT [clang-kcfi]: https://clang.llvm.org/docs/ControlFlowIntegrity.html#fsanitize-kcfi [clang-lsan]: https://clang.llvm.org/docs/LeakSanitizer.html [clang-msan]: https://clang.llvm.org/docs/MemorySanitizer.html +[clan-rtsan]: https://clang.llvm.org/docs/RealtimeSanitizer.html [clang-safestack]: https://clang.llvm.org/docs/SafeStack.html [clang-scs]: https://clang.llvm.org/docs/ShadowCallStack.html [clang-tsan]: https://clang.llvm.org/docs/ThreadSanitizer.html