[V3] doc: sframe: small improvements for readability

  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.
---
[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(-)
  

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:
>