head 1.2; access; symbols netbsd-11-0-RELEASE:1.1.1.1 netbsd-11-0-RC7:1.1.1.1 netbsd-11-0-RC6:1.1.1.1 netbsd-11-0-RC5:1.1.1.1 netbsd-11-0-RC4:1.1.1.1 netbsd-11-0-RC3:1.1.1.1 netbsd-11-0-RC2:1.1.1.1 binutils-2-46:1.1.1.3 netbsd-11-0-RC1:1.1.1.1 binutils-2-45:1.1.1.2 perseant-exfatfs-base-20250801:1.1.1.1 netbsd-11:1.1.1.1.0.2 netbsd-11-base:1.1.1.1 perseant-exfatfs-base-20240630:1.1.1.1 binutils-2-42:1.1.1.1 FSF:1.1.1; locks; strict; comment @# @; 1.2 date 2026.02.14.17.59.15; author christos; state Exp; branches; next 1.1; commitid SIU1PzzDnKtH5nuG; 1.1 date 2024.06.30.16.01.19; author christos; state Exp; branches 1.1.1.1; next ; commitid Eqxmo2uubpM9w1gF; 1.1.1.1 date 2024.06.30.16.01.19; author christos; state Exp; branches; next 1.1.1.2; commitid Eqxmo2uubpM9w1gF; 1.1.1.2 date 2025.08.25.14.43.36; author christos; state Exp; branches; next 1.1.1.3; commitid aUBKFf4jmEzPv78G; 1.1.1.3 date 2026.02.11.19.50.38; author christos; state Exp; branches; next ; commitid vybCSY05tblOMZtG; desc @@ 1.2 log @merge conflicts @ text @This is /usr/src/tools/binutils/../../external/gpl3/binutils/dist/libsframe/doc/sframe-spec.info, produced by makeinfo version 4.8 from /usr/src/tools/binutils/../../external/gpl3/binutils/dist/libsframe/doc/sframe-spec.texi. Copyright (C) 2021-2026 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3 or any later version published by the Free Software Foundation. A copy of the license is included in the section entitled "GNU General Public License". INFO-DIR-SECTION Software development START-INFO-DIR-ENTRY * SFrame: (sframe-spec). The Simple Frame format. END-INFO-DIR-ENTRY  File: sframe-spec.info, Node: Top, Next: Introduction, Up: (dir) The SFrame format ***************** 14 February 2026 This manual describes Version 3 of the SFrame file format. SFrame stands for Simple Frame. The SFrame format keeps track of the minimal necessary information needed for generating stack traces: - Canonical Frame Address (CFA). - Frame Pointer (FP). - Return Address (RA). The reason for existence of the SFrame format is to provide a simple, fast and low-overhead mechanism to generate stack traces. * Menu: * Introduction:: * SFrame Section:: * Interpretation of SFrame FREs:: Appendices * Generating Stack Traces using SFrame:: * Index::  File: sframe-spec.info, Node: Introduction, Next: SFrame Section, Prev: Top, Up: Top 1 Introduction ************** * Menu: * Overview:: * Changes from Version 2 to Version 3:: * Changes from Version 1 to Version 2::  File: sframe-spec.info, Node: Overview, Next: Changes from Version 2 to Version 3, Up: Introduction 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.  File: sframe-spec.info, Node: Changes from Version 2 to Version 3, Next: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction 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_B' to `SFRAME_FRE_DATAWORD_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'.  File: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Changes from Version 2 to Version 3, Up: Introduction 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.  File: sframe-spec.info, Node: SFrame Section, Next: Interpretation of SFrame FREs, Prev: Introduction, Up: Top 2 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 FDE) sub-section, and the SFrame frame row entry (SFrame FRE) sub-section. * Menu: * SFrame Preamble:: * SFrame Header:: * SFrame Function Descriptor Entries:: * SFrame Frame Row Entries::  File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame Section 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: Offset Type Name Description ------------------------------------------------------------------------------------- 0x00 `uint16_t' `sfp_magic' The magic number for SFrame section: 0xdee2. Defined as a macro `SFRAME_MAGIC'. 0x02 `uint8_t' `sfp_version' The version number of this SFrame section. *Note SFrame Version::, for the set of valid values. Current version is `SFRAME_VERSION_3'. 0x03 `uint8_t' `sfp_flags' Flags (section-wide) for this SFrame section. *Note SFrame Flags::, for the set of valid values. * Menu: * SFrame Magic Number and Endianness:: * SFrame Version:: * SFrame Flags::  File: sframe-spec.info, Node: SFrame Magic Number and Endianness, Next: SFrame Version, Up: SFrame Preamble 2.1.1 SFrame Magic Number and Endianness ---------------------------------------- SFrame sections are stored in the target endianness of the system that consumes them. A consumer library reading or writing SFrame sections should detect foreign-endianness by inspecting the SFrame magic number in the `sfp_magic' field in the SFrame header. It may then provide means to endian-flip the SFrame section as necessary.  File: sframe-spec.info, Node: SFrame Version, Next: SFrame Flags, Prev: SFrame Magic Number and Endianness, Up: SFrame Preamble 2.1.2 SFrame Version -------------------- The version of the SFrame format can be determined by inspecting `sfp_version'. The following versions are currently valid: Version Name Number Description ------------------------------------------------------------------ `SFRAME_VERSION_1' 1 First version, obsolete. `SFRAME_VERSION_2' 2 Second version. `SFRAME_VERSION_3' 3 Third version, under development. This document describes `SFRAME_VERSION_3'.  File: sframe-spec.info, Node: SFrame Flags, Prev: SFrame Version, Up: SFrame Preamble 2.1.3 SFrame Flags ------------------ The preamble contains bitflags in its `sfp_flags' field that describe various section-wide properties. The following flags are currently defined. Flag Version Value Meaning -------------------------------------------------------------------------------------- `SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries are sorted on PC. `SFRAME_F_FRAME_POINTER' 1-2 0x2 All functions in the object file preserve frame pointer. `SFRAME_F_FDE_FUNC_START_PCREL'2-3 0x4 The `sfdi_func_start_offset' field in the SFrame FDE is an offset in bytes to the function's start address, from the field itself. If unset, the `sfdi_func_start_offset' field in the SFrame FDE is an offset in bytes to the function's start address, from the start of the SFrame section. The purpose of `SFRAME_F_FRAME_POINTER' flag was 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. Further flags may be added in future. Bits corresponding to the currently undefined flags must be set to zero.  File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame Section 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 (*note 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 *Note SFrame Function Descriptor Entries::. 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. *Note 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 `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: Offset Type Name Description ------------------------------------------------------------------------------------- 0x00 `sframe_ `sfh_preamble' The SFrame preamble. *Note SFrame preamble' Preamble::. 0x04 `uint8_t' `sfh_abi_arch' The ABI/arch identifier. *Note SFrame ABI/arch Identifier::. 0x05 `int8_t' `sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. 0x06 `int8_t' `sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. 0x07 `uint8_t' `sfh_auxhdr_len' Size in bytes of the auxiliary header that follows the `sframe_header' structure. 0x08 `uint32_t' `sfh_num_fdes' The number of SFrame FDEs in the section. 0x0c `uint32_t' `sfh_num_fres' The number of SFrame FREs in the section. 0x10 `uint32_t' `sfh_fre_len' The length in bytes of the SFrame FRE sub-section. 0x14 `uint32_t' `sfh_fdeoff' The offset in bytes to the SFrame FDE sub-section. 0x18 `uint32_t' `sfh_freoff' The offset in bytes to the SFrame FRE sub-section. * Menu: * SFrame ABI/arch Identifier::  File: sframe-spec.info, Node: SFrame ABI/arch Identifier, Up: SFrame Header 2.2.1 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 section, is intended. There are currently four identifiable ABI/arch values in the format. ABI/arch Identifier Value Description --------------------------------------------------------------------- `SFRAME_ABI_AARCH64_ENDIAN_BIG' 1 AArch64 big-endian `SFRAME_ABI_AARCH64_ENDIAN_LITTLE' 2 AArch64 little-endian `SFRAME_ABI_AMD64_ENDIAN_LITTLE' 3 AMD64 little-endian `SFRAME_ABI_S390X_ENDIAN_BIG' 4 s390x big-endian The presence of an explicit identification of ABI/arch in SFrame may allow stack trace generators to make certain ABI/arch-specific decisions.  File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame Section 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. * Menu: * The SFrame FDE Index:: * The SFrame FDE Attribute:: * The SFrame FDE Info Bytes::  File: sframe-spec.info, Node: The SFrame FDE Index, Next: The SFrame FDE Attribute, Up: SFrame Function Descriptor Entries 2.3.1 The SFrame FDE Index -------------------------- The SFrame FDE index entries are stored in a sub-section of their own, forming a searchable index. If the SFrame header flag `SFRAME_F_FDE_SORTED' is set, then the entries are sorted by `sfdi_func_start_offset', allowing for efficient binary search. 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 a binary search scheme to look for the stack trace information pertinent to a given PC. 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; Each entry of the SFrame function descriptor index is naturally aligned. The following table describes each component of the SFrame FDE index entry: Offset Type Name Description ---------------------------------------------------------------------------------------------- 0x00 `int64_t' `sfdi_func_start_offset' Signed 64-bit integral field specifying the offset to the start address of the described function. If the flag `SFRAME_F_FDE_FUNC_START_PCREL', *Note SFrame Flags::, in the SFrame header is set, the value encoded in the `sfdi_func_start_offset' field is the offset in bytes to the function's start address from the `sfdi_func_start_offset' field itself. Otherwise, it is the offset in bytes from the start of the SFrame section. 0x08 `uint32_t' `sfdi_func_size' Unsigned 32-bit integral field specifying the size of the function in bytes. 0x0c `uint32_t' `sfdi_func_start_fre_off' Unsigned 32-bit integral field specifying the offset to the start of the function's stack trace data (SFrame FREs). This offset is relative to the _beginning of the SFrame FRE sub-section_.  File: sframe-spec.info, Node: The SFrame FDE Attribute, Next: The SFrame FDE Info Bytes, Prev: The SFrame FDE Index, Up: SFrame Function Descriptor Entries 2.3.2 The SFrame FDE Attribute ------------------------------ The SFrame FDE attribute structure provides information about the SFrame FRE entries that follow: their number and their encoding. The SFrame FDE attributes are stored at the beginning of each function's stack trace data within the SFrame FRE sub-section. Because these structures are interleaved with variable-length FREs, their elements are not guaranteed to be at naturally aligned boundaries. 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; Following table describes each component of the SFrame FDE attribute: Offset Type Name Description --------------------------------------------------------------------------------------------- 0x00 `uint16_t' `sfda_func_num_fres' Unsigned 16-bit integral field specifying the total number of SFrame FREs used for the function. 0x02 `uint8_t' `sfda_func_info' Unsigned 8-bit integral field specifying the SFrame FDE info byte. 0x03 `uint8_t' `sfda_func_info2' Additional unsigned 8-bit integral field specifying the SFrame FDE info byte. 0x04 `uint8_t' `sfda_func_rep_size' Unsigned 8-bit integral field specifying the size of the repetitive code block for which an SFrame FDE of type `SFRAME_FDE_PCTYPE_MASK' is used. For example, in AMD64, the size of a pltN entry is 16 bytes. `sfda_func_info' and `sfda_func_info2' are the SFrame FDE *Info Bytes*, containing information like the FRE type and their encoding, and the FDE type for the function. *Note The SFrame FDE Info Bytes::. The SFrame FDE attribute has some currently unused bits in the SFrame FDE info bytes, that may be used for the purpose of extending the SFrame file format specification for future ABIs. *Note The SFrame FDE Types:: subsection.  File: sframe-spec.info, Node: The SFrame FDE Info Bytes, Prev: The SFrame FDE Attribute, Up: SFrame Function Descriptor Entries 2.3.3 The SFrame FDE Info Bytes ------------------------------- The SFrame FDE Attribute contains two distinct bytes, `sfda_func_info' and `sfda_func_info2'. Together these are referred to as the SFrame FDE info bytes. These bytes contain vital information necessary to: - read and interpret SFrame FRE data, e.g., the number and size of each SFrame FRE offset, - PC Type for SFrame FDE, - type of SFrame FDE, - size of repeat block, if PC Type is `SFRAME_FDE_PCTYPE_MASK'. The first info byte `sfda_func_info' is a bitfield split into four parts. From MSB to LSB: Bit offset Name Description ----------------------------------------------------------------------------------------- 7 `signal_p' Signal frame. 6 `unused' Unused bit. 5 `pauth_key' (For AArch64) Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: `SFRAME_AARCH64_PAUTH_KEY_A' (0), or `SFRAME_AARCH64_PAUTH_KEY_B' (1). Unsed in AMD64, s390x 4 `fde_pctype' Specify the SFrame FDE PC Type. Two possible values: `SFRAME_FDE_PCTYPE_MASK' (1), or `SFRAME_FDE_PCTYPE_INC' (0). *Note The SFrame FDE PC Types::. 0-3 `fre_type' Choice of three SFrame FRE types. *Note The SFrame FRE Types::. The second info byte `sfda_func_info2' is a bitfield split into two parts. From MSB to LSB: Bit offset Name Description --------------------------------------------------------------------------------------- 7-5 `unused' Unused bits. 4-0 `fde_type' Specify the SFrame FDE type. Two possible values: `SFRAME_FDE_TYPE_DEFAULT' (0), or `SFRAME_FDE_TYPE_FLEX' (1). *Note The SFrame FDE Types::. * Menu: * The SFrame FDE PC Types:: * The SFrame FDE Types:: * The SFrame FRE Types::  File: sframe-spec.info, Node: The SFrame FDE PC Types, Next: The SFrame FDE Types, Up: The SFrame FDE Info Bytes 2.3.3.1 The SFrame FDE PC Types ............................... The SFrame format defines two types of FDE PC types. The choice of which SFrame FDE PC type to use is made based on the instruction patterns in the relevant program stub. An FDE of PC type `SFRAME_V3_FDE_PCTYPE_INC' contains FREs whose PCs are to be interpreted as the address of a single instruction, measured in bytes and relative to the beginning of the function. In contrast, a FDE of PC type `SFRAME_V3_FDE_PCTYPE_MASK' contains FREs whose PCs are to be interpreted as masks that identify several instructions. This is useful for cases where a small pattern of instructions in a program stub is used repeteadly for a specific functionality, like PLT entries and trampolines. Name of SFrame FDE PC Type Value Description ----------------------------------------------------------------------------------- `SFRAME_V3_FDE_PCTYPE_INC' 0 Stacktracers perform a (PC >= FRE_START_ADDR) to look up a matching FRE. `SFRAME_V3_FDE_PCTYPE_MASK' 1 Stacktracers perform a (PC % REP_BLOCK_SIZE >= FRE_START_ADDR) to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the repeating block of program instructions and is encoded via `sfde_func_rep_size' in the SFrame FDE.  File: sframe-spec.info, Node: The SFrame FDE Types, Next: The SFrame FRE Types, Prev: The SFrame FDE PC Types, Up: The SFrame FDE Info Bytes 2.3.3.2 The SFrame FDE Types ............................ The SFrame format defines two types of Function Descriptor Entries (FDEs) to encode stack trace information. The choice of FDE type determines how the data in the variable-length Frame Row Entries (FREs) is interpreted. The FDE type is encoded in the lower 5 bits of the `sfda_func_info2' field in the SFrame FDE attribute. Name Value Description ---------------------------------------------------------------------------------------- `SFRAME_FDE_TYPE_DEFAULT' 0 The default FDE type. CFA is recovered using the Stack Pointer (SP) or Frame Pointer (FP) plus a signed offset. Return Address (RA) and Frame Pointer (FP) are recovered using the CFA plus a signed offset (or a fixed register for specific architectures like s390x). The variable-length array of bytes trailing each SFrame FRE are interpreted according to the ABI/arch-specific rules for the target architecture. More details in *Note Default FDE Type Interpretation::. `SFRAME_FDE_TYPE_FLEX' 1 The flexible FDE type. Used for complex cases such as stack realignment (DRAP), non-standard CFA base registers, or when RA/FP recovery requires dereferencing or non-CFA base registers. The variable-length array of bytes may be interpreted as pairs of Control Data and Offset Data (or Padding Data), allowing for complex recovery rules (e.g., DRAP on AMD64, Stack Realignment). More details in *Note Flexible FDE Type Interpretation::. Currently, five bits are reserved in the `sfda_func_info2' for indicating SFrame FDE types. In future, other ABIs/architectures may add even arch-specific FDE types. Each distinct FDE type may define a different layout, encoding, and interpretation of the variable-length data words trailing each SFrame FRE.  File: sframe-spec.info, Node: The SFrame FRE Types, Prev: The SFrame FDE Types, Up: The SFrame FDE Info Bytes 2.3.3.3 The SFrame FRE Types ............................ A real world application can have functions of size big and small. SFrame format defines three types of SFrame FRE entries to efficiently encode the stack trace information for such a variety of function sizes. These representations vary in the number of bits needed to encode the start address offset in the SFrame FRE. The following constants are defined and used to identify the SFrame FRE types: Name Value Description ------------------------------------------------------------------------------- `SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) of the SFrame FRE is an unsigned 8-bit value. `SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) of the SFrame FRE is an unsigned 16-bit value. `SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) of the SFrame FRE is an unsigned 32-bit value. A single function must use the same type of SFrame FRE throughout. The identifier to reflect the chosen SFrame FRE type is stored in the `fre_type' bits in the SFrame FDE info byte, *Note The SFrame FDE Info Bytes::.  File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame Section 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 *Note 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 *Note 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. * Menu: * The SFrame FRE Info Word::  File: sframe-spec.info, Node: The SFrame FRE Info Word, Up: SFrame Frame Row Entries 2.4.1 The SFrame FRE Info Word ------------------------------ The SFrame FRE info byte is a bitfield split into four parts. From MSB to LSB: Bit offset Name Description ------------------------------------------------------------------------------------------------ 7 `fre_mangled_ra_p' Indicate whether the return address is mangled with any authorization bits (signed RA). 5-6 `fre_dataword_size' Size of data word in bytes. Valid values are: `SFRAME_FRE_DATAWORD_1B', `SFRAME_FRE_DATAWORD_2B', and `SFRAME_FRE_DATAWORD_4B'. 1-4 `fre_dataword_count' Being a 4-bit sized field, a max value of 15 is allowed. Typically, a value of up to 3 is sufficient for most ABIs to track all three of CFA, FP and RA. A value of zero indicates that the return address (RA) is undefined. A stack tracer may use this as indication that an outermost frame has been reached and the stack trace is complete. 0 `fre_cfa_base_reg_id' Distinguish between SP or FP based CFA recovery. Name Value Description ------------------------------------------------------------------------------------ `SFRAME_FRE_DATAWORD_1B' 0 All data words following the fixed-length FRE structure are 1 byte long. `SFRAME_FRE_DATAWORD_2B' 1 All data words following the fixed-length FRE structure are 2 bytes long. `SFRAME_FRE_DATAWORD_4B' 2 All data words following the fixed-length FRE structure are 4 bytes long.  File: sframe-spec.info, Node: Interpretation of SFrame FREs, Next: Generating Stack Traces using SFrame, Prev: SFrame Section, Up: Top 3 Interpretation of SFrame FREs ******************************* Each SFrame Frame Row Entry (FRE) provides information about a PC range within some function, encoded using a variable number of bytes (*note SFrame Frame Row Entries::). The interpretation of these bytes depends on the FDE type used to represent stack tracing information for the function. * Menu: * Default FDE Type Interpretation:: * Flexible FDE Type Interpretation::  File: sframe-spec.info, Node: Default FDE Type Interpretation, Next: Flexible FDE Type Interpretation, Up: Interpretation of SFrame FREs 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. * Menu: * AMD64:: * AArch64:: * s390x::  File: sframe-spec.info, Node: AMD64, Next: AArch64, Up: Default FDE Type Interpretation 3.1.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 byte. 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. *Note 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: Offset ID Interpretation in AMD64 ----------------------------------------------- 1 CFA = `BASE_REG' + offset1 2 FP = CFA + offset2  File: sframe-spec.info, Node: AArch64, Next: s390x, Prev: AMD64, Up: Default FDE Type Interpretation 3.1.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 byte. 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: Offset ID Interpretation in AArch64 --------------------------------------------- 1 CFA = `BASE_REG' + offset1 2 RA = CFA + offset2 3 FP = CFA + offset3  File: sframe-spec.info, Node: s390x, Prev: AArch64, Up: Default FDE Type Interpretation 3.1.3 s390x ----------- A stack tracer implementation must initialize the SP to the designated SP register value, the FP to the preferred FP register value, and the RA to the designated RA register value in the topmost stack frame of the callchain. This is required, as either the SP or FP is used as CFA base register and as the FP and/or RA are not necessarily saved on the stack. For RA this may only be the case in the topmost stack frame of the callchain. For FP this may be the case in any stack frame. Irrespective of the ABI, the first stack offset is always used to locate the CFA. On s390x the value of the offset is stored adjusted by the s390x-specific `SFRAME_S390X_CFA_OFFSET_ADJUSTMENT' and scaled down by the s390x-specific `SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR', to enable and improve the use of signed 8-bit offsets on s390x. s390x-specific helpers `SFRAME_V2_S390X_CFA_OFFSET_ENCODE' and `SFRAME_V2_S390X_CFA_OFFSET_DECODE' are provided to perform or undo the adjustment and scaling. The CFA offset can therefore be interpreted as: CFA = `BASE_REG' + offset1 - `SFRAME_S390X_CFA_OFFSET_ADJUSTMENT' or CFA = `BASE_REG' + (offset1 * `SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR') - `SFRAME_S390X_CFA_OFFSET_ADJUSTMENT'. The identification of the `BASE_REG' is done by using the `fre_cfa_base_reg_id' field in the SFrame FRE info byte. The (64-bit) s390x ELF ABI does not mandate the precise location in a function where the return address (RA) and frame pointer (FP) are saved, 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 stack slot, by interpreting it as: RA = CFA + offset2, unless the offset has a value of `SFRAME_FRE_RA_OFFSET_INVALID'. RA remains unchanged, if the offset is not available or has a value of `SFRAME_FRE_RA_OFFSET_INVALID'. Stack tracers are recommended to validate that the "unchanged RA" pattern, when present, is seen only for the topmost stack frame. The third stack offset is used to locate the FP stack slot, by interpreting it as: FP = CFA + offset3. FP remains unchanged, if the offset is not available. In leaf functions the RA and FP may be saved in other registers, such as floating-point registers (FPRs), instead of being saved on the stack. To represent this in the SFrame stack trace format, SFrame FDE of type `SFRAME_FDE_TYPE_FLEX' may be used. Given the nature of things, for default type FDEs, the number of stack offsets seen on s390x per SFrame FRE is either 1, 2, or 3. Hence, in summary: Offset ID Interpretation in s390x -------------------------------------------------------------------------- 1 CFA = `BASE_REG' + offset1 2 RA stack slot = CFA + offset2 RA not saved if (offset2 == `SFRAME_FRE_RA_OFFSET_INVALID') 3 FP stack slot = CFA + offset3 The s390x ELF ABI defines the CFA as stack pointer (SP) at call site +160. The SP can therefore be obtained using the SP value offset from CFA `SFRAME_S390X_SP_VAL_OFFSET' of -160 as follows: SP = CFA + `SFRAME_S390X_SP_VAL_OFFSET' Future ABIs must specify the algorithm for identifying the appropriate SFrame FRE stack offsets in this chapter. This should inevitably include the blueprint for interpreting the variable number of bytes at the tail end of the SFrame FRE for the specific ABI/arch.  File: sframe-spec.info, Node: Flexible FDE Type Interpretation, Prev: Default FDE Type Interpretation, Up: Interpretation of SFrame FREs 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: Bit Offset Name Description ---------------------------------------------------------------------------------- 0 `reg_p' Register-based Location Rule If 1, the base is a DWARF register (encoded in bits 3+). If 0, the base is the CFA (used for RA/FP recovery). 1 `deref_p' Dereference Flag If 1, the location of the value is the address (`Base + Offset'), i.e., value = `*(Base + Offset)'. If 0, the value is `Base + Offset'. 2 `unused' Unused bit. 3+ `regnum' The DWARF register number used as the base. Effective only if `reg_p' is 1. 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).  File: sframe-spec.info, Node: Generating Stack Traces using SFrame, Next: Index, Prev: Interpretation of SFrame FREs, Up: Top Appendix A Generating Stack Traces using SFrame *********************************************** Using some C-like pseudocode, this section highlights how SFrame provides a simple, fast and low-overhead mechanism to generate stack traces. Needless to say that for generating accurate and useful stack traces, several other aspects will need attention: finding and decoding bits of SFrame section(s) in the program binary, symbolization of addresses, to name a few. In the current context, a `frame' is the abstract construct that encapsulates the following information: - program counter (PC), - stack pointer (SP), and - frame pointer (FP) With that said, establishing the first `frame' should be trivial: // frame 0 frame->pc = current_IP; frame->sp = get_reg_value (REG_SP); frame->fp = get_reg_value (REG_FP); where `REG_SP' and `REG_FP' are are ABI-designated stack pointer and frame pointer registers respectively. Next, given frame N, generating stack trace needs us to get frame N+1. This can be done as follows: // Get the PC, SP, and FP for frame N. pc = frame->pc; sp = frame->sp; fp = frame->fp; // Populate frame N+1. int err = get_next_frame (&next_frame, pc, sp, fp); where given the values of the program counter, stack pointer and frame pointer from frame N, `get_next_frame' populates the provided `next_frame' object and returns the error code, if any. In the following pseudocode for `get_next_frame', the `sframe_*' functions fetch information from the SFrame section. Note that the stack tracer must retrieve the FDE type to decide how to interpret the FRE data words. fre = sframe_find_fre (pc, &fde_type); if (fre && fde_type == SFRAME_FDE_TYPE_DEFAULT) // Whether the base register for CFA tracking is REG_FP. base_reg_val = sframe_fre_base_reg_fp_p (fre) ? fp : sp; // Get the CFA stack offset from the FRE. cfa_offset = sframe_fre_get_cfa_offset (fre); // Get the fixed RA offset or FRE stack offset as applicable. ra_offset = sframe_fre_get_ra_offset (fre); // Get the fixed FP offset or FRE stack offset as applicable. fp_offset = sframe_fre_get_fp_offset (fre); cfa = base_reg_val + cfa_offset; next_frame->sp = cfa [+ SFRAME_S390X_SP_VAL_OFFSET on s390x]; ra_stack_loc = cfa + ra_offset; // Get the address stored in the stack location. next_frame->pc = read_value (ra_stack_loc); if (fp_offset is VALID) fp_stack_loc = cfa + fp_offset; // Get the value stored in the stack location. next_frame->fp = read_value (fp_stack_loc); else // Continue to use the value of fp as it has not // been clobbered by the current frame yet. next_frame->fp = fp; For SFrame FDE of type `SFRAME_FDE_TYPE_FLEX', read the set of data words and apply the recovery rules accordingly. if (fre && fde_type == SFRAME_FDE_TYPE_FLEX) // Get the base register, offset, and deref_p for CFA tracking. // The first FRE offset (index 0) is the CFA Control Data. cfa_reg_data = sframe_fre_get_offset (fre, 0); cfa_offset = sframe_fre_get_offset (fre, 1); // Get the RA reg, offset, and deref_p. // The third FRE data word (index 2) is the RA Control Data. ra_reg_data = sframe_fre_get_udata (fre, 2); if (ra_reg_data != SFRAME_FRE_RA_OFFSET_INVALID) ra_offset = sframe_fre_get_offset (fre, 3); fp_tracking_p = fre.num_offsets > 3; fp_data_index = 3; else fp_tracking_p = fre.num_offsets > 4; fp_data_index = 4; // Get the FP reg, offset, and deref_p (if present). if (fp_tracking_p) fp_reg_data = sframe_fre_get_udata (fre, fp_data_index); fp_offset = sframe_fre_get_fp_offset (fre); // Safety check for topmost frames: // If recovery requires non-standard registers (not SP/FP), // it is only valid if we are at the top of the stack // (where those registers haven't been clobbered). cfa_base_reg = SFRAME_V3_FLEX_FDE_OFFSET_REG_NUM (cfa_reg_data); if (!topmost_frame_p && (cfa_base_reg != REG_FP && cfa_base_reg != REG_SP)) return ERR_SFRAME_UNSAFE_UNWIND; // Apply rules to recover CFA and RA cfa = sframe_apply_rule (cfa_reg_data, cfa_offset, cfa, 1); ra = sframe_apply_rule (ra_reg_data, ra_offset, cfa, 0); if (fp_tracking_p) next_frame->fp = sframe_apply_rule (fp_reg_data, fp_offset, cfa, 0); else next_frame->fp = fp; next_frame->sp = cfa; next_frame->pc = ra; else ret = ERR_NO_SFRAME_FRE; The `sframe_apply_rule' helper function abstracts the logic of interpreting the Control Data and Offset Data pair for flexible FDEs: // Apply SFrame V3 Flex FDE recovery rule. // reg_data: The Control Data (Data word 1) containing reg_p, deref_p, regnum. // offset: The Offset (Data word 2). // cfa: The current CFA value (used as base if reg_p is 0). // cfa_p: Bool indicating if we are currently recovering the CFA itself. sframe_apply_rule (reg_data, offset, cfa, cfa_p) reg_p = SFRAME_V3_FLEX_FDE_OFFSET_REG_P (reg_data); // Determine Base Address: // If reg_p is set, read from the specific DWARF register. // If reg_p is clear, use the CFA (unless we are recovering the // CFA itself, in which case reg_p MUST be set). if (reg_p) reg_num = SFRAME_V3_FLEX_FDE_OFFSET_REG_NUM (reg_data); base_loc = get_reg_value (reg_num); else base_loc = cfa; // CFA recovery must always specify a base register. assert (!cfa_p || reg_p); // Add the displacement loc = base_loc + offset; // Dereference if required deref_p = SFRAME_V3_FLEX_FDE_OFFSET_REG_DEREF_P (reg_data); value = deref_p ? read_value (loc) : loc; return value;  File: sframe-spec.info, Node: Index, Prev: Generating Stack Traces using SFrame, Up: Top Index ***** [index] * Menu: * Changes from Version 1 to Version 2: Changes from Version 1 to Version 2. (line 6) * Changes from Version 2 to Version 3: Changes from Version 2 to Version 3. (line 6) * endianness: SFrame Magic Number and Endianness. (line 6) * Interpretation of SFrame FREs: Interpretation of SFrame FREs. (line 6) * Introduction: Introduction. (line 6) * Overview: Overview. (line 6) * Provisions for future ABIs <1>: SFrame Frame Row Entries. (line 36) * Provisions for future ABIs <2>: SFrame Header. (line 60) * Provisions for future ABIs <3>: The SFrame FDE Attribute. (line 42) * Provisions for future ABIs: The SFrame FDE Types. (line 39) * SFrame ABI/arch Identifier: SFrame ABI/arch Identifier. (line 6) * SFrame FDE: SFrame Function Descriptor Entries. (line 6) * SFrame Flags: SFrame Flags. (line 6) * SFrame FRE: SFrame Frame Row Entries. (line 6) * SFrame header: SFrame Header. (line 6) * SFrame magic number: SFrame Magic Number and Endianness. (line 6) * SFrame preamble: SFrame Preamble. (line 6) * SFrame Section: SFrame Section. (line 6) * SFrame versions: SFrame Version. (line 9) * SFRAME_FDE_TYPE_DEFAULT: Default FDE Type Interpretation. (line 6) * SFRAME_FDE_TYPE_FLEX: Flexible FDE Type Interpretation. (line 6) * The SFrame FDE Attribute: The SFrame FDE Index. (line 48) * The SFrame FDE Index: SFrame Function Descriptor Entries. (line 20) * The SFrame FDE Info Bytes: The SFrame FDE Attribute. (line 47) * The SFrame FDE Types: The SFrame FDE Types. (line 6) * The SFrame FRE Info Word: SFrame Frame Row Entries. (line 86) * The SFrame FRE Types: The SFrame FRE Types. (line 6)  Tag Table: Node: Top711 Node: Introduction1430 Node: Overview1656 Node: Changes from Version 2 to Version 33280 Node: Changes from Version 1 to Version 26080 Node: SFrame Section9567 Node: SFrame Preamble10067 Node: SFrame Magic Number and Endianness11556 Node: SFrame Version12088 Node: SFrame Flags12708 Node: SFrame Header14412 Node: SFrame ABI/arch Identifier19382 Node: SFrame Function Descriptor Entries20294 Node: The SFrame FDE Index21002 Node: The SFrame FDE Attribute23872 Node: The SFrame FDE Info Bytes26385 Node: The SFrame FDE PC Types28655 Node: The SFrame FDE Types30352 Node: The SFrame FRE Types33119 Node: SFrame Frame Row Entries34501 Node: The SFrame FRE Info Word38080 Node: Interpretation of SFrame FREs40128 Node: Default FDE Type Interpretation40711 Node: AMD6441272 Node: AArch6442381 Node: s390x43613 Node: Flexible FDE Type Interpretation47135 Node: Generating Stack Traces using SFrame52025 Node: Index58906  End Tag Table @ 1.1 log @Initial revision @ text @d1 4 a4 2 This is sframe-spec.info, produced by makeinfo version 7.0.2 from sframe-spec.texi. d6 1 a6 1 Copyright © 2021-2024 Free Software Foundation, Inc. d11 2 a12 2 license is included in the section entitled “GNU General Public License”. d25 1 a25 7 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: − Canonical Frame Address (CFA). − Frame Pointer (FP). − Return Address (RA). d27 12 a38 2 The reason for existence of the SFrame format is to provide a simple, fast and low-overhead mechanism to generate stack traces. d43 6 a48 1 * SFrame section:: d52 1 a52 1 File: sframe-spec.info, Node: Introduction, Next: SFrame section, Prev: Top, Up: Top d60 1 d64 1 a64 1 File: sframe-spec.info, Node: Overview, Next: Changes from Version 1 to Version 2, Up: Introduction d70 3 a72 2 known as the ‘.sframe’ section. When available, the ‘.sframe’ section appears in a new segment of its own, PT_GNU_SFRAME. d75 1 a75 1 namely, AMD64 and AAPCS64. d79 1 a79 1 header and the SFrame function descriptor entry) have elements at their d85 1 a85 1 is targetted to be used. An SFrame section reader may use the magic d89 4 a92 1 Addresses in this specification are expressed in bytes. d95 1 a95 1 format, ‘SFRAME_VERSION_2’, in detail. Additional sections outline the d99 40 a138 3 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. d140 28 a167 2 This document is intended to be in sync with the C code in ‘sframe.h’. Please report discrepancies between the two, if any. d170 1 a170 1 File: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction d172 1 a172 1 1.2 Changes from Version 1 to Version 2 d178 10 a187 6 • 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. • SFrame Function Descriptor Entry includes an explicit padding of two bytes to ensure natural alignment for its data members. • The above two imply that each SFrame Function Descriptor Entry has d189 58 a246 1 format version 1. d249 1 a249 1 File: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Introduction, Up: Top d251 1 a251 1 2 SFrame section d255 3 a257 3 preamble, and two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section. d267 1 a267 1 File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame section d273 1 a273 1 whose format cannot vary between versions. d287 11 a297 11 Offset Name Description ----------------------------------------------------------------------------------------- 0x00 ‘uint16_t sfp_magic’ The magic number for SFrame section: 0xdee2. Defined as a macro ‘SFRAME_MAGIC’. 0x02 ‘uint8_t sfp_version’ The version number of this SFrame section. *Note SFrame version::, for the set of valid values. Current version is ‘SFRAME_VERSION_1’. 0x03 ‘uint8_t sfp_flags’ Flags (section-wide) for this SFrame section. *Note SFrame flags::, for the set of valid values. d301 3 a303 3 * SFrame endianness:: * SFrame version:: * SFrame flags:: d306 1 a306 1 File: sframe-spec.info, Node: SFrame endianness, Next: SFrame version, Up: SFrame Preamble d308 2 a309 2 2.1.1 SFrame endianness ----------------------- d312 4 a315 4 consumes them. The SFrame library (‘libsframe’) can, however, detect whether to endian-flip an SFrame section at decode time, by inspecting the ‘sfp_magic’ field in the SFrame header (If it appears as 0xe2de, endian-flipping is needed). d318 1 a318 1 File: sframe-spec.info, Node: SFrame version, Next: SFrame flags, Prev: SFrame endianness, Up: SFrame Preamble d320 1 a320 1 2.1.2 SFrame version d324 1 a324 1 ‘sfp_version’. The following versions are currently valid: d326 5 a330 4 Version Number Description ------------------------------------------------------------------ ‘SFRAME_VERSION_1’ 1 First version, obsolete. ‘SFRAME_VERSION_2’ 2 Current version, under development. d332 1 a332 1 This document describes ‘SFRAME_VERSION_2’. d335 1 a335 1 File: sframe-spec.info, Node: SFrame flags, Prev: SFrame version, Up: SFrame Preamble d337 1 a337 1 2.1.3 SFrame flags d340 1 a340 1 The preamble contains bitflags in its ‘sfp_flags’ field that describe d345 19 a363 6 Flag Versions Value Meaning ---------------------------------------------------------------------------- ‘SFRAME_F_FDE_SORTED’ All 0x1 Function Descriptor Entries are sorted on PC. ‘SFRAME_F_FRAME_POINTER’ All 0x2 Functions preserve frame-pointer. d365 2 a366 1 Further flags may be added in future. d369 1 a369 1 File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame section d377 3 a379 3 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 d403 1 a403 1 The sub-section offsets, namely ‘sfh_fdeoff’ and ‘sfh_freoff’, in the d408 13 d423 15 a437 12 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 made some provisions for supporting more ABIs/architectures in the future. The ‘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 ‘sframe_header’ structure. As for the offset calculations, the _end_ of SFrame header must be the end of the auxiliary SFrame header, if the latter is present. d441 21 a461 39 Offset Name Description ---------------------------------------------------------------------------------------- 0x00 ‘sframe_preamble sfh_preamble’ The SFrame preamble. *Note SFrame Preamble::. 0x04 ‘uint8_t sfh_abi_arch’ The ABI/arch identifier. *Note SFrame ABI/arch identifier::. 0x05 ‘int8_t sfh_cfa_fixed_fp_offset’ The CFA fixed FP offset, if any. 0x06 ‘int8_t sfh_cfa_fixed_ra_offset’ The CFA fixed RA offset, if any. 0x07 ‘uint8_t sfh_auxhdr_len’ Size in bytes of the auxiliary header that follows the ‘sframe_header’ structure. 0x08 ‘uint32_t sfh_num_fdes’ The number of SFrame FDEs in the section. 0xc ‘uint32_t sfh_num_fres’ The number of SFrame FREs in the section. 0x10 ‘uint32_t sfh_fre_len’ The length in bytes of the SFrame FRE sub-section. 0x14 ‘uint32_t sfh_fdeoff’ The offset in bytes of the SFrame FDE sub-section. This sub-section contains ‘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. *Note SFrame Function Descriptor Entries::. 0x18 ‘uint32_t sfh_freoff’ 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. *Note SFrame Frame Row Entries::. d465 1 a465 1 * SFrame ABI/arch identifier:: d468 1 a468 1 File: sframe-spec.info, Node: SFrame ABI/arch identifier, Up: SFrame Header d470 1 a470 1 2.2.1 SFrame ABI/arch identifier d475 1 a475 1 SFrame section, is intended. There are currently three identifiable d479 5 a483 8 --------------------------------------------------------------------- ‘SFRAME_ABI_AARCH64_ENDIAN_BIG’ 1 AARCH64 big-endian ‘SFRAME_ABI_AARCH64_ENDIAN_LITTLE’ 2 AARCH64 little-endian ‘SFRAME_ABI_AMD64_ENDIAN_LITTLE’ 3 AMD64 little-endian d486 2 a487 1 allow stack trace generators to make certain ABI-specific decisions. d490 1 a490 1 File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame section d495 28 a522 4 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 stack trace information at a high-level. d524 1 a524 1 typedef struct sframe_func_desc_entry d526 30 a555 60 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 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 *Note The SFrame FDE info word::. Following table describes each component of the SFrame FDE structure: Offset Name Description ------------------------------------------------------------------------------------------ 0x00 ‘int32_t sfde_func_start_address’ Signed 32-bit integral field denoting the virtual memory address of the described function. 0x04 ‘uint32_t sfde_func_size’ Unsigned 32-bit integral field specifying the size of the function in bytes. 0x08 ‘uint32_t sfde_func_start_fre_off’ Unsigned 32-bit integral field specifying the offset in bytes of the function’s first SFrame FRE in the SFrame section. 0x0c ‘uint32_t sfde_func_num_fres’ Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. 0x10 ‘uint8_t sfde_func_info’ Unsigned 8-bit integral field specifying the SFrame FDE info word. *Note The SFrame FDE info word::. 0x11 ‘uint8_t sfde_func_rep_size’ 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. 0x12 ‘uint16_t sfde_func_padding2’ Padding of 2 bytes. Currently unused bytes. * Menu: * The SFrame FDE info word:: * The SFrame FDE types:: * The SFrame FRE types:: d558 1 a558 1 File: sframe-spec.info, Node: The SFrame FDE info word, Next: The SFrame FDE types, Up: SFrame Function Descriptor Entries d560 1 a560 1 2.3.1 The SFrame FDE info word d563 6 a568 1 The info word is a bitfield split into three parts. From MSB to LSB: d570 82 a651 16 Bit offset Name Description ---------------------------------------------------------------------------------------- 7–6 ‘unused’ Unused bits. 5 ‘pauth_key’ Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: SFRAME_AARCH64_PAUTH_KEY_A (0), or SFRAME_AARCH64_PAUTH_KEY_B (1). 4 ‘fdetype’ Specify the SFrame FDE type. Two possible values: SFRAME_FDE_TYPE_PCMASK (1), or SFRAME_FDE_TYPE_PCINC (0). *Note The SFrame FDE types::. 0–3 ‘fretype’ Choice of three SFrame FRE types. *Note The SFrame FRE types::. d653 1 a653 2  File: sframe-spec.info, Node: The SFrame FDE types, Next: The SFrame FRE types, Prev: The SFrame FDE info word, Up: SFrame Function Descriptor Entries d655 81 a735 32 2.3.2 The SFrame FDE types -------------------------- SFrame format defines two types of FDE entries. The choice of which SFrame FDE type to use is made based on the instruction patterns in the relevant program stub. An SFrame FDE of type ‘SFRAME_FDE_TYPE_PCINC’ is an indication that the PCs in the FREs should be treated as increments in bytes. This is used fo the the bulk of the executable code of a program, which contains instructions with no specific pattern. In contrast, an SFrame FDE of type ‘SFRAME_FDE_TYPE_PCMASK’ is an indication that the PCs in the FREs should be treated as masks. This type is useful for the cases where a small pattern of instructions in a program stub is used repeatedly for a specific functionality. Typical usecases are pltN entries and trampolines. Name of SFrame FDE Value Description type --------------------------------------------------------------------------- SFRAME_FDE_TYPE_PCINC 0 Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE. SFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a (PC % REP_BLOCK_SIZE >= FRE_START_ADDR) to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the repeating block of program instructions. d738 1 a738 1 File: sframe-spec.info, Node: The SFrame FRE types, Prev: The SFrame FDE types, Up: SFrame Function Descriptor Entries d740 2 a741 2 2.3.3 The SFrame FRE types -------------------------- d744 4 a747 4 SFrame format defines three types of SFrame FRE entries to represent the stack trace information for such a variety of function sizes. These representations vary in the number of bits needed to encode the start address offset in the SFrame FRE. d753 7 a759 13 -------------------------------------------------------------------------- ‘SFRAME_FRE_TYPE_ADDR1’ 0 The start address offset (in bytes) of the SFrame FRE is an unsigned 8-bit value. ‘SFRAME_FRE_TYPE_ADDR2’ 1 The start address offset (in bytes) of the SFrame FRE is an unsigned 16-bit value. ‘SFRAME_FRE_TYPE_ADDR4’ 2 The start address offset (in bytes) of the SFrame FRE is an unsigned 32-bit value. d762 3 a764 2 An identifier to reflect the chosen SFrame FRE type is stored in the *Note The SFrame FDE info word::. d767 1 a767 1 File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame section d772 42 a813 2 The SFrame Frame Row Entry sub-section contains the core of the stack trace information. d815 1 a815 25 An SFrame Frame Row Entry is a self-sufficient record containing SFrame stack trace information 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’ *Note The SFrame FRE info word::. Following are the definitions of the allowed SFrame FRE: d840 2 a841 2 ‘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 d843 2 a844 2 ‘sfre_start_address’ field is the offset in bytes of the start address of the SFrame FRE, from the start address of the function. d846 1 a846 1 Further FRE types may be added in future. d850 1 a850 1 * The SFrame FRE info word:: d853 1 a853 1 File: sframe-spec.info, Node: The SFrame FRE info word, Up: SFrame Frame Row Entries d855 1 a855 1 2.4.1 The SFrame FRE info word d858 1 a858 1 The SFrame FRE info word is a bitfield split into four parts. From MSB d862 40 a901 30 ------------------------------------------------------------------------------------- 7 ‘fre_mangled_ra_p’ Indicate whether the return address is mangled with any authorization bits (signed RA). 5-6 ‘fre_offset_size’ Size of stack offsets in bytes. Valid values are: SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B, and SFRAME_FRE_OFFSET_4B. 1-4 ‘fre_offset_count’ A value of upto 3 is allowed to track all three of CFA, FP and RA. 0 ‘fre_cfa_base_reg_id’ Distinguish between SP or FP based CFA recovery. Name Value Description -------------------------------------------------------------------------------- ‘SFRAME_FRE_OFFSET_1B’ 0 All stack offsets following the fixed-length FRE structure are 1 byte long. ‘SFRAME_FRE_OFFSET_2B’ 1 All stack offsets following the fixed-length FRE structure are 2 bytes long. ‘SFRAME_FRE_OFFSET_4B’ 2 All stack offsets following the fixed-length FRE structure are 4 bytes long. d904 425 a1328 1 File: sframe-spec.info, Node: Index, Prev: SFrame section, Up: Top d1338 6 a1343 1 * endianness: SFrame endianness. (line 6) d1346 7 a1352 1 * SFrame ABI/arch identifier: SFrame ABI/arch identifier. d1356 1 a1356 1 * SFrame flags: SFrame flags. (line 6) d1360 2 d1363 15 a1377 27 * SFrame section: SFrame section. (line 6) * SFrame versions: SFrame version. (line 9) * SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch identifier. (line 13) * SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch identifier. (line 16) * SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch identifier. (line 18) * SFRAME_FDE_TYPE_PCINC: The SFrame FDE types. (line 6) * SFRAME_FDE_TYPE_PCMASK: The SFrame FDE types. (line 6) * SFRAME_FRE_OFFSET_1B: The SFrame FRE info word. (line 30) * SFRAME_FRE_OFFSET_2B: The SFrame FRE info word. (line 34) * SFRAME_FRE_OFFSET_4B: The SFrame FRE info word. (line 37) * SFRAME_FRE_TYPE_ADDR1: The SFrame FRE types. (line 17) * SFRAME_FRE_TYPE_ADDR2: The SFrame FRE types. (line 22) * SFRAME_FRE_TYPE_ADDR4: The SFrame FRE types. (line 26) * SFRAME_F_FDE_SORTED: SFrame flags. (line 11) * SFRAME_F_FRAME_POINTER: SFrame flags. (line 14) * SFRAME_MAGIC: SFrame Preamble. (line 24) * SFRAME_VERSION_1: SFrame version. (line 9) * The SFrame FDE info word: SFrame Function Descriptor Entries. (line 73) * The SFrame FRE info word: SFrame Frame Row Entries. (line 69) d1382 29 a1410 18 Node: Top569 Node: Introduction1159 Node: Overview1345 Node: Changes from Version 1 to Version 22932 Node: SFrame section3709 Node: SFrame Preamble4185 Node: SFrame endianness5624 Node: SFrame version6088 Node: SFrame flags6664 Node: SFrame Header7396 Node: SFrame ABI/arch identifier12592 Node: SFrame Function Descriptor Entries13627 Node: The SFrame FDE info word17329 Node: The SFrame FDE types18504 Node: The SFrame FRE types20233 Node: SFrame Frame Row Entries21777 Node: The SFrame FRE info word24470 Node: Index26480 a1412 5  Local Variables: coding: utf-8 End: @ 1.1.1.1 log @Import binutils-2.42 (last was 2.39) 2024-01-15 Nick Clifton * 2.42 branch point. 2023-11-15 Arsen Arsenović * intl: Remove directory. Replaced with out-of-tree GNU gettext. * .gitignore: Add '/gettext*'. * configure.ac (host_libs): Replace intl with gettext. (hbaseargs, bbaseargs, baseargs): Split baseargs into {h,b}baseargs. (skip_barg): New flag. Skips appending current flag to bbaseargs. : Exempt --with-libintl-{type,prefix} from target and build machine argument passing. * configure: Regenerate. * Makefile.def (host_modules): Replace intl module with gettext module. (configure-ld): Depend on configure-gettext. * Makefile.in: Regenerate. * src-release.sh: Remove references to the intl/ directory. 2023-07-03 Nick Clifton 2.41 Branch Point. 2023-06-26 Nick Clifton * Import these updates to the config scripts commit 4ad4bb7c30aca1e705448ba8d51a210bbd47bb52 Author: Paul Eggert Date: Fri Jun 23 09:55:10 2023 -0700 Quote 'like this', not `like this'. commit 63acb96f92473ceb5e21d873d7c0aee266b3d6d3 Author: Paul Eggert Date: Sat Jan 21 00:15:01 2023 -0600 Fix config.sub spelling typo for "athlon" commit 4ce12a5c9125cedc0d0ba584444a6865396923ec Author: Dmitry V. Levin Date: Sun Jan 1 08:00:00 2023 +0000 Update copyright years commit c397e2c040bce50bcdccb131f90115ba7e8bfc19 Author: Arsen Arsenovi Date: Sat Sep 17 23:34:48 2022 +0200 config.sub: add linux-mlibc targets commit 9f9f9b0b13197269848c76e3e057a3ed0680b4bf Author: Arsen Arsenovi Date: Sat Sep 17 23:34:47 2022 +0200 config.guess: support running on Managarm systems commit 87e6687749da7bb2ab158a79fa83721c19ed9246 Author: Arsen Arsenovi Date: Sat Sep 17 23:34:46 2022 +0200 config.sub: add managarm-{mlibc,kernel} targets commit 20403c5701973a4cbd7e0b4bbeb627fcd424a0f1 Author: Xiaotian Wu Date: Mon Aug 1 16:05:29 2022 +0800 Remove loongarchx32 commit 02ba26b218d3d3db6c56e014655faf463cefa983 Author: Alexander von Gluck IV Date: Wed May 25 15:43:13 2022 -0500 config.guess: Update Haiku guesses commit f56a7140386d08a531bcfd444d632b28c61a6329 Author: Bruno Haible Date: Sun May 8 19:08:08 2022 +0200 config.guess (x86_64:Linux:*:*): Detect 32-bit ABI. 2023-04-20 Nick Clifton * SECURITY.txt: New file. * src-release.sh (DEVO_SUPPORT): Add SECURITY.txt. 2022-12-31 Nick Clifton * 2.40 binutils branch created. 2022-10-10 Nick Clifton * src-release.sh: Add "-r " option to create reproducible tarballs based upon a fixed timestamp of . * binutils/README-how-to-make-a-release: Add a line showing how to use -r when creating a binutils release. 2022-10-04 Nick Clifton * README-maintainer-mode: Add a minimum version of dejagnu requirement. 2022-09-08 Nick Clifton * README-maintainer-mode: Update minimum version of gettext required. @ text @@ 1.1.1.2 log @Import binutils 2.45 (previous was 2.42) 2.45 Release Notes ------------------ Assembler: All sframe information generated by the assembler is now in compliance with the SFrame V2 specification. The assembler now supports .errif and .warnif directives, permitting user-controlled diagnostics with conditionals that are evaluated only at the end of assembly. The assembler predefines the symbol "GAS(version)". The assembler now supports the generation of SFrame stack trace information (.sframe) from CFI directives on s390 64-bit (s390x). For RISC-V, the ".option arch, -ext" format is deprecated due to its controversial use. For RISC-V, stop generating mapping symbols $x and replace with $x. The $x was defined to have the same ISA as previous $x, but now is defined to have the same ISA as elf architecture attribute. Once both used .option arch/rvc/norvc/push/pop directives (some code have different architectures with file attribute) and data directives in text, then the file need to be rebuilt since 2.45. The assembler supports the latest architecture extensions for the RISC-V, LoongArch and AArch64 architectures. Linker: The linker's --stats option can take an optional argument which if used is interpreted as a filename into which resource usage information should be stored. As an alternative mechanism the LD_STATS environment variable can also be used to achieve the same results. Resource usage information for various phases of the linking operation is now included in the report. If a map file is being produced then the information is also included there. The --no-stats option can be used to disable stat reporting, should it have been enabled. On s390 64-bit (s390x), generate SFrame stack trace information (.sframe) for the linker generated .plt section. On s390 32-bit, generate ".eh_frame" unwind information for the linker generated .plt section. Both features are enabled by default and can be disabled using linker option --no-ld-generated-unwind-info. On RISC-V, add new PLT formats, and GNU property merge rules for zicfiss and zicfilp extensions. On AVR, the default linker scripts now assert that the .progmem sections don't extend past 0xffff since they are accessed by means of LPM. For data in program memory that may be located past 0xffff, a .progmemx section should be used. On LoongArch, linker relaxation time complexity is no longer quadratic with respect to relocation counts. Linking time of large software should be improved. In addition R_LARCH_32_PCREL records are now checked for overflow. Other binary utilities: New versioned release of libsframe: libsframe.so.2. This release introduces versioned symbols with version node name LIBSFRAME_2.0. Some new symbols have been added to support the new flag SFRAME_F_FDE_FUNC_START_PCREL and retrieving flags from SFrame decoder and encoder objects: - Addition of sframe_decoder_get_flags, sframe_decoder_get_offsetof_fde_start_addr, sframe_encoder_get_flags, sframe_encoder_get_offsetof_fde_start_addr. This release also includes backward-incompatible ABI changes: - Removal of sframe_get_funcdesc_with_addr. - Change in the behavior of sframe_decoder_get_funcdesc_v2, sframe_encoder_add_funcdesc_v2 and sframe_encoder_write. For SFrame stack trace format, the function start address in each SFrame FDE has a changed encoding: The 32-bit signed integer now holds the offset of the start PC of the associated function from the sfde_func_start_address field itself (instead of the earlier where it was the offset from the start of the SFrame section itself). All SFrame sections generated by gas and ld now default to this new encoding, setting the (new) SFRAME_F_FDE_FUNC_START_PCREL flag. Relocatable SFrame links are now fixed. Readelf now recognizes RISC-V GNU_PROPERTY_RISCV_FEATURE_1_CFI_SS and GNU_PROPERTY_RISCV_FEATURE_1_CFI_LP_UNLABELED for zicfiss and zicfilp extensions. The LoongArch disassembler now properly accepts multiple disassembly options given by -M, such as "-M no-aliases,numeric". (Previously only the first option took effect.) 2.44 Release Notes ------------------ Assembler: Support for new architecture extensions for AArch64, Risc-V and x86. Linker: The default maximum page size was changed from 16KiB to 64KiB for LoongArch. This now supports mixed LTO and non-LTO object files in relocatable output. The ELF forms of the linker support a --image-base= option for compatibility with LLD. The --build-id= option now accepts an argument of "xx" which enables the use of the xxhash library. This produces a 128-bit hash and is 2-4x faster than md5 or sha1. The ELF linker option --package-metadata supports percent-encoded and %[string] encoded JSON payloads. Disassembler: The RISC-V disassembler now supports -M,max option like QEMU to dump instruction without checking architecture support as usual. GprofNG: Support added for hardware event counters for Neoverse-N1, Ampere-1, and Appliedmicro processors. Support for the Nios II target has been removed. 2.43 Release Notes ------------------ Assembler: * Add a .base64 directive to the assembler which allows base64 encoded binary data to be provided as strings. * Assembler macros as well as the bodies of .irp / .irpc / .rept can now use the syntax \+ to access the number of times a given macro has been executed. This is similar to the already existing \@@ syntax, except that the count is maintained on a per-macro basis. * References to FB and dollar labels, when supported, are no longer permitted in a radix other than 10. (Note that definitions of such labels were already thus restricted, except that leading zeroes were permitted). Linker: * Add support for DT_RELR type compressed runtime relocations for the AArch64 and LoongArch architectures. * Add --rosegment option which changes the -z separate-code option so that only one read-only segment is created (instead of two). * Add --section-ordering-file option to add extra mapping of input sections to output sections. * Add -plugin-save-temps to store plugin intermediate files permanently. Utilities: * Readelf will now display DT_RELR relocations in full detail. * Readelf now has a -j/--display-section option which takes the name or index of a section and displays its contents according to its type. The option can be used multiple times on the command line to display multiple sections. * When objdump or readelf are used to display the contents of a .eh_frame section they will now also display the contents of the .eh_frame_hdr section, if present. Gprofng: * Improved the support for hardware event counters: - Re-designed and streamlined the implementation. - Defined a common set of events for ARM processors. - Added specific events for AMD ZEN3 / ZEN4, and Intel Ice Lake processors. * Added a minimal support for RISC-V. General: * Target specific improvements for many architectures. @ text @d1 1 a1 1 This is sframe-spec.info, produced by makeinfo version 7.1.1 from d4 1 a4 1 Copyright © 2021-2025 Free Software Foundation, Inc. d9 2 a10 2 license is included in the section entitled "GNU General Public License". d23 2 a24 2 This manual describes version 2 (errata 1) of the SFrame file format. SFrame stands for Simple Frame. The SFrame format keeps track of the d37 1 a37 6 * SFrame Section:: * ABI/arch-specific Definition:: Appendices * Generating Stack Traces using SFrame:: d41 1 a41 1 File: sframe-spec.info, Node: Introduction, Next: SFrame Section, Prev: Top, Up: Top d59 1 a59 2 appears in segment of type PT_GNU_SFRAME. An ELF SFrame section will have the type SHT_GNU_SFRAME. d62 1 a62 1 namely, AMD64, AAPCS64, and s390x. d72 1 a72 1 is targeted to be used. An SFrame section reader may use the magic d99 6 a104 8 • 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 a106 39 • [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_address’ field contains the offset in bytes to the start PC of the associated function from the field itself. − if unset, ‘sfde_func_start_address’ 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. SFrame version 1 is now obsolete and should not be used. d109 1 a109 1 File: sframe-spec.info, Node: SFrame Section, Next: ABI/arch-specific Definition, Prev: Introduction, Up: Top d111 1 a111 1 2 SFrame Section d115 3 a117 3 preamble, and two other sub-sections, namely the SFrame function descriptor entry (SFrame FDE) sub-section, and the SFrame frame row entry (SFrame FRE) sub-section. d127 1 a127 1 File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame Section d133 1 a133 1 section whose format cannot vary between versions. d147 11 a157 13 Offset Type Name Description ------------------------------------------------------------------------------------- 0x00 ‘uint16_t’ ‘sfp_magic’ The magic number for SFrame section: 0xdee2. Defined as a macro ‘SFRAME_MAGIC’. 0x02 ‘uint8_t’ ‘sfp_version’ The version number of this SFrame section. *Note SFrame Version::, for the set of valid values. Current version is ‘SFRAME_VERSION_2’. 0x03 ‘uint8_t’ ‘sfp_flags’ Flags (section-wide) for this SFrame section. *Note SFrame Flags::, for the set of valid values. d161 3 a163 3 * SFrame Magic Number and Endianness:: * SFrame Version:: * SFrame Flags:: d166 1 a166 1 File: sframe-spec.info, Node: SFrame Magic Number and Endianness, Next: SFrame Version, Up: SFrame Preamble d168 2 a169 2 2.1.1 SFrame Magic Number and Endianness ---------------------------------------- d172 4 a175 4 consumes them. A consumer library reading or writing SFrame sections should detect foreign-endianness by inspecting the SFrame magic number in the ‘sfp_magic’ field in the SFrame header. It may then provide means to endian-flip the SFrame section as necessary. d178 1 a178 1 File: sframe-spec.info, Node: SFrame Version, Next: SFrame Flags, Prev: SFrame Magic Number and Endianness, Up: SFrame Preamble d180 1 a180 1 2.1.2 SFrame Version d186 1 a186 1 Version Name Number Description d194 1 a194 1 File: sframe-spec.info, Node: SFrame Flags, Prev: SFrame Version, Up: SFrame Preamble d196 1 a196 1 2.1.3 SFrame Flags d204 6 a209 19 Flag Version Value Meaning -------------------------------------------------------------------------------------- ‘SFRAME_F_FDE_SORTED’ All 0x1 Function Descriptor Entries are sorted on PC. ‘SFRAME_F_FRAME_POINTER’ All 0x2 All functions in the object file preserve frame pointer. ‘SFRAME_F_FDE_FUNC_START_PCREL’2 0x4 The ‘sfde_func_start_address’ field in the SFrame FDE is an offset in bytes to the function's start address, from the field itself. If unset, the ‘sfde_func_start_address’ field in the SFrame FDE is an offset in bytes to the function's start address, from the start of the SFrame section. 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. d211 1 a211 2 Further flags may be added in future. Bits corresponding to the currently undefined flags must be set to zero. d214 1 a214 1 File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame Section a252 12 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. *Note SFrame Function Descriptor Entries::. 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. *Note SFrame Frame Row Entries::. d255 2 a256 2 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, d260 7 a266 10 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. d270 39 a308 31 Offset Type Name Description ------------------------------------------------------------------------------------- 0x00 ‘sframe_ ‘sfh_preamble’ The SFrame preamble. preamble’ *Note SFrame Preamble::. 0x04 ‘uint8_t’ ‘sfh_abi_arch’ The ABI/arch identifier. *Note SFrame ABI/arch Identifier::. 0x05 ‘int8_t’ ‘sfh_cfa_fixed_fp_offset’ The CFA fixed FP offset, if any. 0x06 ‘int8_t’ ‘sfh_cfa_fixed_ra_offset’ The CFA fixed RA offset, if any. 0x07 ‘uint8_t’ ‘sfh_auxhdr_len’ Size in bytes of the auxiliary header that follows the ‘sframe_header’ structure. 0x08 ‘uint32_t’ ‘sfh_num_fdes’ The number of SFrame FDEs in the section. 0x0c ‘uint32_t’ ‘sfh_num_fres’ The number of SFrame FREs in the section. 0x10 ‘uint32_t’ ‘sfh_fre_len’ The length in bytes of the SFrame FRE sub-section. 0x14 ‘uint32_t’ ‘sfh_fdeoff’ The offset in bytes to the SFrame FDE sub-section. 0x18 ‘uint32_t’ ‘sfh_freoff’ The offset in bytes to the SFrame FRE sub-section. d312 1 a312 1 * SFrame ABI/arch Identifier:: d315 1 a315 1 File: sframe-spec.info, Node: SFrame ABI/arch Identifier, Up: SFrame Header d317 1 a317 1 2.2.1 SFrame ABI/arch Identifier a333 2 ‘SFRAME_ABI_S390X_ENDIAN_BIG’ 4 s390x big-endian d336 1 a336 2 allow stack trace generators to make certain ABI/arch-specific decisions. d339 1 a339 1 File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame Section d344 1 a344 1 The SFrame function descriptor entry sub-section is an array of the d347 1 a347 8 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. d365 2 a366 2 sub-section (unlike the sub-section offsets in the SFrame header, which are relative to the _end_ of the SFrame header). d368 3 a370 8 ‘sfde_func_info’ is the SFrame FDE "info word", containing information on the FRE type and the FDE type for the function *Note 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, *Note The SFrame FDE Info Word::, that may be used for the purpose of extending the SFrame file format specification for future ABIs. d374 31 a404 39 Offset Type Name Description ---------------------------------------------------------------------------------------------- 0x00 ‘int32_t’ ‘sfde_func_start_address’ Signed 32-bit integral field denoting the virtual memory address of the described function, for which the SFrame FDE applies. If the flag ‘SFRAME_F_FDE_FUNC_START_PCREL’, *Note SFrame Flags::, in the SFrame header is set, the value encoded in the ‘sfde_func_start_address’ field is the offset in bytes to the function's start address, from the SFrame ‘sfde_func_start_address’ field. 0x04 ‘uint32_t’ ‘sfde_func_size’ Unsigned 32-bit integral field specifying the size of the function in bytes. 0x08 ‘uint32_t’ ‘sfde_func_start_fre_off’ Unsigned 32-bit integral field specifying the offset in bytes of the function's first SFrame FRE in the SFrame section. 0x0c ‘uint32_t’ ‘sfde_func_num_fres’ Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. 0x10 ‘uint8_t’ ‘sfde_func_info’ Unsigned 8-bit integral field specifying the SFrame FDE info word. *Note The SFrame FDE Info Word::. 0x11 ‘uint8_t’ ‘sfde_func_rep_size’ 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. 0x12 ‘uint16_t’ ‘sfde_func_padding2’ Padding of 2 bytes. Currently unused bytes. d408 3 a410 3 * The SFrame FDE Info Word:: * The SFrame FDE Types:: * The SFrame FRE Types:: d413 1 a413 1 File: sframe-spec.info, Node: The SFrame FDE Info Word, Next: The SFrame FDE Types, Up: SFrame Function Descriptor Entries d415 1 a415 1 2.3.1 The SFrame FDE Info Word d422 1 a422 1 7-6 ‘unused’ Unused bits. d424 2 a425 2 5 ‘pauth_key’ (For AARCH64) Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: a427 1 Ununsed in AMD64. d432 1 a432 1 *Note The SFrame FDE Types::. d434 2 a435 2 0-3 ‘fretype’ Choice of three SFrame FRE types. *Note The SFrame FRE Types::. d438 1 a438 1 File: sframe-spec.info, Node: The SFrame FDE Types, Next: The SFrame FRE Types, Prev: The SFrame FDE Info Word, Up: SFrame Function Descriptor Entries d440 1 a440 1 2.3.2 The SFrame FDE Types d443 1 a443 1 The SFrame format defines two types of FDE entries. The choice of which d461 1 a461 1 SFRAME_FDE_TYPE_PCINC 0 Stacktracers perform a d465 1 a465 1 SFRAME_FDE_TYPE_PCMASK 1 Stacktracers perform a d470 1 a470 2 program instructions and is encoded via ‘sfde_func_rep_size’ in the SFrame FDE. d474 1 a474 1 File: sframe-spec.info, Node: The SFrame FRE Types, Prev: The SFrame FDE Types, Up: SFrame Function Descriptor Entries d476 1 a476 1 2.3.3 The SFrame FRE Types d480 4 a483 4 SFrame format defines three types of SFrame FRE entries to effeciently encode the stack trace information for such a variety of function sizes. These representations vary in the number of bits needed to encode the start address offset in the SFrame FRE. d490 4 a493 3 ------------------------------------------------------------------------------- ‘SFRAME_FRE_TYPE_ADDR1’ 0 The start address offset (in bytes) of the SFrame FRE is an unsigned 8-bit value. d495 3 a497 2 ‘SFRAME_FRE_TYPE_ADDR2’ 1 The start address offset (in bytes) of the SFrame FRE is an unsigned 16-bit value. d499 3 a501 2 ‘SFRAME_FRE_TYPE_ADDR4’ 2 The start address offset (in bytes) of the SFrame FRE is an unsigned 32-bit value. d504 2 a505 3 The identifier to reflect the chosen SFrame FRE type is stored in the ‘fretype’ bits in the SFrame FDE info word, *Note The SFrame FDE Info Word::. d508 1 a508 1 File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame Section d513 26 a538 31 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 *Note 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, *Note ABI/arch-specific Definition::. d540 1 a540 1 Next, the definitions of the three SFrame FRE types are as follows: d566 1 a566 1 field denoting the start address of a range of program counters, for d568 2 a569 2 ‘sfre_start_address’ field is the offset in bytes of the range's start address, from the start address of the function. d571 1 a571 1 Further SFrame FRE types may be added in future. d575 1 a575 1 * The SFrame FRE Info Word:: d578 1 a578 1 File: sframe-spec.info, Node: The SFrame FRE Info Word, Up: SFrame Frame Row Entries d580 1 a580 1 2.4.1 The SFrame FRE Info Word d598 2 a599 3 1-4 ‘fre_offset_count’ A max value of 15 is allowed. Typically, a value of upto 3 is sufficient for most ABIs to track all three of CFA, FP and RA. d619 1 a619 238 File: sframe-spec.info, Node: ABI/arch-specific Definition, Next: Generating Stack Traces using SFrame, Prev: SFrame Section, Up: Top 3 ABI/arch-specific Definition ****************************** This section covers the ABI/arch-specific definition of the SFrame file format. Currently, the only part of the SFrame file format definition that is ABI/arch-specific is the interpretation of the variable number of bytes at the tail end of each SFrame FRE. Currently, these bytes are used for representing stack offsets (for AMD64 and AARCH64 ABIs). For s390x ABI, the interpretation of these bytes may be stack offsets or even register numbers. It is recommended to peruse this section along with *Note SFrame Frame Row Entries:: for clarity of context. Future ABIs must specify the algorithm for identifying the appropriate SFrame FRE stack offsets in this chapter. This should inevitably include the blueprint for interpreting the variable number of bytes at the tail end of the SFrame FRE for the specific ABI/arch. Any further provisions, e.g., using the auxiliary SFrame header, etc., if used, must also be outlined here. * Menu: * AMD64:: * AArch64:: * s390x::  File: sframe-spec.info, Node: AMD64, Next: AArch64, Up: ABI/arch-specific Definition 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. *Note 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: Offset ID Interpretation in AMD64 ----------------------------------------------- 1 CFA = ‘BASE_REG’ + offset1 2 FP = CFA + offset2  File: sframe-spec.info, Node: AArch64, Next: s390x, Prev: AMD64, Up: ABI/arch-specific Definition 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: Offset ID Interpretation in AArch64 --------------------------------------------- 1 CFA = ‘BASE_REG’ + offset1 2 RA = CFA + offset2 3 FP = CFA + offset3  File: sframe-spec.info, Node: s390x, Prev: AArch64, Up: ABI/arch-specific Definition 3.3 s390x ========= A stack tracer implementation must initialize the SP to the designated SP register value, the FP to the preferred FP register value, and the RA to the designated RA register value in the topmost stack frame of the callchain. This is required, as either the SP or FP is used as CFA base register and as the FP and/or RA are not necessarily saved on the stack. For RA this may only be the case in the topmost stack frame of the callchain. For FP this may be the case in any stack frame. Irrespective of the ABI, the first stack offset is always used to locate the CFA. On s390x the value of the offset is stored adjusted by the s390x-specific ‘SFRAME_S390X_CFA_OFFSET_ADJUSTMENT’ and scaled down by the s390x-specific ‘SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR’, to enable and improve the use of signed 8-bit offsets on s390x. s390x-specific helpers ‘SFRAME_V2_S390X_CFA_OFFSET_ENCODE’ and ‘SFRAME_V2_S390X_CFA_OFFSET_DECODE’ are provided to perform or undo the adjustment and scaling. The CFA offset can therefore be interpreted as: CFA = ‘BASE_REG’ + offset1 - ‘SFRAME_S390X_CFA_OFFSET_ADJUSTMENT’ or CFA = ‘BASE_REG’ + (offset1 * ‘SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR’) - ‘SFRAME_S390X_CFA_OFFSET_ADJUSTMENT’. The identification of the ‘BASE_REG’ is done by using the ‘fre_cfa_base_reg_id’ field in the SFrame FRE info word. The (64-bit) s390x ELF ABI does not mandate the precise location in a function where the return address (RA) and frame pointer (FP) are saved, 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 stack slot, by interpreting it as: RA = CFA + offset2, unless the offset has a value of ‘SFRAME_FRE_RA_OFFSET_INVALID’. RA remains unchanged, if the offset is not available or has a value of ‘SFRAME_FRE_RA_OFFSET_INVALID’. Stack tracers are recommended to validate that the "unchanged RA" pattern, when present, is seen only for the topmost stack frame. The third stack offset is used to locate the FP stack slot, by interpreting it as: FP = CFA + offset3. FP remains unchanged, if the offset is not available. In leaf functions the RA and FP may be saved in other registers, such as floating-point registers (FPRs), instead of on the stack. To represent this in the SFrame stack trace format the DWARF register number is encoded as RA/FP offset using the least-significant bit (LSB) as indication: offset = (regnum << 1) | 1. A LSB of zero indicates a stack slot offset. A LSB of one indicates a DWARF register number, which is interpreted as: regnum = offset >> 1. Given the nature of leaf functions, this can only occur in the topmost frame during stack tracing. It is recommended that a stack tracer implementation performs the required checks to ensure that restoring FP and RA from the said register locations is done only for topmost stack frame in the callchain. Given the nature of things, the number of stack offsets and/or register numbers seen on s390x per SFrame FRE is either 1, 2, or 3. Hence, in summary: Offset ID Interpretation in s390x -------------------------------------------------------------------------- 1 CFA = ‘BASE_REG’ + offset1 2 RA stack slot = CFA + offset2, if (offset2 & 1 == 0) RA register number = offset2 >> 1, if (offset2 & 1 == 1) RA not saved if (offset2 == ‘SFRAME_FRE_RA_OFFSET_INVALID’) 3 FP stack slot = CFA + offset3, if (offset3 & 1 == 0) FP register number = offset3 >> 1, if (offset3 & 1 == 1) The s390x ELF ABI defines the CFA as stack pointer (SP) at call site +160. The SP can therefore be obtained using the SP value offset from CFA ‘SFRAME_S390X_SP_VAL_OFFSET’ of -160 as follows: SP = CFA + ‘SFRAME_S390X_SP_VAL_OFFSET’  File: sframe-spec.info, Node: Generating Stack Traces using SFrame, Next: Index, Prev: ABI/arch-specific Definition, Up: Top Appendix A Generating Stack Traces using SFrame *********************************************** Using some C-like pseudocode, this section highlights how SFrame provides a simple, fast and low-overhead mechanism to generate stack traces. Needless to say that for generating accurate and useful stack traces, several other aspects will need attention: finding and decoding bits of SFrame section(s) in the program binary, symbolization of addresses, to name a few. In the current context, a ‘frame’ is the abstract construct that encapsulates the following information: − program counter (PC), − stack pointer (SP), and − frame pointer (FP) With that said, establishing the first ‘frame’ should be trivial: // frame 0 frame->pc = current_IP; frame->sp = get_reg_value (REG_SP); frame->fp = get_reg_value (REG_FP); where ‘REG_SP’ and ‘REG_FP’ are are ABI-designated stack pointer and frame pointer registers respectively. Next, given frame N, generating stack trace needs us to get frame N+1. This can be done as follows: // Get the PC, SP, and FP for frame N. pc = frame->pc; sp = frame->sp; fp = frame->fp; // Populate frame N+1. int err = get_next_frame (&next_frame, pc, sp, fp); where given the values of the program counter, stack pointer and frame pointer from frame N, ‘get_next_frame’ populates the provided ‘next_frame’ object and returns the error code, if any. In the following pseudocode for ‘get_next_frame’, the ‘sframe_*’ functions fetch information from the SFrame section. fre = sframe_find_fre (pc); if (fre) // Whether the base register for CFA tracking is REG_FP. base_reg_val = sframe_fre_base_reg_fp_p (fre) ? fp : sp; // Get the CFA stack offset from the FRE. cfa_offset = sframe_fre_get_cfa_offset (fre); // Get the fixed RA offset or FRE stack offset as applicable. ra_offset = sframe_fre_get_ra_offset (fre); // Get the fixed FP offset or FRE stack offset as applicable. fp_offset = sframe_fre_get_fp_offset (fre); cfa = base_reg_val + cfa_offset; next_frame->sp = cfa [+ SFRAME_S390X_SP_VAL_OFFSET on s390x]; ra_stack_loc = cfa + ra_offset; // Get the address stored in the stack location. next_frame->pc = read_value (ra_stack_loc); if (fp_offset is VALID) fp_stack_loc = cfa + fp_offset; // Get the value stored in the stack location. next_frame->fp = read_value (fp_stack_loc); else // Continue to use the value of fp as it has not // been clobbered by the current frame yet. next_frame->fp = fp; else ret = ERR_NO_SFRAME_FRE;  File: sframe-spec.info, Node: Index, Prev: Generating Stack Traces using SFrame, Up: Top a626 2 * ABI/arch-specific Definition: ABI/arch-specific Definition. (line 6) d629 1 a629 2 * endianness: SFrame Magic Number and Endianness. (line 6) d632 1 a632 6 * Provisions for future ABIs: SFrame Header. (line 59) * Provisions for future ABIs <1>: SFrame Function Descriptor Entries. (line 41) * Provisions for future ABIs <2>: SFrame Frame Row Entries. (line 25) * SFrame ABI/arch Identifier: SFrame ABI/arch Identifier. d636 1 a636 1 * SFrame Flags: SFrame Flags. (line 6) a639 2 * SFrame magic number: SFrame Magic Number and Endianness. (line 6) d641 3 a643 3 * SFrame Section: SFrame Section. (line 6) * SFrame versions: SFrame Version. (line 9) * SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch Identifier. d645 1 a645 1 * SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch Identifier. d647 1 a647 1 * SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch Identifier. d649 13 a661 16 * SFRAME_ABI_S390X_ENDIAN_BIG: SFrame ABI/arch Identifier. (line 20) * SFRAME_F_FDE_FUNC_START_PCREL: SFrame Flags. (line 16) * SFRAME_F_FDE_SORTED: SFrame Flags. (line 11) * SFRAME_F_FRAME_POINTER: SFrame Flags. (line 14) * SFRAME_FDE_TYPE_PCINC: The SFrame FDE Types. (line 6) * SFRAME_FDE_TYPE_PCMASK: The SFrame FDE Types. (line 6) * SFRAME_FRE_OFFSET_1B: The SFrame FRE Info Word. (line 31) * SFRAME_FRE_OFFSET_2B: The SFrame FRE Info Word. (line 35) * SFRAME_FRE_OFFSET_4B: The SFrame FRE Info Word. (line 38) * SFRAME_FRE_TYPE_ADDR1: The SFrame FRE Types. (line 17) * SFRAME_FRE_TYPE_ADDR2: The SFrame FRE Types. (line 21) * SFRAME_FRE_TYPE_ADDR4: The SFrame FRE Types. (line 24) d663 5 a667 5 * SFRAME_VERSION_1: SFrame Version. (line 9) * The SFrame FDE Info Word: SFrame Function Descriptor Entries. (line 93) * The SFrame FRE Info Word: SFrame Frame Row Entries. (line 74) d672 18 a689 23 Node: Top565 Node: Introduction1249 Node: Overview1435 Node: Changes from Version 1 to Version 23076 Node: SFrame Section6253 Node: SFrame Preamble6752 Node: SFrame Magic Number and Endianness8351 Node: SFrame Version8887 Node: SFrame Flags9480 Node: SFrame Header11202 Node: SFrame ABI/arch Identifier16760 Node: SFrame Function Descriptor Entries17908 Node: The SFrame FDE Info Word23141 Node: The SFrame FDE Types24371 Node: The SFrame FRE Types26205 Node: SFrame Frame Row Entries27709 Node: The SFrame FRE Info Word30791 Node: ABI/arch-specific Definition32897 Node: AMD6434085 Node: AArch6435209 Node: s390x36448 Node: Generating Stack Traces using SFrame40448 Node: Index43547 @ 1.1.1.3 log @Import binutils-2.46.0 (previous was 2.45) Changes in 2.45: * New versioned release of libsframe: libsframe.so.2. This release introduces versioned symbols with version node name LIBSFRAME_2.0. Some new symbols have been added to support the new flag SFRAME_F_FDE_FUNC_START_PCREL and retrieving flags from SFrame decoder and encoder objects: - Addition of sframe_decoder_get_flags, sframe_decoder_get_offsetof_fde_start_addr, sframe_encoder_get_flags, sframe_encoder_get_offsetof_fde_start_addr. This release also includes backward-incompatible ABI changes: - Removal of sframe_get_funcdesc_with_addr. - Change in the behavior of sframe_decoder_get_funcdesc_v2, sframe_encoder_add_funcdesc_v2 and sframe_encoder_write. * On s390 64-bit (s390x), gas, ld, objdump, and readelf now support generating and processing SFrame V2 stack trace information (.sframe). The assembler generates SFrame info from CFI directives with option "--gsframe". The linker generates SFrame info for the linker-generated .plt section and merges all .sframe sections. Both objdump and readelf dump SFrame info with option "--sframe[=]". * For SFrame stack trace format, the function start address in each SFrame FDE has a changed encoding: The 32-bit signed integer now holds the offset of the start PC of the associated function from the sfde_func_start_address field itself (instead of the earlier where it was the offset from the start of the SFrame section itself). All SFrame sections generated by gas and ld now default to this new encoding, setting the (new) SFRAME_F_FDE_FUNC_START_PCREL flag. Relocatable SFrame links are now fixed. * Readelf now recognizes RISC-V GNU_PROPERTY_RISCV_FEATURE_1_CFI_SS and GNU_PROPERTY_RISCV_FEATURE_1_CFI_LP_UNLABELED for zicfiss and zicfilp extensions. * For RISC-V dis-assembler, the definition of mapping symbol $x is changed, so the file needs to be rebuilt since 2.45 once used .option arch directives. * The LoongArch disassembler now properly accepts multiple disassembly options given by -M, such as "-M no-aliases,numeric". (Previously only the first option took effect.) @ text @d1 1 a1 1 This is sframe-spec.info, produced by makeinfo version 7.2 from d4 1 a4 1 Copyright © 2021-2026 Free Software Foundation, Inc. d23 3 a25 5 February 10, 2026 This manual describes Version 3 of the SFrame file format. SFrame stands for Simple Frame. The SFrame format keeps track of the minimal necessary information needed for generating stack traces: d38 1 a38 1 * Interpretation of SFrame FREs:: a53 1 * Changes from Version 2 to Version 3:: d57 1 a57 1 File: sframe-spec.info, Node: Overview, Next: Changes from Version 2 to Version 3, Up: Introduction d63 3 a65 3 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’. d72 1 a72 1 header and the SFrame function descriptor index) have elements at their d82 1 a82 4 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. d85 1 a85 1 format, ‘SFRAME_VERSION_3’, in detail. Additional sections outline the d89 4 d97 1 a97 54 File: sframe-spec.info, Node: Changes from Version 2 to Version 3, Next: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction 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_B’ to ‘SFRAME_FRE_DATAWORD_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’.  File: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Changes from Version 2 to Version 3, Up: Introduction d99 1 a99 1 1.3 Changes from Version 1 to Version 2 d107 2 a108 2 Such code blocks, e.g., pltN entries, use an SFrame function descriptor entry of type ‘SFRAME_FDE_PCTYPE_MASK’. d114 1 a114 1 format Version 1. d118 1 a118 1 − if set, ‘sfde_func_start_offset’ field contains the offset in d121 1 a121 1 − if unset, ‘sfde_func_start_offset’ field contains the offset d128 1 a128 1 added to SFrame Version 2 only: d151 1 a151 6 • [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. d153 1 a153 1 SFrame Version 1 is now obsolete and should not be used. d156 1 a156 1 File: sframe-spec.info, Node: SFrame Section, Next: Interpretation of SFrame FREs, Prev: Introduction, Up: Top d202 1 a202 1 ‘SFRAME_VERSION_3’. d238 1 a238 2 ‘SFRAME_VERSION_2’ 2 Second version. ‘SFRAME_VERSION_3’ 3 Third version, under development. d240 1 a240 1 This document describes ‘SFRAME_VERSION_3’. d257 1 a257 1 ‘SFRAME_F_FRAME_POINTER’ 1-2 0x2 All functions in the object file d259 1 a259 1 ‘SFRAME_F_FDE_FUNC_START_PCREL’2-3 0x4 The ‘sfdi_func_start_offset’ field in d263 1 a263 1 ‘sfdi_func_start_offset’ field in the d268 1 a268 1 The purpose of ‘SFRAME_F_FRAME_POINTER’ flag was to facilitate stack d285 3 a287 3 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 d320 1 a320 1 *note SFrame Function Descriptor Entries::. d323 3 a325 4 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. *Note SFrame Frame Row d392 1 a392 1 SFrame section, is intended. There are currently four identifiable d398 1 a398 1 ‘SFRAME_ABI_AARCH64_ENDIAN_BIG’ 1 AArch64 big-endian d400 1 a400 1 ‘SFRAME_ABI_AARCH64_ENDIAN_LITTLE’ 2 AArch64 little-endian d417 11 a427 7 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. d429 27 a455 1 * Menu: d457 1 a457 29 * The SFrame FDE Index:: * The SFrame FDE Attribute:: * The SFrame FDE Info Bytes::  File: sframe-spec.info, Node: The SFrame FDE Index, Next: The SFrame FDE Attribute, Up: SFrame Function Descriptor Entries 2.3.1 The SFrame FDE Index -------------------------- The SFrame FDE index entries are stored in a sub-section of their own, forming a searchable index. If the SFrame header flag ‘SFRAME_F_FDE_SORTED’ is set, then the entries are sorted by ‘sfdi_func_start_offset’, allowing for efficient binary search. 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 a binary search scheme to look for the stack trace information pertinent to a given PC. 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; Each entry of the SFrame function descriptor index is naturally aligned. The following table describes each component of the SFrame FDE index entry: d461 4 a464 3 0x00 ‘int64_t’ ‘sfdi_func_start_offset’ Signed 64-bit integral field specifying the offset to the start address of the described function. If the flag d468 1 a468 1 ‘sfdi_func_start_offset’ field is the d470 2 a471 4 address from the ‘sfdi_func_start_offset’ field itself. Otherwise, it is the offset in bytes from the start of the SFrame section. d473 1 a473 1 0x08 ‘uint32_t’ ‘sfdi_func_size’ Unsigned 32-bit integral field specifying d476 21 a496 5 0x0c ‘uint32_t’ ‘sfdi_func_start_fre_off’ Unsigned 32-bit integral field specifying the offset to the start of the function's stack trace data (SFrame FREs). This offset is relative to the _beginning of the SFrame FRE sub-section_. a498 105  File: sframe-spec.info, Node: The SFrame FDE Attribute, Next: The SFrame FDE Info Bytes, Prev: The SFrame FDE Index, Up: SFrame Function Descriptor Entries 2.3.2 The SFrame FDE Attribute ------------------------------ The SFrame FDE attribute structure provides information about the SFrame FRE entries that follow: their number and their encoding. The SFrame FDE attributes are stored at the beginning of each function's stack trace data within the SFrame FRE sub-section. Because these structures are interleaved with variable-length FREs, their elements are not guaranteed to be at naturally aligned boundaries. 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; Following table describes each component of the SFrame FDE attribute: Offset Type Name Description --------------------------------------------------------------------------------------------- 0x00 ‘uint16_t’ ‘sfda_func_num_fres’ Unsigned 16-bit integral field specifying the total number of SFrame FREs used for the function. 0x02 ‘uint8_t’ ‘sfda_func_info’ Unsigned 8-bit integral field specifying the SFrame FDE info byte. 0x03 ‘uint8_t’ ‘sfda_func_info2’ Additional unsigned 8-bit integral field specifying the SFrame FDE info byte. 0x04 ‘uint8_t’ ‘sfda_func_rep_size’ Unsigned 8-bit integral field specifying the size of the repetitive code block for which an SFrame FDE of type ‘SFRAME_FDE_PCTYPE_MASK’ is used. For example, in AMD64, the size of a pltN entry is 16 bytes. ‘sfda_func_info’ and ‘sfda_func_info2’ are the SFrame FDE *Info Bytes*, containing information like the FRE type and their encoding, and the FDE type for the function. *Note The SFrame FDE Info Bytes::. The SFrame FDE attribute has some currently unused bits in the SFrame FDE info bytes, that may be used for the purpose of extending the SFrame file format specification for future ABIs. *Note The SFrame FDE Types:: subsection.  File: sframe-spec.info, Node: The SFrame FDE Info Bytes, Prev: The SFrame FDE Attribute, Up: SFrame Function Descriptor Entries 2.3.3 The SFrame FDE Info Bytes ------------------------------- The SFrame FDE Attribute contains two distinct bytes, ‘sfda_func_info’ and ‘sfda_func_info2’. Together these are referred to as the SFrame FDE info bytes. These bytes contain vital information necessary to: − read and interpret SFrame FRE data, e.g., the number and size of each SFrame FRE offset, − PC Type for SFrame FDE, − type of SFrame FDE, − size of repeat block, if PC Type is ‘SFRAME_FDE_PCTYPE_MASK’. The first info byte ‘sfda_func_info’ is a bitfield split into four parts. From MSB to LSB: Bit offset Name Description ----------------------------------------------------------------------------------------- 7 ‘signal_p’ Signal frame. 6 ‘unused’ Unused bit. 5 ‘pauth_key’ (For AArch64) Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: ‘SFRAME_AARCH64_PAUTH_KEY_A’ (0), or ‘SFRAME_AARCH64_PAUTH_KEY_B’ (1). Unsed in AMD64, s390x 4 ‘fde_pctype’ Specify the SFrame FDE PC Type. Two possible values: ‘SFRAME_FDE_PCTYPE_MASK’ (1), or ‘SFRAME_FDE_PCTYPE_INC’ (0). *Note The SFrame FDE PC Types::. 0-3 ‘fre_type’ Choice of three SFrame FRE types. *Note The SFrame FRE Types::. The second info byte ‘sfda_func_info2’ is a bitfield split into two parts. From MSB to LSB: Bit offset Name Description --------------------------------------------------------------------------------------- 7-5 ‘unused’ Unused bits. 4-0 ‘fde_type’ Specify the SFrame FDE type. Two possible values: ‘SFRAME_FDE_TYPE_DEFAULT’ (0), or ‘SFRAME_FDE_TYPE_FLEX’ (1). *Note The SFrame FDE Types::. d501 1 a501 1 * The SFrame FDE PC Types:: d506 1 a506 1 File: sframe-spec.info, Node: The SFrame FDE PC Types, Next: The SFrame FDE Types, Up: The SFrame FDE Info Bytes d508 2 a509 2 2.3.3.1 The SFrame FDE PC Types ............................... d511 1 a511 13 The SFrame format defines two types of FDE PC types. The choice of which SFrame FDE PC type to use is made based on the instruction patterns in the relevant program stub. An FDE of PC type ‘SFRAME_V3_FDE_PCTYPE_INC’ contains FREs whose PCs are to be interpreted as the address of a single instruction, measured in bytes and relative to the beginning of the function. In contrast, a FDE of PC type ‘SFRAME_V3_FDE_PCTYPE_MASK’ contains FREs whose PCs are to be interpreted as masks that identify several instructions. This is useful for cases where a small pattern of instructions in a program stub is used repeteadly for a specific functionality, like PLT entries and trampolines. d513 17 a529 15 Name of SFrame FDE PC Type Value Description ----------------------------------------------------------------------------------- ‘SFRAME_V3_FDE_PCTYPE_INC’ 0 Stacktracers perform a (PC >= FRE_START_ADDR) to look up a matching FRE. ‘SFRAME_V3_FDE_PCTYPE_MASK’ 1 Stacktracers perform a (PC % REP_BLOCK_SIZE >= FRE_START_ADDR) to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the repeating block of program instructions and is encoded via ‘sfde_func_rep_size’ in the SFrame FDE. d532 1 a532 1 File: sframe-spec.info, Node: The SFrame FDE Types, Next: The SFrame FRE Types, Prev: The SFrame FDE PC Types, Up: The SFrame FDE Info Bytes d534 2 a535 2 2.3.3.2 The SFrame FDE Types ............................ d537 30 a566 39 The SFrame format defines two types of Function Descriptor Entries (FDEs) to encode stack trace information. The choice of FDE type determines how the data in the variable-length Frame Row Entries (FREs) is interpreted. The FDE type is encoded in the lower 5 bits of the ‘sfda_func_info2’ field in the SFrame FDE attribute. Name Value Description ---------------------------------------------------------------------------------------- ‘SFRAME_FDE_TYPE_DEFAULT’ 0 The default FDE type. CFA is recovered using the Stack Pointer (SP) or Frame Pointer (FP) plus a signed offset. Return Address (RA) and Frame Pointer (FP) are recovered using the CFA plus a signed offset (or a fixed register for specific architectures like s390x). The variable-length array of bytes trailing each SFrame FRE are interpreted according to the ABI/arch-specific rules for the target architecture. More details in *note Default FDE Type Interpretation::. ‘SFRAME_FDE_TYPE_FLEX’ 1 The flexible FDE type. Used for complex cases such as stack realignment (DRAP), non-standard CFA base registers, or when RA/FP recovery requires dereferencing or non-CFA base registers. The variable-length array of bytes may be interpreted as pairs of Control Data and Offset Data (or Padding Data), allowing for complex recovery rules (e.g., DRAP on AMD64, Stack Realignment). More details in *note Flexible FDE Type Interpretation::. Currently, five bits are reserved in the ‘sfda_func_info2’ for indicating SFrame FDE types. In future, other ABIs/architectures may add even arch-specific FDE types. Each distinct FDE type may define a different layout, encoding, and interpretation of the variable-length data words trailing each SFrame FRE. d569 1 a569 1 File: sframe-spec.info, Node: The SFrame FRE Types, Prev: The SFrame FDE Types, Up: The SFrame FDE Info Bytes d571 2 a572 2 2.3.3.3 The SFrame FRE Types ............................ d575 1 a575 1 SFrame format defines three types of SFrame FRE entries to efficiently d597 2 a598 2 ‘fre_type’ bits in the SFrame FDE info byte, *Note The SFrame FDE Info Bytes::. d612 4 a615 17 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. d617 5 a621 2 The entities ‘S’, ‘N’ are encoded in the SFrame FRE info byte, via the ‘fre_dataword_size’ and the ‘fre_dataword_count’ respectively. More d623 1 a623 1 ‘N’ is provided later in the *note The SFrame FRE Info Word::. d626 3 a628 4 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. d630 2 a631 2 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 d633 4 a636 3 these bytes is specific to ABI/arch or FDE type. More details about the precise interpretation are covered in the section *note Interpretation of SFrame FREs::. d681 1 a681 1 The SFrame FRE info byte is a bitfield split into four parts. From MSB d685 4 a688 3 ------------------------------------------------------------------------------------------------ 7 ‘fre_mangled_ra_p’ Indicate whether the return address is mangled with any authorization bits (signed RA). d690 5 a694 4 5-6 ‘fre_dataword_size’ Size of data word in bytes. Valid values are: ‘SFRAME_FRE_DATAWORD_1B’, ‘SFRAME_FRE_DATAWORD_2B’, and ‘SFRAME_FRE_DATAWORD_4B’. d696 3 a698 7 1-4 ‘fre_dataword_count’ Being a 4-bit sized field, a max value of 15 is allowed. Typically, a value of up to 3 is sufficient for most ABIs to track all three of CFA, FP and RA. A value of zero indicates that the return address (RA) is undefined. A stack tracer may use this as indication that an outermost frame has been reached and the stack trace is complete. d700 2 a701 1 0 ‘fre_cfa_base_reg_id’ Distinguish between SP or FP based CFA recovery. d704 29 a732 12 Name Value Description ------------------------------------------------------------------------------------ ‘SFRAME_FRE_DATAWORD_1B’ 0 All data words following the fixed-length FRE structure are 1 byte long. ‘SFRAME_FRE_DATAWORD_2B’ 1 All data words following the fixed-length FRE structure are 2 bytes long. ‘SFRAME_FRE_DATAWORD_4B’ 2 All data words following the fixed-length FRE structure are 4 bytes long. d734 6 a739 29  File: sframe-spec.info, Node: Interpretation of SFrame FREs, Next: Generating Stack Traces using SFrame, Prev: SFrame Section, Up: Top 3 Interpretation of SFrame FREs ******************************* Each SFrame Frame Row Entry (FRE) provides information about a PC range within some function, encoded using a variable number of bytes (*note SFrame Frame Row Entries::). The interpretation of these bytes depends on the FDE type used to represent stack tracing information for the function. * Menu: * Default FDE Type Interpretation:: * Flexible FDE Type Interpretation::  File: sframe-spec.info, Node: Default FDE Type Interpretation, Next: Flexible FDE Type Interpretation, Up: Interpretation of SFrame FREs 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. d748 1 a748 1 File: sframe-spec.info, Node: AMD64, Next: AArch64, Up: Default FDE Type Interpretation d750 2 a751 2 3.1.1 AMD64 ----------- d756 1 a756 1 ‘fre_cfa_base_reg_id’ field in the SFrame FRE info byte. d777 1 a777 1 File: sframe-spec.info, Node: AArch64, Next: s390x, Prev: AMD64, Up: Default FDE Type Interpretation d779 2 a780 2 3.1.2 AArch64 ------------- d785 1 a785 1 ‘fre_cfa_base_reg_id’ field in the SFrame FRE info byte. d787 1 a787 1 In AArch64, the AAPCS64 standard specifies that the Frame Record d797 1 a797 1 AArch64 per SFrame FRE is either 1 or 3. d808 1 a808 1 File: sframe-spec.info, Node: s390x, Prev: AArch64, Up: Default FDE Type Interpretation d810 2 a811 2 3.1.3 s390x ----------- d833 1 a833 1 SFrame FRE info byte. d849 11 a859 3 as floating-point registers (FPRs), instead of being saved on the stack. To represent this in the SFrame stack trace format, SFrame FDE of type ‘SFRAME_FDE_TYPE_FLEX’ may be used. d861 2 a862 2 Given the nature of things, for default type FDEs, the number of stack offsets seen on s390x per SFrame FRE is either 1, 2, or 3. d869 2 a870 1 2 RA stack slot = CFA + offset2 d872 2 a873 1 3 FP stack slot = CFA + offset3 a879 5 Future ABIs must specify the algorithm for identifying the appropriate SFrame FRE stack offsets in this chapter. This should inevitably include the blueprint for interpreting the variable number of bytes at the tail end of the SFrame FRE for the specific ABI/arch. d881 1 a881 112 File: sframe-spec.info, Node: Flexible FDE Type Interpretation, Prev: Default FDE Type Interpretation, Up: Interpretation of SFrame FREs 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: Bit Offset Name Description ---------------------------------------------------------------------------------- 0 ‘reg_p’ Register-based Location Rule If 1, the base is a DWARF register (encoded in bits 3+). If 0, the base is the CFA (used for RA/FP recovery). 1 ‘deref_p’ Dereference Flag If 1, the location of the value is the address (‘Base + Offset’), i.e., value = ‘*(Base + Offset)’. If 0, the value is ‘Base + Offset’. 2 ‘unused’ Unused bit. 3+ ‘regnum’ The DWARF register number used as the base. Effective only if ‘reg_p’ is 1. 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).  File: sframe-spec.info, Node: Generating Stack Traces using SFrame, Next: Index, Prev: Interpretation of SFrame FREs, Up: Top d921 3 a923 6 ‘next_frame’ object and returns the error code, if any. In the following pseudocode for ‘get_next_frame’, the ‘sframe_*’ functions fetch information from the SFrame section. Note that the stack tracer must retrieve the FDE type to decide how to interpret the FRE data words. d925 2 a926 2 fre = sframe_find_fre (pc, &fde_type); if (fre && fde_type == SFRAME_FDE_TYPE_DEFAULT) a950 47 For SFrame FDE of type ‘SFRAME_FDE_TYPE_FLEX’, read the set of data words and apply the recovery rules accordingly. if (fre && fde_type == SFRAME_FDE_TYPE_FLEX) // Get the base register, offset, and deref_p for CFA tracking. // The first FRE offset (index 0) is the CFA Control Data. cfa_reg_data = sframe_fre_get_offset (fre, 0); cfa_offset = sframe_fre_get_offset (fre, 1); // Get the RA reg, offset, and deref_p. // The third FRE data word (index 2) is the RA Control Data. ra_reg_data = sframe_fre_get_udata (fre, 2); if (ra_reg_data != SFRAME_FRE_RA_OFFSET_INVALID) ra_offset = sframe_fre_get_offset (fre, 3); fp_tracking_p = fre.num_offsets > 3; fp_data_index = 3; else fp_tracking_p = fre.num_offsets > 4; fp_data_index = 4; // Get the FP reg, offset, and deref_p (if present). if (fp_tracking_p) fp_reg_data = sframe_fre_get_udata (fre, fp_data_index); fp_offset = sframe_fre_get_fp_offset (fre); // Safety check for topmost frames: // If recovery requires non-standard registers (not SP/FP), // it is only valid if we are at the top of the stack // (where those registers haven't been clobbered). cfa_base_reg = SFRAME_V3_FLEX_FDE_OFFSET_REG_NUM (cfa_reg_data); if (!topmost_frame_p && (cfa_base_reg != REG_FP && cfa_base_reg != REG_SP)) return ERR_SFRAME_UNSAFE_UNWIND; // Apply rules to recover CFA and RA cfa = sframe_apply_rule (cfa_reg_data, cfa_offset, cfa, 1); ra = sframe_apply_rule (ra_reg_data, ra_offset, cfa, 0); if (fp_tracking_p) next_frame->fp = sframe_apply_rule (fp_reg_data, fp_offset, cfa, 0); else next_frame->fp = fp; next_frame->sp = cfa; next_frame->pc = ra; a953 36 The ‘sframe_apply_rule’ helper function abstracts the logic of interpreting the Control Data and Offset Data pair for flexible FDEs: // Apply SFrame V3 Flex FDE recovery rule. // reg_data: The Control Data (Data word 1) containing reg_p, deref_p, regnum. // offset: The Offset (Data word 2). // cfa: The current CFA value (used as base if reg_p is 0). // cfa_p: Bool indicating if we are currently recovering the CFA itself. sframe_apply_rule (reg_data, offset, cfa, cfa_p) reg_p = SFRAME_V3_FLEX_FDE_OFFSET_REG_P (reg_data); // Determine Base Address: // If reg_p is set, read from the specific DWARF register. // If reg_p is clear, use the CFA (unless we are recovering the // CFA itself, in which case reg_p MUST be set). if (reg_p) reg_num = SFRAME_V3_FLEX_FDE_OFFSET_REG_NUM (reg_data); base_loc = get_reg_value (reg_num); else base_loc = cfa; // CFA recovery must always specify a base register. assert (!cfa_p || reg_p); // Add the displacement loc = base_loc + offset; // Dereference if required deref_p = SFRAME_V3_FLEX_FDE_OFFSET_REG_DEREF_P (reg_data); value = deref_p ? read_value (loc) : loc; return value; d963 2 a966 2 * Changes from Version 2 to Version 3: Changes from Version 2 to Version 3. (line 6) a968 2 * Interpretation of SFrame FREs: Interpretation of SFrame FREs. (line 6) d971 5 a975 6 * Provisions for future ABIs: SFrame Header. (line 60) * Provisions for future ABIs <1>: The SFrame FDE Attribute. (line 47) * Provisions for future ABIs <2>: The SFrame FDE Types. (line 40) * Provisions for future ABIs <3>: SFrame Frame Row Entries. (line 35) d1000 8 a1007 14 * SFRAME_FDE_TYPE_DEFAULT: The SFrame FDE Types. (line 6) * SFRAME_FDE_TYPE_DEFAULT <1>: The SFrame FDE Types. (line 12) * SFRAME_FDE_TYPE_DEFAULT <2>: Default FDE Type Interpretation. (line 6) * SFRAME_FDE_TYPE_FLEX: The SFrame FDE Types. (line 6) * SFRAME_FDE_TYPE_FLEX <1>: The SFrame FDE Types. (line 27) * SFRAME_FDE_TYPE_FLEX <2>: Flexible FDE Type Interpretation. (line 6) * SFRAME_FRE_DATAWORD_1B: The SFrame FRE Info Word. (line 32) * SFRAME_FRE_DATAWORD_2B: The SFrame FRE Info Word. (line 36) * SFRAME_FRE_DATAWORD_4B: The SFrame FRE Info Word. (line 39) a1011 4 * SFRAME_V3_FDE_PCTYPE_INC: The SFrame FDE PC Types. (line 6) * SFRAME_V3_FDE_PCTYPE_MASK: The SFrame FDE PC Types. (line 6) d1013 2 a1014 6 * The SFrame FDE Attribute: The SFrame FDE Index. (line 50) * The SFrame FDE Index: SFrame Function Descriptor Entries. (line 19) * The SFrame FDE Info Bytes: The SFrame FDE Attribute. (line 51) * The SFrame FDE Types: The SFrame FDE Types. (line 6) d1016 2 a1017 2 (line 84) * The SFrame FRE Types: The SFrame FRE Types. (line 6) d1021 23 a1043 29 Node: Top563 Node: Introduction1287 Node: Overview1513 Node: Changes from Version 2 to Version 33161 Node: Changes from Version 1 to Version 26049 Node: SFrame Section9570 Node: SFrame Preamble10070 Node: SFrame Magic Number and Endianness11669 Node: SFrame Version12205 Node: SFrame Flags12844 Node: SFrame Header14571 Node: SFrame ABI/arch Identifier20181 Node: SFrame Function Descriptor Entries21328 Node: The SFrame FDE Index22036 Node: The SFrame FDE Attribute25106 Node: The SFrame FDE Info Bytes27891 Node: The SFrame FDE PC Types30434 Node: The SFrame FDE Types32266 Node: The SFrame FRE Types35079 Node: SFrame Frame Row Entries36580 Node: The SFrame FRE Info Word40204 Node: Interpretation of SFrame FREs42630 Node: Default FDE Type Interpretation43213 Node: AMD6443778 Node: AArch6444909 Node: s390x46155 Node: Flexible FDE Type Interpretation49736 Node: Generating Stack Traces using SFrame54747 Node: Index61672 @