| Index: docs/processor_design.md
|
| diff --git a/docs/processor_design.md b/docs/processor_design.md
|
| index c2af41a11a67fd2887fc31464b4cd9045645eca8..2b2946ec31048c41b306671ff7558879435d1fd0 100644
|
| --- a/docs/processor_design.md
|
| +++ b/docs/processor_design.md
|
| @@ -12,16 +12,16 @@ process. After processing, this data is made available to users of the library.
|
| The Breakpad processor is intended to sit at the core of a comprehensive
|
| crash-reporting system that does not require debugging information to be
|
| provided to those running applications being monitored. Some existing
|
| -crash-reporting systems, such as [GNOME](http://www.gnome.org/)’s Bug-Buddy and
|
| -[Apple](http://www.apple.com/)’s [CrashReporter]
|
| -(http://developer.apple.com/technotes/tn2004/tn2123.html), require symbolic
|
| -information to be present on the end user’s computer; in the case of
|
| -CrashReporter, the reports are transmitted only to Apple, not to third-party
|
| -developers. Other systems, such as [Microsoft](http://www.microsoft.com/)’s
|
| -[Windows Error Reporting](http://msdn.microsoft.com/isv/resources/wer/) and
|
| -SupportSoft’s Talkback, transmit only a snapshot of a crashed process’ state,
|
| +crash-reporting systems, such as [GNOME](https://www.gnome.org/)'s Bug-Buddy and
|
| +[Apple](https://www.apple.com/)'s
|
| +[CrashReporter](https://developer.apple.com/technotes/tn2004/tn2123.html),
|
| +require symbolic information to be present on the end user's computer; in the
|
| +case of CrashReporter, the reports are transmitted only to Apple, not to third-party
|
| +developers. Other systems, such as [Microsoft](https://www.microsoft.com/)'s
|
| +[Windows Error Reporting](https://msdn.microsoft.com/isv/resources/wer/) and
|
| +SupportSoft's Talkback, transmit only a snapshot of a crashed process' state,
|
| which can later be combined with symbolic debugging information without the need
|
| -for it to be present on end users’ computers. Because symbolic debugging
|
| +for it to be present on end users' computers. Because symbolic debugging
|
| information consumes a large amount of space and is otherwise not needed during
|
| the normal operation of software, and because some developers are reluctant to
|
| release debugging symbols to their customers, Breakpad follows the latter
|
| @@ -32,12 +32,12 @@ requirements, which are to: * allow for symbols to be separate from the
|
| application, * handle crash reports from multiple platforms, * allow developers
|
| to operate their own crash-reporting platform, and to * be open-source. Windows
|
| Error Reporting only functions for Microsoft products, and requires the
|
| -involvement of Microsoft’s servers. Talkback, while cross-platform, has not been
|
| +involvement of Microsoft's servers. Talkback, while cross-platform, has not been
|
| maintained and at this point does not support Mac OS X on x86, which we consider
|
| to be a significant platform. Talkback is also closed-source commercial
|
| software, and has very specific requirements for its server platform.
|
|
|
| -We are aware of Windows-only crash-reporting systems that leverage Microsoft’s
|
| +We are aware of Windows-only crash-reporting systems that leverage Microsoft's
|
| debugging interfaces. Such systems, even if extended to support dumps from other
|
| platforms, are tied to using Windows for at least a portion of the processor
|
| platform.
|
| @@ -65,7 +65,7 @@ contain:
|
| (program counter).
|
| * Information about each thread of execution within a crashed process,
|
| including:
|
| - * The memory region used for each thread’s stack.
|
| + * The memory region used for each thread's stack.
|
| * CPU context for each thread, which for various reasons is not the same
|
| as the crash context in the case of the crashed thread.
|
| * A list of loaded code segments (or modules), including:
|
| @@ -79,35 +79,33 @@ contain:
|
| Ordinarily, dumps are produced as a result of a crash, but other triggers may be
|
| set to produce dumps at any time a developer deems appropriate. The Breakpad
|
| processor can handle dumps in the minidump format, either generated by an
|
| -[Breakpad client “handler”](client_design.md) implementation, or by another
|
| +[Breakpad client "handler"](client_design.md) implementation, or by another
|
| implementation that produces dumps in this format. The
|
| -[DbgHelp.dll!MiniDumpWriteDump]
|
| -(http://msdn2.microsoft.com/en-us/library/ms680360.aspx) function on Windows
|
| -produces dumps in this format, and is the basis for the Breakpad handler
|
| -implementation on that platform.
|
| -
|
| -The [minidump format]
|
| -(http://msdn.microsoft.com/en-us/library/ms679293%28VS.85%29.aspx) is
|
| -essentially a simple container format, organized as a series of streams. Each
|
| -stream contains some type of data relevant to the crash. A typical “normal”
|
| +[DbgHelp.dll!MiniDumpWriteDump](https://msdn.microsoft.com/en-us/library/ms680360.aspx)
|
| +function on Windows produces dumps in this format, and is the basis for the
|
| +Breakpad handler implementation on that platform.
|
| +
|
| +The [minidump format](https://msdn.microsoft.com/en-us/library/ms679293%28VS.85%29.aspx)
|
| +is essentially a simple container format, organized as a series of streams. Each
|
| +stream contains some type of data relevant to the crash. A typical "normal"
|
| minidump contains streams for the thread list, the module list, the CPU context
|
| at the time of the crash, and various bits of additional system information.
|
| Other types of minidump can be generated, such as a full-memory minidump, which
|
| -in addition to stack memory contains snapshots of all of a process’ mapped
|
| +in addition to stack memory contains snapshots of all of a process' mapped
|
| memory regions.
|
|
|
| -The minidump format was chosen as Breakpad’s dump format because it has an
|
| +The minidump format was chosen as Breakpad's dump format because it has an
|
| established track record on Windows, and it can be adapted to meet the needs of
|
| the other platforms that Breakpad supports. Most other operating systems use
|
| -“core” files as their native dump formats, but the capabilities of core files
|
| +"core" files as their native dump formats, but the capabilities of core files
|
| vary across platforms, and because core files are usually presented in a
|
| -platform’s native executable format, there are complications involved in
|
| +platform's native executable format, there are complications involved in
|
| accessing the data contained therein without the benefit of the header files
|
| -that define an executable format’s entire structure. Because minidumps are
|
| +that define an executable format's entire structure. Because minidumps are
|
| leaner than a typical executable format, a redefinition of the format in a
|
| cross-platform header file, `minidump_format.h`, was a straightforward task.
|
| Similarly, the capabilities of the minidump format are understood, and because
|
| -it provides an extensible container, any of Breakpad’s needs that could not be
|
| +it provides an extensible container, any of Breakpad's needs that could not be
|
| met directly by the standard minidump format could likely be met by extending it
|
| as needed. Finally, using this format means that the dump file is compatible
|
| with native debugging tools at least on Windows. A possible future avenue for
|
| @@ -123,12 +121,12 @@ execution requested a dump be produced for non-crash dumps.
|
|
|
| Often, the information contained within a dump alone is sufficient to produce a
|
| full stack backtrace for each thread. Certain optimizations that compilers
|
| -employ in producing code frustrate this process. Specifically, the “frame
|
| -pointer omission” optimization of x86 compilers can make it impossible to
|
| +employ in producing code frustrate this process. Specifically, the "frame
|
| +pointer omission" optimization of x86 compilers can make it impossible to
|
| produce useful stack traces given only a stack snapshot and CPU context. In
|
| these cases, however, compiler-emitted debugging information can aid in
|
| producing useful stack traces. The Breakpad processor is able to take advantage
|
| -of this debugging information as supplied by Microsoft’s C/C++ compiler, the
|
| +of this debugging information as supplied by Microsoft's C/C++ compiler, the
|
| only compiler to apply such optimizations by default. As a result, the Breakpad
|
| processor can produce useful stack traces even from code with frame pointer
|
| omission optimizations as produced by this compiler.
|
| @@ -145,7 +143,7 @@ program (`exe` files on Windows) or shared libraries (`.so` files on Linux,
|
| Windows). Dumps contain information about which of these modules were loaded at
|
| the time the dump was produced, and given this information, the Breakpad
|
| processor attempts to locate debugging symbols for the module through a
|
| -user-supplied function embodied in a “symbol supplier.” Breakpad includes a
|
| +user-supplied function embodied in a "symbol supplier." Breakpad includes a
|
| sample symbol supplier, called `SimpleSymbolSupplier`, that is used by its
|
| command-line tools; this supplier locates symbol files by pathname.
|
| `SimpleSymbolSupplier` is also available to other users of the Breakpad
|
| @@ -153,38 +151,38 @@ processor library. This allows for the use of a simple reference implementation,
|
| but preserves flexibility for users who may have more demanding symbol file
|
| storage needs.
|
|
|
| -Breakpad’s symbol file format is text-based, and was defined to be fairly
|
| +Breakpad's symbol file format is text-based, and was defined to be fairly
|
| human-readable and to encompass the needs of multiple platforms. The Breakpad
|
| -processor itself does not operate directly with native symbol formats ([DWARF]
|
| -(http://dwarf.freestandards.org/) and [STABS]
|
| -(http://sourceware.org/gdb/current/onlinedocs/stabs.html) on most Unix-like
|
| -systems, [.pdb files]
|
| -(http://msdn2.microsoft.com/en-us/library/yd4f8bd1(VS.80).aspx) on Windows),
|
| +processor itself does not operate directly with native symbol formats
|
| +([DWARF](http://dwarf.freestandards.org/) and
|
| +[STABS](https://sourceware.org/gdb/current/onlinedocs/stabs.html)
|
| +on most Unix-like systems,
|
| +[.pdb files](https://msdn.microsoft.com/en-us/library/yd4f8bd1(VS.80).aspx) on Windows),
|
| because of the complications in accessing potentially complex symbol formats
|
| with slight variations between platforms, stored within different types of
|
| binary formats. In the case of `.pdb` files, the debugging format is not even
|
| -documented. Instead, Breakpad’s symbol files are produced on each platform,
|
| +documented. Instead, Breakpad's symbol files are produced on each platform,
|
| using specific debugging APIs where available, to convert native symbols to
|
| -Breakpad’s cross-platform format.
|
| +Breakpad's cross-platform format.
|
|
|
| ### Processing
|
|
|
| Most commonly, a developer will enable an application to use Breakpad by
|
| -building it with a platform-specific [client “handler”](client_design.md)
|
| +building it with a platform-specific [client "handler"](client_design.md)
|
| library. After building the application, the developer will create symbol files
|
| -for Breakpad’s use using the included `dump_syms` or `symupload` tools, or
|
| -another suitable tool, and place the symbol files where the processor’s symbol
|
| +for Breakpad's use using the included `dump_syms` or `symupload` tools, or
|
| +another suitable tool, and place the symbol files where the processor's symbol
|
| supplier will be able to locate them.
|
|
|
| -When a dump file is given to the processor’s `MinidumpProcessor` class, it will
|
| +When a dump file is given to the processor's `MinidumpProcessor` class, it will
|
| read it using its included minidump reader, contained in the `Minidump` family
|
| of classes. It will collect information about the operating system and CPU that
|
| produced the dump, and determine whether the dump was produced as a result of a
|
| crash or at the direct request of the application itself. It then loops over all
|
| of the threads in a process, attempting to walk the stack associated with each
|
| -thread. This process is achieved by the processor’s `Stackwalker` components, of
|
| +thread. This process is achieved by the processor's `Stackwalker` components, of
|
| which there are a slightly different implementations for each CPU type that the
|
| -processor is able to handle dumps from. Beginning with a thread’s context, and
|
| +processor is able to handle dumps from. Beginning with a thread's context, and
|
| possibly using debugging data, the stackwalker produces a list of stack frames,
|
| containing each instruction executed in the chain. These instructions are
|
| matched up with the modules that contributed them to a process, and the
|
|
|