|
| 1 | +================= |
| 2 | +RealtimeSanitizer |
| 3 | +================= |
| 4 | + |
| 5 | +.. contents:: |
| 6 | + :local: |
| 7 | + |
| 8 | +Introduction |
| 9 | +============ |
| 10 | +RealtimeSanitizer (a.k.a. RTSan) is a real-time safety testing tool for C and C++ |
| 11 | +projects. RTSan can be used to detect real-time violations, i.e. calls to methods |
| 12 | +that are not safe for use in functions with deterministic runtime requirements. |
| 13 | +RTSan considers any function marked with the ``[[clang::nonblocking]]`` attribute |
| 14 | +to be a real-time function. If RTSan detects a call to ``malloc``, ``free``, |
| 15 | +``pthread_mutex_lock``, or anything else that could have a non-deterministic |
| 16 | +execution time in a function marked ``[[clang::nonblocking]]`` |
| 17 | +RTSan raises an error. |
| 18 | + |
| 19 | +The runtime slowdown introduced by RealtimeSanitizer is negligible. |
| 20 | + |
| 21 | +How to build |
| 22 | +============ |
| 23 | + |
| 24 | +Build LLVM/Clang with `CMake <https://llvm.org/docs/CMake.html>` and enable the |
| 25 | +``compiler-rt`` runtime. An example CMake configuration that will allow for the |
| 26 | +use/testing of RealtimeSanitizer: |
| 27 | + |
| 28 | +.. code-block:: console |
| 29 | +
|
| 30 | + $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="compiler-rt" <path to source>/llvm |
| 31 | +
|
| 32 | +Usage |
| 33 | +===== |
| 34 | + |
| 35 | +There are two requirements: |
| 36 | + |
| 37 | +1. The code must be compiled with the ``-fsanitize=realtime`` flag. |
| 38 | +2. Functions that are subject to real-time constraints must be marked |
| 39 | + with the ``[[clang::nonblocking]]`` attribute. |
| 40 | + |
| 41 | +Typically, these attributes should be added onto the functions that are entry |
| 42 | +points for threads with real-time priority. These threads are subject to a fixed |
| 43 | +callback time, such as audio callback threads or rendering loops in video game |
| 44 | +code. |
| 45 | + |
| 46 | +.. code-block:: console |
| 47 | +
|
| 48 | + % cat example_realtime_violation.cpp |
| 49 | + #include <vector> |
| 50 | +
|
| 51 | + void violation() [[clang::nonblocking]]{ |
| 52 | + std::vector<float> v; |
| 53 | + v.resize(100); |
| 54 | + } |
| 55 | +
|
| 56 | + int main() { |
| 57 | + violation(); |
| 58 | + return 0; |
| 59 | + } |
| 60 | + # Compile and link |
| 61 | + % clang++ -fsanitize=realtime -g example_realtime_violation.cpp |
| 62 | +
|
| 63 | +If a real-time safety violation is detected in a ``[[clang::nonblocking]]`` |
| 64 | +context, or any function invoked by that function, the program will exit with a |
| 65 | +non-zero exit code. |
| 66 | + |
| 67 | +.. code-block:: console |
| 68 | +
|
| 69 | + % clang++ -fsanitize=realtime -g example_realtime_violation.cpp |
| 70 | + % ./a.out |
| 71 | + Real-time violation: intercepted call to real-time unsafe function `malloc` in real-time context! Stack trace: |
| 72 | + #0 0x000102893034 in __rtsan::PrintStackTrace() rtsan_stack.cpp:45 |
| 73 | + #1 0x000102892e64 in __rtsan::Context::ExpectNotRealtime(char const*) rtsan_context.cpp:78 |
| 74 | + #2 0x00010289397c in malloc rtsan_interceptors.cpp:286 |
| 75 | + #3 0x000195bd7bd0 in operator new(unsigned long)+0x1c (libc++abi.dylib:arm64+0x16bd0) |
| 76 | + #4 0x5c7f00010230f07c (<unknown module>) |
| 77 | + #5 0x00010230f058 in std::__1::__libcpp_allocate[abi:ue170006](unsigned long, unsigned long) new:324 |
| 78 | + #6 0x00010230effc in std::__1::allocator<float>::allocate[abi:ue170006](unsigned long) allocator.h:114 |
| 79 | + ... snip ... |
| 80 | + #10 0x00010230e4bc in std::__1::vector<float, std::__1::allocator<float>>::__append(unsigned long) vector:1162 |
| 81 | + #11 0x00010230dcdc in std::__1::vector<float, std::__1::allocator<float>>::resize(unsigned long) vector:1981 |
| 82 | + #12 0x00010230dc28 in violation() main.cpp:5 |
| 83 | + #13 0x00010230dd64 in main main.cpp:9 |
| 84 | + #14 0x0001958960dc (<unknown module>) |
| 85 | + #15 0x2f557ffffffffffc (<unknown module>) |
0 commit comments