Merge header codeblock from <sanitizer/asan_interface.h>

asan_example.cpp

@@ -84,8 +84,22 @@ int main()
         "## Overview\n"
         "\n"
         "ASAN provides a way to manually markup ranges of bytes to\n"
-        "prohibit or permit reads to those addresses. There's a short\n"
-        "foot-note in Google's "
+        "prohibit or permit reads to those addresses. In\n"
+        "`<sanitizer/asan_interface.h>` there's a vague brief mention to\n"
+        "alignment requirements for the poison API:\n"
+        "\n"
+        "```cpp\n"
+        "/// ... This function is not guaranteed to poison the entire region -\n"
+        "/// it could poison only a subregion of <c>[addr, addr+size)</c> due to ASan\n"
+        "/// alignment restrictions.\n"
+        "void __asan_poison_memory_region(void const volatile *addr, size_t size);\n"
+        "\n"
+        "/// ... This function could unpoison a super-region of <c>[addr, addr+size)</c> due\n"
+        "/// to ASan alignment restrictions.\n"
+        "void __asan_unpoison_memory_region(void const volatile *addr, size_t size);\n"
+        "```\n"
+        "\n"
+        "There's another small foot-note in Google's "
         "[AddressSanitizerManualPoisoning](https://github.com/google/"
         "sanitizers/wiki/AddressSanitizerManualPoisoning)\n"
         "documentation that states:\n"
@@ -97,25 +111,24 @@ int main()
         "chunks should start with 8-aligned addresses.\n"
         "```\n"
         "\n"
-        "This repository runs some simple tests to clarify the behaviour of\n"
-        "the API on un/aligned addresses at various sizes without having\n"
+        "So then this repository runs some simple tests to clarify the behaviour\n"
+        "of the API on un/aligned addresses at various sizes without having\n"
         "to dig into source code or read the [ASAN paper](https://static."
         "googleusercontent.com/media/research.google.com/en/pubs/archive/"
         "37752.pdf).\n"
         "\n"
         "We use a stack-allocated 16 byte array and test un/poisoning\n"
         "various ranges of bytes from different alignments to clarify the\n"
-        "poisoning behaviour of the API.\n"
-        "\n"
-        "This reveals that calling the API haphazardly, unaligned or\n"
-        "straddling boundaries can lead to gaps in poisoned memory and hide\n"
-        "potential leaks (as also demonstrated in [Manual ASAN poisoning and\n"
-        "alignment](https://github.com/mcgov/asan_alignment_example)).\n"
+        "poisoning behaviour of the API. This reveals that calling the API\n"
+        "haphazardly, unaligned or straddling boundaries can lead to gaps in\n"
+        "poisoned memory and hide potential leaks (as also demonstrated in\n"
+        "[Manual ASAN poisoning and alignment]"
+        "(https://github.com/mcgov/asan_alignment_example)).\n"
         "\n"
         "## References\n"
         "\n"
         "- [Manual ASAN poisoning and alignment](https://github.com/mcgov/asan_alignment_example) example by `mcgov`\n"
-        "- [Address Sanitizer: A Fast Address Sanity Checker](https://static.googleusercontent.com/media/research.google.com/en/pubs/archive/37752.pdf)\n"
+        "- [Address Sanitizer: A Fast Address Sanity Checker](https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/37752.pdf)\n"
         "- [sanitizer/asan_interface.h](https://github.com/llvm-mirror/compiler-rt/blob/master/include/sanitizer/asan_interface.h)\n"
         "\n"
         "## Raw Test Results\n"

readme.md

@@ -25,8 +25,22 @@ marked-up memory that may lead to undetected read/writes.
 ## Overview
 
 ASAN provides a way to manually markup ranges of bytes to
-prohibit or permit reads to those addresses. There's a short
-foot-note in Google's [AddressSanitizerManualPoisoning](https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning)
+prohibit or permit reads to those addresses. In
+`<sanitizer/asan_interface.h>` there's a vague brief mention to
+alignment requirements for the poison API:
+
+```cpp
+/// ... This function is not guaranteed to poison the entire region -
+/// it could poison only a subregion of <c>[addr, addr+size)</c> due to ASan
+/// alignment restrictions.
+void __asan_poison_memory_region(void const volatile *addr, size_t size);
+
+/// ... This function could unpoison a super-region of <c>[addr, addr+size)</c> due
+/// to ASan alignment restrictions.
+void __asan_unpoison_memory_region(void const volatile *addr, size_t size);
+```
+
+There's another small foot-note in Google's [AddressSanitizerManualPoisoning](https://github.com/google/sanitizers/wiki/AddressSanitizerManualPoisoning)
 documentation that states:
 
 ```
@@ -36,32 +50,30 @@ of memory leaving poisoned redzones between them. The allocated
 chunks should start with 8-aligned addresses.
 ```
 
-This repository runs some simple tests to clarify the behaviour of
-the API on un/aligned addresses at various sizes without having
+So then this repository runs some simple tests to clarify the behaviour
+of the API on un/aligned addresses at various sizes without having
 to dig into source code or read the [ASAN paper](https://static.googleusercontent.com/media/research.google.com/en/pubs/archive/37752.pdf).
 
 We use a stack-allocated 16 byte array and test un/poisoning
 various ranges of bytes from different alignments to clarify the
-poisoning behaviour of the API.
-
-This reveals that calling the API haphazardly, unaligned or
-straddling boundaries can lead to gaps in poisoned memory and hide
-potential leaks (as also demonstrated in [Manual ASAN poisoning and
-alignment](https://github.com/mcgov/asan_alignment_example) example
-by `mcgov`.
+poisoning behaviour of the API. This reveals that calling the API
+haphazardly, unaligned or straddling boundaries can lead to gaps in
+poisoned memory and hide potential leaks (as also demonstrated in
+[Manual ASAN poisoning and alignment](https://github.com/mcgov/asan_alignment_example)).
 
 ## References
 
 - [Manual ASAN poisoning and alignment](https://github.com/mcgov/asan_alignment_example) example by `mcgov`
-- [Address Sanitizer: A Fast Address Sanity Checker](https://static.googleusercontent.com/media/research.google.com/en/pubs/archive/37752.pdf)
+- [Address Sanitizer: A Fast Address Sanity Checker](https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/37752.pdf)
 - [sanitizer/asan_interface.h](https://github.com/llvm-mirror/compiler-rt/blob/master/include/sanitizer/asan_interface.h)
 
 ## Raw Test Results
-Here we demonstrate that ASAN poison-ing will only poison the
-byte region if the region meets an 8 byte boundary. It will only
-poison bytes upto the 8 byte boundary, any bytes that straddle
-the boundary that do not hit the next 8 byte boundary are not
-poison-ed.
+
+Here we poison a sliding window of 7 bytes to demonstrate that ASAN
+poisoning will only poison the byte region if the region meets an 8
+byte aligned address. It will only poison bytes up to the boundary,
+any bytes that straddle the boundary that do not hit the next 8 byte
+boundary are not poisoned.
 
 ```
    Byte Array                    00 01 02 03 04 05 06 07 | 08 09 10 11 12 13 14 15