[PATCH] D40938: update hwasan docs

[Kostya Serebryany via Phabricator via cfe-commits]

kcc created this revision.
Herald added a subscriber: cfe-commits.

- use more readable name
- document the hwasan attribute


Repository:
  rC Clang

https://reviews.llvm.org/D40938

Files:
  docs/HardwareAssistedAddressSanitizerDesign.rst


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,
@@ -99,7 +114,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.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D40938.125868.patch
Type: text/x-patch
Size: 2661 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20171207/0d6d2acc/attachment-0001.bin>