14b169a6bSchristosThis is sframe-spec.info, produced by makeinfo version 6.8 from 24b169a6bSchristossframe-spec.texi. 34b169a6bSchristos 4*6817db7fSchristosCopyright (C) 2021-2024 Free Software Foundation, Inc. 54b169a6bSchristos 64b169a6bSchristos Permission is granted to copy, distribute and/or modify this document 74b169a6bSchristosunder the terms of the GNU General Public License, Version 3 or any 84b169a6bSchristoslater version published by the Free Software Foundation. A copy of the 94b169a6bSchristoslicense is included in the section entitled "GNU General Public 104b169a6bSchristosLicense". 114b169a6bSchristos 124b169a6bSchristosINFO-DIR-SECTION Software development 134b169a6bSchristosSTART-INFO-DIR-ENTRY 144b169a6bSchristos* SFrame: (sframe-spec). The Simple Frame format. 154b169a6bSchristosEND-INFO-DIR-ENTRY 164b169a6bSchristos 174b169a6bSchristos 18*6817db7fSchristosFile: sframe-spec.info, Node: Top, Next: Introduction, Up: (dir) 194b169a6bSchristos 204b169a6bSchristosThe SFrame format 214b169a6bSchristos***************** 224b169a6bSchristos 23*6817db7fSchristosThis manual describes version 2 of the SFrame file format. SFrame 244b169a6bSchristosstands for Simple Frame format. SFrame format keeps track of the 25*6817db7fSchristosminimal necessary information needed for generating stack traces: 264b169a6bSchristos 274b169a6bSchristos - Canonical Frame Address (CFA). 284b169a6bSchristos - Frame Pointer (FP). 294b169a6bSchristos - Return Address (RA). 304b169a6bSchristos 31*6817db7fSchristos The reason for existence of the SFrame format is to provide a simple, 32*6817db7fSchristosfast and low-overhead mechanism to generate stack traces. 334b169a6bSchristos 344b169a6bSchristos* Menu: 354b169a6bSchristos 36*6817db7fSchristos* Introduction:: 374b169a6bSchristos* SFrame section:: 384b169a6bSchristos* Index:: 394b169a6bSchristos 404b169a6bSchristos 41*6817db7fSchristosFile: sframe-spec.info, Node: Introduction, Next: SFrame section, Prev: Top, Up: Top 424b169a6bSchristos 43*6817db7fSchristos1 Introduction 44*6817db7fSchristos************** 454b169a6bSchristos 46*6817db7fSchristos* Menu: 47*6817db7fSchristos 48*6817db7fSchristos* Overview:: 49*6817db7fSchristos* Changes from Version 1 to Version 2:: 50*6817db7fSchristos 51*6817db7fSchristos 52*6817db7fSchristosFile: sframe-spec.info, Node: Overview, Next: Changes from Version 1 to Version 2, Up: Introduction 53*6817db7fSchristos 54*6817db7fSchristos1.1 Overview 55*6817db7fSchristos============ 56*6817db7fSchristos 57*6817db7fSchristosThe SFrame stack trace information is provided in a loaded section, 58*6817db7fSchristosknown as the '.sframe' section. When available, the '.sframe' section 59*6817db7fSchristosappears in a new segment of its own, PT_GNU_SFRAME. 604b169a6bSchristos 614b169a6bSchristos The SFrame format is currently supported only for select ABIs, 624b169a6bSchristosnamely, AMD64 and AAPCS64. 634b169a6bSchristos 64*6817db7fSchristos A portion of the SFrame format follows an unaligned on-disk 65*6817db7fSchristosrepresentation. Some data structures, however, (namely the SFrame 66*6817db7fSchristosheader and the SFrame function descriptor entry) have elements at their 67*6817db7fSchristosnatural boundaries. All data structures are packed, unless otherwise 68*6817db7fSchristosstated. 69*6817db7fSchristos 704b169a6bSchristos The contents of the SFrame section are stored in the target 714b169a6bSchristosendianness, i.e., in the endianness of the system on which the section 724b169a6bSchristosis targetted to be used. An SFrame section reader may use the magic 734b169a6bSchristosnumber in the SFrame header to identify the endianness of the SFrame 744b169a6bSchristossection. 754b169a6bSchristos 764b169a6bSchristos Addresses in this specification are expressed in bytes. 774b169a6bSchristos 78*6817db7fSchristos The rest of this specification describes the current version of the 79*6817db7fSchristosformat, 'SFRAME_VERSION_2', in detail. Additional sections outline the 80*6817db7fSchristosmajor changes made to each previously published version of the SFrame 81*6817db7fSchristosstack trace format. 82*6817db7fSchristos 834b169a6bSchristos The associated API to decode, probe and encode the SFrame section, 844b169a6bSchristosprovided via 'libsframe', is not accompanied here at this time. This 854b169a6bSchristoswill be added later. 864b169a6bSchristos 874b169a6bSchristos This document is intended to be in sync with the C code in 88*6817db7fSchristos'sframe.h'. Please report discrepancies between the two, if any. 894b169a6bSchristos 904b169a6bSchristos 91*6817db7fSchristosFile: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction 924b169a6bSchristos 93*6817db7fSchristos1.2 Changes from Version 1 to Version 2 94*6817db7fSchristos======================================= 95*6817db7fSchristos 96*6817db7fSchristosThe following is a list of the changes made to the SFrame stack trace 97*6817db7fSchristosformat since Version 1 was published. 98*6817db7fSchristos 99*6817db7fSchristos * SFrame Function Descriptor Entry encodes the size of the repetitive 100*6817db7fSchristos code blocks, e.g., pltN entries for which an FDE of type 101*6817db7fSchristos SFRAME_FDE_TYPE_PCMASK is used. 102*6817db7fSchristos * SFrame Function Descriptor Entry includes an explicit padding of 103*6817db7fSchristos two bytes to ensure natural alignment for its data members. 104*6817db7fSchristos * The above two imply that each SFrame Function Descriptor Entry has 105*6817db7fSchristos a fixed size of 20 bytes instead of its size of 17 bytes in SFrame 106*6817db7fSchristos format version 1. 107*6817db7fSchristos 108*6817db7fSchristos 109*6817db7fSchristosFile: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Introduction, Up: Top 110*6817db7fSchristos 111*6817db7fSchristos2 SFrame section 1124b169a6bSchristos**************** 1134b169a6bSchristos 1144b169a6bSchristosThe SFrame section consists of an SFrame header, starting with a 1154b169a6bSchristospreamble, and two other sub-sections, namely the SFrame Function 1164b169a6bSchristosDescriptor Entry (SFrame FDE) sub-section, and the SFrame Frame Row 1174b169a6bSchristosEntry (SFrame FRE) sub-section. 1184b169a6bSchristos 1194b169a6bSchristos* Menu: 1204b169a6bSchristos 1214b169a6bSchristos* SFrame Preamble:: 1224b169a6bSchristos* SFrame Header:: 1234b169a6bSchristos* SFrame Function Descriptor Entries:: 1244b169a6bSchristos* SFrame Frame Row Entries:: 1254b169a6bSchristos 1264b169a6bSchristos 1274b169a6bSchristosFile: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame section 1284b169a6bSchristos 129*6817db7fSchristos2.1 SFrame Preamble 1304b169a6bSchristos=================== 1314b169a6bSchristos 1324b169a6bSchristosThe preamble is a 32-bit packed structure; the only part of the SFrame 1334b169a6bSchristoswhose format cannot vary between versions. 1344b169a6bSchristos 1354b169a6bSchristos typedef struct sframe_preamble 1364b169a6bSchristos { 1374b169a6bSchristos uint16_t sfp_magic; 1384b169a6bSchristos uint8_t sfp_version; 1394b169a6bSchristos uint8_t sfp_flags; 1404b169a6bSchristos } ATTRIBUTE_PACKED sframe_preamble; 1414b169a6bSchristos 142*6817db7fSchristos Every element of the SFrame preamble is naturally aligned. 143*6817db7fSchristos 1444b169a6bSchristos All values are stored in the endianness of the target system for 1454b169a6bSchristoswhich the SFrame section is intended. Further details: 1464b169a6bSchristos 1474b169a6bSchristosOffset Name Description 1484b169a6bSchristos----------------------------------------------------------------------------------------- 1494b169a6bSchristos0x00 'uint16_t sfp_magic' The magic number for SFrame section: 0xdee2. Defined 1504b169a6bSchristos as a macro 'SFRAME_MAGIC'. 1514b169a6bSchristos 1524b169a6bSchristos0x02 'uint8_t sfp_version' The version number of this SFrame section. 1534b169a6bSchristos *Note SFrame version::, for the set of valid values. 1544b169a6bSchristos Current version is 'SFRAME_VERSION_1'. 1554b169a6bSchristos 1564b169a6bSchristos0x03 'uint8_t sfp_flags' Flags (section-wide) for this SFrame section. 1574b169a6bSchristos *Note SFrame flags::, for the set of valid values. 1584b169a6bSchristos 1594b169a6bSchristos* Menu: 1604b169a6bSchristos 1614b169a6bSchristos* SFrame endianness:: 1624b169a6bSchristos* SFrame version:: 1634b169a6bSchristos* SFrame flags:: 1644b169a6bSchristos 1654b169a6bSchristos 1664b169a6bSchristosFile: sframe-spec.info, Node: SFrame endianness, Next: SFrame version, Up: SFrame Preamble 1674b169a6bSchristos 168*6817db7fSchristos2.1.1 SFrame endianness 1694b169a6bSchristos----------------------- 1704b169a6bSchristos 1714b169a6bSchristosSFrame sections are stored in the target endianness of the system that 1724b169a6bSchristosconsumes them. The SFrame library ('libsframe') can, however, detect 1734b169a6bSchristoswhether to endian-flip an SFrame section at decode time, by inspecting 1744b169a6bSchristosthe 'sfp_magic' field in the SFrame header (If it appears as 0xe2de, 1754b169a6bSchristosendian-flipping is needed). 1764b169a6bSchristos 1774b169a6bSchristos 1784b169a6bSchristosFile: sframe-spec.info, Node: SFrame version, Next: SFrame flags, Prev: SFrame endianness, Up: SFrame Preamble 1794b169a6bSchristos 180*6817db7fSchristos2.1.2 SFrame version 1814b169a6bSchristos-------------------- 1824b169a6bSchristos 1834b169a6bSchristosThe version of the SFrame format can be determined by inspecting 1844b169a6bSchristos'sfp_version'. The following versions are currently valid: 1854b169a6bSchristos 1864b169a6bSchristosVersion Number Description 187*6817db7fSchristos------------------------------------------------------------------ 188*6817db7fSchristos'SFRAME_VERSION_1' 1 First version, obsolete. 189*6817db7fSchristos'SFRAME_VERSION_2' 2 Current version, under development. 1904b169a6bSchristos 191*6817db7fSchristos This document describes 'SFRAME_VERSION_2'. 1924b169a6bSchristos 1934b169a6bSchristos 1944b169a6bSchristosFile: sframe-spec.info, Node: SFrame flags, Prev: SFrame version, Up: SFrame Preamble 1954b169a6bSchristos 196*6817db7fSchristos2.1.3 SFrame flags 1974b169a6bSchristos------------------ 1984b169a6bSchristos 1994b169a6bSchristosThe preamble contains bitflags in its 'sfp_flags' field that describe 2004b169a6bSchristosvarious section-wide properties. 2014b169a6bSchristos 2024b169a6bSchristos The following flags are currently defined. 2034b169a6bSchristos 2044b169a6bSchristosFlag Versions Value Meaning 2054b169a6bSchristos---------------------------------------------------------------------------- 2064b169a6bSchristos'SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries 2074b169a6bSchristos are sorted on PC. 2084b169a6bSchristos'SFRAME_F_FRAME_POINTER' All 0x2 Functions preserve 2094b169a6bSchristos frame-pointer. 2104b169a6bSchristos 2114b169a6bSchristos Further flags may be added in future. 2124b169a6bSchristos 2134b169a6bSchristos 2144b169a6bSchristosFile: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame section 2154b169a6bSchristos 216*6817db7fSchristos2.2 SFrame Header 2174b169a6bSchristos================= 2184b169a6bSchristos 2194b169a6bSchristosThe SFrame header is the first part of an SFrame section. It begins 2204b169a6bSchristoswith the SFrame preamble. All parts of it other than the preamble 2214b169a6bSchristos(*note SFrame Preamble::) can vary between SFrame file versions. It 2224b169a6bSchristoscontains things that apply to the section as a whole, and offsets to the 2234b169a6bSchristosvarious other sub-sections defined in the format. As with the rest of 2244b169a6bSchristosthe SFrame section, all values are stored in the endianness of the 2254b169a6bSchristostarget system. 2264b169a6bSchristos 2274b169a6bSchristos The two sub-sections tile the SFrame section: each section runs from 2284b169a6bSchristosthe offset given until the start of the next section. An explicit 2294b169a6bSchristoslength is given for the last sub-section, the SFrame Frame Row Entry 2304b169a6bSchristos(SFrame FRE) sub-section. 2314b169a6bSchristos 2324b169a6bSchristos typedef struct sframe_header 2334b169a6bSchristos { 2344b169a6bSchristos sframe_preamble sfh_preamble; 2354b169a6bSchristos uint8_t sfh_abi_arch; 2364b169a6bSchristos int8_t sfh_cfa_fixed_fp_offset; 2374b169a6bSchristos int8_t sfh_cfa_fixed_ra_offset; 2384b169a6bSchristos uint8_t sfh_auxhdr_len; 2394b169a6bSchristos uint32_t sfh_num_fdes; 2404b169a6bSchristos uint32_t sfh_num_fres; 2414b169a6bSchristos uint32_t sfh_fre_len; 2424b169a6bSchristos uint32_t sfh_fdeoff; 2434b169a6bSchristos uint32_t sfh_freoff; 2444b169a6bSchristos } ATTRIBUTE_PACKED sframe_header; 2454b169a6bSchristos 246*6817db7fSchristos Every element of the SFrame header is naturally aligned. 247*6817db7fSchristos 2484b169a6bSchristos The sub-section offsets, namely 'sfh_fdeoff' and 'sfh_freoff', in the 2494b169a6bSchristosSFrame header are relative to the _end_ of the SFrame header; they are 2504b169a6bSchristoseach an offset in bytes into the SFrame section where the SFrame FDE 2514b169a6bSchristossub-section and the SFrame FRE sub-section respectively start. 2524b169a6bSchristos 2534b169a6bSchristos SFrame header allows specifying explicitly the fixed offsets from 2544b169a6bSchristosCFA, if any, from which FP or RA may be recovered. For example, in 2554b169a6bSchristosAMD64, the stack offset of the return address is 'CFA - 8'. Since this 2564b169a6bSchristosoffset is in close vicinity with the CFA in most ABIs, 2574b169a6bSchristos'sfh_cfa_fixed_fp_offset' and 'sfh_cfa_fixed_ra_offset' are limited to 2584b169a6bSchristossigned 8-bit integers. 2594b169a6bSchristos 260*6817db7fSchristos SFrame format has made some provisions for supporting more 261*6817db7fSchristosABIs/architectures in the future. The 'sframe_header' structure 262*6817db7fSchristosprovides an unsigned 8-bit integral field to denote the size of an 263*6817db7fSchristosauxiliary SFrame header. The auxiliary SFrame header follows right 264*6817db7fSchristosafter the 'sframe_header' structure. As for the offset calculations, 265*6817db7fSchristosthe _end_ of SFrame header must be the end of the auxiliary SFrame 266*6817db7fSchristosheader, if the latter is present. 2674b169a6bSchristos 268*6817db7fSchristos Putting it all together: 2694b169a6bSchristos 2704b169a6bSchristosOffset Name Description 271*6817db7fSchristos---------------------------------------------------------------------------------------- 2724b169a6bSchristos0x00 'sframe_preamble sfh_preamble' The SFrame preamble. 2734b169a6bSchristos *Note SFrame Preamble::. 2744b169a6bSchristos 2754b169a6bSchristos0x04 'uint8_t sfh_abi_arch' The ABI/arch identifier. 2764b169a6bSchristos *Note SFrame ABI/arch identifier::. 2774b169a6bSchristos 2784b169a6bSchristos0x05 'int8_t sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. 2794b169a6bSchristos 2804b169a6bSchristos0x06 'int8_t sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. 2814b169a6bSchristos 282*6817db7fSchristos0x07 'uint8_t sfh_auxhdr_len' Size in bytes of the auxiliary header 283*6817db7fSchristos that follows the 'sframe_header' 284*6817db7fSchristos structure. 2854b169a6bSchristos 286*6817db7fSchristos0x08 'uint32_t sfh_num_fdes' The number of SFrame FDEs in the section. 2874b169a6bSchristos 288*6817db7fSchristos0xc 'uint32_t sfh_num_fres' The number of SFrame FREs in the section. 2894b169a6bSchristos 290*6817db7fSchristos0x10 'uint32_t sfh_fre_len' The length in bytes of the SFrame FRE 291*6817db7fSchristos sub-section. 2924b169a6bSchristos 293*6817db7fSchristos0x14 'uint32_t sfh_fdeoff' The offset in bytes of the SFrame FDE 294*6817db7fSchristos sub-section. This sub-section contains 295*6817db7fSchristos 'sfh_num_fdes' number of fixed-length 296*6817db7fSchristos array elements. The array element is of 297*6817db7fSchristos type SFrame function desciptor entry, 298*6817db7fSchristos each providing a high-level function 2994b169a6bSchristos description for backtracing. 3004b169a6bSchristos *Note SFrame Function Descriptor Entries::. 3014b169a6bSchristos 302*6817db7fSchristos0x18 'uint32_t sfh_freoff' The offset in bytes of the SFrame FRE 303*6817db7fSchristos sub-section, the core of the SFrame 304*6817db7fSchristos section, which describes the stack trace 305*6817db7fSchristos information using variable-length array 306*6817db7fSchristos elements. 3074b169a6bSchristos *Note SFrame Frame Row Entries::. 3084b169a6bSchristos 3094b169a6bSchristos 3104b169a6bSchristos* Menu: 3114b169a6bSchristos 3124b169a6bSchristos* SFrame ABI/arch identifier:: 3134b169a6bSchristos 3144b169a6bSchristos 3154b169a6bSchristosFile: sframe-spec.info, Node: SFrame ABI/arch identifier, Up: SFrame Header 3164b169a6bSchristos 317*6817db7fSchristos2.2.1 SFrame ABI/arch identifier 3184b169a6bSchristos-------------------------------- 3194b169a6bSchristos 3204b169a6bSchristosSFrame header identifies the ABI/arch of the target system for which the 321*6817db7fSchristosexecutable and hence, the stack trace information contained in the 322*6817db7fSchristosSFrame section, is intended. There are currently three identifiable 323*6817db7fSchristosABI/arch values in the format. 3244b169a6bSchristos 3254b169a6bSchristosABI/arch Identifier Value Description 3264b169a6bSchristos 3274b169a6bSchristos--------------------------------------------------------------------- 3284b169a6bSchristos'SFRAME_ABI_AARCH64_ENDIAN_BIG' 1 AARCH64 big-endian 3294b169a6bSchristos 3304b169a6bSchristos'SFRAME_ABI_AARCH64_ENDIAN_LITTLE' 2 AARCH64 little-endian 3314b169a6bSchristos 3324b169a6bSchristos'SFRAME_ABI_AMD64_ENDIAN_LITTLE' 3 AMD64 little-endian 3334b169a6bSchristos 3344b169a6bSchristos 3354b169a6bSchristos The presence of an explicit identification of ABI/arch in SFrame may 336*6817db7fSchristosallow stack trace generators to make certain ABI-specific decisions. 3374b169a6bSchristos 3384b169a6bSchristos 3394b169a6bSchristosFile: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame section 3404b169a6bSchristos 341*6817db7fSchristos2.3 SFrame FDE 3424b169a6bSchristos============== 3434b169a6bSchristos 3444b169a6bSchristosThe SFrame Function Descriptor Entry sub-section is a sorted array of 3454b169a6bSchristosfixed-length SFrame function descriptor entries (SFrame FDEs). Each 3464b169a6bSchristosSFrame FDE is a packed structure which contains information to describe 347*6817db7fSchristosa function's stack trace information at a high-level. 3484b169a6bSchristos 3494b169a6bSchristos typedef struct sframe_func_desc_entry 3504b169a6bSchristos { 3514b169a6bSchristos int32_t sfde_func_start_address; 3524b169a6bSchristos uint32_t sfde_func_size; 3534b169a6bSchristos uint32_t sfde_func_start_fre_off; 3544b169a6bSchristos uint32_t sfde_func_num_fres; 3554b169a6bSchristos uint8_t sfde_func_info; 356*6817db7fSchristos uint8_t sfde_func_rep_size; 357*6817db7fSchristos uint16_t sfde_func_padding2; 3584b169a6bSchristos } ATTRIBUTE_PACKED sframe_func_desc_entry; 3594b169a6bSchristos 360*6817db7fSchristos Every element of the SFrame function descriptor entry is naturally 361*6817db7fSchristosaligned. 362*6817db7fSchristos 3634b169a6bSchristos 'sfde_func_start_fre_off' is the offset to the first SFrame FRE for 3644b169a6bSchristosthe function. This offset is relative to the _end of the SFrame FDE_ 3654b169a6bSchristossub-section (unlike the offsets in the SFrame header, which are relative 3664b169a6bSchristosto the _end_ of the SFrame header). 3674b169a6bSchristos 3684b169a6bSchristos 'sfde_func_info' is the "info word", containing information on the 3694b169a6bSchristosFRE type and the FDE type for the function *Note The SFrame FDE info 3704b169a6bSchristosword::. 3714b169a6bSchristos 3724b169a6bSchristos Following table describes each component of the SFrame FDE structure: 3734b169a6bSchristos 3744b169a6bSchristosOffset Name Description 375*6817db7fSchristos------------------------------------------------------------------------------------------ 376*6817db7fSchristos0x00 'int32_t sfde_func_start_address' Signed 32-bit integral field denoting the 377*6817db7fSchristos virtual memory address of the described 378*6817db7fSchristos function. 3794b169a6bSchristos 380*6817db7fSchristos0x04 'uint32_t sfde_func_size' Unsigned 32-bit integral field specifying 381*6817db7fSchristos the size of the function in bytes. 3824b169a6bSchristos 383*6817db7fSchristos0x08 'uint32_t sfde_func_start_fre_off' Unsigned 32-bit integral field specifying 384*6817db7fSchristos the offset in bytes of the function's 385*6817db7fSchristos first SFrame FRE in the SFrame section. 3864b169a6bSchristos 387*6817db7fSchristos0x0c 'uint32_t sfde_func_num_fres' Unsigned 32-bit integral field specifying 388*6817db7fSchristos the total number of SFrame FREs used for 389*6817db7fSchristos the function. 3904b169a6bSchristos 391*6817db7fSchristos0x10 'uint8_t sfde_func_info' Unsigned 8-bit integral field specifying 392*6817db7fSchristos the SFrame FDE info word. 3934b169a6bSchristos *Note The SFrame FDE info word::. 3944b169a6bSchristos 395*6817db7fSchristos0x11 'uint8_t sfde_func_rep_size' Unsigned 8-bit integral field specifying 396*6817db7fSchristos the size of the repetitive code block for 397*6817db7fSchristos which an SFrame FDE of type 398*6817db7fSchristos SFRAME_FDE_TYPE_PCMASK is used. For 399*6817db7fSchristos example, in AMD64, the size of a pltN 400*6817db7fSchristos entry is 16 bytes. 401*6817db7fSchristos 402*6817db7fSchristos0x12 'uint16_t sfde_func_padding2' Padding of 2 bytes. Currently unused 403*6817db7fSchristos bytes. 404*6817db7fSchristos 4054b169a6bSchristos 4064b169a6bSchristos* Menu: 4074b169a6bSchristos 4084b169a6bSchristos* The SFrame FDE info word:: 4094b169a6bSchristos* The SFrame FDE types:: 4104b169a6bSchristos* The SFrame FRE types:: 4114b169a6bSchristos 4124b169a6bSchristos 4134b169a6bSchristosFile: sframe-spec.info, Node: The SFrame FDE info word, Next: The SFrame FDE types, Up: SFrame Function Descriptor Entries 4144b169a6bSchristos 415*6817db7fSchristos2.3.1 The SFrame FDE info word 4164b169a6bSchristos------------------------------ 4174b169a6bSchristos 4184b169a6bSchristosThe info word is a bitfield split into three parts. From MSB to LSB: 4194b169a6bSchristos 4204b169a6bSchristosBit offset Name Description 421*6817db7fSchristos---------------------------------------------------------------------------------------- 422*6817db7fSchristos7-6 'unused' Unused bits. 4234b169a6bSchristos 424*6817db7fSchristos5 'pauth_key' Specify which key is used for signing the return addresses 425*6817db7fSchristos in the SFrame FDE. Two possible values: 426*6817db7fSchristos SFRAME_AARCH64_PAUTH_KEY_A (0), or 427*6817db7fSchristos SFRAME_AARCH64_PAUTH_KEY_B (1). 428*6817db7fSchristos 429*6817db7fSchristos4 'fdetype' Specify the SFrame FDE type. Two possible values: 430*6817db7fSchristos SFRAME_FDE_TYPE_PCMASK (1), or 431*6817db7fSchristos SFRAME_FDE_TYPE_PCINC (0). 4324b169a6bSchristos *Note The SFrame FDE types::. 4334b169a6bSchristos 4344b169a6bSchristos0-3 'fretype' Choice of three SFrame FRE types. 4354b169a6bSchristos *Note The SFrame FRE types::. 4364b169a6bSchristos 4374b169a6bSchristos 4384b169a6bSchristosFile: sframe-spec.info, Node: The SFrame FDE types, Next: The SFrame FRE types, Prev: The SFrame FDE info word, Up: SFrame Function Descriptor Entries 4394b169a6bSchristos 440*6817db7fSchristos2.3.2 The SFrame FDE types 4414b169a6bSchristos-------------------------- 4424b169a6bSchristos 4434b169a6bSchristosSFrame format defines two types of FDE entries. The choice of which 4444b169a6bSchristosSFrame FDE type to use is made based on the instruction patterns in the 4454b169a6bSchristosrelevant program stub. 4464b169a6bSchristos 4474b169a6bSchristos An SFrame FDE of type 'SFRAME_FDE_TYPE_PCINC' is an indication that 4484b169a6bSchristosthe PCs in the FREs should be treated as increments in bytes. This is 4494b169a6bSchristosused fo the the bulk of the executable code of a program, which contains 4504b169a6bSchristosinstructions with no specific pattern. 4514b169a6bSchristos 4524b169a6bSchristos In contrast, an SFrame FDE of type 'SFRAME_FDE_TYPE_PCMASK' is an 4534b169a6bSchristosindication that the PCs in the FREs should be treated as masks. This 4544b169a6bSchristostype is useful for the cases where a small pattern of instructions in a 4554b169a6bSchristosprogram stub is used repeatedly for a specific functionality. Typical 4564b169a6bSchristosusecases are pltN entries and trampolines. 4574b169a6bSchristos 458*6817db7fSchristosName of SFrame FDE Value Description 459*6817db7fSchristostype 460*6817db7fSchristos--------------------------------------------------------------------------- 461*6817db7fSchristosSFRAME_FDE_TYPE_PCINC 0 Unwinders perform a 462*6817db7fSchristos (PC >= FRE_START_ADDR) to look up a 4634b169a6bSchristos matching FRE. 4644b169a6bSchristos 465*6817db7fSchristosSFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a 466*6817db7fSchristos (PC % REP_BLOCK_SIZE 467*6817db7fSchristos >= FRE_START_ADDR) to look up a 468*6817db7fSchristos matching FRE. REP_BLOCK_SIZE is the 469*6817db7fSchristos size in bytes of the repeating block of 470*6817db7fSchristos program instructions. 471*6817db7fSchristos 4724b169a6bSchristos 4734b169a6bSchristos 4744b169a6bSchristosFile: sframe-spec.info, Node: The SFrame FRE types, Prev: The SFrame FDE types, Up: SFrame Function Descriptor Entries 4754b169a6bSchristos 476*6817db7fSchristos2.3.3 The SFrame FRE types 4774b169a6bSchristos-------------------------- 4784b169a6bSchristos 4794b169a6bSchristosA real world application can have functions of size big and small. 4804b169a6bSchristosSFrame format defines three types of SFrame FRE entries to represent the 481*6817db7fSchristosstack trace information for such a variety of function sizes. These 4824b169a6bSchristosrepresentations vary in the number of bits needed to encode the start 4834b169a6bSchristosaddress offset in the SFrame FRE. 4844b169a6bSchristos 4854b169a6bSchristos The following constants are defined and used to identify the SFrame 4864b169a6bSchristosFRE types: 4874b169a6bSchristos 4884b169a6bSchristosName Value Description 4894b169a6bSchristos 4904b169a6bSchristos-------------------------------------------------------------------------- 4914b169a6bSchristos'SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) 4924b169a6bSchristos of the SFrame FRE is an unsigned 4934b169a6bSchristos 8-bit value. 4944b169a6bSchristos 4954b169a6bSchristos'SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) 4964b169a6bSchristos of the SFrame FRE is an unsigned 4974b169a6bSchristos 16-bit value. 4984b169a6bSchristos 4994b169a6bSchristos'SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) 5004b169a6bSchristos of the SFrame FRE is an unsigned 5014b169a6bSchristos 32-bit value. 5024b169a6bSchristos 503*6817db7fSchristos A single function must use the same type of SFrame FRE throughout. 504*6817db7fSchristosAn identifier to reflect the chosen SFrame FRE type is stored in the 505*6817db7fSchristos*Note The SFrame FDE info word::. 5064b169a6bSchristos 5074b169a6bSchristos 5084b169a6bSchristosFile: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame section 5094b169a6bSchristos 510*6817db7fSchristos2.4 SFrame FRE 5114b169a6bSchristos============== 5124b169a6bSchristos 513*6817db7fSchristosThe SFrame Frame Row Entry sub-section contains the core of the stack 514*6817db7fSchristostrace information. 5154b169a6bSchristos 5164b169a6bSchristos An SFrame Frame Row Entry is a self-sufficient record containing 517*6817db7fSchristosSFrame stack trace information for a range of contiguous addresses, 518*6817db7fSchristosstarting at the specified offset from the start of the function. Each 519*6817db7fSchristosSFrame Frame Row Entry is followed by S*N bytes, where: 5204b169a6bSchristos 5214b169a6bSchristos - 'S' is the size of the stack frame offset for the FRE, and 5224b169a6bSchristos - 'N' is the number of stack frame offsets in the FRE 5234b169a6bSchristos 5244b169a6bSchristos The stack offsets, following the FRE, are interpreted in order as 5254b169a6bSchristosfollows: 5264b169a6bSchristos 5274b169a6bSchristos - The first offset is always used to locate the CFA, by interpreting 5284b169a6bSchristos it as: CFA = 'BASE_REG' + offset1. 5294b169a6bSchristos - If RA is being tracked, the second offset is always used to locate 5304b169a6bSchristos the RA, by interpreting it as: RA = CFA + offset2. If RA is _not_ 5314b169a6bSchristos being tracked _and_ FP is being tracked, the second offset will be 5324b169a6bSchristos used to locate the FP, by interpreting it as: FP = CFA + offset2. 5334b169a6bSchristos - If both RA and FP are being tracked, the third offset will be used 5344b169a6bSchristos to locate the FP, by interpreting it as FP = CFA + offset3. 5354b169a6bSchristos 5364b169a6bSchristos The entities 'S', 'N' and 'BASE_REG' are identified using the SFrame 5374b169a6bSchristosFRE info word, a.k.a. the 'sframe_fre_info' *Note The SFrame FRE info 5384b169a6bSchristosword::. 5394b169a6bSchristos 5404b169a6bSchristos Following are the definitions of the allowed SFrame FRE: 5414b169a6bSchristos 5424b169a6bSchristos typedef struct sframe_frame_row_entry_addr1 5434b169a6bSchristos { 5444b169a6bSchristos uint8_t sfre_start_address; 5454b169a6bSchristos sframe_fre_info sfre_info; 5464b169a6bSchristos } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; 5474b169a6bSchristos 5484b169a6bSchristos typedef struct sframe_frame_row_entry_addr2 5494b169a6bSchristos { 5504b169a6bSchristos uint16_t sfre_start_address; 5514b169a6bSchristos sframe_fre_info sfre_info; 5524b169a6bSchristos } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; 5534b169a6bSchristos 5544b169a6bSchristos typedef struct sframe_frame_row_entry_addr4 5554b169a6bSchristos { 5564b169a6bSchristos uint32_t sfre_start_address; 5574b169a6bSchristos sframe_fre_info sfre_info; 5584b169a6bSchristos } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; 5594b169a6bSchristos 560*6817db7fSchristos For ensuring compactness, SFrame frame row entries are stored 561*6817db7fSchristosunaligned on disk. Appropriate mechanisms need to be employed, as 562*6817db7fSchristosnecessary, by the serializing and deserializing entities, if unaligned 563*6817db7fSchristosaccesses need to be avoided. 564*6817db7fSchristos 5654b169a6bSchristos 'sfre_start_address' is an unsigned 8-bit/16-bit/32-bit integral 5664b169a6bSchristosfield identifies the start address of the range of program counters, for 5674b169a6bSchristoswhich the SFrame FRE applies. The value encoded in the 5684b169a6bSchristos'sfre_start_address' field is the offset in bytes of the start address 5694b169a6bSchristosof the SFrame FRE, from the start address of the function. 5704b169a6bSchristos 5714b169a6bSchristos Further FRE types may be added in future. 5724b169a6bSchristos 5734b169a6bSchristos* Menu: 5744b169a6bSchristos 5754b169a6bSchristos* The SFrame FRE info word:: 5764b169a6bSchristos 5774b169a6bSchristos 5784b169a6bSchristosFile: sframe-spec.info, Node: The SFrame FRE info word, Up: SFrame Frame Row Entries 5794b169a6bSchristos 580*6817db7fSchristos2.4.1 The SFrame FRE info word 5814b169a6bSchristos------------------------------ 5824b169a6bSchristos 5834b169a6bSchristosThe SFrame FRE info word is a bitfield split into four parts. From MSB 5844b169a6bSchristosto LSB: 5854b169a6bSchristos 5864b169a6bSchristosBit offset Name Description 5874b169a6bSchristos------------------------------------------------------------------------------------- 5884b169a6bSchristos7 'fre_mangled_ra_p' Indicate whether the return address is 5894b169a6bSchristos mangled with any authorization bits (signed 5904b169a6bSchristos RA). 5914b169a6bSchristos 5924b169a6bSchristos5-6 'fre_offset_size' Size of stack offsets in bytes. Valid values 593*6817db7fSchristos are: 594*6817db7fSchristos SFRAME_FRE_OFFSET_1B, 5954b169a6bSchristos SFRAME_FRE_OFFSET_2B, and 5964b169a6bSchristos SFRAME_FRE_OFFSET_4B. 5974b169a6bSchristos 5984b169a6bSchristos1-4 'fre_offset_count' A value of upto 3 is allowed to track all 5994b169a6bSchristos three of CFA, FP and RA. 6004b169a6bSchristos 6014b169a6bSchristos0 'fre_cfa_base_reg_id' Distinguish between SP or FP based CFA 6024b169a6bSchristos recovery. 6034b169a6bSchristos 6044b169a6bSchristos 6054b169a6bSchristosName Value Description 6064b169a6bSchristos 6074b169a6bSchristos-------------------------------------------------------------------------------- 6084b169a6bSchristos'SFRAME_FRE_OFFSET_1B' 0 All stack offsets following the fixed-length 6094b169a6bSchristos FRE structure are 1 byte long. 6104b169a6bSchristos 6114b169a6bSchristos'SFRAME_FRE_OFFSET_2B' 1 All stack offsets following the fixed-length 6124b169a6bSchristos FRE structure are 2 bytes long. 6134b169a6bSchristos 6144b169a6bSchristos'SFRAME_FRE_OFFSET_4B' 2 All stack offsets following the fixed-length 6154b169a6bSchristos FRE structure are 4 bytes long. 6164b169a6bSchristos 6174b169a6bSchristos 6184b169a6bSchristos 6194b169a6bSchristosFile: sframe-spec.info, Node: Index, Prev: SFrame section, Up: Top 6204b169a6bSchristos 6214b169a6bSchristosIndex 6224b169a6bSchristos***** 6234b169a6bSchristos 6244b169a6bSchristos[index] 6254b169a6bSchristos* Menu: 6264b169a6bSchristos 627*6817db7fSchristos* Changes from Version 1 to Version 2: Changes from Version 1 to Version 2. 628*6817db7fSchristos (line 6) 6294b169a6bSchristos* endianness: SFrame endianness. (line 6) 630*6817db7fSchristos* Introduction: Introduction. (line 6) 6314b169a6bSchristos* Overview: Overview. (line 6) 6324b169a6bSchristos* SFrame ABI/arch identifier: SFrame ABI/arch identifier. 6334b169a6bSchristos (line 6) 6344b169a6bSchristos* SFrame FDE: SFrame Function Descriptor Entries. 6354b169a6bSchristos (line 6) 6364b169a6bSchristos* SFrame flags: SFrame flags. (line 6) 6374b169a6bSchristos* SFrame FRE: SFrame Frame Row Entries. 6384b169a6bSchristos (line 6) 6394b169a6bSchristos* SFrame header: SFrame Header. (line 6) 6404b169a6bSchristos* SFrame preamble: SFrame Preamble. (line 6) 6414b169a6bSchristos* SFrame section: SFrame section. (line 6) 6424b169a6bSchristos* SFrame versions: SFrame version. (line 9) 6434b169a6bSchristos* SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch identifier. 644*6817db7fSchristos (line 13) 6454b169a6bSchristos* SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch identifier. 646*6817db7fSchristos (line 16) 6474b169a6bSchristos* SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch identifier. 648*6817db7fSchristos (line 18) 6494b169a6bSchristos* SFRAME_FDE_TYPE_PCINC: The SFrame FDE types. (line 6) 6504b169a6bSchristos* SFRAME_FDE_TYPE_PCMASK: The SFrame FDE types. (line 6) 6514b169a6bSchristos* SFRAME_FRE_OFFSET_1B: The SFrame FRE info word. 652*6817db7fSchristos (line 30) 6534b169a6bSchristos* SFRAME_FRE_OFFSET_2B: The SFrame FRE info word. 654*6817db7fSchristos (line 34) 6554b169a6bSchristos* SFRAME_FRE_OFFSET_4B: The SFrame FRE info word. 656*6817db7fSchristos (line 37) 6574b169a6bSchristos* SFRAME_FRE_TYPE_ADDR1: The SFrame FRE types. (line 17) 6584b169a6bSchristos* SFRAME_FRE_TYPE_ADDR2: The SFrame FRE types. (line 22) 6594b169a6bSchristos* SFRAME_FRE_TYPE_ADDR4: The SFrame FRE types. (line 26) 6604b169a6bSchristos* SFRAME_F_FDE_SORTED: SFrame flags. (line 11) 6614b169a6bSchristos* SFRAME_F_FRAME_POINTER: SFrame flags. (line 14) 662*6817db7fSchristos* SFRAME_MAGIC: SFrame Preamble. (line 24) 6634b169a6bSchristos* SFRAME_VERSION_1: SFrame version. (line 9) 6644b169a6bSchristos* The SFrame FDE info word: SFrame Function Descriptor Entries. 665*6817db7fSchristos (line 73) 6664b169a6bSchristos* The SFrame FRE info word: SFrame Frame Row Entries. 667*6817db7fSchristos (line 69) 6684b169a6bSchristos 6694b169a6bSchristos 6704b169a6bSchristos 6714b169a6bSchristosTag Table: 6724b169a6bSchristosNode: Top564 673*6817db7fSchristosNode: Introduction1148 674*6817db7fSchristosNode: Overview1334 675*6817db7fSchristosNode: Changes from Version 1 to Version 22901 676*6817db7fSchristosNode: SFrame section3672 677*6817db7fSchristosNode: SFrame Preamble4148 678*6817db7fSchristosNode: SFrame endianness5567 679*6817db7fSchristosNode: SFrame version6023 680*6817db7fSchristosNode: SFrame flags6583 681*6817db7fSchristosNode: SFrame Header7303 682*6817db7fSchristosNode: SFrame ABI/arch identifier12423 683*6817db7fSchristosNode: SFrame Function Descriptor Entries13446 684*6817db7fSchristosNode: The SFrame FDE info word17108 685*6817db7fSchristosNode: The SFrame FDE types18263 686*6817db7fSchristosNode: The SFrame FRE types19984 687*6817db7fSchristosNode: SFrame Frame Row Entries21516 688*6817db7fSchristosNode: The SFrame FRE info word24163 689*6817db7fSchristosNode: Index26145 6904b169a6bSchristos 6914b169a6bSchristosEnd Tag Table 6924b169a6bSchristos 6934b169a6bSchristos 6944b169a6bSchristosLocal Variables: 6954b169a6bSchristoscoding: utf-8 6964b169a6bSchristosEnd: 697