add docs

Author: luca3s

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,66 @@ 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 realtime contexts.
+Usafe of RTSan is on a function-by-function basis. The sanitizer only inspects code that
+is marked as being real-time sensitive. This is done with the `sanitize` attribute.
+Any function that is subject to real-time contraints should be marked with `#[sanitize(realtime = "nonblocking")]`.
+
+Besides "nonblocking" the attribute can also be used with "disable", "blocking" and "caller".
+- "disable" disables the sanitizer for this function. Not real-time sensitive operations in this
+function aren't detected anymore.
+- "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 any given function could be both sanitized and not sanitized in one program execution.
+
+Due to limitations in the current implementation it is not possible to have "nonblocking" code inside "disabled" code.
+This means that in the following example no violation will be detected:
+
+```rust
+#[sanitize(realtime = "disable")]
+fn disabled() {
+  supposedly_nonblocking();
+}
+
+#[sanitize(realtime = "nonblocking")]
+fn supposedly_nonblocking() {
+  let _ = vec![1, 2, 3]; // won't report a violation when called from disabled
+}
+```
+
+See the [Clang RealtimeSanitizer documentation][clang-rtsan] for more details.
+
+## Example
+
+```rust
+#[sanitize(realtime = "nonblocking")]
+fn main() {
+  let vec = vec![0, 1, 2];
+  println!("alloc not detected");
+}
+```
+
+```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 +980,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 +989,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