================
@@ -0,0 +1,85 @@
+=================
+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 <https://llvm.org/docs/CMake.html>` 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" <path to source>/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
----------------
MaskRay wrote:
While `clang` can be used for a compile action, when performing a link action,
`clang++` should be used to ensure libc++/libstdc++ is linked.
https://github.com/llvm/llvm-project/pull/102622
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
