[PATCH, V3] doc: sframe: small improvements for readability
Indu Bhagat
indu.bhagat@oracle.com
Wed Jun 26 17:49:18 GMT 2024
On 6/21/24 10:14, Indu Bhagat wrote:
> 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 has now been committed.
Thanks
> ---
> [Changes in V3]
> - Addressed review comments by Jens.
> [End of changes in V3]
>
> [Changes in V2]
> - Fixed build failure reported by Linaro CI. Newer makeinfo versions
> do not report the error:
> <src>/libsframe/doc/sframe-spec.texi:646: @xref reference to nonexistent node `The SFrame FRE info word'
> make[3]: *** [Makefile:977: doc/sframe-spec.info] Error 1
> [End of changes in V2]
>
> Notes:
> - The changes do not affect the current definition of the format.
> - Sending it to the list as more eyes on this won't hurt. Ideally I
> would like to commit this sometime next week. Thanks.
>
> libsframe/doc/sframe-spec.texi | 313 +++++++++++++++++++--------------
> 1 file changed, 183 insertions(+), 130 deletions(-)
>
> diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi
> index d0f99bd698e..bb2b35a46d9 100644
> --- a/libsframe/doc/sframe-spec.texi
> +++ b/libsframe/doc/sframe-spec.texi
> @@ -34,7 +34,7 @@ License''.
> @top The SFrame format
>
> 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:
>
> @itemize @minus
> @@ -51,7 +51,7 @@ low-overhead mechanism to generate stack traces.
>
> @menu
> * Introduction::
> -* SFrame section::
> +* SFrame Section::
> * Index::
> @end menu
>
> @@ -83,7 +83,7 @@ function descriptor entry) have elements at their natural boundaries. All data
> structures are packed, unless otherwise stated.
>
> 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
> identify the endianness of the SFrame section.
>
> @@ -110,24 +110,28 @@ since Version 1 was published.
>
> @itemize @bullet
> @item
> -SFrame Function Descriptor Entry encodes the size of the repetitive code
> -blocks, e.g., pltN entries for which an FDE of type SFRAME_FDE_TYPE_PCMASK is
> -used.
> +Add an unsigned 8-bit integral field to the SFrame function descriptor entry to
> +encode the size of the repetitive code blocks. Such code blocks, e.g, pltN
> +entries, use an SFrame function descriptor entry of type
> +SFRAME_FDE_TYPE_PCMASK.
> @item
> -SFrame Function Descriptor Entry includes an explicit padding of two bytes to
> -ensure natural alignment for its data members.
> +Add an unsigned 16-bit integral field to the SFrame function descriptor entry
> +to serve as padding. This helps ensure natural alignment for the members of
> +the data structure.
> @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.
> @end itemize
>
> -@node SFrame section
> -@chapter SFrame section
> -@cindex SFrame section
> +SFrame version 1 is now obsolete and should not be used.
> +
> +@node SFrame Section
> +@chapter SFrame Section
> +@cindex SFrame Section
>
> The SFrame section consists of an SFrame header, starting with a preamble, and
> -two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame
> -FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section.
> +two other sub-sections, namely the SFrame function descriptor entry (SFrame
> +FDE) sub-section, and the SFrame frame row entry (SFrame FRE) sub-section.
>
> @menu
> * SFrame Preamble::
> @@ -140,8 +144,8 @@ FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section.
> @section SFrame Preamble
> @cindex SFrame preamble
>
> -The preamble is a 32-bit packed structure; the only part of the SFrame whose
> -format cannot vary between versions.
> +The preamble is a 32-bit packed structure; the only part of the SFrame section
> +whose format cannot vary between versions.
>
> @example
> 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
> SFrame section is intended. Further details:
>
> -@multitable {Offset} {@code{uint8_t sfp_version}} {The magic number for SFrame section: 0xdee2. Defined}
> -@headitem Offset @tab Name @tab Description
> +@multitable {Offset} {@code{uint16_t}} {@code{sfp_version}} {The magic number for SFrame section: 0xdee2.}
> +@headitem Offset @tab Type @tab Name @tab Description
> @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}.
> @tindex SFRAME_MAGIC
>
> @item 0x02
> -@tab @code{uint8_t sfp_version}
> -@tab The version number of this SFrame section. @xref{SFrame version}, for the
> +@tab @code{uint8_t}
> +@tab @code{sfp_version}
> +@tab The version number of this SFrame section. @xref{SFrame Version}, for the
> set of valid values. Current version is
> -@code{SFRAME_VERSION_1}.
> +@code{SFRAME_VERSION_2}.
>
> @item 0x03
> -@tab @code{uint8_t sfp_flags}
> -@tab Flags (section-wide) for this SFrame section. @xref{SFrame flags}, for the
> +@tab @code{uint8_t}
> +@tab @code{sfp_flags}
> +@tab Flags (section-wide) for this SFrame section. @xref{SFrame Flags}, for the
> set of valid values.
> @end multitable
>
> @menu
> -* SFrame endianness::
> -* SFrame version::
> -* SFrame flags::
> +* SFrame Magic Number and Endianness::
> +* SFrame Version::
> +* SFrame Flags::
> @end menu
>
> -@node SFrame endianness
> -@subsection SFrame endianness
> +@node SFrame Magic Number and Endianness
> +@subsection SFrame Magic Number and Endianness
>
> @cindex endianness
> +@cindex SFrame magic number
> SFrame sections are stored in the target endianness of the system that consumes
> -them. The SFrame library (@code{libsframe}) can, however, detect whether to
> -endian-flip an SFrame section at decode time, by inspecting the
> -@code{sfp_magic} field in the SFrame header (If it appears as 0xe2de,
> -endian-flipping is needed).
> +them. A consumer library reading or writing SFrame sections should detect
> +foreign-endianness by inspecting the SFrame magic number in the
> +@code{sfp_magic} field in the SFrame header. It may then provide means to
> +endian-flip the SFrame section as necessary.
>
> -@node SFrame version
> -@subsection SFrame version
> +@node SFrame Version
> +@subsection SFrame Version
>
> The version of the SFrame format can be determined by inspecting
> @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
> @cindex SFrame versions
> @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}
> @tab 1 @tab First version, obsolete.
> @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}.
>
> -@node SFrame flags
> -@subsection SFrame flags
> -@cindex SFrame flags
> -@comment @vindex sfp_flags
> -@comment @vindex SFrame section-wide flags
> -@comment @subsection SFrame section-wide flags
> +@node SFrame Flags
> +@subsection SFrame Flags
> +@cindex SFrame Flags
>
> The preamble contains bitflags in its @code{sfp_flags} field that
> describe various section-wide properties.
> @@ -229,9 +234,13 @@ The following flags are currently defined.
> Entries are sorted on PC.
> @tindex SFRAME_F_FRAME_POINTER
> @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
>
> +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.
>
> @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
> 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,
> 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
> -vicinity with the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset} 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
> -in the future. The @code{sframe_header} structure provides an unsigned 8-bit
> -integral field to denote the size of an auxiliary SFrame header. The
> -auxiliary SFrame header follows right after the @code{sframe_header}
> -structure. As for the offset calculations, the @emph{end} of SFrame header
> -must be the end of the auxiliary SFrame header, if the latter is present.
> +of the return address is @code{CFA - 8}. Since these offsets are expected to
> +be in close vicinity to the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset}
> +and @code{sfh_cfa_fixed_ra_offset} are limited to signed 8-bit integers.
> +
> +@cindex Provisions for future ABIs
> +The SFrame format has made some provisions for supporting more
> +ABIs/architectures in the future. One of them is the concept of the auxiliary
> +SFrame header. Bytes in the auxiliary SFrame header may be used to convey
> +further ABI-specific information. The @code{sframe_header} structure provides
> +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:
>
> -@multitable {Offset} {@code{int8_t sfh_cfa_fixed_fp_offset}} {The number of SFrame FREs in the section.}
> -@headitem Offset @tab Name @tab Description
> +@multitable {Offset} {@code{uint32_t}} {@code{sfh_cfa_fixed_fp_offset}} {The number of SFrame FREs in the}
> +@headitem Offset @tab Type @tab Name @tab Description
> @item 0x00
> -@tab @code{sframe_preamble sfh_preamble}
> +@tab @code{sframe_ @* preamble}
> +@tab @code{sfh_preamble}
> @tab The SFrame preamble. @xref{SFrame Preamble}.
>
> @item 0x04
> -@tab @code{uint8_t sfh_abi_arch}
> -@tab The ABI/arch identifier. @xref{SFrame ABI/arch identifier}.
> +@tab @code{uint8_t}
> +@tab @code{sfh_abi_arch}
> +@tab The ABI/arch identifier. @xref{SFrame ABI/arch Identifier}.
>
> @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.
>
> @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.
>
> @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
> @code{sframe_header} structure.
>
> @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.
>
> -@item 0xc
> -@tab @code{uint32_t sfh_num_fres}
> +@item 0x0c
> +@tab @code{uint32_t}
> +@tab @code{sfh_num_fres}
> @tab The number of SFrame FREs in the section.
>
> @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.
>
> @item 0x14
> -@tab @code{uint32_t sfh_fdeoff}
> -@tab The offset in bytes of the SFrame FDE sub-section. This sub-section
> -contains @code{sfh_num_fdes} number of fixed-length array elements. The array
> -element is of type SFrame function desciptor entry, each providing a
> -high-level function description for backtracing.
> -@xref{SFrame Function Descriptor Entries}.
> +@tab @code{uint32_t}
> +@tab @code{sfh_fdeoff}
> +@tab The offset in bytes to the SFrame FDE sub-section.
>
> @item 0x18
> -@tab @code{uint32_t sfh_freoff}
> -@tab The offset in bytes of the SFrame FRE sub-section, the core of the SFrame
> -section, which describes the stack trace information using variable-length array
> -elements. @xref{SFrame Frame Row Entries}.
> +@tab @code{uint32_t}
> +@tab @code{sfh_freoff}
> +@tab The offset in bytes to the SFrame FRE sub-section.
>
> @end multitable
>
> @menu
> -* SFrame ABI/arch identifier::
> +* SFrame ABI/arch Identifier::
> @end menu
>
> -@node SFrame ABI/arch identifier
> -@subsection SFrame ABI/arch identifier
> -@cindex SFrame ABI/arch identifier
> +@node SFrame ABI/arch Identifier
> +@subsection SFrame ABI/arch Identifier
> +@cindex SFrame ABI/arch Identifier
>
> SFrame header identifies the ABI/arch of the target system for which the
> 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
> @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
> is a packed structure which contains information to describe a function's stack
> 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
> 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
> 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
> -@emph{end} of the SFrame header).
> +sub-section (unlike the sub-section offsets in the SFrame header, which are
> +relative to the @emph{end} of the SFrame header).
> +
> +@code{sfde_func_info} is the SFrame FDE "info word", containing information on
> +the FRE type and the FDE type for the function @xref{The SFrame FDE Info Word}.
>
> -@code{sfde_func_info} is the "info word", containing information on 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:
>
> -@multitable {Offset} {@code{uint32_t sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the}
> -@headitem Offset @tab Name @tab Description
> +@multitable {Offset} {@code{uint32_t}} {@code{sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the}
> +@headitem Offset @tab Type @tab Name @tab Description
> @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
> described function.
>
> @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
> bytes.
>
> @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
> function's first SFrame FRE in the SFrame section.
>
> @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
> used for the function.
>
> @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.
> -@xref{The SFrame FDE info word}.
> +@xref{The SFrame FDE Info Word}.
>
> @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
> 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.
>
> @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.
>
> @end multitable
>
> @menu
> -* The SFrame FDE info word::
> -* The SFrame FDE types::
> -* The SFrame FRE types::
> +* The SFrame FDE Info Word::
> +* The SFrame FDE Types::
> +* The SFrame FRE Types::
> @end menu
>
> -@cindex The SFrame FDE info word
> -@node The SFrame FDE info word
> -@subsection The SFrame FDE info word
> +@cindex The SFrame FDE Info Word
> +@node 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:
>
> @@ -464,31 +514,32 @@ The info word is a bitfield split into three parts. From MSB to LSB:
>
> @item 5
> @tab @code{pauth_key}
> -@tab Specify which key is used for signing the return addresses in the SFrame
> -FDE. Two possible values: @*
> +@tab (For AARCH64) Specify which key is used for signing the return addresses
> +in the SFrame FDE. Two possible values: @*
> SFRAME_AARCH64_PAUTH_KEY_A (0), or @*
> -SFRAME_AARCH64_PAUTH_KEY_B (1).
> +SFRAME_AARCH64_PAUTH_KEY_B (1). @*
> +Ununsed in AMD64.
>
> @item 4
> @tab @code{fdetype}
> @tab Specify the SFrame FDE type. Two possible values: @*
> SFRAME_FDE_TYPE_PCMASK (1), or @*
> SFRAME_FDE_TYPE_PCINC (0). @*
> -@xref{The SFrame FDE types}.
> +@xref{The SFrame FDE Types}.
>
> @item 0--3
> @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
>
> -@node The SFrame FDE types
> -@subsection The SFrame FDE types
> +@node The SFrame FDE Types
> +@subsection The SFrame FDE Types
> @tindex SFRAME_FDE_TYPE_PCMASK
> @tindex SFRAME_FDE_TYPE_PCINC
>
> -SFrame format defines two types of FDE entries. The choice of which SFrame FDE
> -type to use is made based on the instruction patterns in the relevant program
> -stub.
> +The SFrame format defines two types of FDE entries. The choice of which SFrame
> +FDE type to use is made based on the instruction patterns in the relevant
> +program stub.
>
> 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
> @@ -505,30 +556,31 @@ entries and trampolines.
> @headitem Name of SFrame FDE type @tab Value @tab Description
>
> @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.
>
> @item SFRAME_FDE_TYPE_PCMASK
> -@tab 1 @tab Unwinders perform a @*
> +@tab 1 @tab Stacktracers perform a @*
> (PC % REP_BLOCK_SIZE @*
> >= FRE_START_ADDR)
> 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
>
> -@node The SFrame FRE types
> -@subsection The SFrame FRE types
> +@node The SFrame FRE Types
> +@subsection The SFrame FRE Types
>
> 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
> -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
> -FRE.
> +format defines three types of SFrame FRE entries to effeciently encode the
> +stack trace 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 FRE.
>
> 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
>
> @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.
> @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
> -@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
> @section 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.
>
> -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
> -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:
>
> @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
> 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:
>
> @@ -633,12 +686,12 @@ address of the function.
> Further FRE types may be added in future.
>
> @menu
> -* The SFrame FRE info word::
> +* The SFrame FRE Info Word::
> @end menu
>
> -@cindex The SFrame FRE info word
> -@node The SFrame FRE info word
> -@subsection The SFrame FRE info word
> +@cindex The SFrame FRE Info Word
> +@node 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:
>
More information about the Binutils
mailing list