[lldb-dev] Minidump support in LLDB

[Adrian McCarthy via lldb-dev]

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.

Thanks,
Adrian.

---
Minidump support in LLDB

Adrian McCarthy

amccarth at google.com

This is an “as-built” design document describing how minidump support was
added to LLDB on Windows.

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 other platforms
<http://dev.chromium.org/developers/crash-reports#TOC-Working-with-Minidumps>
it supports.  Chromium and other Google projects use Breakpad, so minidump
support in LLDB is important for Google.
Status

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.
Process Plugin for Minidump

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).

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.

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.

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.

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.

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.

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.
Writing Minidumps

The `process save-core` command was extended for Windows to create a
minidump file.  It currently uses the Windows API MiniDumpWriteDump
<https://msdn.microsoft.com/en-us/library/windows/desktop/ms680360(v=vs.85).aspx>.
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).

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.
Testing

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.

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.
Future Work

   -

   Test minidump debugging functionality with a substantial application
   like Chromium.
   -

   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.
   -

   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.
   -

   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.
   - 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.)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/lldb-dev/attachments/20160204/ee378507/attachment.html>