diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst new file mode 100644 index 000000000000000..f9af41467df05f4 --- /dev/null +++ b/clang/docs/RealtimeSanitizer.rst @@ -0,0 +1,81 @@ +================= +RealtimeSanitizer +================= + +.. contents:: + :local: + +Introduction +============ +RealtimeSanitizer (a.k.a. RTSan) is a real-time safety testing tool for C and +C++ projects. RTSan can be used to detect real-time violations,such as calls to +methods that are not safe for use in functions with deterministic runtime +requirements. + +The tool can detect the following types of real-time violations: + +* System calls +* Allocations +* Exceptions + +These checks are put in place when compiling with the +``-fsanitize=realtime`` flag, for functions marked with +``[[clang::nonblocking]]``. + +.. code-block:: c + void process_audio(float* buffer) [[clang::nonblocking]] { + ... + } + +The runtime slowdown introduced by RealtimeSanitizer is trivial. Code in +real-time contexts without real-time safety violations have no slowdown. + +How to build +============ + +Build LLVM/Clang with `CMake ` and enable the +``compiler-rt`` runtime. An example CMake configuration that will allow for the +use/testing of RealtimeSanitizer: + +.. code-block:: console + + $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang" -DLLVM_ENABLE_RUNTIMES="compiler-rt" /llvm + +Usage +===== + +There are two requirements: +1. The code must be compiled with the ``-fsanitize=realtime`` flag. +2. Functions that are subject to real-time constraints must be + marked with the ``[[clang::nonblocking]]`` attribute. + +Typically, these attributes should be added onto the functions that are entry +points for threads with real-time priority. These threads are subject to a fixed +callback time, such as audio callback threads or rendering loops in video game +code. + +.. code-block:: console + % cat example_realtime_violation.cpp + int main() [[clang::nonblocking]] { + int* p = new int; + return 0; + } + + # Compile and link + % clang -fsanitize=realtime -g example_realtime_violation.cpp + +If a real-time safety violation is detected in a ``[[clang::nonblocking]]`` +context, or any function invoked by that function, the program will exit with a +non-zero exit code. + +.. code-block:: console + % clang -fsanitize=realtime -g example_realtime_violation.cpp + % ./a.out + Real-time violation: intercepted call to real-time unsafe function `malloc` in real-time context! Stack trace: + #0 0x00010065ad9c in __rtsan::PrintStackTrace() rtsan_stack.cpp:45 + #1 0x00010065abcc in __rtsan::Context::ExpectNotRealtime(char const*) rtsan_context.cpp:78 + #2 0x00010065b8d0 in malloc rtsan_interceptors.cpp:289 + #3 0x000195bd7bd0 in operator new(unsigned long)+0x1c (libc++abi.dylib:arm64+0x16bd0) + #4 0xb338001000dbf68 () + #5 0x0001958960dc () + #6 0x45737ffffffffffc () diff --git a/clang/docs/ReleaseNotes.rst b/clang/docs/ReleaseNotes.rst index 6796a619ba97f8e..79f721169fdbb28 100644 --- a/clang/docs/ReleaseNotes.rst +++ b/clang/docs/ReleaseNotes.rst @@ -349,6 +349,11 @@ Moved checkers Sanitizers ---------- +- Introduced Realtime Sanitizer, activated by using the -fsanitize=realtime + flag. This sanitizer detects unsafe system library calls, such as memory + allocations and mutex locks. If any such function is called during invocation + of a function marked with the ``[[clang::nonblocking]]`` attribute, an error + is printed to the console and the process exits non-zero. Python Binding Changes ----------------------