debugging_firefox_with_valgrind.rst (6242B)
1 Debugging Firefox with Valgrind 2 =============================== 3 4 +--------------------------------------------------------------------+ 5 | This page is an import from MDN and the contents might be outdated | 6 +--------------------------------------------------------------------+ 7 8 This page describes how to use Valgrind (specifically, its Memcheck 9 tool) to find memory errors. 10 11 Supported platforms 12 ------------------- 13 14 Valgrind runs desktop Firefox fine on Linux, especially on x86 and 15 x86-64. Firefox for Android and Firefox OS on ARMv7 should also run, 16 though perhaps not as smoothly. The other architectures supported by 17 Valgrind on Linux (AARCH64, PPC{32,64}, MIPS{32,64}, S390X) should also 18 work, in theory. 19 20 MacOS X 10.10 (Yosemite), 64-bit only, works, although it can be a bit 21 of a rough ride. 22 23 - Expect lower performance and a somewhat higher false positive error 24 rate than on Linux. 25 - Valgrind's handling of malloc zones on Yosemite is imperfect. Regard 26 leak reports with caution. 27 - Valgrind has been known to cause kernel panics, for unknown reasons. 28 29 Where to get Valgrind 30 --------------------- 31 32 Linux: Download `Valgrind <https://valgrind.org/>`__ directly, or use 33 your distribution's package manager (if it has a recent enough version). 34 35 MacOSX: `Get Valgrind trunk from 36 SVN <https://valgrind.org/downloads/repository.html>`__ and build it. 37 Don't use 3.10.x or any other tarball. 38 39 Make sure you have Valgrind 3.14 or later, version 3.16.1 is known to work, 40 3.13.0 did not. Newer versions tend to have better compatibility with both 41 Firefox's JITs and newer toolchain components (compiler, libc and linker 42 versions). 43 44 Basics 45 ------ 46 47 Build 48 ~~~~~ 49 50 Build Firefox with the following options, which maximize speed and 51 accuracy. 52 53 .. code:: 54 55 ac_add_options --disable-jemalloc 56 ac_add_options --disable-strip 57 ac_add_options --enable-valgrind 58 ac_add_options --enable-optimize="-g -O2" 59 ac_add_options --disable-sandbox 60 61 Run 62 ~~~ 63 64 Note that programs run *much* more slowly under Valgrind than they do 65 natively. Slow-downs of 20x or 30x aren't unexpected, and it's slower on 66 Mac than on Linux. Don't try this on an underpowered machine. 67 68 Linux 69 ^^^^^ 70 71 On Linux, run Valgrind with the following options. 72 73 .. code:: 74 75 --smc-check=all-non-file --vex-iropt-register-updates=allregs-at-mem-access --show-mismatched-frees=no --read-inline-info=yes 76 77 The ``--smc-check`` and ``--vex-iropt-register-updates`` options are 78 necessary to avoid crashes in JIT-generated code. 79 80 The ``--show-mismatched-frees`` option is necessary due to inconsistent 81 inlining of ``new`` and ``delete`` -- i.e. one gets inlined but the 82 other doesn't -- which lead to false-positive mismatched-free errors. 83 84 The ``--read-inline-info`` option improves stack trace readability in 85 the presence of inlining. 86 87 Also, run with the following environment variable set. 88 89 .. code:: 90 91 G_SLICE=always-malloc 92 93 This is necessary to get the Gnome system libraries to use plain 94 ``malloc`` instead of pool allocators. 95 96 Mac 97 ^^^ 98 99 On Mac, run Valgrind with the following options. 100 101 .. code:: 102 103 --smc-check=all-non-file --vex-iropt-register-updates=allregs-at-mem-access --show-mismatched-frees=no --dsymutil=yes 104 105 The ``--dsymutil`` option ensures line number information is present in 106 stack traces. 107 108 Advanced usage 109 -------------- 110 111 Shared suppression files 112 ~~~~~~~~~~~~~~~~~~~~~~~~ 113 114 `/build/valgrind/ <https://searchfox.org/mozilla-central/source/build/valgrind/>`__ 115 contains the suppression files used by the periodic Valgrind jobs on 116 Treeherder. Some of these files are platform-specific. 117 118 Running mochitests under Valgrind? 119 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 121 To run a mochitest under Valgrind, use the following command. 122 123 .. code:: bash 124 125 $ ./mach mochitest-plain --debugger="valgrind" --debugger-args="$VALGRIND_OPTIONS" relative/path/to/tests 126 127 Where ``$VALGRIND_OPTIONS`` are the options described 128 :ref:`above <Debugging Firefox With Valgrind>`. You might also 129 need ``--trace-children=yes`` to trace into child processes. 130 131 As of December 2014 it is possible to do a complete run of 132 mochitests-plain on Valgrind in about 8 CPU hours on a Core i4910 133 (Haswell) machine. Maximum process size is 5.4G, of which about 80% is 134 in memory. Runs of small subsets of mochitests take far less memory. 135 136 Bits and pieces 137 ~~~~~~~~~~~~~~~ 138 139 For un-released Linux distros (Fedora Rawhide, etc.) you'll need to use 140 a version of Valgrind trunk build, because fixes for the latest gcc and 141 glibc versions appear there first. Without them you'll be flooded with 142 false errors from Memcheck, and have debuginfo reading problems. 143 144 On Linux, code compiled by LLVM at high optimisation levels can cause 145 Memcheck to report false uninitialised value errors. See 146 `here <https://bugs.kde.org/show_bug.cgi?id=242137#c3>`__ for an easy 147 workaround. On Mac, Valgrind has this workaround built in. 148 149 You can make stack traces easier to read by asking for source file names 150 to be given relative to the root of your source tree. Do this by using 151 ``--fullpath-after=`` to specify the rightmost part of the absolute path 152 that you don't want to see. For example, if your source tree is rooted 153 at ``/home/sewardj/MC-20-12-2014``, use ``--fullpath-after=2014/`` to 154 get path names relative to the source directory. 155 156 The ``--track-origins=yes`` slows down Valgrind greatly, so don't use it 157 unless you are hunting down a specific uninitialised value error. But if 158 you are hunting down such an error, it's extremely helpful and worth 159 waiting for. 160 161 Additional help 162 --------------- 163 164 The `Valgrind Quick Start 165 Guide <http://www.valgrind.org/docs/manual/quick-start.html>`__ is short 166 and worth reading. The `User 167 Manual <https://valgrind.org/docs/manual/manual.html>`__ is also useful. 168 169 If Valgrind asserts, crashes, doesn't do what you expect, or otherwise 170 acts up, first of all read this page and make sure you have both Firefox 171 and Valgrind correctly configured. If that's all OK, try using the 172 `Valgrind trunk from 173 SVN <http://www.valgrind.org/downloads/repository.html>`__. Oftentimes 174 bugs are fixed in the trunk before most users fall across them. If that 175 doesn't help, consider `filing a bug 176 report <http://www.valgrind.org/support/bug_reports.html>`__, and/or 177 mailing Julian Seward or Nick Nethercote.