docs/linux_minidump_to_core.md

   1 # Linux Minidump to Core
   2
   3 On Linux, Chromium can use Breakpad to generate minidump files for crashes. It
   4 is possible to convert the minidump files to core files, and examine the core
   5 file in gdb, cgdb, or Qtcreator. In the examples below cgdb is assumed but any
   6 gdb based debugger can be used.
   7
   8 [TOC]
   9
  10 ## Creating the core file
  11
  12 Use `minidump-2-core` to convert the minidump file to a core file. On Linux, one
  13 can build the minidump-2-core target in a Chromium checkout, or alternatively,
  14 build it in a Google Breakpad checkout.
  15
  16     $ minidump-2-core foo.dmp > foo.core
  17
  18 ## Retrieving Chrome binaries
  19
  20 If the minidump is from a public build then Googlers can find Google Chrome
  21 Linux binaries and debugging symbols via https://goto.google.com/chromesymbols.
  22 Otherwise, use the locally built chrome files. Google Chrome uses the
  23 _debug link_ method to specify the debugging file. Either way be sure to put
  24 `chrome` and `chrome.debug` (the stripped debug information) in the same
  25 directory as the core file so that the debuggers can find them.
  26
  27 ## Loading the core file into gdb/cgdb
  28
  29 The recommended syntax for loading a core file into gdb/cgdb is as follows,
  30 specifying both the executable and the core file:
  31
  32     $ cgdb chrome foo.core
  33
  34 If the executable is not available then the core file can be loaded on its own
  35 but debugging options will be limited:
  36
  37     $ cgdb -c foo.core
  38
  39 ## Loading the core file into Qtcreator
  40
  41 Qtcreator is a full GUI wrapper for gdb and it can also load Chrome's core
  42 files. From Qtcreator select the Debug menu, Start Debugging, Load Core File...
  43 and then enter the paths to the core file and executable. Qtcreator has windows
  44 to display the call stack, locals, registers, etc. For more information on
  45 debugging with Qtcreator see
  46 [Getting Started Debugging on Linux.](https://www.youtube.com/watch?v=xTmAknUbpB0)
  47
  48 ## Source debugging
  49
  50 If you have a Chromium repo that is synchronized to exactly (or even
  51 approximately) when the Chrome build was created then you can tell
  52 `gdb/cgdb/Qtcreator` to load source code. Since all source paths in Chrome are
  53 relative to the out/Release directory you just need to add that directory to
  54 your debugger search path, by adding a line similar to this to `~/.gdbinit`:
  55
  56     (gdb) directory /usr/local/chromium/src/out/Release/
  57
  58 ## Notes
  59
  60 *   Since the core file is created from a minidump, it is incomplete and the
  61     debugger may not know values for variables in memory. Minidump files contain
  62     thread stacks so local variables and function parameters should be
  63     available, subject to the limitations of optimized builds.
  64 *   For gdb's `add-symbol-file` command to work, the file must have debugging
  65     symbols.
  66     *   In case of separate debug files,
  67     [the gdb manual](https://sourceware.org/gdb/onlinedocs/gdb/Separate-Debug-Files.html)
  68     explains how gdb looks for them.
  69 *   If the stack trace involve system libraries, the Advanced module loading
  70     steps shown below need to be repeated for each library.
  71
  72 ## Advanced module loading
  73
  74 If gdb doesn't find shared objects that are needed you can force it to load
  75 them. In gdb, the `add-symbol-file` command takes a filename and an address. To
  76 figure out the address, look near the end of `foo.dmp`, which contains a copy of
  77 `/proc/pid/maps` from the process that crashed.
  78
  79 One quick way to do this is with `grep`. For instance, if the executable is
  80 `/path/to/chrome`, one can simply run:
  81
  82     $ grep -a /path/to/chrome$ foo.dmp
  83
  84     7fe749a90000-7fe74d28f000 r-xp 00000000 08:07 289158        /path/to/chrome
  85     7fe74d290000-7fe74d4b7000 r--p 037ff000 08:07 289158        /path/to/chrome
  86     7fe74d4b7000-7fe74d4e0000 rw-p 03a26000 08:07 289158        /path/to/chrome
  87
  88 In this case, `7fe749a90000` is the base address for `/path/to/chrome`, but gdb
  89 takes the start address of the file's text section. To calculate this, one will
  90 need a copy of `/path/to/chrome`, and run:
  91
  92     $ objdump -x /path/to/chrome | grep '\.text' | head -n 1 | tr -s ' ' | \
  93       cut -d' ' -f 7
  94
  95     005282c0
  96
  97 Now add the two addresses: `7fe749a90000 + 005282c0 = 7fe749fb82c0` and in gdb, run:
  98
  99     (gdb) add-symbol-file /path/to/chrome 0x7fe749fb82c0
 100
 101 Then use gdb as normal.
 102
 103 ## Other resources
 104
 105 For more discussion on this process see
 106 [Debugging a Minidump](http://www.chromium.org/chromium-os/how-tos-and-troubleshooting/crash-reporting/debugging-a-minidump).
 107 This page discusses the same process in the context of ChromeOS and many of the
 108 concepts and techniques overlap.