tools/sanitizer/docs/memory_sanitizer.rst

   1 Memory Sanitizer
   2 ================
   3
   4 +--------------------------------------------------------------------+
   5 | This page is an import from MDN and the contents might be outdated |
   6 +--------------------------------------------------------------------+
   7
   8 What is Memory Sanitizer?
   9 -------------------------
  10
  11 Memory Sanitizer (MSan) is a fast detector used for uninitialized memory
  12 in C/C++ programs. It uses a compile-time instrumentation to ensure that
  13 all memory access at runtime uses only memory that has been initialized.
  14 Unlike most other sanitizers, MSan can easily cause false positives if
  15 not all libraries are instrumented. This happens because MSan is
  16 not able to observe memory initialization in uninstrumented libraries.
  17 More information on MSan can be found on `the Memory Sanitizer
  18 wiki <https://github.com/google/sanitizers/wiki/MemorySanitizer>`__.
  19
  20 Public Builds
  21 -------------
  22
  23 **Note:** No public builds are available at this time yet.
  24
  25 Manual Build
  26 ------------
  27
  28 Build prerequisites
  29 ~~~~~~~~~~~~~~~~~~~
  30
  31 **Note:** MemorySanitizer requires **64-bit Linux** to work. Other
  32 platforms/operating systems are not supported.
  33
  34 LLVM/Clang
  35 ^^^^^^^^^^
  36
  37 The MSan instrumentation is implemented as an LLVM pass and integrated
  38 into Clang. As MSan is one of the newer sanitizers, we recommend using a
  39 recent Clang version, such as Clang 3.7+.
  40
  41 You can find precompiled binaries for LLVM/Clang on `the LLVM releases
  42 page <https://releases.llvm.org/download.html>`__.
  43
  44 Building Firefox
  45 ~~~~~~~~~~~~~~~~
  46
  47 .. warning::
  48
  49    **Warning: Running Firefox with MemorySanitizer would require all
  50    external dependencies to be built with MemorySanitizer as well. To
  51    our knowledge, this has never been attempted yet, so the build
  52    configuration provided here is untested and without an appropriately
  53    instrumented userland, it will cause false positives.**
  54
  55 Getting the source
  56 ^^^^^^^^^^^^^^^^^^
  57
  58 If you don't have a source code repository clone yet, you need to :ref:`get
  59 yourself a clone of Mozilla-central <Mercurial Overview>`.
  60
  61 Adjusting the build configuration
  62 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  63
  64 Create the build configuration file ``.mozconfig`` with the following
  65 content in your Mozilla-central directory:
  66
  67 .. code:: bash
  68
  69    mk_add_options MOZ_OBJDIR=@TOPSRCDIR@/objdir-ff-msan
  70
  71    # Enable LLVM specific code and build workarounds
  72    ac_add_options --enable-memory-sanitizer
  73    # If clang is already in your $PATH, then these can simply be:
  74    #   export CC=clang
  75    #   export CXX=clang++
  76    export CC="/path/to/clang"
  77    export CXX="/path/to/clang++"
  78
  79    # llvm-symbolizer displays much more complete backtraces when data races are detected.
  80    # If it's not already in your $PATH, then uncomment this next line:
  81    #export LLVM_SYMBOLIZER="/path/to/llvm-symbolizer"
  82
  83    # Add MSan to our compiler flags
  84    export CFLAGS="-fsanitize=memory"
  85    export CXXFLAGS="-fsanitize=memory"
  86
  87    # Additionally, we need the MSan flag during linking. Normally, our C/CXXFLAGS would
  88    # be used during linking as well but there is at least one place in our build where
  89    # our CFLAGS are not added during linking.
  90    # Note: The use of this flag causes Clang to automatically link the MSan runtime :)
  91    export LDFLAGS="-fsanitize=memory"
  92
  93    # These three are required by MSan
  94    ac_add_options --disable-jemalloc
  95    ac_add_options --disable-crashreporter
  96    ac_add_options --disable-elf-hack
  97
  98    # Keep symbols to symbolize MSan traces
  99    export MOZ_DEBUG_SYMBOLS=1
 100    ac_add_options --enable-debug-symbols
 101    ac_add_options --disable-install-strip
 102
 103    # Settings for an opt build
 104    ac_add_options --enable-optimize="-O2 -gline-tables-only"
 105    ac_add_options --disable-debug
 106
 107 Starting the build process
 108 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 109
 110 Now you start the build process using the regular ``make -f client.mk``
 111 command.
 112
 113 Starting Firefox
 114 ^^^^^^^^^^^^^^^^
 115
 116 After the build has completed, you can start Firefox from the ``objdir``
 117 as usual.
 118
 119 Building the JavaScript shell
 120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 121
 122 **Note:** Unlike Firefox itself, the JavaScript shell does **not**
 123 require an instrumented userland. Calls to external libraries like
 124 zlib are handled with special annotations inside the engine.
 125
 126 .. warning::
 127
 128    **Warning: Certain technologies used inside the JavaScript engine are
 129    incompatible with MSan and must be disabled at runtime to prevent
 130    false positives. This includes the JITs and asm.js. Therefore always
 131    make sure to run with
 132    ``--no-ion --no-baseline --no-asmjs --no-native-regexp``.**
 133
 134 If you want to build only the JavaScript shell instead of doing a full
 135 Firefox build, the build script below will probably help you to do so.
 136 Before using it, you must, of course, adjust the path name for
 137 ``LLVM_ROOT`` to match your setup. Once you have adjusted everything,
 138 execute this script in the ``js/src/`` subdirectory and pass a directory
 139 name as the first parameter. The build will then be created in a new
 140 subdirectory with that name.
 141
 142 .. code:: bash
 143
 144    #! /bin/sh
 145
 146    if [ -z $1 ] ; then
 147        echo "usage: $0 <dirname>"
 148    elif [ -d $1 ] ; then
 149        echo "directory $1 already exists"
 150    else
 151        autoconf2.13
 152        mkdir $1
 153        cd $1
 154        LLVM_ROOT="/path/to/llvm"
 155        CC="$LLVM_ROOT/build/bin/clang" \
 156        CXX="$LLVM_ROOT/build/bin/clang++" \
 157        CFLAGS="-fsanitize=memory" \
 158        CXXFLAGS="-fsanitize=memory" \
 159        LDFLAGS="-fsanitize=memory" \
 160                ../configure --enable-debug --enable-optimize --enable-memory-sanitizer --disable-jemalloc --enable-posix-nspr-emulation
 161        make -j 8
 162    fi
 163
 164 Using LLVM Symbolizer for faster/better traces
 165 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 166
 167 By default, MSan traces are not symbolized.
 168
 169 LLVM ships with the symbolizer binary ``llvm-symbolize`` that MSan will
 170 readily use to immediately output symbolized traces if the program is
 171 found on the ``PATH``. If your ``llvm-symbolizer`` lives outside the
 172 ``PATH``, you can set the ``MSAN_SYMBOLIZER_PATH`` environment variable
 173 to point to your symbolizer binary.