[PATCH, V2] doc: sframe: small improvements for readability
Indu Bhagat
indu.bhagat@oracle.com
Fri Jun 21 15:00:38 GMT 2024
On 6/21/24 00:44, Jens Remus wrote:
> Hello Indu!
>
>
> Am 21.06.2024 um 08:50 schrieb Indu Bhagat:
>> 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.
>
> Thank you!
>
>>
>> libsframe/
>> * doc/sframe-spec.texi: Small improvements for readability.
>> ---
>> [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 | 296 +++++++++++++++++++--------------
>> 1 file changed, 174 insertions(+), 122 deletions(-)
>>
>> diff --git a/libsframe/doc/sframe-spec.texi
>> b/libsframe/doc/sframe-spec.texi
>> index d0f99bd698e..e4509a351c0 100644
>> --- a/libsframe/doc/sframe-spec.texi
>> +++ b/libsframe/doc/sframe-spec.texi
>> @@ -34,8 +34,8 @@ 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
>> -information needed for generating stack traces:
>> +Simple Frame. SFrame format keeps track of the minimal necessary
>> information
>
> "The SFrame format keeps ..."?
>
Thanks. Updated all occurrences.
>> +needed for generating stack traces:
>> @itemize @minus
>> @item
>> @@ -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,23 +110,27 @@ 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
>> +two other sub-sections, namely the SFrame function descriptor entry
>> (SFrame
>> FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE)
>> sub-section.
>
> Since you changed "SFrame function descriptor entry" to lower case maybe
> akso do so for "SFrame Frame Row Entry"?
>
Yes. Updated all occurrences of "Frame Row Entry" as well.
>> @menu
>> @@ -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.
>
> I was not aware of the SFRAME_F_FRAME_POINTER flag before. It appears it
> is not set at the moment by the assembler. Is the idea to set it if code
> is compiled with -fno-omit-frame-pointer (and
> -mno-omit-leaf-frame-pointer on aarch64 and x86_64)? Any idea how to
> transfort this from the compiler to the assembler?
>
Yes, your understanding is correct.
Frankly, I have not explored how to have compiler convey this
information yet. An additional (global) CFI directive could be one, but
it remains to be explored and discussed.
>> +
>> Further flags may be added in future.
>> @node SFrame Header
>> @@ -272,79 +281,99 @@ 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.
>> +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
>> 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.
>> +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 +404,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
>
> Capital or lower case?
>
Lower case. Updated all occurrences.
Thanks for reviewing,
Indu
More information about the Binutils
mailing list