https://github.com/alazarev created
https://github.com/llvm/llvm-project/pull/220075
Create basic user-facing documentation for Hardware-assisted AddressSanitizer
(HWASan / `-fsanitize=hwaddress`) covering:
- Overview of HWASan and detectable bug types
- Comparison with AddressSanitizer (memory overhead, large out-of-bounds
detection)
- Supported platforms and kernel requirements
- How to build Clang with compiler-rt
- Compilation and usage example with sample error report
- Symbolization via llvm-symbolizer
- Runtime flags via `HWASAN_OPTIONS` and `__hwasan_default_options`
- Selective disabling via `__attribute__((no_sanitize("hwaddress")))`,
`__has_feature(hwaddress_sanitizer)`, and sanitizer ignorelists
- Cross-references to HardwareAssistedAddressSanitizerDesign and UsersManual
AI tool usage: An AI assistant was used to help research and draft the
documentation updates.
>From 27e728d2e6944847d640b258ec6a219282813a98 Mon Sep 17 00:00:00 2001
From: Andrew Lazarev <[email protected]>
Date: Mon, 31 Aug 2026 19:53:56 +0000
Subject: [PATCH] [clang][docs] Add user documentation for Hardware-assisted
AddressSanitizer (HWASan)
Create basic user-facing documentation for Hardware-assisted AddressSanitizer
(HWASan / -fsanitize=hwaddress) covering:
- Overview of HWASan and detectable bug types
- Comparison with AddressSanitizer (memory overhead, large out-of-bounds
detection)
- Supported platforms and kernel requirements
- How to build Clang with compiler-rt
- Compilation and usage example with sample error report
- Symbolization via llvm-symbolizer
- Runtime flags via HWASAN_OPTIONS and __hwasan_default_options
- Selective disabling via __attribute__((no_sanitize("hwaddress"))),
__has_feature(hwaddress_sanitizer), and sanitizer ignorelists
- Cross-references to HardwareAssistedAddressSanitizerDesign and UsersManual
AI tool usage: An AI assistant was used to help research and draft the
documentation updates.
---
.../docs/HardwareAssistedAddressSanitizer.md | 219 ++++++++++++++++++
.../HardwareAssistedAddressSanitizerDesign.md | 4 +-
clang/docs/SanitizerSpecialCaseList.md | 2 +-
clang/docs/UsersManual.md | 4 +
clang/docs/index.rst | 1 +
5 files changed, 228 insertions(+), 2 deletions(-)
create mode 100644 clang/docs/HardwareAssistedAddressSanitizer.md
diff --git a/clang/docs/HardwareAssistedAddressSanitizer.md
b/clang/docs/HardwareAssistedAddressSanitizer.md
new file mode 100644
index 0000000000000..fdcc52c162ad0
--- /dev/null
+++ b/clang/docs/HardwareAssistedAddressSanitizer.md
@@ -0,0 +1,219 @@
+# Hardware-assisted AddressSanitizer
+
+```{contents}
+:local: true
+```
+
+## Introduction
+
+Hardware-assisted AddressSanitizer (HWASan, or HWAddressSanitizer) is a fast
+memory error detector based on memory tagging and address tagging (such as
+Top-Byte Ignore / TBI on AArch64, Linear Address Masking / LAM on x86_64, or
+pointer masking on RISC-V). Similar to {doc}`AddressSanitizer`, it consists of
a
+compiler instrumentation module and a run-time library.
+
+HWASan can detect the following types of bugs:
+
+- Out-of-bounds accesses to heap, stack, and globals
+- Use-after-free
+- Use-after-return and use-after-scope
+- Double-free and invalid free
+
+### Comparison with AddressSanitizer
+
+While {doc}`AddressSanitizer` places unmapped/poisoned redzones around
+allocations and uses a 1:8 shadow memory to track byte states,
+Hardware-assisted AddressSanitizer assigns a random 8-bit tag to every 16-byte
+granule of memory (stored in a 1:16 shadow memory) as well as the pointer's
+top byte. On every memory access, the pointer tag is checked against the memory
+tag.
+
+Key advantages of HWASan over AddressSanitizer:
+
+- **Significantly lower memory overhead**: HWASan requires only a 1:16 shadow
+ memory (~6.25% of the application's address space) and does not require
+ redzones between heap allocations. Typical memory overhead is ~10-20%
+ (compared to ~2x or more for AddressSanitizer).
+- **Detection of large out-of-bounds errors**: AddressSanitizer can miss large
+ out-of-bounds accesses that jump over the redzone into adjacent memory.
+ HWASan detects mismatched tags probabilistically with a ~99.6% (255/256)
+ detection rate per bad access, regardless of distance.
+- **Smaller footprint**: Suitable for memory-constrained environments, large
+ server workloads, and whole-system testing (such as system-wide deployment in
+ Android).
+
+The execution time slowdown of HWASan is typically around **2x**, comparable to
+AddressSanitizer.
+
+## Supported Platforms
+
+Hardware-assisted AddressSanitizer is supported on:
+
+- **Linux AArch64**: Requires 64-bit ARM (ARMv8-A or later) with Top-Byte
Ignore
+ (TBI) and Linux kernel 5.4 or later (with the tagged address ABI).
+- **Android AArch64**: Supported natively on Android 10 (API level 29) and
later.
+- **Linux RISC-V 64**: With pointer masking support.
+- **Linux x86_64**: Experimental support using Intel Linear Address Masking
+ (LAM) or page aliasing.
+- **Fuchsia**: AArch64.
+
+## How to Build
+
+Build LLVM/Clang with [CMake](https://llvm.org/docs/CMake.html) and enable the
+`compiler-rt` runtime. An example CMake configuration:
+
+```console
+$ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS="clang"
-DLLVM_ENABLE_RUNTIMES="compiler-rt" <path to source>/llvm
+```
+
+## Usage
+
+Compile and link your program with the `-fsanitize=hwaddress` flag. The
+HWASan run-time library should be linked to the final executable, so make sure
+to use `clang` (not `ld`) for the final link step:
+
+```console
+% cat example_uaf.c
+#include <stdlib.h>
+
+int main() {
+ char *volatile x = (char *)malloc(10);
+ free(x);
+ return x[5]; // Use-after-free!
+}
+
+# Compile and link
+% clang -O1 -g -fsanitize=hwaddress -fno-omit-frame-pointer example_uaf.c
+```
+
+To get reasonable performance, add `-O1` or higher. To get nicer stack traces
+in error messages, add `-fno-omit-frame-pointer`.
+
+If a bug is detected, the program prints an error report to `stderr` and exits
+with a non-zero exit code (default: 99):
+
+```console
+% ./a.out
+==12345==ERROR: HWAddressSanitizer: tag-mismatch on address 0xef7a2b910005 at
pc 0xaaaacb240898
+READ of size 1 at 0xef7a2b910005 tags: 0xef/0x7b (ptr/mem)
+ #0 0xaaaacb240898 in main example_uaf.c:6
+[0xef7a2b910000,0xef7a2b910010) is a small unallocated heap chunk; size: 16
offset: 5
+
+Cause: use-after-free
+0xef7a2b910005 is located 5 bytes inside a 10-byte region
[0xef7a2b910000,0xef7a2b91000a)
+freed by thread T0 here:
+ #0 0xaaaacb2046df in free
/path/to/compiler-rt/lib/hwasan/hwasan_interceptors.cpp:110
+ #1 0xaaaacb24088c in main example_uaf.c:5
+
+previously allocated by thread T0 here:
+ #0 0xaaaacb204460 in malloc
/path/to/compiler-rt/lib/hwasan/hwasan_interceptors.cpp:95
+ #1 0xaaaacb24087c in main example_uaf.c:4
+
+Memory tags around the buggy address (one tag corresponds to 16 bytes):
+ 0xef7a2b90ff80: 00 00 00 00 00 00 00 00
+ 0xef7a2b90ff90: 00 00 00 00 00 00 00 00
+ 0xef7a2b90ffa0: 00 00 00 00 00 00 00 00
+ 0xef7a2b90ffb0: 00 00 00 00 00 00 00 00
+ 0xef7a2b90ffc0: 00 00 00 00 00 00 00 00
+ 0xef7a2b90ffd0: 00 00 00 00 00 00 00 00
+ 0xef7a2b90ffe0: 00 00 00 00 00 00 00 00
+ 0xef7a2b90fff0: 00 00 00 00 00 00 00 00
+=>0xef7a2b910000:[7b] 00 00 00 00 00 00 00
+ 0xef7a2b910010: 00 00 00 00 00 00 00 00
+SUMMARY: HWAddressSanitizer: tag-mismatch example_uaf.c:6 in main
+```
+
+## Symbolizing the Reports
+
+To make HWAddressSanitizer symbolize its output, ensure `llvm-symbolizer` is in
+your `$PATH` or set the `HWASAN_SYMBOLIZER_PATH` environment variable:
+
+```console
+% HWASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
+```
+
+## Flags and Options
+
+Runtime flags can be passed to HWAddressSanitizer via the `HWASAN_OPTIONS`
+environment variable:
+
+```console
+$ HWASAN_OPTIONS="halt_on_error=0:print_stats=1" ./a.out
+```
+
+To see the full list of available flags and their default values, run an
+instrumented binary with `HWASAN_OPTIONS="help=1"`.
+
+Commonly used flags include:
+
+- `halt_on_error` (default: `true`): If set to `false`, continue execution
after
+ reporting an error instead of terminating immediately.
+- `print_stats` (default: `false`): Print runtime statistics upon process exit.
+- `random_tags` (default: `true`): Use random tag values. If set to `false`,
use
+ a simple thread-local counter increment for tag generation.
+- `tag_in_malloc` (default: `true`): Enable memory tagging for heap
allocations.
+- `tag_in_free` (default: `true`): Retag memory with a new tag when deallocated
+ via `free`.
+
+### Compile-time Default Options
+
+Default options can be specified at compile/link time by defining the
+`__hwasan_default_options` function in your source code:
+
+```c
+#include <sanitizer/hwasan_interface.h>
+
+extern "C" const char *__hwasan_default_options() {
+ return "halt_on_error=0:print_stats=1";
+}
+```
+
+Flags passed via the `HWASAN_OPTIONS` environment variable take precedence over
+compile-time default options.
+
+## Selective Disabling
+
+### Disabling Instrumentation with `__attribute__((no_sanitize("hwaddress")))`
+
+Some functions should not be instrumented by HWAddressSanitizer. Use the
+`__attribute__((no_sanitize("hwaddress")))` attribute to disable
instrumentation
+for a specific function:
+
+```c
+__attribute__((no_sanitize("hwaddress")))
+void uninstrumented_function() {
+ // ...
+}
+```
+
+You can also use `__attribute__((disable_sanitizer_instrumentation))` to
disable
+instrumentation across all sanitizers.
+
+### Conditional Compilation with `__has_feature(hwaddress_sanitizer)`
+
+To execute code conditionally when HWAddressSanitizer is enabled:
+
+```c
+#if defined(__has_feature)
+# if __has_feature(hwaddress_sanitizer)
+// Code enabled only under HWAddressSanitizer
+# endif
+#endif
+```
+
+### Ignorelist
+
+To suppress instrumentation for specific functions or source files without
+modifying code, pass an ignorelist file via the `-fsanitize-ignorelist` flag:
+
+```console
+% clang -fsanitize=hwaddress -fsanitize-ignorelist=hwasan_ignorelist.txt ...
+```
+
+See {doc}`SanitizerSpecialCaseList` for syntax and details.
+
+## Design Documentation
+
+For details on the HWASan algorithm, tagging granularity, short granules,
+shadow memory mapping, outlined vs. inline check implementations, and
+architecture-specific internals, see
{doc}`HardwareAssistedAddressSanitizerDesign`.
diff --git a/clang/docs/HardwareAssistedAddressSanitizerDesign.md
b/clang/docs/HardwareAssistedAddressSanitizerDesign.md
index f999c6c57f507..980cba1a99b41 100644
--- a/clang/docs/HardwareAssistedAddressSanitizerDesign.md
+++ b/clang/docs/HardwareAssistedAddressSanitizerDesign.md
@@ -1,9 +1,11 @@
# Hardware-assisted AddressSanitizer Design Documentation
This page is a design document for
-**hardware-assisted AddressSanitizer** (or **HWASAN**)
+**hardware-assisted AddressSanitizer** (or **HWASAN**),
a tool similar to {doc}`AddressSanitizer`,
but based on partial hardware assistance.
+For the user-facing documentation on how to use HWASan, see
+{doc}`HardwareAssistedAddressSanitizer`.
## Introduction
diff --git a/clang/docs/SanitizerSpecialCaseList.md
b/clang/docs/SanitizerSpecialCaseList.md
index 989a73d15a886..7b36322e9ec98 100644
--- a/clang/docs/SanitizerSpecialCaseList.md
+++ b/clang/docs/SanitizerSpecialCaseList.md
@@ -13,7 +13,7 @@ file at compile-time.
## Goal and usage
Users of sanitizer tools, such as {doc}`AddressSanitizer`,
-{doc}`HardwareAssistedAddressSanitizerDesign`, {doc}`ThreadSanitizer`,
+{doc}`HardwareAssistedAddressSanitizer`, {doc}`ThreadSanitizer`,
{doc}`MemorySanitizer` or {doc}`UndefinedBehaviorSanitizer` may want to disable
or alter some checks for certain source-level entities to:
diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index 40834746e1218..48c2da145a967 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -2280,6 +2280,10 @@ or suspicious behavior:
`-fsanitize=address`:
{doc}`AddressSanitizer`, a memory error
detector.
+- (opt_fsanitize_hwaddress)=
+ `-fsanitize=hwaddress`:
+ {doc}`HardwareAssistedAddressSanitizer`, a memory error detector with
+ lower memory overhead based on address tagging.
- (opt_fsanitize_thread)=
`-fsanitize=thread`: {doc}`ThreadSanitizer`, a data race detector.
- (opt_fsanitize_memory)=
diff --git a/clang/docs/index.rst b/clang/docs/index.rst
index ca2fc0b18d3af..451777ec7ddc0 100644
--- a/clang/docs/index.rst
+++ b/clang/docs/index.rst
@@ -33,6 +33,7 @@ Using Clang as a Compiler
DataFlowAnalysisIntro
FunctionEffectAnalysis
AddressSanitizer
+ HardwareAssistedAddressSanitizer
ThreadSanitizer
MemorySanitizer
UndefinedBehaviorSanitizer
_______________________________________________
cfe-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
