mirror/binutils-gdb
2
0
Fork 0
mirror of https://sourceware.org/git/binutils-gdb.git synced 2025-01-30 12:44:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

doc: sframe: update specification for SFRAME_VERSION_2

Browse Source 
Add details for the changes made from Version 1 to Version 2 of the format.

Also add details about alignment in the SFrame format.  A portion of the
SFrame stack trace format has an unaligned on-disk representation.  Add
description at relevant points in the specificatin to clarify the
alignment related details.
This commit is contained in:
Indu Bhagat 2023-06-29 16:29:12 -07:00
parent ce9a87252c
commit a5cddf7b64
1 changed files with 74 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -20,7 +20,7 @@ License''.
@titlepage
@title The SFrame Format
@subtitle Version 1
@subtitle Version 2
@author Indu Bhagat
@page
@ -33,7 +33,7 @@ License''.
@node Top
@top The SFrame format
This manual describes version 1 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
information needed for generating stack traces:
@ -50,17 +50,25 @@ The reason for existence of the SFrame format is to provide a simple, fast and
low-overhead mechanism to generate stack traces.
@menu
* Overview::
* Introduction::
* SFrame section::
* Index::
@end menu
@end ifnottex
@node Introduction
@chapter Introduction
@cindex Introduction
@menu
* Overview::
* Changes from Version 1 to Version 2::
@end menu
@node Overview
@unnumbered Overview
@section Overview
@cindex Overview
@tindex PT_GNU_SFRAME
The SFrame stack trace information is provided in a loaded section, known as the
@code{.sframe} section. When available, the @code{.sframe} section appears in
@ -69,6 +77,11 @@ a new segment of its own, PT_GNU_SFRAME.
The SFrame format is currently supported only for select ABIs, namely, AMD64
and AAPCS64.
A portion of the SFrame format follows an unaligned on-disk representation.
Some data structures, however, (namely the SFrame header and the SFrame
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.
An SFrame section reader may use the magic number in the SFrame header to
@ -76,6 +89,11 @@ identify the endianness of the SFrame section.
Addresses in this specification are expressed in bytes.
The rest of this specification describes the current version of the format,
@code{SFRAME_VERSION_2}, in detail. Additional sections outline the major
changes made to each previously published version of the SFrame stack trace
format.
The associated API to decode, probe and encode the SFrame section, provided via
@code{libsframe}, is not accompanied here at this time. This will be added
later.
@ -83,6 +101,26 @@ later.
This document is intended to be in sync with the C code in @file{sframe.h}.
Please report discrepancies between the two, if any.
@node Changes from Version 1 to Version 2
@section Changes from Version 1 to Version 2
@cindex Changes from Version 1 to Version 2
The following is a list of the changes made to the SFrame stack trace format
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.
@item
SFrame Function Descriptor Entry includes an explicit padding of two bytes to
ensure natural alignment for its data members.
@item
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
@ -114,6 +152,8 @@ typedef struct sframe_preamble
@} ATTRIBUTE_PACKED sframe_preamble;
@end example
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:
@ -160,13 +200,15 @@ The version of the SFrame format can be determined by inspecting
@tindex SFRAME_VERSION_1
@cindex SFrame versions
@multitable {SFRAME_VERSION_1} {Number} {First version, under development.}
@multitable {SFRAME_VERSION_2} {Number} {Current version, under development.}
@headitem Version @tab Number @tab Description
@item @code{SFRAME_VERSION_1}
@tab 1 @tab First version, under development.
@tab 1 @tab First version, obsolete.
@item @code{SFRAME_VERSION_2}
@tab 2 @tab Current version, under development.
@end multitable
This section documents @code{SFRAME_VERSION_1}.
This document describes @code{SFRAME_VERSION_2}.
@node SFrame flags
@subsection SFrame flags
@ -223,6 +265,8 @@ typedef struct sframe_header
@} ATTRIBUTE_PACKED sframe_header;
@end example
Every element of the SFrame header is naturally aligned.
The sub-section offsets, namely @code{sfh_fdeoff} and @code{sfh_freoff}, in the
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
@ -344,9 +388,13 @@ typedef struct sframe_func_desc_entry
uint32_t sfde_func_start_fre_off;
uint32_t sfde_func_num_fres;
uint8_t sfde_func_info;
uint8_t sfde_func_rep_size;
uint16_t sfde_func_padding2;
@} ATTRIBUTE_PACKED sframe_func_desc_entry;
@end example
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
@ -357,7 +405,7 @@ type and the FDE type for the function @xref{The SFrame FDE info word}.
Following table describes each component of the SFrame FDE structure:
@multitable {Offset} {@code{uint32_t sfde_func_start_fre_off}} {The ABI/arch identifier. See above}
@multitable {Offset} {@code{uint32_t sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the}
@headitem Offset @tab Name @tab Description
@item 0x00
@tab @code{int32_t sfde_func_start_address}
@ -381,7 +429,18 @@ used for the function.
@item 0x10
@tab @code{uint8_t sfde_func_info}
@tab The SFrame FDE info word. @xref{The SFrame FDE info word}.
@tab Unsigned 8-bit integral field specifying the SFrame FDE info word.
@xref{The SFrame FDE info word}.
@item 0x11
@tab @code{uint8_t 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 Padding of 2 bytes. Currently unused bytes.
@end multitable
@ -560,6 +619,11 @@ typedef struct sframe_frame_row_entry_addr4
@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr4;
@end example
For ensuring compactness, SFrame frame row entries are stored unaligned on
disk. Appropriate mechanisms need to be employed, as necessary, by the
serializing and deserializing entities, if unaligned accesses need to be
avoided.
@code{sfre_start_address} is an unsigned 8-bit/16-bit/32-bit integral field
identifies the start address of the range of program counters, for which the
SFrame FRE applies. The value encoded in the @code{sfre_start_address} field