Index: cfe/trunk/docs/MemorySanitizer.rst =================================================================== --- cfe/trunk/docs/MemorySanitizer.rst +++ cfe/trunk/docs/MemorySanitizer.rst @@ -48,10 +48,7 @@ % 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 @@ -60,7 +57,9 @@ #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 `. ``__has_feature(memory_sanitizer)`` ------------------------------------ @@ -102,10 +101,12 @@ 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 @@ -143,14 +144,29 @@ 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. @@ -167,9 +183,7 @@ Supported Platforms =================== -MemorySanitizer is supported on - -* Linux x86\_64 (tested on Ubuntu 12.04); +MemorySanitizer is supported on Linux x86\_64/MIPS64/AArch64. Limitations =========== @@ -180,19 +194,17 @@ 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 ================ Index: cfe/trunk/docs/UsersManual.rst =================================================================== --- cfe/trunk/docs/UsersManual.rst +++ cfe/trunk/docs/UsersManual.rst @@ -958,8 +958,8 @@ - .. _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`, @@ -986,31 +986,6 @@ - ``-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