llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-clang Author: Chris Apple (cjappl) <details> <summary>Changes</summary> --- Full diff: https://github.com/llvm/llvm-project/pull/112727.diff 1 Files Affected: - (modified) clang/docs/RealtimeSanitizer.rst (+62-4) ``````````diff 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 -------------------------------- `````````` </details> https://github.com/llvm/llvm-project/pull/112727 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
