Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(2514)

Unified Diff: docs/processor_design.md

Issue 2103273003: docs: clean up markdown Base URL: https://chromium.googlesource.com/breakpad/breakpad.git@master
Patch Set: Created 4 years, 6 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View side-by-side diff with in-line comments
Download patch
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

Powered by Google App Engine
This is Rietveld 408576698