The SFrame format

1.1 Overview

The SFrame stack trace information is provided in a loaded section, known as the .sframe section. When available, the .sframe section appears in 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 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 rest of this specification describes the current version of the format, 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 libsframe, is not accompanied here at this time. This will be added later.

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 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_TYPE_PCMASK.
• 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.

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 things 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 a subsequent section. See SFrame FDE.

Next, the SFrame FRE sub-section, starting at offset sfh_fre_off, describes the stack trace information for each function, using a total of 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

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 sfde_func_start_address if the SFrame section header flag sfp_flags has SFRAME_F_FDE_SORTED set. Typically (as is the case with GNU ld) a linked object or executable will have the 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.

typedef struct sframe_func_desc_entry
{
  int32_t sfde_func_start_address;
  uint32_t sfde_func_size;
  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;

Every element of the SFrame function descriptor entry is naturally aligned.

sfde_func_start_fre_off is the offset to the first SFrame FRE for the function. This offset is relative to the end of the SFrame FDE sub-section (unlike the sub-section offsets in the SFrame header, which are relative to the end of the SFrame header).

sfde_func_info is the SFrame FDE "info word", containing information on the FRE type and the FDE type for the function See The SFrame FDE Info Word.

Apart from the sfde_func_padding2, the SFrame FDE has some currently unused bits in the SFrame FDE info word, See 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:

• The SFrame FDE Info Word
• The SFrame FDE Types
• The SFrame FRE Types

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 stack offsets to recover the CFA, FP and RA (where applicable) for the respective instruction addresses. To encode this information, each SFrame FRE is followed by S*N bytes, where:

• S is the size of a stack offset for the FRE, and
• N is the number of stack offsets in the FRE

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

It is important to underline here that although the canonical interpretation of these bytes is as stack offsets (to recover CFA, FP and RA), 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 number of stack offsets at the tail end of each SFrame FRE. To keep the SFrame file format specification flexible yet extensible, the interpretation of the stack offsets is ABI/arch-specific. The precise interpretation of the FRE stack offsets in the currently supported ABIs/architectures is covered in the ABI/arch-specific definition of the SFrame file format, See ABI/arch-specific Definition.

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 identifies the start address of the 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 start address of the SFrame FRE, from the start address of the function.

Further SFrame FRE types may be added in future.

• The SFrame FRE Info Word

3.1 AMD64

Irrespective of the ABI, the first stack offset is always used to locate the CFA, by interpreting it as: CFA = BASE_REG + offset1. The identification of the BASE_REG is done by using the fre_cfa_base_reg_id field in the SFrame FRE info word.

In AMD64, the return address (RA) is always saved on stack when a function call is executed. Further, AMD64 ABI mandates that the RA be saved at a fixed offset from the CFA when entering a new function. This means that the RA does not need to be tracked per SFrame FRE. The fixed offset is encoded in the SFrame file format in the field sfh_cfa_fixed_ra_offset in the SFrame header. See SFrame Header.

Hence, the second stack offset (in the SFrame FRE), when present, will be used to locate the FP, by interpreting it as: FP = CFA + offset2.

Hence, in summary:

3.2 AArch64

Irrespective of the ABI, the first stack offset is always used to locate the CFA, by interpreting it as: CFA = BASE_REG + offset1. The identification of the BASE_REG is done by using the fre_cfa_base_reg_id field in the SFrame FRE info word.

In AARCH64, the AAPCS64 standard specifies that the Frame Record saves both FP and LR (a.k.a the RA). However, the standard does not mandate the precise location in the function where the frame record is created, if at all. Hence the need to track RA in the SFrame stack trace format. As RA is being tracked in this ABI, the second stack offset is always used to locate the RA, by interpreting it as: RA = CFA + offset2. The third stack offset will be used to locate the FP, by interpreting it as: FP = CFA + offset3.

Given the nature of things, the number of stack offsets seen on AARCH64 per SFrame FRE is either 1 or 3.

Hence, in summary: