Toolchain/binutils-gdb
1
0
Fork 0
forked from Imagelibrary/binutils-gdb
Code Pull Requests Activity

doc: sframe: small improvements for readability

Browse Source 
Update some of the content to make the specification document hopefully
clearer:
  - Fix some typos.
  - Use Title case consistently for headings.
  - Update text around detection of foreign endianness.
  - Split the structure field "Name" in each table to two separate
    colunms for additional attention: "Type" and "Name".
  - Rename "SFrame endianness" section to "SFrame magic number and
    endianness"
  - Update text around provisions for extending SFrame for future
    ABIs/architectures.  Make it clear by tagging all provisions with an
    explicit index item "Provisions for future ABIs".
  - Add a paragraph on sort order of SFrame FDEs.
  - Add a statement for SFRAME_F_FRAME_POINTER flag.
  - Add a statement to assert that SFrame version 1 is now obsolete and
    should not be used.

libsframe/
	* doc/sframe-spec.texi: Small improvements for readability.
This commit is contained in:
Indu Bhagat
2024-06-25 22:27:12 -07:00
parent b57ce13242
commit f8ed9c5722
1 changed files with 182 additions and 129 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
libsframe/doc/sframe-spec.texi
View File

@@ -34,7 +34,7 @@ License''.
@top The SFrame format @top The SFrame format
This manual describes version 2 of the SFrame file format. SFrame stands for This manual describes version 2 of the SFrame file format. SFrame stands for
Simple Frame format. SFrame format keeps track of the minimal necessary Simple Frame. The SFrame format keeps track of the minimal necessary
information needed for generating stack traces: information needed for generating stack traces:
@itemize @minus @itemize @minus
@@ -51,7 +51,7 @@ low-overhead mechanism to generate stack traces.
@menu @menu
* Introduction:: * Introduction::
* SFrame section:: * SFrame Section::
* Index:: * Index::
@end menu @end menu
@@ -83,7 +83,7 @@ function descriptor entry) have elements at their natural boundaries. All data
structures are packed, unless otherwise stated. structures are packed, unless otherwise stated.
The contents of the SFrame section are stored in the target endianness, i.e., The contents of the SFrame section are stored in the target endianness, i.e.,
in the endianness of the system on which the section is targetted to be used. in the endianness of the system on which the section is targeted to be used.
An SFrame section reader may use the magic number in the SFrame header to An SFrame section reader may use the magic number in the SFrame header to
identify the endianness of the SFrame section. identify the endianness of the SFrame section.
@@ -110,24 +110,28 @@ since Version 1 was published.
@itemize @bullet @itemize @bullet
@item @item
SFrame Function Descriptor Entry encodes the size of the repetitive code Add an unsigned 8-bit integral field to the SFrame function descriptor entry to
blocks, e.g., pltN entries for which an FDE of type SFRAME_FDE_TYPE_PCMASK is encode the size of the repetitive code blocks. Such code blocks, e.g, pltN
used. entries, use an SFrame function descriptor entry of type
SFRAME_FDE_TYPE_PCMASK.
@item @item
SFrame Function Descriptor Entry includes an explicit padding of two bytes to Add an unsigned 16-bit integral field to the SFrame function descriptor entry
ensure natural alignment for its data members. to serve as padding. This helps ensure natural alignment for the members of
the data structure.
@item @item
The above two imply that each SFrame Function Descriptor Entry has a fixed size The above two imply that each SFrame function descriptor entry has a fixed size
of 20 bytes instead of its size of 17 bytes in SFrame format version 1. of 20 bytes instead of its size of 17 bytes in SFrame format version 1.
@end itemize @end itemize
@node SFrame section SFrame version 1 is now obsolete and should not be used.
@chapter SFrame section
@cindex SFrame section @node SFrame Section
@chapter SFrame Section
@cindex SFrame Section
The SFrame section consists of an SFrame header, starting with a preamble, and The SFrame section consists of an SFrame header, starting with a preamble, and
two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame two other sub-sections, namely the SFrame function descriptor entry (SFrame
FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section. FDE) sub-section, and the SFrame frame row entry (SFrame FRE) sub-section.
@menu @menu
* SFrame Preamble:: * SFrame Preamble::
@@ -140,8 +144,8 @@ FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section.
@section SFrame Preamble @section SFrame Preamble
@cindex SFrame preamble @cindex SFrame preamble
The preamble is a 32-bit packed structure; the only part of the SFrame whose The preamble is a 32-bit packed structure; the only part of the SFrame section
format cannot vary between versions. whose format cannot vary between versions.
@example @example
typedef struct sframe_preamble typedef struct sframe_preamble
@@ -157,43 +161,47 @@ Every element of the SFrame preamble is naturally aligned.
All values are stored in the endianness of the target system for which the All values are stored in the endianness of the target system for which the
SFrame section is intended. Further details: SFrame section is intended. Further details:
@multitable {Offset} {@code{uint8_t sfp_version}} {The magic number for SFrame section: 0xdee2. Defined} @multitable {Offset} {@code{uint16_t}} {@code{sfp_version}} {The magic number for SFrame section: 0xdee2.}
@headitem Offset @tab Name @tab Description @headitem Offset @tab Type @tab Name @tab Description
@item 0x00 @item 0x00
@tab @code{uint16_t sfp_magic} @tab @code{uint16_t}
@tab @code{sfp_magic}
@tab The magic number for SFrame section: 0xdee2. Defined as a macro @code{SFRAME_MAGIC}. @tab The magic number for SFrame section: 0xdee2. Defined as a macro @code{SFRAME_MAGIC}.
@tindex SFRAME_MAGIC @tindex SFRAME_MAGIC
@item 0x02 @item 0x02
@tab @code{uint8_t sfp_version} @tab @code{uint8_t}
@tab The version number of this SFrame section. @xref{SFrame version}, for the @tab @code{sfp_version}
@tab The version number of this SFrame section. @xref{SFrame Version}, for the
set of valid values. Current version is set of valid values. Current version is
@code{SFRAME_VERSION_1}. @code{SFRAME_VERSION_2}.
@item 0x03 @item 0x03
@tab @code{uint8_t sfp_flags} @tab @code{uint8_t}
@tab Flags (section-wide) for this SFrame section. @xref{SFrame flags}, for the @tab @code{sfp_flags}
@tab Flags (section-wide) for this SFrame section. @xref{SFrame Flags}, for the
set of valid values. set of valid values.
@end multitable @end multitable
@menu @menu
* SFrame endianness:: * SFrame Magic Number and Endianness::
* SFrame version:: * SFrame Version::
* SFrame flags:: * SFrame Flags::
@end menu @end menu
@node SFrame endianness @node SFrame Magic Number and Endianness
@subsection SFrame endianness @subsection SFrame Magic Number and Endianness
@cindex endianness @cindex endianness
@cindex SFrame magic number
SFrame sections are stored in the target endianness of the system that consumes SFrame sections are stored in the target endianness of the system that consumes
them. The SFrame library (@code{libsframe}) can, however, detect whether to them. A consumer library reading or writing SFrame sections should detect
endian-flip an SFrame section at decode time, by inspecting the foreign-endianness by inspecting the SFrame magic number in the
@code{sfp_magic} field in the SFrame header (If it appears as 0xe2de, @code{sfp_magic} field in the SFrame header. It may then provide means to
endian-flipping is needed). endian-flip the SFrame section as necessary.
@node SFrame version @node SFrame Version
@subsection SFrame version @subsection SFrame Version
The version of the SFrame format can be determined by inspecting The version of the SFrame format can be determined by inspecting
@code{sfp_version}. The following versions are currently valid: @code{sfp_version}. The following versions are currently valid:
@@ -201,7 +209,7 @@ The version of the SFrame format can be determined by inspecting
@tindex SFRAME_VERSION_1 @tindex SFRAME_VERSION_1
@cindex SFrame versions @cindex SFrame versions
@multitable {SFRAME_VERSION_2} {Number} {Current version, under development.} @multitable {SFRAME_VERSION_2} {Number} {Current version, under development.}
@headitem Version @tab Number @tab Description @headitem Version Name @tab Number @tab Description
@item @code{SFRAME_VERSION_1} @item @code{SFRAME_VERSION_1}
@tab 1 @tab First version, obsolete. @tab 1 @tab First version, obsolete.
@item @code{SFRAME_VERSION_2} @item @code{SFRAME_VERSION_2}
@@ -210,12 +218,9 @@ The version of the SFrame format can be determined by inspecting
This document describes @code{SFRAME_VERSION_2}. This document describes @code{SFRAME_VERSION_2}.
@node SFrame flags @node SFrame Flags
@subsection SFrame flags @subsection SFrame Flags
@cindex SFrame flags @cindex SFrame Flags
@comment @vindex sfp_flags
@comment @vindex SFrame section-wide flags
@comment @subsection SFrame section-wide flags
The preamble contains bitflags in its @code{sfp_flags} field that The preamble contains bitflags in its @code{sfp_flags} field that
describe various section-wide properties. describe various section-wide properties.
@@ -229,9 +234,13 @@ The following flags are currently defined.
Entries are sorted on PC. Entries are sorted on PC.
@tindex SFRAME_F_FRAME_POINTER @tindex SFRAME_F_FRAME_POINTER
@item @code{SFRAME_F_FRAME_POINTER} @tab All @tab 0x2 @item @code{SFRAME_F_FRAME_POINTER} @tab All @tab 0x2
@tab Functions preserve frame-pointer. @tab All functions in the object file preserve frame pointer.
@end multitable @end multitable
The purpose of SFRAME_F_FRAME_POINTER flag is to facilitate stack tracers to
reliably fallback on the frame pointer based stack tracing method, if SFrame
information is not present for some function in the SFrame section.
Further flags may be added in future. Further flags may be added in future.
@node SFrame Header @node SFrame Header
@@ -272,79 +281,100 @@ SFrame header are relative to the @emph{end} of the SFrame header; they are
each an offset in bytes into the SFrame section where the SFrame FDE each an offset in bytes into the SFrame section where the SFrame FDE
sub-section and the SFrame FRE sub-section respectively start. sub-section and the SFrame FRE sub-section respectively start.
The SFrame section contains @code{sfh_num_fdes} number of fixed-length array
elements in the SFrame FDE sub-section. Each array element is of type SFrame
function descriptor entry; each providing a high-level function description for
the purpose of stack tracing. More details in a subsequent section.
@xref{SFrame Function Descriptor Entries}.
Next, the SFrame FRE sub-section, starting at offset @code{sfh_fre_off},
describes the stack trace information for each function, using a total of
@code{sfh_num_fres} number of variable-length array elements. Each array
element is of type SFrame frame row entry.
@xref{SFrame Frame Row Entries}.
SFrame header allows specifying explicitly the fixed offsets from CFA, if any, SFrame header allows specifying explicitly the fixed offsets from CFA, if any,
from which FP or RA may be recovered. For example, in AMD64, the stack offset from which FP or RA may be recovered. For example, in AMD64, the stack offset
of the return address is @code{CFA - 8}. Since this offset is in close of the return address is @code{CFA - 8}. Since these offsets are expected to
vicinity with the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset} and be in close vicinity to the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset}
@code{sfh_cfa_fixed_ra_offset} are limited to signed 8-bit integers. and @code{sfh_cfa_fixed_ra_offset} are limited to signed 8-bit integers.
SFrame format has made some provisions for supporting more ABIs/architectures @cindex Provisions for future ABIs
in the future. The @code{sframe_header} structure provides an unsigned 8-bit The SFrame format has made some provisions for supporting more
integral field to denote the size of an auxiliary SFrame header. The ABIs/architectures in the future. One of them is the concept of the auxiliary
auxiliary SFrame header follows right after the @code{sframe_header} SFrame header. Bytes in the auxiliary SFrame header may be used to convey
structure. As for the offset calculations, the @emph{end} of SFrame header further ABI-specific information. The @code{sframe_header} structure provides
must be the end of the auxiliary SFrame header, if the latter is present. an unsigned 8-bit integral field to denote the size (in bytes) of an auxiliary
SFrame header. The auxiliary SFrame header follows right after the
@code{sframe_header} structure. As for the calculation of the sub-section
offsets, namely @code{sfh_fdeoff} and @code{sfh_freoff}, the @emph{end} of
SFrame header must be the end of the auxiliary SFrame header, if the latter is
present.
Putting it all together: Putting it all together:
@multitable {Offset} {@code{int8_t sfh_cfa_fixed_fp_offset}} {The number of SFrame FREs in the section.} @multitable {Offset} {@code{uint32_t}} {@code{sfh_cfa_fixed_fp_offset}} {The number of SFrame FREs in the}
@headitem Offset @tab Name @tab Description @headitem Offset @tab Type @tab Name @tab Description
@item 0x00 @item 0x00
@tab @code{sframe_preamble sfh_preamble} @tab @code{sframe_ @* preamble}
@tab @code{sfh_preamble}
@tab The SFrame preamble. @xref{SFrame Preamble}. @tab The SFrame preamble. @xref{SFrame Preamble}.
@item 0x04 @item 0x04
@tab @code{uint8_t sfh_abi_arch} @tab @code{uint8_t}
@tab The ABI/arch identifier. @xref{SFrame ABI/arch identifier}. @tab @code{sfh_abi_arch}
@tab The ABI/arch identifier. @xref{SFrame ABI/arch Identifier}.
@item 0x05 @item 0x05
@tab @code{int8_t sfh_cfa_fixed_fp_offset} @tab @code{int8_t}
@tab @code{sfh_cfa_fixed_fp_offset}
@tab The CFA fixed FP offset, if any. @tab The CFA fixed FP offset, if any.
@item 0x06 @item 0x06
@tab @code{int8_t sfh_cfa_fixed_ra_offset} @tab @code{int8_t}
@tab @code{sfh_cfa_fixed_ra_offset}
@tab The CFA fixed RA offset, if any. @tab The CFA fixed RA offset, if any.
@item 0x07 @item 0x07
@tab @code{uint8_t sfh_auxhdr_len} @tab @code{uint8_t}
@tab @code{sfh_auxhdr_len}
@tab Size in bytes of the auxiliary header that follows the @tab Size in bytes of the auxiliary header that follows the
@code{sframe_header} structure. @code{sframe_header} structure.
@item 0x08 @item 0x08
@tab @code{uint32_t sfh_num_fdes} @tab @code{uint32_t}
@tab @code{sfh_num_fdes}
@tab The number of SFrame FDEs in the section. @tab The number of SFrame FDEs in the section.
@item 0xc @item 0x0c
@tab @code{uint32_t sfh_num_fres} @tab @code{uint32_t}
@tab @code{sfh_num_fres}
@tab The number of SFrame FREs in the section. @tab The number of SFrame FREs in the section.
@item 0x10 @item 0x10
@tab @code{uint32_t sfh_fre_len} @tab @code{uint32_t}
@tab @code{sfh_fre_len}
@tab The length in bytes of the SFrame FRE sub-section. @tab The length in bytes of the SFrame FRE sub-section.
@item 0x14 @item 0x14
@tab @code{uint32_t sfh_fdeoff} @tab @code{uint32_t}
@tab The offset in bytes of the SFrame FDE sub-section. This sub-section @tab @code{sfh_fdeoff}
contains @code{sfh_num_fdes} number of fixed-length array elements. The array @tab The offset in bytes to the SFrame FDE sub-section.
element is of type SFrame function desciptor entry, each providing a
high-level function description for backtracing.
@xref{SFrame Function Descriptor Entries}.
@item 0x18 @item 0x18
@tab @code{uint32_t sfh_freoff} @tab @code{uint32_t}
@tab The offset in bytes of the SFrame FRE sub-section, the core of the SFrame @tab @code{sfh_freoff}
section, which describes the stack trace information using variable-length array @tab The offset in bytes to the SFrame FRE sub-section.
elements. @xref{SFrame Frame Row Entries}.
@end multitable @end multitable
@menu @menu
* SFrame ABI/arch identifier:: * SFrame ABI/arch Identifier::
@end menu @end menu
@node SFrame ABI/arch identifier @node SFrame ABI/arch Identifier
@subsection SFrame ABI/arch identifier @subsection SFrame ABI/arch Identifier
@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 hence, the stack trace information contained in the SFrame executable and hence, the stack trace information contained in the SFrame
@@ -375,11 +405,18 @@ stack trace generators to make certain ABI-specific decisions.
@section SFrame FDE @section SFrame FDE
@cindex SFrame FDE @cindex SFrame FDE
The SFrame Function Descriptor Entry sub-section is a sorted array of The SFrame function descriptor entry sub-section is an array of the
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 stack is a packed structure which contains information to describe a function's stack
trace information at a high-level. trace information at a high-level.
The array of SFrame FDEs is sorted on the @code{sfde_func_start_address} if
the SFrame section header flag @code{sfp_flags} has @code{SFRAME_F_FDE_SORTED}
set. Typically (as is the case with GNU ld) a linked object or executable
will have the @code{SFRAME_F_FDE_SORTED} set. This makes the job of a stack
tracer easier as it may then employ binary search schemes to look for the
pertinent SFrame FDE.
@example @example
typedef struct sframe_func_desc_entry typedef struct sframe_func_desc_entry
@{ @{
@@ -397,62 +434,75 @@ Every element of the SFrame function descriptor entry is naturally aligned.
@code{sfde_func_start_fre_off} is the offset to the first SFrame FRE for the @code{sfde_func_start_fre_off} is the offset to the first SFrame FRE for the
function. This offset is relative to the @emph{end of the SFrame FDE} function. This offset is relative to the @emph{end of the SFrame FDE}
sub-section (unlike the offsets in the SFrame header, which are relative to the sub-section (unlike the sub-section offsets in the SFrame header, which are
@emph{end} of the SFrame header). relative to the @emph{end} of the SFrame header).
@code{sfde_func_info} is the "info word", containing information on the FRE @code{sfde_func_info} is the SFrame FDE "info word", containing information on
type and the FDE type for the function @xref{The SFrame FDE info word}. the FRE type and the FDE type for the function @xref{The SFrame FDE Info Word}.
@cindex Provisions for future ABIs
Apart from the @code{sfde_func_padding2}, the SFrame FDE has some currently
unused bits in the SFrame FDE info word, @xref{The SFrame FDE Info Word}, that
may be used for the purpose of extending the SFrame file format specification
for future ABIs.
Following table describes each component of the SFrame FDE structure: Following table describes each component of the SFrame FDE structure:
@multitable {Offset} {@code{uint32_t sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the} @multitable {Offset} {@code{uint32_t}} {@code{sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the}
@headitem Offset @tab Name @tab Description @headitem Offset @tab Type @tab Name @tab Description
@item 0x00 @item 0x00
@tab @code{int32_t sfde_func_start_address} @tab @code{int32_t}
@tab @code{sfde_func_start_address}
@tab Signed 32-bit integral field denoting the virtual memory address of the @tab Signed 32-bit integral field denoting the virtual memory address of the
described function. described function.
@item 0x04 @item 0x04
@tab @code{uint32_t sfde_func_size} @tab @code{uint32_t}
@tab @code{sfde_func_size}
@tab Unsigned 32-bit integral field specifying the size of the function in @tab Unsigned 32-bit integral field specifying the size of the function in
bytes. bytes.
@item 0x08 @item 0x08
@tab @code{uint32_t sfde_func_start_fre_off} @tab @code{uint32_t}
@tab @code{sfde_func_start_fre_off}
@tab Unsigned 32-bit integral field specifying the offset in bytes of the @tab Unsigned 32-bit integral field specifying the offset in bytes of the
function's first SFrame FRE in the SFrame section. function's first SFrame FRE in the SFrame section.
@item 0x0c @item 0x0c
@tab @code{uint32_t sfde_func_num_fres} @tab @code{uint32_t}
@tab @code{sfde_func_num_fres}
@tab Unsigned 32-bit integral field specifying the total number of SFrame FREs @tab Unsigned 32-bit integral field specifying the total number of SFrame FREs
used for the function. used for the function.
@item 0x10 @item 0x10
@tab @code{uint8_t sfde_func_info} @tab @code{uint8_t}
@tab @code{sfde_func_info}
@tab Unsigned 8-bit integral field specifying the SFrame FDE info word. @tab Unsigned 8-bit integral field specifying the SFrame FDE info word.
@xref{The SFrame FDE info word}. @xref{The SFrame FDE Info Word}.
@item 0x11 @item 0x11
@tab @code{uint8_t sfde_func_rep_size} @tab @code{uint8_t}
@tab @code{sfde_func_rep_size}
@tab Unsigned 8-bit integral field specifying the size of the repetitive code @tab Unsigned 8-bit integral field specifying the size of the repetitive code
block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For
example, in AMD64, the size of a pltN entry is 16 bytes. example, in AMD64, the size of a pltN entry is 16 bytes.
@item 0x12 @item 0x12
@tab @code{uint16_t sfde_func_padding2} @tab @code{uint16_t}
@tab @code{sfde_func_padding2}
@tab Padding of 2 bytes. Currently unused bytes. @tab Padding of 2 bytes. Currently unused bytes.
@end multitable @end multitable
@menu @menu
* The SFrame FDE info word:: * The SFrame FDE Info Word::
* The SFrame FDE types:: * The SFrame FDE Types::
* The SFrame FRE types:: * The SFrame FRE Types::
@end menu @end menu
@cindex The SFrame FDE info word @cindex The SFrame FDE Info Word
@node The SFrame FDE info word @node The SFrame FDE Info Word
@subsection The SFrame FDE info word @subsection The SFrame FDE Info Word
The info word is a bitfield split into three parts. From MSB to LSB: The info word is a bitfield split into three parts. From MSB to LSB:
@@ -464,31 +514,32 @@ The info word is a bitfield split into three parts. From MSB to LSB:
@item 5 @item 5
@tab @code{pauth_key} @tab @code{pauth_key}
@tab Specify which key is used for signing the return addresses in the SFrame @tab (For AARCH64) Specify which key is used for signing the return addresses
FDE. Two possible values: @* in the SFrame FDE. Two possible values: @*
SFRAME_AARCH64_PAUTH_KEY_A (0), or @* SFRAME_AARCH64_PAUTH_KEY_A (0), or @*
SFRAME_AARCH64_PAUTH_KEY_B (1). SFRAME_AARCH64_PAUTH_KEY_B (1). @*
Ununsed in AMD64.
@item 4 @item 4
@tab @code{fdetype} @tab @code{fdetype}
@tab Specify the SFrame FDE type. Two possible values: @* @tab Specify the SFrame FDE type. Two possible values: @*
SFRAME_FDE_TYPE_PCMASK (1), or @* SFRAME_FDE_TYPE_PCMASK (1), or @*
SFRAME_FDE_TYPE_PCINC (0). @* SFRAME_FDE_TYPE_PCINC (0). @*
@xref{The SFrame FDE types}. @xref{The SFrame FDE Types}.
@item 0--3 @item 0--3
@tab @code{fretype} @tab @code{fretype}
@tab Choice of three SFrame FRE types. @xref{The SFrame FRE types}. @tab Choice of three SFrame FRE types. @xref{The SFrame FRE Types}.
@end multitable @end multitable
@node The SFrame FDE types @node The SFrame FDE Types
@subsection The SFrame FDE types @subsection The SFrame FDE Types
@tindex SFRAME_FDE_TYPE_PCMASK @tindex SFRAME_FDE_TYPE_PCMASK
@tindex SFRAME_FDE_TYPE_PCINC @tindex SFRAME_FDE_TYPE_PCINC
SFrame format defines two types of FDE entries. The choice of which SFrame FDE The SFrame format defines two types of FDE entries. The choice of which SFrame
type to use is made based on the instruction patterns in the relevant program FDE type to use is made based on the instruction patterns in the relevant
stub. program stub.
An SFrame FDE of type @code{SFRAME_FDE_TYPE_PCINC} is an indication that the PCs in the An SFrame FDE of type @code{SFRAME_FDE_TYPE_PCINC} is an indication that the PCs in the
FREs should be treated as increments in bytes. This is used fo the the bulk of FREs should be treated as increments in bytes. This is used fo the the bulk of
@@ -505,30 +556,31 @@ entries and trampolines.
@headitem Name of SFrame FDE type @tab Value @tab Description @headitem Name of SFrame FDE type @tab Value @tab Description
@item SFRAME_FDE_TYPE_PCINC @item SFRAME_FDE_TYPE_PCINC
@tab 0 @tab Unwinders perform a @* @tab 0 @tab Stacktracers perform a @*
(PC >= FRE_START_ADDR) to look up a matching FRE. (PC >= FRE_START_ADDR) to look up a matching FRE.
@item SFRAME_FDE_TYPE_PCMASK @item SFRAME_FDE_TYPE_PCMASK
@tab 1 @tab Unwinders perform a @* @tab 1 @tab Stacktracers perform a @*
(PC % REP_BLOCK_SIZE @* (PC % REP_BLOCK_SIZE @*
>= FRE_START_ADDR) >= FRE_START_ADDR)
to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the
repeating block of program instructions. repeating block of program instructions and is encoded via
@code{sfde_func_rep_size} in the SFrame FDE.
@end multitable @end multitable
@node The SFrame FRE types @node The SFrame FRE Types
@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 stack trace format defines three types of SFrame FRE entries to effeciently encode the
information for such a variety of function sizes. These representations vary stack trace information for such a variety of function sizes. These
in the number of bits needed to encode the start address offset in the SFrame representations vary in the number of bits needed to encode the start address
FRE. offset in the SFrame FRE.
The following constants are defined and used to identify the SFrame FRE types: The following constants are defined and used to identify the SFrame FRE types:
@multitable {SFRAME_FRE_TYPE_ADDR1} {@code{Value}} {The start address offset of FRE is an} @multitable {SFRAME_FRE_TYPE_ADDR1} {@code{Value}} {The start address offset (in bytes) of the}
@headitem Name @tab Value @tab Description @headitem Name @tab Value @tab Description
@tindex SFRAME_FRE_TYPE_ADDR1 @tindex SFRAME_FRE_TYPE_ADDR1
@@ -550,20 +602,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 SFrame FRE throughout. An A single function must use the same type of SFrame FRE throughout. The
identifier to reflect the chosen SFrame FRE type is stored in the identifier to reflect the chosen SFrame FRE type is stored in the
@xref{The SFrame FDE info word}. @code{fretype} bits in 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 stack trace 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 stack An SFrame frame row entry is a self-sufficient record containing SFrame stack
trace information for a range of contiguous addresses, starting at the trace information for a range of contiguous addresses, starting at the
specified offset from the start of the function. Each SFrame Frame Row Entry specified offset from the start of the function. Each SFrame frame row entry
is followed by S*N bytes, where: is followed by S*N bytes, where:
@itemize @minus @itemize @minus
@@ -591,7 +644,7 @@ the FP, by interpreting it as FP = CFA + offset3.
The entities @code{S}, @code{N} and @code{BASE_REG} are identified using the The entities @code{S}, @code{N} and @code{BASE_REG} are identified using the
SFrame FRE info word, a.k.a. the @code{sframe_fre_info} SFrame FRE info word, a.k.a. the @code{sframe_fre_info}
@xref{The SFrame FRE info word}. @xref{The SFrame FRE Info Word}.
Following are the definitions of the allowed SFrame FRE: Following are the definitions of the allowed SFrame FRE:
@@ -633,12 +686,12 @@ address of the function.
Further FRE types may be added in future. Further FRE types may be added in future.
@menu @menu
* The SFrame FRE info word:: * The SFrame FRE Info Word::
@end menu @end menu
@cindex The SFrame FRE info word @cindex The SFrame FRE Info Word
@node The SFrame FRE info word @node The SFrame FRE Info Word
@subsection The SFrame FRE info word @subsection The SFrame FRE Info Word
The SFrame FRE info word is a bitfield split into four parts. From MSB to LSB: The SFrame FRE info word is a bitfield split into four parts. From MSB to LSB: