[clang] [rtsan][NFC] Documentation of suppression flag (PR #112727)
Chris Apple via cfe-commits
cfe-commits at lists.llvm.org
Fri Oct 25 10:57:37 PDT 2024
https://github.com/cjappl updated https://github.com/llvm/llvm-project/pull/112727
>From 1bdbc3baf8399c4571429cff727bfa9bb260e400 Mon Sep 17 00:00:00 2001
From: Chris Apple <cja-private at pm.me>
Date: Thu, 17 Oct 2024 08:20:08 -0700
Subject: [PATCH 1/5] [rtsan][NFC] Documentation of suppression flag
---
clang/docs/RealtimeSanitizer.rst | 66 ++++++++++++++++++++++++++++++--
1 file changed, 62 insertions(+), 4 deletions(-)
diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index 103842e055db70..bec15fd6cad2ac 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -183,6 +183,10 @@ A **partial** list of flags RealtimeSanitizer respects:
- ``true``
- boolean
- If set, use the symbolizer to turn virtual addresses to file/line locations. If false, can greatly speed up the error reporting.
+ * - ``suppressions``
+ - ""
+ - path
+ - If set to a valid suppressions file, will suppress issue reporting. See details in "Disabling", below.
Some issues with flags can be debugged using the ``verbosity=$NUM`` flag:
@@ -194,12 +198,43 @@ Some issues with flags can be debugged using the ``verbosity=$NUM`` flag:
misspelled_flag
...
-Disabling
----------
+Disabling and suppressing
+-------------------------
-In some circumstances, you may want to suppress error reporting in a specific scope.
+There are multiple ways to suppress error reporting when using RealtimeSanitizer.
-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 general, ``ScopedDisabler`` should be preferred, as it is the most performant.
+
+.. list-table:: Suppression methods
+ :widths: 30 15 15 10 70
+ :header-rows: 1
+
+ * - Suppression method
+ - Specified at?
+ - Scope
+ - Run-time cost
+ - Description
+ * - ``ScopedDisabler``
+ - Compile-time
+ - Stack
+ - Very low
+ - Suppresses all sanitizer error reports in the current scope and all invoked functions.
+ * - ``function-name-matches`` suppression
+ - Run-time
+ - Single function
+ - Medium
+ - Suppresses intercepted and ``[[clang::blocking]]`` function calls by name.
+ * - ``call-stack-contains`` suppression
+ - Run-time
+ - Stack
+ - High
+ - Suppresses any stack trace contaning the specified pattern.
+
+
+``ScopedDisabler``
+##################
+
+At compile time, RealtimeSanitizer may be disabled for a scope using ``__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++
@@ -233,6 +268,29 @@ In C, you can use the ``__rtsan_disable()`` and ``rtsan_enable()`` functions to
Each call to ``__rtsan_disable()`` must be paired with a subsequent call to ``__rtsan_enable()`` to restore normal sanitizer functionality. If a corresponding ``rtsan_enable()`` call is not made, the behavior is undefined.
+Suppression file
+################
+
+At run-time, suppressions may be specified using a suppressions file passed in ``RTSAN_OPTIONS``. Run-time suppression may be useful if the source cannot be changed.
+
+.. code-block:: console
+
+ > cat suppressions.supp
+ call-stack-contains:MallocViolation
+ call-stack-contains:std::*vector
+ function-name-matches:free
+ function-name-matches:CustomMarkedBlocking*
+ > RTSAN_OPTIONS="suppressions=suppressions.supp" ./a.out
+ ...
+
+Suppressions specified in this file are one of two flavors.
+
+``function-name-matches`` suppresses reporting of any intercepted library call, or function marked ``[[clang::blocking]]`` by name. If, for instance, you know that ``malloc`` is real-time safe on your system, you can disable the check for it via ``function-name-matches:malloc``.
+
+``call-stack-contains`` suppresses reporting of errors in any stack that contains a string matching the pattern specified. For example, suppressing error reporting of any non-real-time-safe behavior in ``std::vector`` may be specified ``call-stack-contains:std::*vector``. You must include symbols in your build for this method to be effective, unsymbolicated stack traces cannot be matched. ``call-stack-contains`` has the highest run-time cost of any method of suppression.
+
+Patterns may be exact matches or are "regex-light" patterns, containing special characters such as ``^$*``.
+
Compile-time sanitizer detection
--------------------------------
>From 41013702415d83b8207dace479b6c6def6d3a094 Mon Sep 17 00:00:00 2001
From: Chris Apple <cja-private at pm.me>
Date: Thu, 17 Oct 2024 19:22:50 -0700
Subject: [PATCH 2/5] [PR] fmayer - few tweaks
---
clang/docs/RealtimeSanitizer.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index bec15fd6cad2ac..b4ad9b126b6a88 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -218,7 +218,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
- Compile-time
- Stack
- Very low
- - Suppresses all sanitizer error reports in the current scope and all invoked functions.
+ - Suppresses all RTSan error reports in the current scope and all invoked functions.
* - ``function-name-matches`` suppression
- Run-time
- Single function
@@ -234,7 +234,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
``ScopedDisabler``
##################
-At compile time, RealtimeSanitizer may be disabled for a scope using ``__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.
+At compile time, RealtimeSanitizer may be disabled for a scope using ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all RTSan error reports are suppressed for that thread. This suppression applies to the current scope as well as all invoked functions, including any functions called transitively.
.. code-block:: c++
>From acc7db97145ea49447dc017a04a606da4bb853e5 Mon Sep 17 00:00:00 2001
From: Chris Apple <cja-private at pm.me>
Date: Thu, 24 Oct 2024 08:11:08 -0700
Subject: [PATCH 3/5] [PR] dtraev - Suppresses->ignored
---
clang/docs/RealtimeSanitizer.rst | 10 ++++++----
1 file changed, 6 insertions(+), 4 deletions(-)
diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index b4ad9b126b6a88..3a6fe3a6458b57 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -201,7 +201,7 @@ Some issues with flags can be debugged using the ``verbosity=$NUM`` flag:
Disabling and suppressing
-------------------------
-There are multiple ways to suppress error reporting when using RealtimeSanitizer.
+There are multiple ways to disable error reporting when using RealtimeSanitizer.
In general, ``ScopedDisabler`` should be preferred, as it is the most performant.
@@ -209,7 +209,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
:widths: 30 15 15 10 70
:header-rows: 1
- * - Suppression method
+ * - Method
- Specified at?
- Scope
- Run-time cost
@@ -218,7 +218,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
- Compile-time
- Stack
- Very low
- - Suppresses all RTSan error reports in the current scope and all invoked functions.
+ - Violations are ignored for the lifetime of the ``ScopedDisabler`` object.
* - ``function-name-matches`` suppression
- Run-time
- Single function
@@ -234,7 +234,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
``ScopedDisabler``
##################
-At compile time, RealtimeSanitizer may be disabled for a scope using ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all RTSan error reports are suppressed for that thread. This suppression applies to the current scope as well as all invoked functions, including any functions called transitively.
+At compile time, RealtimeSanitizer may be disabled using ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all potential RTSan errors are ignored for that thread including all invoked functions, and any functions called transitively.
.. code-block:: c++
@@ -291,6 +291,8 @@ Suppressions specified in this file are one of two flavors.
Patterns may be exact matches or are "regex-light" patterns, containing special characters such as ``^$*``.
+The number of potential errors suppressed via this method may be seen on exit when using the ``print_stats_on_exit`` flag.
+
Compile-time sanitizer detection
--------------------------------
>From c3187f705606807589c9d741bd701063c2d43749 Mon Sep 17 00:00:00 2001
From: Chris Apple <cja-private at pm.me>
Date: Thu, 24 Oct 2024 10:54:27 -0700
Subject: [PATCH 4/5] [PR] dtraev - Simplify sentence
---
clang/docs/RealtimeSanitizer.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index 3a6fe3a6458b57..c4358175b33957 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -234,7 +234,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
``ScopedDisabler``
##################
-At compile time, RealtimeSanitizer may be disabled using ``__rtsan::ScopedDisabler``. Within the scope where the ``ScopedDisabler`` object is instantiated, all potential RTSan errors are ignored for that thread including all invoked functions, and any functions called transitively.
+At compile time, RealtimeSanitizer may be disabled using ``__rtsan::ScopedDisabler``. All RTSan errors are ignored within the lifetime scope of the ``ScopedDisabler`` object.
.. code-block:: c++
>From f5e86ef2e8272f09e157525ecc245fe216dcda1c Mon Sep 17 00:00:00 2001
From: Chris Apple <cja-private at pm.me>
Date: Fri, 25 Oct 2024 10:56:22 -0700
Subject: [PATCH 5/5] Reword sentence about scopeddisabler
---
clang/docs/RealtimeSanitizer.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index c4358175b33957..b09162cd99f450 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -234,7 +234,7 @@ In general, ``ScopedDisabler`` should be preferred, as it is the most performant
``ScopedDisabler``
##################
-At compile time, RealtimeSanitizer may be disabled using ``__rtsan::ScopedDisabler``. All RTSan errors are ignored within the lifetime scope of the ``ScopedDisabler`` object.
+At compile time, RealtimeSanitizer may be disabled using ``__rtsan::ScopedDisabler``. RTSan ignores any errors originating within the ``ScopedDisabler`` instance variable scope.
.. code-block:: c++
More information about the cfe-commits
mailing list