https://github.com/melver updated https://github.com/llvm/llvm-project/pull/175106
>From a11fdc617683a4470a174a10c2abba6ed774e9bb Mon Sep 17 00:00:00 2001 From: Marco Elver <[email protected]> Date: Fri, 9 Jan 2026 02:13:54 +0100 Subject: [PATCH] [Clang] Improve documentation for __builtin_allow_sanitize_check() Clarify that the builtin is intended for guarding explicit sanitizer checks that use the runtime API to perform such checks. Update the description to use "allowed" instead of "active" to better reflect the intended usage and semantics, which would allow policy refinements in future [1]. Also make the examples more concrete. [1] https://discourse.llvm.org/t/explicit-sanitizer-checks-with-builtin-allow-sanitize-check/89383 --- clang/docs/AddressSanitizer.rst | 29 ++++++++++++++++------------- clang/docs/MemorySanitizer.rst | 29 ++++++++++++++++------------- clang/docs/ThreadSanitizer.rst | 29 ++++++++++++++++------------- 3 files changed, 48 insertions(+), 39 deletions(-) diff --git a/clang/docs/AddressSanitizer.rst b/clang/docs/AddressSanitizer.rst index dc0ba79f66cc2..3ae10e798ae95 100644 --- a/clang/docs/AddressSanitizer.rst +++ b/clang/docs/AddressSanitizer.rst @@ -254,37 +254,40 @@ AddressSanitizer also supports works similarly to ``__attribute__((no_sanitize("address")))``, but it also prevents instrumentation performed by other sanitizers. -Conditional Sanitizer Checks with ``__builtin_allow_sanitize_check`` --------------------------------------------------------------------- +Explicit Sanitizer Checks with ``__builtin_allow_sanitize_check`` +----------------------------------------------------------------- The ``__builtin_allow_sanitize_check("address")`` builtin can be used to -conditionally execute code only when AddressSanitizer is active for the current -function (after inlining). This is particularly useful for inserting explicit, -sanitizer-specific checks around operations like syscalls or inline assembly, -which might otherwise be unchecked by the sanitizer. +conditionally execute code depending on whether AddressSanitizer checks are +enabled and permitted by the current policy (after inlining). This is +particularly useful for inserting explicit, sanitizer-specific checks around +operations like syscalls or inline assembly, which might otherwise be unchecked +by the sanitizer. Example: .. code-block:: c + void __asan_load8(void *); + inline __attribute__((always_inline)) - void copy_to_device(void *addr, size_t size) { - if (__builtin_allow_sanitize_check("address")) { - // Custom checks that address range is valid. - } - // ... actual device memory copy logic, potentially a syscall ... + void my_helper(void *addr) { + if (__builtin_allow_sanitize_check("address")) + __asan_load8(addr); + // ... actual logic, e.g. inline assembly ... + asm volatile ("..." : : "r" (addr) : "memory"); } void instrumented_function() { ... - copy_to_device(buf, sizeof(buf)); // checks are active + my_helper(buf); // checks are active ... } __attribute__((no_sanitize("address"))) void uninstrumented_function() { ... - copy_to_device(buf, sizeof(buf)); // checks are skipped + my_helper(buf); // checks are skipped ... } diff --git a/clang/docs/MemorySanitizer.rst b/clang/docs/MemorySanitizer.rst index 54f88d076d36e..9b570841e799f 100644 --- a/clang/docs/MemorySanitizer.rst +++ b/clang/docs/MemorySanitizer.rst @@ -101,37 +101,40 @@ positives and therefore should be used with care, and only if absolutely required; for example for certain code that cannot tolerate any instrumentation and resulting side-effects. This attribute overrides ``no_sanitize("memory")``. -Conditional Sanitizer Checks with ``__builtin_allow_sanitize_check`` --------------------------------------------------------------------- +Explicit Sanitizer Checks with ``__builtin_allow_sanitize_check`` +----------------------------------------------------------------- The ``__builtin_allow_sanitize_check("memory")`` builtin can be used to -conditionally execute code only when MemorySanitizer is active for the current -function (after inlining). This is particularly useful for inserting explicit, -sanitizer-specific checks around operations like syscalls or inline assembly, -which might otherwise be unchecked by the sanitizer. +conditionally execute code depending on whether MemorySanitizer checks are +enabled and permitted by the current policy (after inlining). This is +particularly useful for inserting explicit, sanitizer-specific checks around +operations like syscalls or inline assembly, which might otherwise be unchecked +by the sanitizer. Example: .. code-block:: c + void __msan_check_mem_is_initialized(const void *, size_t); + inline __attribute__((always_inline)) - void copy_to_device(void *addr, size_t size) { - if (__builtin_allow_sanitize_check("memory")) { - // Custom checks if `data` is initialized. - } - // ... actual device memory copy logic, potentially a syscall ... + void my_send(void *addr, size_t size) { + if (__builtin_allow_sanitize_check("memory")) + __msan_check_mem_is_initialized(addr, size); + // ... syscall or other logic where MSan may not see the access ... + send(addr, size); } void instrumented_function() { ... - copy_to_device(buf, sizeof(buf)); // checks are active + my_send(buf, sizeof(buf)); // checks are active ... } __attribute__((no_sanitize("memory"))) void uninstrumented_function() { ... - copy_to_device(buf, sizeof(buf)); // checks are skipped + my_send(buf, sizeof(buf)); // checks are skipped ... } diff --git a/clang/docs/ThreadSanitizer.rst b/clang/docs/ThreadSanitizer.rst index c90d668600ec9..2f6b78ee2e00e 100644 --- a/clang/docs/ThreadSanitizer.rst +++ b/clang/docs/ThreadSanitizer.rst @@ -110,37 +110,40 @@ and only if absolutely required; for example for certain code that cannot tolerate any instrumentation and resulting side-effects. This attribute overrides ``no_sanitize("thread")``. -Conditional Sanitizer Checks with ``__builtin_allow_sanitize_check`` --------------------------------------------------------------------- +Explicit Sanitizer Checks with ``__builtin_allow_sanitize_check`` +----------------------------------------------------------------- The ``__builtin_allow_sanitize_check("thread")`` builtin can be used to -conditionally execute code only when ThreadSanitizer is active for the current -function (after inlining). This is particularly useful for inserting explicit, -sanitizer-specific checks around operations like syscalls or inline assembly, -which might otherwise be unchecked by the sanitizer. +conditionally execute code depending on whether ThreadSanitizer checks are +enabled and permitted by the current policy (after inlining). This is +particularly useful for inserting explicit, sanitizer-specific checks around +operations like syscalls or inline assembly, which might otherwise be unchecked +by the sanitizer. Example: .. code-block:: c + void __tsan_read8(void *); + inline __attribute__((always_inline)) - void copy_to_device(void *addr, size_t size) { - if (__builtin_allow_sanitize_check("thread")) { - // Custom checks that `data` is not concurrently modified. - } - // ... actual device memory copy logic, potentially a syscall ... + void my_helper(void *addr) { + if (__builtin_allow_sanitize_check("thread")) + __tsan_read8(addr); + // ... actual logic, e.g. inline assembly ... + asm volatile ("..." : : "r" (addr) : "memory"); } void instrumented_function() { ... - copy_to_device(&shared_data, size); // checks are active + my_helper(&shared_data); // checks are active ... } __attribute__((no_sanitize("thread"))) void uninstrumented_function() { ... - copy_to_device(&shared_data, size); // checks are skipped + my_helper(&shared_data); // checks are skipped ... } _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
