[Docs] Update MSan docs

[samsonov]

Summary

1. Move MSan-specific flags and features from user manual to MSan page.
2. Update current status / list of supported platforms.

[eugenis]

docs/MemorySanitizer.rst

109 ↗

(On Diff #41941)

uninitialized

188 ↗

(On Diff #41941)

14.04, too
maybe not mention the version at all?

[samsonov]

Addressed, thanks!

cfe/trunk/docs/MemorySanitizer.rst

int main(int argc, char** argv) {
       if (a[argc])
         printf("xx\n");
       return 0;
     }
 
     % clang -fsanitize=memory -fno-omit-frame-pointer -g -O2 umr.cc
 
 If a bug is detected, the program will print an error message to
-stderr and exit with a non-zero exit code. Currently, MemorySanitizer
-does not symbolize its output by default, so you may need to use a
-separate script to symbolize the result offline (this will be fixed in
-future).
+stderr and exit with a non-zero exit code.
 
 .. code-block:: console
 
     % ./a.out
     WARNING: MemorySanitizer: use-of-uninitialized-value
         #0 0x7f45944b418a in main umr.cc:6
         #1 0x7f45938b676c in __libc_start_main libc-start.c:226
 
-By default, MemorySanitizer exits on the first detected error.
+By default, MemorySanitizer exits on the first detected error. If you
+find the error report hard to understand, try enabling
+:ref:`origin tracking <msan-origins>`.
 
 ``__has_feature(memory_sanitizer)``
 ------------------------------------
 
 In some cases one may need to execute different code depending on
 whether MemorySanitizer is enabled. :ref:`\_\_has\_feature
 <langext-__has_feature-__has_extension>` can be used for this purpose.
 

 
 Report symbolization
 ====================
 
 MemorySanitizer uses an external symbolizer to print files and line numbers in
 reports. Make sure that ``llvm-symbolizer`` binary is in ``PATH``,
 or set environment variable ``MSAN_SYMBOLIZER_PATH`` to point to it.
 
+.. _msan-origins:
+
 Origin Tracking
 ===============
 
-MemorySanitizer can track origins of unitialized values, similar to
+MemorySanitizer can track origins of uninitialized values, similar to
 Valgrind's --track-origins option. This feature is enabled by
 ``-fsanitize-memory-track-origins=2`` (or simply
 ``-fsanitize-memory-track-origins``) Clang option. With the code from
 the example above,
 
 .. code-block:: console
 
     % cat umr2.cc
WARNING: MemorySanitizer: use-of-uninitialized-value
       Uninitialized value was created by a heap allocation
         #0 0x7f7893901cbd in operator new[](unsigned long) msan_new_delete.cc:44
         #1 0x7f7893912e06 in main umr2.cc:4
 
 By default, MemorySanitizer collects both allocation points and all
 intermediate stores the uninitialized value went through.  Origin
 tracking has proved to be very useful for debugging MemorySanitizer
 reports. It slows down program execution by a factor of 1.5x-2x on top
-of the usual MemorySanitizer slowdown.
+of the usual MemorySanitizer slowdown and increases memory overhead.
 
-Clang option ``-fsanitize-memory-track-origins=1`` enabled a slightly
+Clang option ``-fsanitize-memory-track-origins=1`` enables a slightly
 faster mode when MemorySanitizer collects only allocation points but
 not intermediate stores.
 
+Use-after-destruction detection
+===============================
+
+You can enable experimental use-after-destruction detection in MemorySanitizer.
+After invocation of the destructor, the object will be considered no longer
+readable, and using underlying memory will lead to error reports in runtime.
+
+This feature is still experimental, in order to enable it at runtime you need
+to:
+
+#. Pass addition Clang option ``-fsanitize-memory-use-after-dtor`` during
+   compilation.
+#. Set environment variable `MSAN_OPTIONS=poison_in_dtor=1` before running
+   the program.
+
 Handling external code
-============================
+======================
 
 MemorySanitizer requires that all program code is instrumented. This
 also includes any libraries that the program depends on, even libc.
 Failing to achieve this may result in false reports.
 
 Full MemorySanitizer instrumentation is very difficult to achieve. To
 make it easier, MemorySanitizer runtime library includes 70+
 interceptors for the most common libc functions. They make it possible
 to run MemorySanitizer-instrumented programs linked with
 uninstrumented libc. For example, the authors were able to bootstrap
 MemorySanitizer-instrumented Clang compiler by linking it with
 self-built instrumented libc++ (as a replacement for libstdc++).
 
 Supported Platforms
 ===================
 
-MemorySanitizer is supported on
-
-* Linux x86\_64 (tested on Ubuntu 12.04);
+MemorySanitizer is supported on Linux x86\_64/MIPS64/AArch64.
 
 Limitations
 ===========
 
 * MemorySanitizer uses 2x more real memory than a native run, 3x with
   origin tracking.
 * MemorySanitizer maps (but not reserves) 64 Terabytes of virtual
   address space. This means that tools like ``ulimit`` may not work as
   usually expected.
 * Static linking is not supported.
-* Non-position-independent executables are not supported.  Therefore, the
-  ``fsanitize=memory`` flag will cause Clang to act as though the ``-fPIE``
-  flag had been supplied if compiling without ``-fPIC``, and as though the
-  ``-pie`` flag had been supplied if linking an executable.
-* Depending on the version of Linux kernel, running without ASLR may
-  be not supported. Note that GDB disables ASLR by default. To debug
-  instrumented programs, use "set disable-randomization off".
+* Older versions of MSan (LLVM 3.7 and older) didn't work with
+  non-position-independent executables, and could fail on some Linux
+  kernel versions with disabled ASLR. Refer to documentation for older versions
+  for more details.
 
 Current Status
 ==============
 
-MemorySanitizer is an experimental tool. It is known to work on large
-real-world programs, like Clang/LLVM itself.
+MemorySanitizer is known to work on large real-world programs
+(like Clang/LLVM itself) that can be recompiled from source, including all
+dependent libraries.
 
 More Information
 ================
 
 `<https://github.com/google/sanitizers/wiki/MemorySanitizer>`_

cfe/trunk/docs/UsersManual.rst

-  .. _opt_fsanitize_address:
       :doc:`AddressSanitizer`, a memory error
       detector.
    -  .. _opt_fsanitize_thread:
 
       ``-fsanitize=thread``: :doc:`ThreadSanitizer`, a data race detector.
    -  .. _opt_fsanitize_memory:
 
       ``-fsanitize=memory``: :doc:`MemorySanitizer`,
-      an *experimental* detector of uninitialized reads. Not ready for
-      widespread use.
+      a detector of uninitialized reads. Requires instrumentation of all
+      program code.
    -  .. _opt_fsanitize_undefined:
 
       ``-fsanitize=undefined``: :doc:`UndefinedBehaviorSanitizer`,
       a fast and compatible undefined behavior checker.
 
    -  ``-fsanitize=dataflow``: :doc:`DataFlowSanitizer`, a general data
       flow analysis.
    -  ``-fsanitize=cfi``: :doc:`control flow integrity <ControlFlowIntegrity>`
**-f[no-]sanitize=check1,check2,...**
    or even variables by providing a special file:
 
    -  ``-fsanitize-blacklist=/path/to/blacklist/file``: disable or modify
       sanitizer checks for objects listed in the file. See
       :doc:`SanitizerSpecialCaseList` for file format description.
    -  ``-fno-sanitize-blacklist``: don't use blacklist file, if it was
       specified earlier in the command line.
 
-   Extra features of MemorySanitizer (require explicit
-   ``-fsanitize=memory``):
-
-   -  ``-fsanitize-memory-track-origins[=level]``: Enables origin tracking in
-      MemorySanitizer. Adds a second section to MemorySanitizer
-      reports pointing to the heap or stack allocation the
-      uninitialized bits came from. Slows down execution by additional
-      1.5x-2x.
-
-      Possible values for level are 0 (off), 1, 2 (default). Level 2
-      adds more sections to MemorySanitizer reports describing the
-      order of memory stores the uninitialized value went
-      through. This mode may use extra memory in programs that copy
-      uninitialized memory a lot.
-   -  ``-fsanitize-memory-use-after-dtor``: Enables use-after-destruction
-      detection in MemorySanitizer. After invocation of the destructor,
-      the object is considered no longer readable. Facilitates the
-      detection of use-after-destroy bugs.
-
-      Setting the MSAN_OPTIONS=poison_in_dtor=1 enables the poisoning of
-      memory at runtime. Any subsequent access to the destroyed object
-      fails at runtime. This feature is still experimental, but this
-      environment variable must be set to 1 in order for the above flag
-      to have any effect.
-
    The ``-fsanitize=`` argument must also be provided when linking, in
    order to link to the appropriate runtime library. When using
    ``-fsanitize=vptr`` (or a group that includes it, such as
    ``-fsanitize=undefined``) with a C++ program, the link must be
    performed by ``clang++``, not ``clang``, in order to link against the
    C++-specific parts of the runtime library.
 
    It is not possible to combine more than one of the ``-fsanitize=address``,