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

Unified Diff: docs/stack_walking.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/stack_walking.md
diff --git a/docs/stack_walking.md b/docs/stack_walking.md
index c74f22d4949e38104dd903502e9b5b2f3f4fad00..a3b8cd45abc28575e918fa53d10dd8d5f767f83f 100644
--- a/docs/stack_walking.md
+++ b/docs/stack_walking.md
@@ -8,47 +8,45 @@ traces from the information contained within a minidump file.
## Starting the Process
Typically the stack walking process is initiated by instantiating the
-[MinidumpProcessor]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/processor/minidump_processor.cc)
-class and calling the [MinidumpProcessor::Process]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/processor/minidump_processor.cc#61)
+[MinidumpProcessor](/src/processor/minidump_processor.cc)
+class and calling the
+[MinidumpProcessor::Process](/src/processor/minidump_processor.cc#61)
method, providing it a minidump file to process. To produce a useful stack
trace, the MinidumpProcessor requires two other objects which are passed in its
-constructor: a [SymbolSupplier]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/symbol_supplier.h)
-and a [SourceLineResolverInterface]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/source_line_resolver_interface.h).
+constructor: a
+[SymbolSupplier](/src/google_breakpad/processor/symbol_supplier.h)
+and a
+[SourceLineResolverInterface](/src/google_breakpad/processor/source_line_resolver_interface.h).
The SymbolSupplier object is responsible for locating and providing SymbolFiles
that match modules from the minidump. The SourceLineResolverInterface is
-responsible for loading the symbol files and using the information contained
+responsible for loading the [symbol files](symbol_files.md) and using the information contained
within to provide function and source information for stack frames, as well as
information on how to unwind from a stack frame to its caller. More detail will
be provided on these interactions later.
A number of data streams are extracted from the minidump to begin stack walking:
-the list of threads from the process ([MinidumpThreadList]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/minidump.h#335)),
-the list of modules loaded in the process ([MinidumpModuleList]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/minidump.h#501)),
+the list of threads from the process
+([MinidumpThreadList](/src/google_breakpad/processor/minidump.h#335)),
+the list of modules loaded in the process
+([MinidumpModuleList](/src/google_breakpad/processor/minidump.h#501)),
and information about the exception that caused the process to crash
-([MinidumpException]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/minidump.h#615)).
+([MinidumpException](/src/google_breakpad/processor/minidump.h#615)).
## Enumerating Threads
-For each thread in the thread list ([MinidumpThread]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/minidump.h#299)),
-the thread memory containing the stack for the thread ([MinidumpMemoryRegion]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/minidump.h#236))
+For each thread in the thread list
+([MinidumpThread](/src/google_breakpad/processor/minidump.h#299)),
+the thread memory containing the stack for the thread
+([MinidumpMemoryRegion](/src/google_breakpad/processor/minidump.h#236))
and the CPU context representing the CPU state of the thread at the time the
-dump was written ([MinidumpContext]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/minidump.h#171))
+dump was written
+([MinidumpContext](/src/google_breakpad/processor/minidump.h#171))
are extracted from the minidump. If the thread being processed is the thread
that produced the exception then a CPU context is obtained from the
MinidumpException object instead, which represents the CPU state of the thread
at the point of the exception. A stack walker is then instantiated by calling
-the [Stackwalker::StackwalkerForCPU]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/stackwalker.h#77)
+the
+[Stackwalker::StackwalkerForCPU](/src/google_breakpad/processor/stackwalker.h#77)
method and passing it the CPU context, the thread memory, the module list, as
well as the SymbolSupplier and SourceLineResolverInterface. This method selects
the specific !Stackwalker subclass based on the CPU architecture of the provided
@@ -57,8 +55,7 @@ CPU context and returns an instance of that subclass.
## Walking a thread's stack
Once a !Stackwalker instance has been obtained, the processor calls the
-[Stackwalker::Walk]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/source_line_resolver_interface.h)
+[Stackwalker::Walk](/src/google_breakpad/processor/source_line_resolver_interface.h)
method to obtain a list of frames representing the stack of this thread. The
!Stackwalker starts by calling the GetContextFrame method which returns a
StackFrame representing the top of the stack, with CPU state provided by the
@@ -69,71 +66,68 @@ for each frame in turn:
The address of the instruction pointer of the current frame is used to determine
which module contains the current frame by calling the module list's
-[GetModuleForAddress]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/code_modules.h#56)
+[GetModuleForAddress](/src/google_breakpad/processor/code_modules.h#56)
method.
### Locating Symbols
If a module is located, the SymbolSupplier is asked to locate symbols
-corresponding to the module by calling its [GetCStringSymbolData]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/symbol_supplier.h#87)
+corresponding to the module by calling its
+[GetCStringSymbolData](/src/google_breakpad/processor/symbol_supplier.h#87)
method. Typically this is implemented by using the module's debug filename (the
PDB filename for Windows dumps) and debug identifier (a GUID plus one extra
-digit) as a lookup key. The [SimpleSymbolSupplier]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/processor/simple_symbol_supplier.cc)
+digit) as a lookup key. The
+[SimpleSymbolSupplier](/src/processor/simple_symbol_supplier.cc)
class simply uses these as parts of a file path to locate a flat file on disk.
### Loading Symbols
-If a symbol file is located, the SourceLineResolverInterface is then asked to
-load the symbol file by calling its [LoadModuleUsingMemoryBuffer]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/source_line_resolver_interface.h#71)
-method. The [BasicSourceLineResolver]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/processor/basic_source_line_resolver.cc)
+If a [symbol file](symbol_files.md) is located, the SourceLineResolverInterface is then asked to
+load the [symbol file](symbol_files.md) by calling its
+[LoadModuleUsingMemoryBuffer](/src/google_breakpad/processor/source_line_resolver_interface.h#71)
+method. The
+[BasicSourceLineResolver](/src/processor/basic_source_line_resolver.cc)
implementation parses the text-format [symbol file](symbol_files.md) into
in-memory data structures to make lookups by address of function names, source
line information, and unwind information easy.
### Getting source line information
-If a symbol file has been successfully loaded, the SourceLineResolverInterface's
-[FillSourceLineInfo]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/source_line_resolver_interface.h#89)
+If a [symbol file](symbol_files.md) has been successfully loaded, the SourceLineResolverInterface's
+[FillSourceLineInfo](/src/google_breakpad/processor/source_line_resolver_interface.h#89)
method is called to provide a function name and source line information for the
current frame. This is done by subtracting the base address of the module
containing the current frame from the instruction pointer of the current frame
to obtain a relative virtual address (RVA), which is a code offset relative to
the start of the module. This RVA is then used as a lookup into a table of
-functions ([FUNC lines](SymbolFiles#FUNC_records.md) from the symbol file), each
+functions ([FUNC lines](symbol_files.md#records-3) from the [symbol file](symbol_files.md)), each
of which has an associated address range (function start address, function
size). If a function is found whose address range contains the RVA, then its
name is used. The RVA is then used as a lookup into a table of source lines
-([line records](SymbolFiles#Line_records.md) from the symbol file), each of
+([line records](symbol_files.md#Line-records) from the [symbol file](symbol_files.md)), each of
which also has an associated address range. If a match is found it will provide
the file name and source line associated with the current frame. If no match was
found in the function table, another table of publicly exported symbols may be
-consulted ([PUBLIC lines](SymbolFiles#PUBLIC_records.md) from the symbol file).
+consulted ([PUBLIC lines](symbol_files.md#records-4) from the [symbol file](symbol_files.md)).
Public symbols contain only a start address, so the lookup simply looks for the
nearest symbol that is less than the provided RVA.
### Finding the caller frame
-To find the next frame in the stack, the !Stackwalker calls its [GetCallerFrame]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/stackwalker.h#186)
+To find the next frame in the stack, the !Stackwalker calls its
+[GetCallerFrame](/src/google_breakpad/processor/stackwalker.h#186)
method, passing in the current frame. Each !Stackwalker subclass implements
GetCallerFrame differently, but there are common patterns.
Typically the first step is to query the SourceLineResolverInterface for the
presence of detailed unwind information. This is done using its
-[FindWindowsFrameInfo]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/source_line_resolver_interface.h#96)
-and [FindCFIFrameInfo]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/source_line_resolver_interface.h#102)
+[FindWindowsFrameInfo](/src/google_breakpad/processor/source_line_resolver_interface.h#96)
+and
+[FindCFIFrameInfo](/src/google_breakpad/processor/source_line_resolver_interface.h#102)
methods. These methods look for Windows unwind info extracted from a PDB file
-([STACK WIN](SymbolFiles#STACK_WIN_records.md) lines from the symbol file), or
-DWARF CFI extracted from a binary ([STACK CFI](SymbolFiles#STACK_CFI_records.md)
-lines from the symbol file) respectively. The information covers address ranges,
+([STACK WIN](symbol_files.md#records-5) lines from the [symbol file](symbol_files.md)), or
+DWARF CFI extracted from a binary ([STACK CFI](symbol_files.md#records-6)
+lines from the [symbol file](symbol_files.md)) respectively. The information covers address ranges,
so the RVA of the current frame is used for lookup as with function and source
line information.
@@ -148,11 +142,11 @@ to produce the caller frame.
If no caller frame was found by any other method most !Stackwalker
implementations resort to stack scanning by looking at each word on the stack
-down to a fixed depth (implemented in the [Stackwalker::ScanForReturnAddress]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/stackwalker.h#131)
+down to a fixed depth (implemented in the
+[Stackwalker::ScanForReturnAddress](/src/google_breakpad/processor/stackwalker.h#131)
method) and using a heuristic to attempt to find a reasonable return address
-(implemented in the [Stackwalker::InstructionAddressSeemsValid]
-(http://code.google.com/p/google-breakpad/source/browse/trunk/src/google_breakpad/processor/stackwalker.h#111)
+(implemented in the
+[Stackwalker::InstructionAddressSeemsValid](/src/google_breakpad/processor/stackwalker.h#111)
method).
If no caller frame is found or the caller frame seems invalid, stack walking
« docs/client_design.md ('K') | « docs/processor_design.md ('k') | docs/symbol_files.md » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698