1.1 SFrame Preamble

The preamble is a 32-bit packed structure; the only part of the SFrame 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;

All values are stored in the endianness of the target system for which the SFrame section is intended. Further details:

• SFrame endianness
• SFrame version
• SFrame flags

1.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;

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.

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 this offset is in close vicinity with the CFA in most ABIs, sfh_cfa_fixed_fp_offset and sfh_cfa_fixed_ra_offset are limited to signed 8-bit integers.

SFrame format has provisioned for future ABIs/architectures that it may support. The sframe_header structure provides an unsigned 8-bit integral field to denote the size of an auxilliary SFrame header. The auxilliary SFrame header follows right after the sframe_header structure. As for the offset calculations, the end of SFrame header must be the end of the auxilliary SFrame header, if the latter is present.

Tieing it all together:

• SFrame ABI/arch identifier

1.3 SFrame FDE

The SFrame Function Descriptor Entry sub-section is a sorted array of fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE is a packed structure which contains information to describe a function’s unwind information at a high-level.

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;
} ATTRIBUTE_PACKED sframe_func_desc_entry;

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 offsets in the SFrame header, which are relative to the end of the SFrame header).

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

Following table describes each component of the SFrame FDE structure:

• The SFrame FDE info word
• The SFrame FDE types
• The SFrame FRE types

1.4 SFrame FRE

The SFrame Frame Row Entry sub-section contains the core of the unwind information.

An SFrame Frame Row Entry is a self-sufficient record containing SFrame unwind info for a range of contiguous addresses, starting at the specified offset from the start of the function. Each SFrame Frame Row Entry is followed by S*N bytes, where:

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

The stack offsets, following the FRE, are interpreted in order as follows:

• - The first offset is always used to locate the CFA, by interpreting it as: CFA = BASE_REG + offset1.
• - If RA is being tracked, the second offset is always used to locate the RA, by interpreting it as: RA = CFA + offset2. If RA is not being tracked and FP is being tracked, the second offset will be used to locate the FP, by interpreting it as: FP = CFA + offset2.
• - If both RA and FP are being tracked, the third offset will be used to locate the FP, by interpreting it as FP = CFA + offset3.

The entities S, N and BASE_REG are identified using the SFrame FRE info word, a.k.a. the sframe_fre_info See The SFrame FRE info word.

Following are the definitions of the allowed SFrame FRE:

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;

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 FRE types may be added in future.

• The SFrame FRE info word