The SFrame format ¶

1.1 Overview ¶

The SFrame stack trace information is provided in a loaded section, named .sframe. When available, the .sframe section appears in segment of type PT_GNU_SFRAME. An ELF SFrame section will have the type SHT_GNU_SFRAME.

The SFrame format is currently supported only for select ABIs, namely, AMD64, AAPCS64, and s390x.

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 index) 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 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.

Addresses in this specification are expressed in bytes. The use of term ‘data word’ in this document is colloquial; it should not be understood to correlate with the architectural machine word or any specific hardware data width.

The rest of this specification describes the current version of the format, SFRAME_VERSION_3, in detail. Additional sections outline the major changes made to each previously published version of the SFrame stack trace format.

This document is intended to be in sync with the C code in sframe.h. Please report discrepancies between the two, if any.

1.2 Changes from Version 2 to Version 3 ¶

The following is a list of the changes made to the SFrame stack trace format since Version 2 was published. Note that SFrame Version 2 had up to two Errata.

• Terminology improvements and renames for readability
  • Use the terminology ‘PC offset’ in place of ‘Addr’ for function start PC offset consistently.
  • Make a distinction between SFrame FDE Type (e.g., SFRAME_FDE_TYPE_DEFAULT, SFRAME_FDE_TYPE_FLEX) vs SFrame FDE PC Type (i.e., SFRAME_FDE_PCTYPE_MASK, SFRAME_FDE_PCTYPE_INC).
  • Instead of using the term ‘info word’, use a more precise term ‘info byte’ in specification for the info bytes in SFrame FDE and SFrame FRE.
  • Use term ‘data word’ instead of ‘offset’ to convey the functional role of the variable-length array of bytes trailing the SFrame FRE header. With the introduction of flexible FDE type, the interpretation of those bytes is not always as an offset.
  • Rename SFRAME_FRE_OFFSET_<N>B to SFRAME_FRE_DATAWORD_<N>B.
• Reorganize the SFrame function descriptor entry into two distinct structures:
  • SFrame function descriptor index
  • SFrame function descriptor attribute

  Rename structure members as a consequence.

• Narrow the width of sfda_func_num_fres to uint16_t and remove padding field sfde_func_padding2.
• Increase the width of the sfdi_func_start_offset to int64_t. This field is renamed from the sfde_func_start_address in SFrame Version 2 specification.
• Signal frames are marked with one bit in sfda_func_info.
• Addition of a new function info byte sfda_func_info2 in SFrame function descriptor attribute structure to store additional information about the stack trace data for the function.
• Reserve 5-bits for FDE types. Define two FDE types: default FDE type SFRAME_FDE_TYPE_DEFAULT, and flexible FDE type SFRAME_FDE_TYPE_FLEX.
• Define a new FDE type SFRAME_FDE_TYPE_FLEX to convey stack trace information for specific cases, e.g., when CFA is non-SP/FP based, or when FP/RA recovery is REG-based.
• An SFrame FDE of type SFRAME_FDE_TYPE_DEFAULT with no FREs is used to indicate an outermost frame.
• On s390x, use FDE type SFRAME_FDE_TYPE_FLEX to encode FP/RA recovery from REG, instead of encoding DWARF register number in the SFrame FRE variable-length data of FDE type SFRAME_FDE_TYPE_DEFAULT.

1.3 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.

• 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_PCTYPE_MASK.
• 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.
• 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.
• [Errata 1] Add a new flag SFRAME_F_FDE_FUNC_START_PCREL, as an erratum to SFrame Version 2, to indicate the encoding of the SFrame FDE function start address field:
  • if set, sfde_func_start_offset field contains the offset in bytes to the start PC of the associated function from the field itself.
  • if unset, sfde_func_start_offset field contains the offset in bytes to the start PC of the associated function from the start of the SFrame section.
• [Errata 1] Add a new ABI/arch identifier SFRAME_ABI_S390X_ENDIAN_BIG for the s390 architecture (64-bit) s390x ABI. Other s390x-specific backward compatible changes including the following helper definitions have been incrementally added to SFrame Version 2 only:
  • SFRAME_S390X_SP_VAL_OFFSET: SP value offset from CFA.
  • SFRAME_V2_S390X_OFFSET_IS_REGNUM: Test whether FP/RA offset is an encoded DWARF register number.
  • SFRAME_V2_S390X_OFFSET_ENCODE_REGNUM: Encode a DWARF register number as an FP/RA offset.
  • SFRAME_V2_S390X_OFFSET_DECODE_REGNUM: Decode a DWARF register number from an FP/RA offset.
  • SFRAME_FRE_RA_OFFSET_INVALID: Invalid RA offset value (like SFRAME_CFA_FIXED_RA_INVALID). Used on s390x as padding offset to represent FP without RA saved.
  • SFRAME_S390X_CFA_OFFSET_ADJUSTMENT: CFA offset (from CFA base register) adjustment value. Used to enable use of 8-bit SFrame offsets on s390x.
  • SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR: CFA offset alignment factor. Used to scale down the CFA offset to improve the use of 8-bit SFrame offsets.
  • SFRAME_V2_S390X_CFA_OFFSET_ENCODE: Encode CFA offset (i.e., apply CFA offset adjustment and then scale down by CFA offset alignment factor).
  • SFRAME_V2_S390X_CFA_OFFSET_DECODE: Decode CFA offset (i.e., scale up by CFA offset alignment factor and then revert CFA offset adjustment).
• [Errata 1] An ELF SFrame section has the type SHT_GNU_SFRAME.
• [Errata 2] An offset count of zero in the SFrame FRE info byte indicates that the return address (RA) is undefined for the range of PCs covered by the SFrame FRE. A stack tracer may use this as indication that an outermost frame has been reached and the stack trace is complete.

SFrame Version 1 is now obsolete and should not be used.

2.1 SFrame Preamble ¶

The preamble is a 32-bit packed structure; the only part of the SFrame section whose format cannot vary between versions.

typedef struct sframe_preamble
{
  uint16_t sfp_magic;
  uint8_t sfp_version;
  uint8_t sfp_flags;
} ATTRIBUTE_PACKED sframe_preamble;

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:

• SFrame Magic Number and Endianness
• SFrame Version
• SFrame Flags

2.2 SFrame Header ¶

The SFrame header is the first part of an SFrame section. It begins with the SFrame preamble. All parts of it other than the preamble (see SFrame Preamble) can vary between SFrame file versions. It contains metadata that apply to the section as a whole, and offsets to the various other sub-sections defined in the format. As with the rest of the SFrame section, all values are stored in the endianness of the target system.

The two sub-sections tile the SFrame section: each section runs from the offset given until the start of the next section. An explicit length is given for the last sub-section, the SFrame Frame Row Entry (SFrame FRE) sub-section.

typedef struct sframe_header
{
  sframe_preamble sfh_preamble;
  uint8_t sfh_abi_arch;
  int8_t sfh_cfa_fixed_fp_offset;
  int8_t sfh_cfa_fixed_ra_offset;
  uint8_t sfh_auxhdr_len;
  uint32_t sfh_num_fdes;
  uint32_t sfh_num_fres;
  uint32_t sfh_fre_len;
  uint32_t sfh_fdeoff;
  uint32_t sfh_freoff;
} ATTRIBUTE_PACKED sframe_header;

Every element of the SFrame header is naturally aligned.

The sub-section offsets, namely sfh_fdeoff and sfh_freoff, in the SFrame header are relative to the 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 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 SFrame FDE.

Next, the SFrame FRE sub-section, starting at offset sfh_fre_off, describes the stack trace information for each function. For each function, the SFrame FRE sub-section contains the SFrame FDE attribute data and sfh_num_fres number of variable-length array elements. Each array element is of type SFrame frame row entry. See SFrame FRE.

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 CFA - 8. Since these offsets are expected to be in close vicinity to the CFA in most ABIs, sfh_cfa_fixed_fp_offset and sfh_cfa_fixed_ra_offset are limited to signed 8-bit integers.

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 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 sframe_header structure. As for the calculation of the sub-section offsets, namely sfh_fdeoff and sfh_freoff, the end of SFrame header must be the end of the auxiliary SFrame header, if the latter is present.

Putting it all together:

• SFrame ABI/arch Identifier

2.3 SFrame FDE ¶

SFrame function descriptor entry is a conceptual entity which contains the function-level metadata necessary for stack tracing through the function. It is composed of two physical entities: the SFrame function descriptor index (SFrame FDE index) and the SFrame function descriptor attribute (SFrame FDE attribute). Both SFrame FDE index and SFrame FDE attribute are fixed-length structures, albeit with different alignment guarantees.

• The SFrame FDE Index
• The SFrame FDE Attribute
• The SFrame FDE Info Bytes

typedef struct sframe_func_desc_idx
{
  int64_t sfdi_func_start_offset;
  uint32_t sfdi_func_size;
  uint32_t sfdi_func_start_fre_off;
} ATTRIBUTE_PACKED sframe_func_desc_idx;

typedef struct sframe_func_desc_attr
{
  uint16_t sfda_func_num_fres;
  uint8_t sfda_func_info;
  uint8_t sfda_func_info2;
  uint8_t sfda_func_rep_size;
} ATTRIBUTE_PACKED sframe_func_desc_attr;

2.4 SFrame FRE ¶

The SFrame frame row entry sub-section contains the core of the stack trace information. An SFrame frame row entry (FRE) is a self-sufficient record containing SFrame stack trace information for a range of contiguous (instruction) addresses, starting at the specified offset from the start of the function.

Each SFrame FRE encodes the information to recover the CFA, FP and RA (as specified by the ABI or the FDE type) for the respective instruction addresses. To encode this information, each SFrame FRE is followed by S*N bytes, where:

• S is the size of each data word in the variable-length array of data words trailing the SFrame FRE, and
• N is the number of data words trailing the SFrame FRE.

NB: The term ‘data word’ is used throughout this specification in a colloquial sense to denote a discrete unit of information within an SFrame Frame Row Entry (FRE). It is intended to describe the semantic role of the data rather than its physical size. Consequently, ‘data word’ should not be understood to correlate with the architectural machine word size or any specific hardware data width; the actual size of a data word in the SFrame format is variable and is defined in the SFrame FRE info byte.

The entities S, N are encoded in the SFrame FRE info byte, via the fre_dataword_size and the fre_dataword_count respectively. More information about the precise encoding and range of values for S and N is provided later in the The SFrame FRE Info Word.

It is important to underline here that although the canonical interpretation of these data words is as stack offsets (to recover CFA, FP and RA) for default FDE type, these bytes may be used by future ABIs/architectures to convey other information on a per SFrame FRE basis.

In summary, SFrame file format, by design, supports a variable length array of bytes at the tail end of each SFrame FRE. To keep the SFrame file format specification flexible yet extensible, the interpretation of these bytes is specific to ABI/arch or FDE type. More details about the precise interpretation are covered in the section Interpretation of SFrame FREs.

Next, the definitions of the three SFrame FRE types are as follows:

typedef struct sframe_frame_row_entry_addr1
{
  uint8_t sfre_start_address;
  sframe_fre_info sfre_info;
} ATTRIBUTE_PACKED sframe_frame_row_entry_addr1;

typedef struct sframe_frame_row_entry_addr2
{
  uint16_t sfre_start_address;
  sframe_fre_info sfre_info;
} ATTRIBUTE_PACKED sframe_frame_row_entry_addr2;

typedef struct sframe_frame_row_entry_addr4
{
  uint32_t sfre_start_address;
  sframe_fre_info sfre_info;
} ATTRIBUTE_PACKED sframe_frame_row_entry_addr4;

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.

sfre_start_address is an unsigned 8-bit/16-bit/32-bit integral field denoting the start address of a range of program counters, for which the SFrame FRE applies. The value encoded in the sfre_start_address field is the offset in bytes of the range’s start address, from the start address of the function.

Further SFrame FRE types may be added in future.

• The SFrame FRE Info Word

3.1 Default FDE Type Interpretation ¶

If the FDE type is SFRAME_FDE_TYPE_DEFAULT, the interpretation of the FRE bytes is ABI/arch-specific. Typically, these bytes are interpreted as a sequence of (signed integer) stack offsets.

The following sections describe the specific interpretation rules for currently supported architectures.

• AMD64
• AArch64
• s390x

3.2 Flexible FDE Type Interpretation ¶

Flexible FDEs (SFRAME_FDE_TYPE_FLEX) are used in cases where the most common default recovery rules implied by SFRAME_FDE_TYPE_DEFAULT are insufficient. Common use cases include:

• DRAP (Dynamically Realigned Argument Pointer): Where the CFA is based on a register other than SP or FP, or requires dereferencing.
• Stack Realignment: Where strict alignment requirements (e.g., AVX512) force dynamic stack adjustments.
• Register-based RA/FP Locations: Where the Return Address or Frame Pointer is transiently saved in a general-purpose register and/or requires a dereference rule.

For flexible FDE types, the variable-length bytes trailing an SFrame FRE can be interpreted as one of the following:

1. Control Data: Encodes the base register number, a dereference flag, and a register-mode flag. A value of 0 is reserved as the padding data word.
2. Offset Data: Encodes the signed offset to be added to the base.

For each tracked entity (CFA, RA, FP), the SFrame FRE carries a pair of data words to specify the respective recovery rule. The pair of data words appear in the order: CFA, RA, FP. These data words obey the fre_dataword_size defined in the FRE info byte (i.e., they are 1, 2, or 4 bytes wide).

Given the nature of things, since CFA is always tracked, the first two data words pertain to CFA recovery. If RA recovery rule is unspecified (because the RA can be recovered from its default location), a single padding data word is used instead of the pair of Control data word and Offset data word if FP recovery rule is to be specified using the subsequent data words.

Following is the order of information for specifying the recovery rule for a tracked entity in a flexible FDE.

Encoding of Data Word 1 (Control Data) ¶

The first data word of the pair is an unsigned integer of size fre_dataword_size. It is used as a bitfield that describes register/control data for the tracked entity. From LSB to MSB:

A value of 0 (i.e., regnum = 0, deref_p = 0, reg_p = 0) in the Control Data Word is used to indicate that no further data words follow for the tracked entity. This is to convey an absence of recovery rule for the respective tracked entity (which means that fixed offsets sfh_cfa_fixed_fp_offset or sfh_cfa_fixed_ra_offset apply if used for the ABI/arch). Note that, using a value of 0 as padding data word, does mean that currently, e.g., for RA, the rule RA = CFA + 0 cannot be encoded. NB: RA = CFA + 0 is distinct from RA = *(CFA + 0). The former should not be needed for any ABI, and the latter is representable (regnum = 0, deref_p = 1, reg_p = 0).

Encoding of Data Word 2 (Offset Data) ¶

The second data word of the pair is a signed integer of width fre_dataword_size. It is used as a offset for the respective tracked entity (CFA, FP or RA).

Recovery Rules ¶

The value of the tracked entity (CFA, RA, or FP) is calculated using the following logic:

    Base   = (reg_p == 1) ? Register[regnum] : CFA;
    Addr   = Base + Offset2;
    Value  = (deref_p == 1) ? *Addr : Addr;

Examples:

• CFA = *(RBP - 8): (Typical DRAP pattern on AMD64)
  Data Word 1: (RBP << 3) | (1 << 1) | 1 (Reg RBP, deref_p=True, reg_p=True)
  Data Word 2: -8
• FP = *(RBP + 0):
  Data Word 1: (RBP << 3) | (1 << 1) | 1 (Reg RBP, deref_p=True, reg_p=True)
  Data Word 2: 0
• RA = *(CFA - 8): (Standard RA recovery on AMD64)
  Data Word 1: (0 << 3 | (1 << 1) | 0) (reg_p=False, implies Base=CFA, deref_p=True by implication of standard stack save)
  Data Word 2: -8

If the FDE type is SFRAME_FDE_TYPE_FLEX, the FRE bytes are interpreted using a universal encoding scheme designed to handle complex recovery rules (such as DRAP or non-standard RA locations).