update hwasan docs

[kcc]

Summary

• use more readable name
• document the hwasan attribute

[kcc]

mention https://www.kernel.org/doc/Documentation/arm64/tagged-pointers.txt

docs/HardwareAssistedAddressSanitizerDesign.rst

-=====================================================
-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.
 
 The document is a draft, suggestions are welcome.
 
 
 Introduction
 ============
 
 :doc:`AddressSanitizer`
 tags every 8 bytes of the application memory with a 1 byte tag (using *shadow memory*),
 uses *redzones* to find buffer-overflows and
 *quarantine* to find use-after-free.
 The redzones, the quarantine, and, to a less extent, the shadow, are the
 sources of AddressSanitizer's memory overhead.
 See the `AddressSanitizer paper`_ for details.
 
 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.
 
 Algorithm
 =========
 * Every heap/stack/global memory object is forcibly aligned by `N` bytes
   (`N` is e.g. 16 or 64)

 
 TODO: details.
 
 Error reporting
 ---------------
 
 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,
     but it will require the instrumentation to remove the tags before
     any load or store, which is infeasible in any realistic environment
     that contains non-instrumented code.
   * 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.
   * **Does not require quarantine to detect heap-use-after-free,
     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.
 
 
 Related Work
 ============
 * `SPARC ADI`_ implements a similar tool mostly in hardware.