mirror of
https://github.com/bminor/binutils-gdb.git
synced 2025-12-05 15:15:42 +00:00
libsframe/doc: use "stack trace" instead of "unwind" for SFrame
SFrame format is meant for generating stack traces only. libsframe/ * doc/sframe-spec.texi: Use "stack trace" instead of "unwind".
This commit is contained in:
@@ -35,7 +35,7 @@ License''.
|
|||||||
|
|
||||||
This manual describes version 1 of the SFrame file format. SFrame stands for
|
This manual describes version 1 of the SFrame file format. SFrame stands for
|
||||||
Simple Frame format. SFrame format keeps track of the minimal necessary
|
Simple Frame format. SFrame format keeps track of the minimal necessary
|
||||||
information needed for stack unwinding:
|
information needed for generating stack traces:
|
||||||
|
|
||||||
@itemize @minus
|
@itemize @minus
|
||||||
@item
|
@item
|
||||||
@@ -47,7 +47,7 @@ Return Address (RA).
|
|||||||
@end itemize
|
@end itemize
|
||||||
|
|
||||||
The reason for existence of the SFrame format is to support fast, online
|
The reason for existence of the SFrame format is to support fast, online
|
||||||
backtracing using a simple unwinder.
|
generation of stack traces using simple means.
|
||||||
|
|
||||||
@menu
|
@menu
|
||||||
* Overview::
|
* Overview::
|
||||||
@@ -62,7 +62,7 @@ backtracing using a simple unwinder.
|
|||||||
@cindex Overview
|
@cindex Overview
|
||||||
@tindex PT_GNU_SFRAME
|
@tindex PT_GNU_SFRAME
|
||||||
|
|
||||||
The SFrame unwind information is provided in a loaded section, known as the
|
The SFrame stack trace information is provided in a loaded section, known as the
|
||||||
@code{.sframe} section. When available, the @code{.sframe} section appears in
|
@code{.sframe} section. When available, the @code{.sframe} section appears in
|
||||||
a new segment of its own, PT_GNU_SFRAME.
|
a new segment of its own, PT_GNU_SFRAME.
|
||||||
|
|
||||||
@@ -289,7 +289,7 @@ high-level function description for backtracing.
|
|||||||
@item 0x18
|
@item 0x18
|
||||||
@tab @code{uint32_t sfh_freoff}
|
@tab @code{uint32_t sfh_freoff}
|
||||||
@tab The offset in bytes of the SFrame FRE sub-section, the core of the SFrame
|
@tab The offset in bytes of the SFrame FRE sub-section, the core of the SFrame
|
||||||
section, which describes the unwind information using variable-length array
|
section, which describes the stack trace information using variable-length array
|
||||||
elements. @xref{SFrame Frame Row Entries}.
|
elements. @xref{SFrame Frame Row Entries}.
|
||||||
|
|
||||||
@end multitable
|
@end multitable
|
||||||
@@ -303,8 +303,9 @@ elements. @xref{SFrame Frame Row Entries}.
|
|||||||
@cindex SFrame ABI/arch identifier
|
@cindex SFrame ABI/arch identifier
|
||||||
|
|
||||||
SFrame header identifies the ABI/arch of the target system for which the
|
SFrame header identifies the ABI/arch of the target system for which the
|
||||||
executable and it's unwind information is intended. There are currently three
|
executable and hence, the stack trace information contained in the SFrame
|
||||||
identifiable ABI/arch values in the format.
|
section, is intended. There are currently three identifiable ABI/arch values
|
||||||
|
in the format.
|
||||||
|
|
||||||
@multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 little-endian}}
|
@multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 little-endian}}
|
||||||
@headitem ABI/arch Identifier @tab Value @tab Description
|
@headitem ABI/arch Identifier @tab Value @tab Description
|
||||||
@@ -324,7 +325,7 @@ identifiable ABI/arch values in the format.
|
|||||||
@end multitable
|
@end multitable
|
||||||
|
|
||||||
The presence of an explicit identification of ABI/arch in SFrame may allow
|
The presence of an explicit identification of ABI/arch in SFrame may allow
|
||||||
unwinders to make certain ABI-specific decisions.
|
stack trace generators to make certain ABI-specific decisions.
|
||||||
|
|
||||||
@node SFrame Function Descriptor Entries
|
@node SFrame Function Descriptor Entries
|
||||||
@section SFrame FDE
|
@section SFrame FDE
|
||||||
@@ -332,8 +333,8 @@ unwinders to make certain ABI-specific decisions.
|
|||||||
|
|
||||||
The SFrame Function Descriptor Entry sub-section is a sorted array of
|
The SFrame Function Descriptor Entry sub-section is a sorted array of
|
||||||
fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE
|
fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE
|
||||||
is a packed structure which contains information to describe a function's unwind
|
is a packed structure which contains information to describe a function's stack
|
||||||
information at a high-level.
|
trace information at a high-level.
|
||||||
|
|
||||||
@example
|
@example
|
||||||
typedef struct sframe_func_desc_entry
|
typedef struct sframe_func_desc_entry
|
||||||
@@ -459,7 +460,7 @@ to look up a matching FRE.
|
|||||||
@subsection The SFrame FRE types
|
@subsection The SFrame FRE types
|
||||||
|
|
||||||
A real world application can have functions of size big and small. SFrame
|
A real world application can have functions of size big and small. SFrame
|
||||||
format defines three types of SFrame FRE entries to represent the unwind
|
format defines three types of SFrame FRE entries to represent the stack trace
|
||||||
information for such a variety of function sizes. These representations vary
|
information for such a variety of function sizes. These representations vary
|
||||||
in the number of bits needed to encode the start address offset in the SFrame
|
in the number of bits needed to encode the start address offset in the SFrame
|
||||||
FRE.
|
FRE.
|
||||||
@@ -488,21 +489,21 @@ The following constants are defined and used to identify the SFrame FRE types:
|
|||||||
32-bit value.
|
32-bit value.
|
||||||
@end multitable
|
@end multitable
|
||||||
|
|
||||||
A single function must use the same type of FRE throughout. The choice of
|
A single function must use the same type of SFrame FRE throughout. An
|
||||||
which SFrame FRE is used to encode the unwind information of a function, is
|
identifier to reflect the chosen SFrame FRE type is stored in the
|
||||||
stored in the @xref{The SFrame FDE info word}.
|
@xref{The SFrame FDE info word}.
|
||||||
|
|
||||||
@node SFrame Frame Row Entries
|
@node SFrame Frame Row Entries
|
||||||
@section SFrame FRE
|
@section SFrame FRE
|
||||||
@cindex SFrame FRE
|
@cindex SFrame FRE
|
||||||
|
|
||||||
The SFrame Frame Row Entry sub-section contains the core of the unwind
|
The SFrame Frame Row Entry sub-section contains the core of the stack trace
|
||||||
information.
|
information.
|
||||||
|
|
||||||
An SFrame Frame Row Entry is a self-sufficient record containing SFrame unwind
|
An SFrame Frame Row Entry is a self-sufficient record containing SFrame stack
|
||||||
info for a range of contiguous addresses, starting at the specified offset from
|
trace information for a range of contiguous addresses, starting at the
|
||||||
the start of the function. Each SFrame Frame Row Entry is followed by S*N
|
specified offset from the start of the function. Each SFrame Frame Row Entry
|
||||||
bytes, where:
|
is followed by S*N bytes, where:
|
||||||
|
|
||||||
@itemize @minus
|
@itemize @minus
|
||||||
@item
|
@item
|
||||||
|
|||||||
Reference in New Issue
Block a user