Index: docs/HardwareAssistedAddressSanitizerDesign.rst
===================================================================
--- docs/HardwareAssistedAddressSanitizerDesign.rst
+++ docs/HardwareAssistedAddressSanitizerDesign.rst
@@ -1,9 +1,9 @@
-=====================================================
-HardwareAssistedAddressSanitizer Design Documentation
-=====================================================
+=======================================================
+Hardware-assisted AddressSanitizer Design Documentation
+=======================================================
 
 This page is a design document for
-**HardwareAssistedAddressSanitizer** (or HWASAN)
+**hardware-assisted AddressSanitizer** (or **HWASAN**)
 a tool similar to :doc:`AddressSanitizer`,
 but based on partial hardware assistance.
 
@@ -23,7 +23,7 @@
 
 AArch64 has the `Address Tagging`_, a hardware feature that allows
 software to use 8 most significant bits of a 64-bit pointer as
-a tag. HardwareAssistedAddressSanitizer uses `Address Tagging`_
+a tag. HWASAN uses `Address Tagging`_
 to implement a memory safety tool, similar to :doc:`AddressSanitizer`,
 but with smaller memory overhead and slightly different (mostly better)
 accuracy guarantees.
@@ -77,11 +77,26 @@
 
 Errors are generated by `__builtin_trap` and are handled by a signal handler.
 
+Attribute
+---------
+
+HWASAN uses it's own LLVM IR Attribute `sanitize_hwaddress` and a matching
+C function attribute. An alternative would be to re-use ASAN's attribute
+`sanitize_address`. The reasons to use a separate attribute are:
+
+  * Users may need to disable ASAN but not HWASAN, or vise versa,
+    because the tools have different trade-offs and compatibility issues.
+  * LLVM (ideally) does not use flags to decide which pass is being used,
+    ASAN or HWASAN are being applied, based on the function attributes.
+
+This does mean that users of HWASAN may need to add the new attribute
+to the code that already uses the old attribute.
+
 
 Comparison with AddressSanitizer
 ================================
 
-HardwareAssistedAddressSanitizer:
+HWASAN:
   * Is less portable than :doc:`AddressSanitizer`
     as it relies on hardware `Address Tagging`_ (AArch64).
     Address Tagging can be emulated with compiler instrumentation,
@@ -91,7 +106,8 @@
   * May have compatibility problems if the target code uses higher
     pointer bits for other purposes.
   * May require changes in the OS kernels (e.g. Linux seems to dislike
-    tagged pointers passed from address space).
+    tagged pointers passed from address space:
+    https://www.kernel.org/doc/Documentation/arm64/tagged-pointers.txt).
   * **Does not require redzones to detect buffer overflows**,
     but the buffer overflow detection is probabilistic, with roughly
     `(2**K-1)/(2**K)` probability of catching a bug.
@@ -99,7 +115,7 @@
     or stack-use-after-return**.
     The detection is similarly probabilistic.
 
-The memory overhead of HardwareAssistedAddressSanitizer is expected to be much smaller
+The memory overhead of HWASAN is expected to be much smaller
 than that of AddressSanitizer:
 `1/N` extra memory for the shadow
 and some overhead due to `N`-aligning all objects.