<div dir="ltr">Below is an after-the-fact design doc on the minidump support in LLDB.  We don't seem to have a documents repository, so I thought I'd post it here on the mailing list in case anyone wants to know more.  Comments and questions welcome.<div><br></div><div>Thanks,</div><div>Adrian.<br><div><br></div><div>---</div><div><span style="color:rgb(0,0,0);font-family:Arial;font-size:26.6667px;white-space:pre-wrap;line-height:1.38;background-color:transparent">Minidump support in LLDB</span><br></div><div><span id="docs-internal-guid-0f83f5b9-ae93-2d9d-41a0-8396e8cc86c6"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Adrian McCarthy</span></p><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent"><a href="mailto:amccarth@google.com">amccarth@google.com</a></span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">This is an “as-built” design document describing how minidump support was added to LLDB on Windows.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Minidumps are the Windows equivalent of a core file.  The format is well-documented (unlike core files), so some crash-reporting tools (like Breakpad) have chosen to use the minidump format not only on Windows, but also on all </span><a href="http://dev.chromium.org/developers/crash-reports#TOC-Working-with-Minidumps" style="text-decoration:none"><span style="font-size:14.6667px;font-family:Arial;text-decoration:underline;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">other platforms</span></a><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent"> it supports.  Chromium and other Google projects use Breakpad, so minidump support in LLDB is important for Google.</span></p><h2 dir="ltr" style="line-height:1.38;margin-top:18pt;margin-bottom:6pt"><span style="font-size:21.3333px;font-family:Arial;color:rgb(0,0,0);font-weight:400;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Status</span></h2><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Currently, LLDB supports debugging 32-bit minidumps on Windows for binaries built with DWARF debug information (e.g., with clang-cl).  Tests ensure that we can see stacks for all threads and inspect local variables and parameters and that it is possible to inspect any section of process memory captured in the dump.</span></p><h2 dir="ltr" style="line-height:1.38;margin-top:18pt;margin-bottom:6pt"><span style="font-size:21.3333px;font-family:Arial;color:rgb(0,0,0);font-weight:400;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Process Plugin for Minidump</span></h2><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">A new process plugin was created for minidump support.  It parallels the Windows process plugin (for debugging live processes on Windows) and the ELF core process plugin (for postmortem analysis of core files).</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">The minidump plugin is smaller than the ELF core plugin, largely because the ELF core plugin contains all of the code for parsing a core file.  The minidump plugin currently relies on a Windows API and structure definitions in order to parse it.  The minidump format appears simpler than the core file format.  Nevertheless, if we decide to parse it directly in LLDB, the parsing code should probably be in a separate translation unit than the minidump plugin.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">The minidump plugin is also smaller than the Windows process plugin, which handles debugging of live processes.  Debugging a live process on Windows involves tracking more state and managing a separate debugger thread for receiving and dispatching debugging events.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Small parts of the existing ProcessWindows plugin were factored up into a new base class to be used by both the ProcessWindowsLive and the new ProcessWindowsMiniDump process plugins.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Small amounts of code were factored out of the Windows-specific Register and Thread classes so they could also be re-used by the minidump counterparts.  The minidump versions of these classes are simpler than their live-debugging counterparts since they are read-only.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Upon opening the minidump, the plugin reads several sections in order to capture the process ID, the module list, and the exception record.  The plugin extracts information about the threads that were running when LLDB calls back into the plugin’s UpdateThreadList.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">As a first pass, LLDB supports Minidump only on Windows, because it uses the Windows-provided API MiniDumpReadDumpStream for accessing the minidump.  But use of this API is localized to a single location, so it can easily be swapped out for an independent implementation of this functionality.</span></p><h2 dir="ltr" style="line-height:1.38;margin-top:18pt;margin-bottom:6pt"><span style="font-size:21.3333px;font-family:Arial;color:rgb(0,0,0);font-weight:400;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Writing Minidumps</span></h2><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">The `process save-core` command was extended for Windows to create a minidump file.  It currently uses the Windows API </span><a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms680360(v=vs.85).aspx" style="text-decoration:none"><span style="font-size:14.6667px;font-family:Arial;text-decoration:underline;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">MiniDumpWriteDump</span></a><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">.  As with reading, this could be replaced to allow writing a minidump on any platform.  That would require an option on the `process save-core` command in order to specify which format was desired when there is a choice (we’re not like to start offer Unix-style core files on Windows).</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Since the minidump format is documented and not particularly complex, providing another implementation should be straightforward and would allow for debugging minidumps on MacOS or Linux, even if those minidumps are from a Windows host.</span></p><h2 dir="ltr" style="line-height:1.38;margin-top:18pt;margin-bottom:6pt"><span style="font-size:21.3333px;font-family:Arial;color:rgb(0,0,0);font-weight:400;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Testing</span></h2><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">There are a small number of basic tests to ensure that LLDB can open a minidump, find the threads, inspect the stack and local variables, and write a minidump.</span></p><br><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Some of these tests execute against checked-in minidumps that were captured with Visual Studio and others use LLDB’s ability to write a minidump to first capture a dump and then to inspect it.  We need tests that check minidumps from more elaborate (or, at least larger scale) programs.</span></p><h2 dir="ltr" style="line-height:1.38;margin-top:18pt;margin-bottom:6pt"><span style="font-size:21.3333px;font-family:Arial;color:rgb(0,0,0);font-weight:400;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Future Work</span></h2><ul style="margin-top:0pt;margin-bottom:0pt"><li dir="ltr" style="list-style-type:disc;font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;background-color:transparent"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Test minidump debugging functionality with a substantial application like Chromium.</span></p></li><li dir="ltr" style="list-style-type:disc;font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;background-color:transparent"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Read the minidump directly instead of using the Windows API interface.  This would be the key step in making cross-platform crash dump analysis possible.</span></p></li><li dir="ltr" style="list-style-type:disc;font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;background-color:transparent"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Implement the 64-bit register model for Windows crash-dump debugging.  There is a bit of work here to make sure it works on WoW32.</span></p></li><li dir="ltr" style="list-style-type:disc;font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;background-color:transparent"><p dir="ltr" style="line-height:1.38;margin-top:0pt;margin-bottom:0pt"><span style="font-size:14.6667px;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Write minidumps on any platform by implementing our own version of MiniDumpWriteDump and adding an option to the `process save-core` command to select the format.</span></p></li><li dir="ltr" style="list-style-type:disc;font-size:14.6667px;font-family:Arial;color:rgb(0,0,0);vertical-align:baseline;background-color:transparent"><span style="font-size:14.6667px;vertical-align:baseline;white-space:pre-wrap;background-color:transparent">Investigate whether thread names can be recovered from the minidump.  Can we at least identify the “main” thread based on the entrypoint in the call stack?  (This would be useful for live debugging as well as postmortem.)</span></li></ul></span></div></div></div>