[asan] Update the llvm webpage describing ASan

[zaks.anna]

Summary

This commit contains several updates to the Address Sanitizer webpage:

• Add the description of the interceptor suppression ("Suppressing Reports in external Libraries")
• Re-organized a bit: grouped a few things under the Issue Suppression section, grouped IOC and leaks under a section, placed symbolication info into Symbolizing the Reports section..
• "MacOS" -> "OS X"
• Added a paragraph to the Usage section describing when DYLD_INSERT_LIBRARIES might need to be used.

(I've added the generated html into the Test Plan. Hope that works:))

[zaks.anna]

Let's try to add the generated html again:

AddressSanitizer.html21 KBDownload

[samsonov]

Thanks for working on this!

docs/AddressSanitizer.rst

64

I would prefer bullet points for reasons.

66

I think we don't have to mention Valgrind, and just claim that all ASan errors are true positives, and
the program can be in inconsistent state, causing confusing results, and (potentially) misleading
subsequent reports.

235–236

I wonder if we can bump it to 10.7...

275

That's weird to have this at the very bottom. Maybe, put between limitations and platforms?

282

While you're here.... it's not experimental anymore - it's on by default for Linux. (not implemented on Mac)

[zaks.anna]

docs/AddressSanitizer.rst

66

Will do. This was copy and pasted from the original.

235–236

I'd definitely be ok with this!

282

What about Android and FreeBSD? Is it only available on Linux?

[samsonov]

docs/AddressSanitizer.rst

235–236

Yes, I see that we already build runtime with -mmacosx-version-min=10.7

282

Yes, for now it's Linux-only (though porting to FreeBSD is probably manageable).

[zaks.anna]

• Addressed Alexey's review comments.
• Moved the Additional Checks much closer to the top.
• Updated the LeakSanitizer page as well.

[samsonov]

LGTM

docs/AddressSanitizer.rst

69

s/inconstant/inconsistent?

[glider]

LGTM with a couple of nits.

docs/AddressSanitizer.rst

69

"the program heap" instead of "the program", maybe?

78

"the ASan library"

130

IIRC this feature still doesn't work on OSX, shall we mention that?

195–196

What about __attribute__((no_sanitize("address")))?

254

Shall we reflect the current iOS port state?

[zaks.anna]

docs/AddressSanitizer.rst

69

It does not have to be the heap; it can be anything. All you know is that something is trying to access an address that is not accessible.

78

I am going to correct the capitalization and add the following:
(You can find the library by searching for dynamic libraries with "asan" in their name.)

130

What about Android and FreeBSD?

195–196

Should we suggest using attribute((no_sanitize("address"))) instead of attribute((no_sanitize_address))?

And not mention attribute((no_sanitize_address)) at all?

[samsonov]

docs/AddressSanitizer.rst

130

Should work there.

195–196

Yeah, we want no_sanitize("list", "of", "sanitizers") to eventually replace it.

[zaks.anna]

Addressed comments from glider.

[glider]

Still LGTM
So what about the iOS port?

docs/AddressSanitizer.rst

69

Agreed.

[zaks.anna]

In r240725
(I've added iOS Simulator as supported.)

docs/AddressSanitizer.rst

 .. code-block:: console
 
     # Compile
     % clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
     # Link
     % clang -g -fsanitize=address example_UseAfterFree.o
 
 If a bug is detected, the program will print an error message to stderr and
-exit with a non-zero exit code. To make AddressSanitizer symbolize its output
+exit with a non-zero exit code. AddressSanitizer exits on the first detected error.
+This is by design:
+
+* This approach allows AddressSanitizer to produce faster and smaller generated code
+  (both by ~5%).
+* Fixing bugs becomes unavoidable. AddressSaniftizer does not produce
+  false alarms. Once a memory corruption occurs, the program is in an inconsistent
+  state, which could lead to confusing results and potentially misleading
+  subsequent reports.
+
+If your process is sandboxed and you are running on OS X 10.10 or earlier, you
+will need to set ``DYLD_INSERT_LIBRARIES`` environment variable and point it to
+the ASan library that is packaged with the compiler used to build the
+executable. (You can find the library by searching for dynamic libraries with
+``asan`` in their name.) If the environment variable is not set, the process will
+try to re-exec. Also keep in mind that when moving the executable to another machine,
+the ASan library will also need to be copied over.
+
+Symbolizing the Reports
+=========================
+
+To make AddressSanitizer symbolize its output
 you need to set the ``ASAN_SYMBOLIZER_PATH`` environment variable to point to
 the ``llvm-symbolizer`` binary (or make sure ``llvm-symbolizer`` is in your
 ``$PATH``):
 
 .. code-block:: console
 
     % ASAN_SYMBOLIZER_PATH=/usr/local/bin/llvm-symbolizer ./a.out
     ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
.. code-block:: console
     READ of size 4 at 0x7f7ddab8c084 thread T0
         #0 0x403c8c in main example_UseAfterFree.cc:4
         #1 0x7f7ddabcac4d in __libc_start_main ??:0
     ...
 
 Note that on OS X you may need to run ``dsymutil`` on your binary to have the
 file\:line info in the AddressSanitizer reports.
 
-AddressSanitizer exits on the first detected error. This is by design.
-One reason: it makes the generated code smaller and faster (both by
-~5%). Another reason: this makes fixing bugs unavoidable. With Valgrind,
-it is often the case that users treat Valgrind warnings as false
-positives (which they are not) and don't fix them.
+Additional Checks
+=================
+
+Initialization order checking
+-----------------------------
+
+AddressSanitizer can optionally detect dynamic initialization order problems,
+when initialization of globals defined in one translation unit uses
+globals defined in another translation unit. To enable this check at runtime,
+you should set environment variable
+``ASAN_OPTIONS=check_initialization_order=1``.
+
+Note that this option is not supported on OS X.
+
+Memory leak detection
+---------------------
+
+For more information on leak detector in AddressSanitizer, see
+:doc:`LeakSanitizer`. The leak detection is turned on by default on Linux;
+however, it is not yet supported on other platforms.
+
+Issue Suppression
+=================
+
+AddressSanitizer is not expected to produce false positives. If you see one,
+look again; most likely it is a true positive!
+
+Suppressing Reports in External Libraries
+-----------------------------------------
+Runtime interposition allows AddressSanitizer to find bugs in code that is
+not being recompiled. If you run into an issue in external libraries, we
+recommend immediately reporting it to the library maintainer so that it
+gets addressed. However, you can use the following suppression mechanism
+to unblock yourself and continue on with the testing. This suppression
+mechanism should only be used for suppressing issues in external code; it
+does not work on code recompiled with AddressSanitizer. To suppress errors
+in external libraries, set the ``ASAN_OPTIONS`` environment variable to point
+to a suppression file. You can either specify the full path to the file or the
+path of the file relative to the location of your executable.
+
+.. code-block:: bash
+
+    ASAN_OPTIONS=suppressions=MyASan.supp
+
+Use the following format to specify the names of the functions or libraries
+you want to suppress. You can see these in the error report. Remember that
+the narrower the scope of the suppression, the more bugs you will be able to
+catch.
 
-``__has_feature(address_sanitizer)``
-------------------------------------
+.. code-block:: bash
+
+    interceptor_via_fun:NameOfCFunctionToSuppress
+    interceptor_via_fun:-[ClassName objCMethodToSuppress:]
+    interceptor_via_lib:NameOfTheLibraryToSuppress
+
+Conditional Compilation with ``__has_feature(address_sanitizer)``
+-----------------------------------------------------------------
 
 In some cases one may need to execute different code depending on whether
 AddressSanitizer is enabled.
 :ref:`\_\_has\_feature <langext-__has_feature-__has_extension>` can be used for
 this purpose.
 
 .. code-block:: c
 
     #if defined(__has_feature)
     #  if __has_feature(address_sanitizer)
     // code that builds only under AddressSanitizer
     #  endif
     #endif
 
-``__attribute__((no_sanitize_address))``
------------------------------------------------
+Disabling Instrumentation with ``__attribute__((no_sanitize("address")))``
+--------------------------------------------------------------------------
 
 Some code should not be instrumented by AddressSanitizer. One may use the
-function attribute
-:ref:`no_sanitize_address <langext-address_sanitizer>`
-(or a deprecated synonym `no_address_safety_analysis`)
-to disable instrumentation of a particular function. This attribute may not be
-supported by other compilers, so we suggest to use it together with
-``__has_feature(address_sanitizer)``.
+function attribute ``__attribute__((no_sanitize("address")))``
+(which has deprecated synonyms
+:ref:`no_sanitize_address <langext-address_sanitizer>` and
+`no_address_safety_analysis`) to disable instrumentation of a particular
+function. This attribute may not be supported by other compilers, so we suggest
+to use it together with ``__has_feature(address_sanitizer)``.
 
-Initialization order checking
------------------------------
-
-AddressSanitizer can optionally detect dynamic initialization order problems,
-when initialization of globals defined in one translation unit uses
-globals defined in another translation unit. To enable this check at runtime,
-you should set environment variable
-``ASAN_OPTIONS=check_initialization_order=1``.
-
-Blacklist
----------
+Suppressing Errors in Recompiled Code (Blacklist)
+-------------------------------------------------
 
 AddressSanitizer supports ``src`` and ``fun`` entity types in
 :doc:`SanitizerSpecialCaseList`, that can be used to suppress error reports
 in the specified source files or functions. Additionally, AddressSanitizer
 introduces ``global`` and ``type`` entity types that can be used to
 suppress error reports for out-of-bound access to globals with certain
 names and types (you may only specify class or struct types).
 
.. code-block:: bash
     # Disable out-of-bound checks for global instances of a given class ...
     type:Namespace::BadClassName
     # ... or a given struct. Use wildcard to deal with anonymous namespace.
     type:Namespace2::*::BadStructName
     # Disable initialization-order checks for globals:
     global:bad_init_global=init
     type:*BadInitClassSubstring*=init
     src:bad/init/files/*=init
 
-Memory leak detection
----------------------
-
-For the experimental memory leak detector in AddressSanitizer, see
-:doc:`LeakSanitizer`.
-
-Supported Platforms
-===================
-
-AddressSanitizer is supported on
-
-* Linux i386/x86\_64 (tested on Ubuntu 12.04);
-* MacOS 10.6 - 10.9 (i386/x86\_64).
-* Android ARM
-* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
-
-Ports to various other platforms are in progress.
-
 Limitations
 ===========
 
 * AddressSanitizer uses more real memory than a native run. Exact overhead
   depends on the allocations sizes. The smaller the allocations you make the
   bigger the overhead is.
 * AddressSanitizer uses more stack memory. We have seen up to 3x increase.
 * On 64-bit platforms AddressSanitizer maps (but not reserves) 16+ Terabytes of
   virtual address space. This means that tools like ``ulimit`` may not work as
   usually expected.
 * Static linking is not supported.
 
+Supported Platforms
+===================
+
+AddressSanitizer is supported on:
+
+* Linux i386/x86\_64 (tested on Ubuntu 12.04)
+* OS X 10.7 - 10.11 (i386/x86\_64)
+* Android ARM
+* FreeBSD i386/x86\_64 (tested on FreeBSD 11-current)
+
+Ports to various other platforms are in progress.
+
 Current Status
 ==============
 
 AddressSanitizer is fully functional on supported platforms starting from LLVM
 3.1. The test suite is integrated into CMake build and can be run with ``make
 check-asan`` command.
 
 More Information
 ================
 
 `http://code.google.com/p/address-sanitizer <http://code.google.com/p/address-sanitizer/>`_
 

docs/LeakSanitizer.rst

 :doc:`AddressSanitizer` to get both memory error and leak detection.
 LeakSanitizer does not introduce any additional slowdown when used in this mode.
 The LeakSanitizer runtime can also be linked in separately to get leak detection
 only, at a minimal performance cost.
 
 Current status
 ==============
 
-LeakSanitizer is experimental and supported only on x86\_64 Linux.
+LeakSanitizer is turned on by default, but it is only supported on x86\_64 
+Linux.
 
 The combined mode has been tested on fairly large software projects. The
 stand-alone mode has received much less testing.
 
 There are plans to support LeakSanitizer in :doc:`MemorySanitizer` builds.
 
 More Information
 ================
 
 `https://code.google.com/p/address-sanitizer/wiki/LeakSanitizer
 <https://code.google.com/p/address-sanitizer/wiki/LeakSanitizer>`_