[NFC][rtsan] Update docs to include [[clang::blocking]] #111249
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
@llvm/pr-subscribers-clang Author: None (davidtrevelyan) ChangesUpdates the RealtimeSanitizer documentation to:
@cjappl for review Full diff: https://github.com/llvm/llvm-project/pull/111249.diff 1 Files Affected:
diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index 3f96267603aefa..c3beefce4018c1 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -9,7 +9,7 @@ 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, i.e. calls to methods
-that are not safe for use in functions with deterministic runtime requirements.
+that are not safe for use in functions with deterministic run time requirements.
RTSan considers any function marked with the ``[[clang::nonblocking]]`` attribute
to be a real-time function. If RTSan detects a call to ``malloc``, ``free``,
``pthread_mutex_lock``, or anything else that could have a non-deterministic
@@ -58,7 +58,7 @@ code.
return 0;
}
# Compile and link
- % clang++ -fsanitize=realtime -g example_realtime_violation.cpp
+ % clang++ -fsanitize=realtime 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
@@ -66,23 +66,63 @@ non-zero exit code.
.. code-block:: console
- % clang++ -fsanitize=realtime -g example_realtime_violation.cpp
+ % clang++ -fsanitize=realtime example_realtime_violation.cpp
% ./a.out
- Real-time violation: intercepted call to real-time unsafe function `malloc` in real-time context! Stack trace:
- #0 0x000102893034 in __rtsan::PrintStackTrace() rtsan_stack.cpp:45
- #1 0x000102892e64 in __rtsan::Context::ExpectNotRealtime(char const*) rtsan_context.cpp:78
- #2 0x00010289397c in malloc rtsan_interceptors.cpp:286
- #3 0x000195bd7bd0 in operator new(unsigned long)+0x1c (libc++abi.dylib:arm64+0x16bd0)
- #4 0x5c7f00010230f07c (<unknown module>)
- #5 0x00010230f058 in std::__1::__libcpp_allocate[abi:ue170006](unsigned long, unsigned long) new:324
- #6 0x00010230effc in std::__1::allocator<float>::allocate[abi:ue170006](unsigned long) allocator.h:114
- ... snip ...
- #10 0x00010230e4bc in std::__1::vector<float, std::__1::allocator<float>>::__append(unsigned long) vector:1162
- #11 0x00010230dcdc in std::__1::vector<float, std::__1::allocator<float>>::resize(unsigned long) vector:1981
- #12 0x00010230dc28 in violation() main.cpp:5
- #13 0x00010230dd64 in main main.cpp:9
- #14 0x0001958960dc (<unknown module>)
- #15 0x2f557ffffffffffc (<unknown module>)
+ ==76290==ERROR: RealtimeSanitizer: unsafe-library-call
+ Intercepted call to real-time unsafe function `malloc` in real-time context!
+ #0 0x000102a7b884 in malloc rtsan_interceptors.cpp:426
+ #1 0x00019c326bd0 in operator new(unsigned long)+0x1c (libc++abi.dylib:arm64+0x16bd0)
+ #2 0xa30d0001024f79a8 (<unknown module>)
+ #3 0x0001024f794c in std::__1::__libcpp_allocate[abi:ne200000](unsigned long, unsigned long)+0x44
+ #4 0x0001024f78c4 in std::__1::allocator<float>::allocate[abi:ne200000](unsigned long)+0x44
+ ... snip ...
+ #9 0x0001024f6868 in std::__1::vector<float, std::__1::allocator<float>>::resize(unsigned long)+0x48
+ #10 0x0001024f67b4 in violation()+0x24
+ #11 0x0001024f68f0 in main+0x18 (a.out:arm64+0x1000028f0)
+ #12 0x00019bfe3150 (<unknown module>)
+ #13 0xed5efffffffffffc (<unknown module>)
+
+
+Blocking functions
+------------------
+
+Calls to system library functions such as ``malloc`` are automatically caught by
+RealtimeSanitizer. Real-time programmers may also write their own blocking
+(real-time unsafe) functions that they wish RealtimeSanitizer to be aware of.
+RealtimeSanitizer will raise an error if any function attributed with
+``[[clang::blocking]]`` is called in a ``[[clang::nonblocking]]`` context.
+
+.. code-block:: console
+
+ $ cat example_blocking_violation.cpp
+ #include <atomic>
+ #include <thread>
+
+ std::atomic<bool> has_permission{false};
+
+ int wait_for_permission() [[clang::blocking]] {
+ while (has_permission.load() == false)
+ std::this_thread::yield();
+ return 0;
+ }
+
+ int real_time_function() [[clang::nonblocking]] {
+ return wait_for_permission();
+ }
+
+ int main() {
+ return real_time_function();
+ }
+
+ $ clang++ -fsanitize=realtime example_blocking_violation.cpp && ./a.out
+ ==76131==ERROR: RealtimeSanitizer: blocking-call
+ Call to blocking function `wait_for_permission()` in real-time context!
+ #0 0x0001000c3db0 in wait_for_permission()+0x10 (a.out:arm64+0x100003db0)
+ #1 0x0001000c3e3c in real_time_function()+0x10 (a.out:arm64+0x100003e3c)
+ #2 0x0001000c3e68 in main+0x10 (a.out:arm64+0x100003e68)
+ #3 0x00019bfe3150 (<unknown module>)
+ #4 0x5a27fffffffffffc (<unknown module>)
+
Run-time flags
--------------
@@ -159,7 +199,7 @@ Disabling
In some circumstances, you may want to suppress error reporting in a specific scope.
-In C++, this is achieved via ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all sanitizer error reports are suppressed. This suppression applies to the current scope as well as all invoked functions, including any functions called transitively.
+In C++, this is achieved via ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all sanitizer error reports are suppressed. This suppression applies to the current scope as well as all invoked functions, including any functions called transitively.
.. code-block:: c++
@@ -174,7 +214,7 @@ In C++, this is achieved via ``__rtsan::ScopedDisabler``. Within the scope wher
If RealtimeSanitizer is not enabled at compile time (i.e., the code is not compiled with the ``-fsanitize=realtime`` flag), the ``ScopedDisabler`` is compiled as a no-op.
-In C, you can use the ``__rtsan_disable()`` and ``rtsan_enable()`` functions to manually disable and re-enable RealtimeSanitizer checks.
+In C, you can use the ``__rtsan_disable()`` and ``rtsan_enable()`` functions to manually disable and re-enable RealtimeSanitizer checks.
.. code-block:: c++
|
cjappl
approved these changes
Oct 5, 2024
clang/docs/RealtimeSanitizer.rst
Outdated
| Calls to system library functions such as ``malloc`` are automatically caught by | ||
| RealtimeSanitizer. Real-time programmers may also write their own blocking | ||
| (real-time unsafe) functions that they wish RealtimeSanitizer to be aware of. | ||
| RealtimeSanitizer will raise an error if any function attributed with |
There was a problem hiding this comment.
nit, take or leave: "raise an error at run time" - to differentiate between compile time.
Author's choice on whether or not to change it, may be obvious from the rest of the context
There was a problem hiding this comment.
Agreed - "at run time" is a good addition - thanks
|
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/73/builds/6650 Here is the relevant piece of the build log for the reference |
Kyvangka1610
added a commit
to Kyvangka1610/llvm-project
that referenced
this pull request
Oct 6, 2024
* commit 'FETCH_HEAD': [X86] combineAndLoadToBZHI - don't do an return early return if we fail to match a load [X86] replace-load-and-with-bzhi.ll - add commuted test cases to show failure to fold [X86] replace-load-and-with-bzhi.ll - cleanup check-prefixes to use X86/X64 for 32/64-bit targets [ExecutionEngine] Avoid repeated hash lookups (NFC) (llvm#111275) [ByteCode] Avoid repeated hash lookups (NFC) (llvm#111273) [StaticAnalyzer] Avoid repeated hash lookups (NFC) (llvm#111272) [CodeGen] Avoid repeated hash lookups (NFC) (llvm#111274) [RISCV] Simplify fixed-vector-fp.ll run lines. NFC [libc++][format][1/3] Adds more benchmarks. (llvm#101803) [X86] combineOrXorWithSETCC - avoid duplicate SDLoc/operands code. NFC. [X86] convertIntLogicToFPLogic - avoid duplicate SDLoc/operands code. NFC. [libc] Clean up some include in `libc`. (llvm#110980) [X86] combineBitOpWithPACK - avoid duplicate SDLoc/operands code. NFC. [X86] combineBitOpWithMOVMSK - avoid duplicate SDLoc/operands code. NFC. [X86] combineBitOpWithShift - avoid duplicate SDLoc/operands code. NFC. [x86] combineMul - use computeKnownBits directly to find MUL_IMM constant splat. [X86] combineSubABS - avoid duplicate SDLoc. NFC. [ValueTypes][RISCV] Add v1bf16 type (llvm#111112) [VPlan] Add additional FOR hoisting test. [clang-tidy] Create bugprone-bitwise-pointer-cast check (llvm#108083) [InstCombine] Canonicalize more geps with constant gep bases and constant offsets. (llvm#110033) [LV] Honor uniform-after-vectorization in setVectorizedCallDecision. [ELF] Pass Ctx & to Arch/ [ELF] Pass Ctx & to Arch/ [libc++] Fix a typo (llvm#111239) [X86] For minsize memset/memcpy, use byte or double-word accesses (llvm#87003) [RISCV] Unify RVBShift_ri and RVBShiftW_ri with Shift_ri and ShiftW_ri. NFC (llvm#111263) Revert "Reapply "[AMDGPU][GlobalISel] Fix load/store of pointer vectors, buffer.*.pN (llvm#110714)" (llvm#111059)" [libc] Add missing include to __support/StringUtil/tables/stdc_errors.h. (llvm#111271) [libc] remove errno.h includes (llvm#110934) [NFC][rtsan] Update docs to include [[clang::blocking]] (llvm#111249) [RISCV] Give ZEXT_H_RV32 and ZEXT_H_RV64 R-type format to match PACK. NFC [mlir][SPIRV] Fix build (2) (llvm#111265) [mlir][SPIRV] Fix build error (llvm#111264) [mlir][NFC] Mark type converter in `populate...` functions as `const` (llvm#111250) [Basic] Avoid repeated hash lookups (NFC) (llvm#111228) [RISCV] Use THShift_ri class instead of RVBShift_ri for TH_TST instruction. NFC [VPlan] Only generate first lane for VPPredInstPHI if no others used. [ELF] Don't call getPPC64TargetInfo outside Driver. NFC [GISel] Don't preserve NSW flag when converting G_MUL of INT_MIN to G_SHL. (llvm#111230) [APInt] Slightly simplify APInt::ashrSlowCase. NFC (llvm#111220) [Sema] Avoid repeated hash lookups (NFC) (llvm#111227) [Affine] Avoid repeated hash lookups (NFC) (llvm#111226) [Driver] Avoid repeated hash lookups (NFC) (llvm#111225) [clang][test] Remove a broken bytecode test [ELF] Pass Ctx & [ELF] Pass Ctx & to Relocations Signed-off-by: kyvangka1610 <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Updates the RealtimeSanitizer documentation to:
[[clang::blocking]], and@cjappl for review