mirror of
https://github.com/yuzu-emu/breakpad
synced 2024-11-22 21:04:06 +00:00
11d7510c08
code.google.com is obsolete. Fix all broken markdown links while at it. Change-Id: I6a337bf4b84eacd5f5c749a4ee61331553279009 Reviewed-on: https://chromium-review.googlesource.com/411800 Reviewed-by: Mike Frysinger <vapier@chromium.org>
115 lines
5.3 KiB
Markdown
115 lines
5.3 KiB
Markdown
# Introduction
|
||
|
||
Breakpad is a library and tool suite that allows you to distribute an
|
||
application to users with compiler-provided debugging information removed,
|
||
record crashes in compact "minidump" files, send them back to your server, and
|
||
produce C and C++ stack traces from these minidumps. Breakpad can also write
|
||
minidumps on request for programs that have not crashed.
|
||
|
||
Breakpad is currently used by Google Chrome, Firefox, Google Picasa, Camino,
|
||
Google Earth, and other projects.
|
||
|
||
|
||
|
||
Breakpad has three main components:
|
||
|
||
* The **client** is a library that you include in your application. It can
|
||
write minidump files capturing the current threads' state and the identities
|
||
of the currently loaded executable and shared libraries. You can configure
|
||
the client to write a minidump when a crash occurs, or when explicitly
|
||
requested.
|
||
|
||
* The **symbol dumper** is a program that reads the debugging information
|
||
produced by the compiler and produces a **symbol file**, in [Breakpad's own
|
||
format](symbol_files.md).
|
||
|
||
* The **processor** is a program that reads a minidump file, finds the
|
||
appropriate symbol files for the versions of the executables and shared
|
||
libraries the minidump mentions, and produces a human-readable C/C++ stack
|
||
trace.
|
||
|
||
# The minidump file format
|
||
|
||
The minidump file format is similar to core files but was developed by Microsoft
|
||
for its crash-uploading facility. A minidump file contains:
|
||
|
||
* A list of the executable and shared libraries that were loaded in the
|
||
process at the time the dump was created. This list includes both file names
|
||
and identifiers for the particular versions of those files that were loaded.
|
||
|
||
* A list of threads present in the process. For each thread, the minidump
|
||
includes the state of the processor registers, and the contents of the
|
||
threads' stack memory. These data are uninterpreted byte streams, as the
|
||
Breakpad client generally has no debugging information available to produce
|
||
function names or line numbers, or even identify stack frame boundaries.
|
||
|
||
* Other information about the system on which the dump was collected:
|
||
processor and operating system versions, the reason for the dump, and so on.
|
||
|
||
Breakpad uses Windows minidump files on all platforms, instead of the
|
||
traditional core files, for several reasons:
|
||
|
||
* Core files can be very large, making them impractical to send across a
|
||
network to the collector for processing. Minidumps are smaller, as they were
|
||
designed to be used this way.
|
||
|
||
* The core file format is poorly documented. For example, the Linux Standards
|
||
Base does not describe how registers are stored in `PT_NOTE` segments.
|
||
|
||
* It is harder to persuade a Windows machine to produce a core dump file than
|
||
it is to persuade other machines to write a minidump file.
|
||
|
||
* It simplifies the Breakpad processor to support only one file format.
|
||
|
||
# Overview/Life of a minidump
|
||
|
||
A minidump is generated via calls into the Breakpad library. By default,
|
||
initializing Breakpad installs an exception/signal handler that writes a
|
||
minidump to disk at exception time. On Windows, this is done via
|
||
`SetUnhandledExceptionFilter()`; on OS X, this is done by creating a thread that
|
||
waits on the Mach exception port; and on Linux, this is done by installing a
|
||
signal handler for various exceptions like `SIGILL, SIGSEGV` etc.
|
||
|
||
Once the minidump is generated, each platform has a slightly different way of
|
||
uploading the crash dump. On Windows & Linux, a separate library of functions is
|
||
provided that can be called into to do the upload. On OS X, a separate process
|
||
is spawned that prompts the user for permission, if configured to do so, and
|
||
sends the file.
|
||
|
||
# Terminology
|
||
|
||
**In-process vs. out-of-process exception handling** - it's generally considered
|
||
that writing the minidump from within the crashed process is unsafe - key
|
||
process data structures could be corrupted, or the stack on which the exception
|
||
handler runs could have been overwritten, etc. All 3 platforms support what's
|
||
known as "out-of-process" exception handling.
|
||
|
||
# Integration overview
|
||
|
||
## Breakpad Code Overview
|
||
|
||
All the client-side code is found by visiting the Google Project at
|
||
https://chromium.googlesource.com/breakpad/breakpad. The following directory structure is
|
||
present in the `src` directory:
|
||
|
||
* `processor` Contains minidump-processing code that is used on the server
|
||
side and isn't of use on the client side
|
||
* `client` Contains client minidump-generation libraries for all platforms
|
||
* `tools` Contains source code & projects for building various tools on each
|
||
platform.
|
||
|
||
(Among other directories)
|
||
|
||
* [Windows Integration Guide](windows_client_integration.md)
|
||
* [Mac Integration Guide](mac_breakpad_starter_guide.md)
|
||
* [Linux Integration Guide](linux_starter_guide.md)
|
||
|
||
## Build process specifics(symbol generation)
|
||
|
||
This applies to all platforms. Inside `src/tools/{platform}/dump_syms` is a tool
|
||
that can read debugging information for each platform (e.g. for OS X/Linux,
|
||
DWARF and STABS, and for Windows, PDB files) and generate a Breakpad symbol
|
||
file. This tool should be run on your binary before it's stripped(in the case of
|
||
OS X/Linux) and the symbol files need to be stored somewhere that the minidump
|
||
processor can find. There is another tool, `symupload`, that can be used to
|
||
upload symbol files if you have written a server that can accept them.
|