From a962eebcb65fe9716b68ff4b5d3b81e515a268e9 Mon Sep 17 00:00:00 2001 From: Kostya Serebryany Date: Thu, 7 Dec 2017 19:21:30 +0000 Subject: [PATCH] update hwasan docs Summary: * use more readable name * document the hwasan attribute Reviewers: eugenis Reviewed By: eugenis Subscribers: llvm-commits, cfe-commits Differential Revision: https://reviews.llvm.org/D40938 git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@320075 91177308-0d34-0410-b5e6-96231b3b80d8 --- ...HardwareAssistedAddressSanitizerDesign.rst | 32 ++++++++++++++----- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/docs/HardwareAssistedAddressSanitizerDesign.rst b/docs/HardwareAssistedAddressSanitizerDesign.rst index c0ee680f9d..2abd648a53 100644 --- a/docs/HardwareAssistedAddressSanitizerDesign.rst +++ b/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 @@ 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. @@ -77,11 +77,26 @@ 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, @@ -91,7 +106,8 @@ HardwareAssistedAddressSanitizer: * 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 @@ HardwareAssistedAddressSanitizer: 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. -- 2.50.1