1*cb63e24eSchristosThis is sframe-spec.info, produced by makeinfo version 7.0.2 from 2*cb63e24eSchristossframe-spec.texi. 3*cb63e24eSchristos 4*cb63e24eSchristosCopyright © 2021-2024 Free Software Foundation, Inc. 5*cb63e24eSchristos 6*cb63e24eSchristos Permission is granted to copy, distribute and/or modify this document 7*cb63e24eSchristosunder the terms of the GNU General Public License, Version 3 or any 8*cb63e24eSchristoslater version published by the Free Software Foundation. A copy of the 9*cb63e24eSchristoslicense is included in the section entitled “GNU General Public 10*cb63e24eSchristosLicense”. 11*cb63e24eSchristos 12*cb63e24eSchristosINFO-DIR-SECTION Software development 13*cb63e24eSchristosSTART-INFO-DIR-ENTRY 14*cb63e24eSchristos* SFrame: (sframe-spec). The Simple Frame format. 15*cb63e24eSchristosEND-INFO-DIR-ENTRY 16*cb63e24eSchristos 17*cb63e24eSchristos 18*cb63e24eSchristosFile: sframe-spec.info, Node: Top, Next: Introduction, Up: (dir) 19*cb63e24eSchristos 20*cb63e24eSchristosThe SFrame format 21*cb63e24eSchristos***************** 22*cb63e24eSchristos 23*cb63e24eSchristosThis manual describes version 2 of the SFrame file format. SFrame 24*cb63e24eSchristosstands for Simple Frame format. SFrame format keeps track of the 25*cb63e24eSchristosminimal necessary information needed for generating stack traces: 26*cb63e24eSchristos 27*cb63e24eSchristos − Canonical Frame Address (CFA). 28*cb63e24eSchristos − Frame Pointer (FP). 29*cb63e24eSchristos − Return Address (RA). 30*cb63e24eSchristos 31*cb63e24eSchristos The reason for existence of the SFrame format is to provide a simple, 32*cb63e24eSchristosfast and low-overhead mechanism to generate stack traces. 33*cb63e24eSchristos 34*cb63e24eSchristos* Menu: 35*cb63e24eSchristos 36*cb63e24eSchristos* Introduction:: 37*cb63e24eSchristos* SFrame section:: 38*cb63e24eSchristos* Index:: 39*cb63e24eSchristos 40*cb63e24eSchristos 41*cb63e24eSchristosFile: sframe-spec.info, Node: Introduction, Next: SFrame section, Prev: Top, Up: Top 42*cb63e24eSchristos 43*cb63e24eSchristos1 Introduction 44*cb63e24eSchristos************** 45*cb63e24eSchristos 46*cb63e24eSchristos* Menu: 47*cb63e24eSchristos 48*cb63e24eSchristos* Overview:: 49*cb63e24eSchristos* Changes from Version 1 to Version 2:: 50*cb63e24eSchristos 51*cb63e24eSchristos 52*cb63e24eSchristosFile: sframe-spec.info, Node: Overview, Next: Changes from Version 1 to Version 2, Up: Introduction 53*cb63e24eSchristos 54*cb63e24eSchristos1.1 Overview 55*cb63e24eSchristos============ 56*cb63e24eSchristos 57*cb63e24eSchristosThe SFrame stack trace information is provided in a loaded section, 58*cb63e24eSchristosknown as the ‘.sframe’ section. When available, the ‘.sframe’ section 59*cb63e24eSchristosappears in a new segment of its own, PT_GNU_SFRAME. 60*cb63e24eSchristos 61*cb63e24eSchristos The SFrame format is currently supported only for select ABIs, 62*cb63e24eSchristosnamely, AMD64 and AAPCS64. 63*cb63e24eSchristos 64*cb63e24eSchristos A portion of the SFrame format follows an unaligned on-disk 65*cb63e24eSchristosrepresentation. Some data structures, however, (namely the SFrame 66*cb63e24eSchristosheader and the SFrame function descriptor entry) have elements at their 67*cb63e24eSchristosnatural boundaries. All data structures are packed, unless otherwise 68*cb63e24eSchristosstated. 69*cb63e24eSchristos 70*cb63e24eSchristos The contents of the SFrame section are stored in the target 71*cb63e24eSchristosendianness, i.e., in the endianness of the system on which the section 72*cb63e24eSchristosis targetted to be used. An SFrame section reader may use the magic 73*cb63e24eSchristosnumber in the SFrame header to identify the endianness of the SFrame 74*cb63e24eSchristossection. 75*cb63e24eSchristos 76*cb63e24eSchristos Addresses in this specification are expressed in bytes. 77*cb63e24eSchristos 78*cb63e24eSchristos The rest of this specification describes the current version of the 79*cb63e24eSchristosformat, ‘SFRAME_VERSION_2’, in detail. Additional sections outline the 80*cb63e24eSchristosmajor changes made to each previously published version of the SFrame 81*cb63e24eSchristosstack trace format. 82*cb63e24eSchristos 83*cb63e24eSchristos The associated API to decode, probe and encode the SFrame section, 84*cb63e24eSchristosprovided via ‘libsframe’, is not accompanied here at this time. This 85*cb63e24eSchristoswill be added later. 86*cb63e24eSchristos 87*cb63e24eSchristos This document is intended to be in sync with the C code in 88*cb63e24eSchristos‘sframe.h’. Please report discrepancies between the two, if any. 89*cb63e24eSchristos 90*cb63e24eSchristos 91*cb63e24eSchristosFile: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction 92*cb63e24eSchristos 93*cb63e24eSchristos1.2 Changes from Version 1 to Version 2 94*cb63e24eSchristos======================================= 95*cb63e24eSchristos 96*cb63e24eSchristosThe following is a list of the changes made to the SFrame stack trace 97*cb63e24eSchristosformat since Version 1 was published. 98*cb63e24eSchristos 99*cb63e24eSchristos • SFrame Function Descriptor Entry encodes the size of the repetitive 100*cb63e24eSchristos code blocks, e.g., pltN entries for which an FDE of type 101*cb63e24eSchristos SFRAME_FDE_TYPE_PCMASK is used. 102*cb63e24eSchristos • SFrame Function Descriptor Entry includes an explicit padding of 103*cb63e24eSchristos two bytes to ensure natural alignment for its data members. 104*cb63e24eSchristos • The above two imply that each SFrame Function Descriptor Entry has 105*cb63e24eSchristos a fixed size of 20 bytes instead of its size of 17 bytes in SFrame 106*cb63e24eSchristos format version 1. 107*cb63e24eSchristos 108*cb63e24eSchristos 109*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Introduction, Up: Top 110*cb63e24eSchristos 111*cb63e24eSchristos2 SFrame section 112*cb63e24eSchristos**************** 113*cb63e24eSchristos 114*cb63e24eSchristosThe SFrame section consists of an SFrame header, starting with a 115*cb63e24eSchristospreamble, and two other sub-sections, namely the SFrame Function 116*cb63e24eSchristosDescriptor Entry (SFrame FDE) sub-section, and the SFrame Frame Row 117*cb63e24eSchristosEntry (SFrame FRE) sub-section. 118*cb63e24eSchristos 119*cb63e24eSchristos* Menu: 120*cb63e24eSchristos 121*cb63e24eSchristos* SFrame Preamble:: 122*cb63e24eSchristos* SFrame Header:: 123*cb63e24eSchristos* SFrame Function Descriptor Entries:: 124*cb63e24eSchristos* SFrame Frame Row Entries:: 125*cb63e24eSchristos 126*cb63e24eSchristos 127*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame section 128*cb63e24eSchristos 129*cb63e24eSchristos2.1 SFrame Preamble 130*cb63e24eSchristos=================== 131*cb63e24eSchristos 132*cb63e24eSchristosThe preamble is a 32-bit packed structure; the only part of the SFrame 133*cb63e24eSchristoswhose format cannot vary between versions. 134*cb63e24eSchristos 135*cb63e24eSchristos typedef struct sframe_preamble 136*cb63e24eSchristos { 137*cb63e24eSchristos uint16_t sfp_magic; 138*cb63e24eSchristos uint8_t sfp_version; 139*cb63e24eSchristos uint8_t sfp_flags; 140*cb63e24eSchristos } ATTRIBUTE_PACKED sframe_preamble; 141*cb63e24eSchristos 142*cb63e24eSchristos Every element of the SFrame preamble is naturally aligned. 143*cb63e24eSchristos 144*cb63e24eSchristos All values are stored in the endianness of the target system for 145*cb63e24eSchristoswhich the SFrame section is intended. Further details: 146*cb63e24eSchristos 147*cb63e24eSchristosOffset Name Description 148*cb63e24eSchristos----------------------------------------------------------------------------------------- 149*cb63e24eSchristos0x00 ‘uint16_t sfp_magic’ The magic number for SFrame section: 0xdee2. Defined 150*cb63e24eSchristos as a macro ‘SFRAME_MAGIC’. 151*cb63e24eSchristos 152*cb63e24eSchristos0x02 ‘uint8_t sfp_version’ The version number of this SFrame section. 153*cb63e24eSchristos *Note SFrame version::, for the set of valid values. 154*cb63e24eSchristos Current version is ‘SFRAME_VERSION_1’. 155*cb63e24eSchristos 156*cb63e24eSchristos0x03 ‘uint8_t sfp_flags’ Flags (section-wide) for this SFrame section. 157*cb63e24eSchristos *Note SFrame flags::, for the set of valid values. 158*cb63e24eSchristos 159*cb63e24eSchristos* Menu: 160*cb63e24eSchristos 161*cb63e24eSchristos* SFrame endianness:: 162*cb63e24eSchristos* SFrame version:: 163*cb63e24eSchristos* SFrame flags:: 164*cb63e24eSchristos 165*cb63e24eSchristos 166*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame endianness, Next: SFrame version, Up: SFrame Preamble 167*cb63e24eSchristos 168*cb63e24eSchristos2.1.1 SFrame endianness 169*cb63e24eSchristos----------------------- 170*cb63e24eSchristos 171*cb63e24eSchristosSFrame sections are stored in the target endianness of the system that 172*cb63e24eSchristosconsumes them. The SFrame library (‘libsframe’) can, however, detect 173*cb63e24eSchristoswhether to endian-flip an SFrame section at decode time, by inspecting 174*cb63e24eSchristosthe ‘sfp_magic’ field in the SFrame header (If it appears as 0xe2de, 175*cb63e24eSchristosendian-flipping is needed). 176*cb63e24eSchristos 177*cb63e24eSchristos 178*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame version, Next: SFrame flags, Prev: SFrame endianness, Up: SFrame Preamble 179*cb63e24eSchristos 180*cb63e24eSchristos2.1.2 SFrame version 181*cb63e24eSchristos-------------------- 182*cb63e24eSchristos 183*cb63e24eSchristosThe version of the SFrame format can be determined by inspecting 184*cb63e24eSchristos‘sfp_version’. The following versions are currently valid: 185*cb63e24eSchristos 186*cb63e24eSchristosVersion Number Description 187*cb63e24eSchristos------------------------------------------------------------------ 188*cb63e24eSchristos‘SFRAME_VERSION_1’ 1 First version, obsolete. 189*cb63e24eSchristos‘SFRAME_VERSION_2’ 2 Current version, under development. 190*cb63e24eSchristos 191*cb63e24eSchristos This document describes ‘SFRAME_VERSION_2’. 192*cb63e24eSchristos 193*cb63e24eSchristos 194*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame flags, Prev: SFrame version, Up: SFrame Preamble 195*cb63e24eSchristos 196*cb63e24eSchristos2.1.3 SFrame flags 197*cb63e24eSchristos------------------ 198*cb63e24eSchristos 199*cb63e24eSchristosThe preamble contains bitflags in its ‘sfp_flags’ field that describe 200*cb63e24eSchristosvarious section-wide properties. 201*cb63e24eSchristos 202*cb63e24eSchristos The following flags are currently defined. 203*cb63e24eSchristos 204*cb63e24eSchristosFlag Versions Value Meaning 205*cb63e24eSchristos---------------------------------------------------------------------------- 206*cb63e24eSchristos‘SFRAME_F_FDE_SORTED’ All 0x1 Function Descriptor Entries 207*cb63e24eSchristos are sorted on PC. 208*cb63e24eSchristos‘SFRAME_F_FRAME_POINTER’ All 0x2 Functions preserve 209*cb63e24eSchristos frame-pointer. 210*cb63e24eSchristos 211*cb63e24eSchristos Further flags may be added in future. 212*cb63e24eSchristos 213*cb63e24eSchristos 214*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame section 215*cb63e24eSchristos 216*cb63e24eSchristos2.2 SFrame Header 217*cb63e24eSchristos================= 218*cb63e24eSchristos 219*cb63e24eSchristosThe SFrame header is the first part of an SFrame section. It begins 220*cb63e24eSchristoswith the SFrame preamble. All parts of it other than the preamble 221*cb63e24eSchristos(*note SFrame Preamble::) can vary between SFrame file versions. It 222*cb63e24eSchristoscontains things that apply to the section as a whole, and offsets to the 223*cb63e24eSchristosvarious other sub-sections defined in the format. As with the rest of 224*cb63e24eSchristosthe SFrame section, all values are stored in the endianness of the 225*cb63e24eSchristostarget system. 226*cb63e24eSchristos 227*cb63e24eSchristos The two sub-sections tile the SFrame section: each section runs from 228*cb63e24eSchristosthe offset given until the start of the next section. An explicit 229*cb63e24eSchristoslength is given for the last sub-section, the SFrame Frame Row Entry 230*cb63e24eSchristos(SFrame FRE) sub-section. 231*cb63e24eSchristos 232*cb63e24eSchristos typedef struct sframe_header 233*cb63e24eSchristos { 234*cb63e24eSchristos sframe_preamble sfh_preamble; 235*cb63e24eSchristos uint8_t sfh_abi_arch; 236*cb63e24eSchristos int8_t sfh_cfa_fixed_fp_offset; 237*cb63e24eSchristos int8_t sfh_cfa_fixed_ra_offset; 238*cb63e24eSchristos uint8_t sfh_auxhdr_len; 239*cb63e24eSchristos uint32_t sfh_num_fdes; 240*cb63e24eSchristos uint32_t sfh_num_fres; 241*cb63e24eSchristos uint32_t sfh_fre_len; 242*cb63e24eSchristos uint32_t sfh_fdeoff; 243*cb63e24eSchristos uint32_t sfh_freoff; 244*cb63e24eSchristos } ATTRIBUTE_PACKED sframe_header; 245*cb63e24eSchristos 246*cb63e24eSchristos Every element of the SFrame header is naturally aligned. 247*cb63e24eSchristos 248*cb63e24eSchristos The sub-section offsets, namely ‘sfh_fdeoff’ and ‘sfh_freoff’, in the 249*cb63e24eSchristosSFrame header are relative to the _end_ of the SFrame header; they are 250*cb63e24eSchristoseach an offset in bytes into the SFrame section where the SFrame FDE 251*cb63e24eSchristossub-section and the SFrame FRE sub-section respectively start. 252*cb63e24eSchristos 253*cb63e24eSchristos SFrame header allows specifying explicitly the fixed offsets from 254*cb63e24eSchristosCFA, if any, from which FP or RA may be recovered. For example, in 255*cb63e24eSchristosAMD64, the stack offset of the return address is ‘CFA - 8’. Since this 256*cb63e24eSchristosoffset is in close vicinity with the CFA in most ABIs, 257*cb63e24eSchristos‘sfh_cfa_fixed_fp_offset’ and ‘sfh_cfa_fixed_ra_offset’ are limited to 258*cb63e24eSchristossigned 8-bit integers. 259*cb63e24eSchristos 260*cb63e24eSchristos SFrame format has made some provisions for supporting more 261*cb63e24eSchristosABIs/architectures in the future. The ‘sframe_header’ structure 262*cb63e24eSchristosprovides an unsigned 8-bit integral field to denote the size of an 263*cb63e24eSchristosauxiliary SFrame header. The auxiliary SFrame header follows right 264*cb63e24eSchristosafter the ‘sframe_header’ structure. As for the offset calculations, 265*cb63e24eSchristosthe _end_ of SFrame header must be the end of the auxiliary SFrame 266*cb63e24eSchristosheader, if the latter is present. 267*cb63e24eSchristos 268*cb63e24eSchristos Putting it all together: 269*cb63e24eSchristos 270*cb63e24eSchristosOffset Name Description 271*cb63e24eSchristos---------------------------------------------------------------------------------------- 272*cb63e24eSchristos0x00 ‘sframe_preamble sfh_preamble’ The SFrame preamble. 273*cb63e24eSchristos *Note SFrame Preamble::. 274*cb63e24eSchristos 275*cb63e24eSchristos0x04 ‘uint8_t sfh_abi_arch’ The ABI/arch identifier. 276*cb63e24eSchristos *Note SFrame ABI/arch identifier::. 277*cb63e24eSchristos 278*cb63e24eSchristos0x05 ‘int8_t sfh_cfa_fixed_fp_offset’ The CFA fixed FP offset, if any. 279*cb63e24eSchristos 280*cb63e24eSchristos0x06 ‘int8_t sfh_cfa_fixed_ra_offset’ The CFA fixed RA offset, if any. 281*cb63e24eSchristos 282*cb63e24eSchristos0x07 ‘uint8_t sfh_auxhdr_len’ Size in bytes of the auxiliary header 283*cb63e24eSchristos that follows the ‘sframe_header’ 284*cb63e24eSchristos structure. 285*cb63e24eSchristos 286*cb63e24eSchristos0x08 ‘uint32_t sfh_num_fdes’ The number of SFrame FDEs in the section. 287*cb63e24eSchristos 288*cb63e24eSchristos0xc ‘uint32_t sfh_num_fres’ The number of SFrame FREs in the section. 289*cb63e24eSchristos 290*cb63e24eSchristos0x10 ‘uint32_t sfh_fre_len’ The length in bytes of the SFrame FRE 291*cb63e24eSchristos sub-section. 292*cb63e24eSchristos 293*cb63e24eSchristos0x14 ‘uint32_t sfh_fdeoff’ The offset in bytes of the SFrame FDE 294*cb63e24eSchristos sub-section. This sub-section contains 295*cb63e24eSchristos ‘sfh_num_fdes’ number of fixed-length 296*cb63e24eSchristos array elements. The array element is of 297*cb63e24eSchristos type SFrame function desciptor entry, 298*cb63e24eSchristos each providing a high-level function 299*cb63e24eSchristos description for backtracing. 300*cb63e24eSchristos *Note SFrame Function Descriptor Entries::. 301*cb63e24eSchristos 302*cb63e24eSchristos0x18 ‘uint32_t sfh_freoff’ The offset in bytes of the SFrame FRE 303*cb63e24eSchristos sub-section, the core of the SFrame 304*cb63e24eSchristos section, which describes the stack trace 305*cb63e24eSchristos information using variable-length array 306*cb63e24eSchristos elements. 307*cb63e24eSchristos *Note SFrame Frame Row Entries::. 308*cb63e24eSchristos 309*cb63e24eSchristos 310*cb63e24eSchristos* Menu: 311*cb63e24eSchristos 312*cb63e24eSchristos* SFrame ABI/arch identifier:: 313*cb63e24eSchristos 314*cb63e24eSchristos 315*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame ABI/arch identifier, Up: SFrame Header 316*cb63e24eSchristos 317*cb63e24eSchristos2.2.1 SFrame ABI/arch identifier 318*cb63e24eSchristos-------------------------------- 319*cb63e24eSchristos 320*cb63e24eSchristosSFrame header identifies the ABI/arch of the target system for which the 321*cb63e24eSchristosexecutable and hence, the stack trace information contained in the 322*cb63e24eSchristosSFrame section, is intended. There are currently three identifiable 323*cb63e24eSchristosABI/arch values in the format. 324*cb63e24eSchristos 325*cb63e24eSchristosABI/arch Identifier Value Description 326*cb63e24eSchristos 327*cb63e24eSchristos--------------------------------------------------------------------- 328*cb63e24eSchristos‘SFRAME_ABI_AARCH64_ENDIAN_BIG’ 1 AARCH64 big-endian 329*cb63e24eSchristos 330*cb63e24eSchristos‘SFRAME_ABI_AARCH64_ENDIAN_LITTLE’ 2 AARCH64 little-endian 331*cb63e24eSchristos 332*cb63e24eSchristos‘SFRAME_ABI_AMD64_ENDIAN_LITTLE’ 3 AMD64 little-endian 333*cb63e24eSchristos 334*cb63e24eSchristos 335*cb63e24eSchristos The presence of an explicit identification of ABI/arch in SFrame may 336*cb63e24eSchristosallow stack trace generators to make certain ABI-specific decisions. 337*cb63e24eSchristos 338*cb63e24eSchristos 339*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame section 340*cb63e24eSchristos 341*cb63e24eSchristos2.3 SFrame FDE 342*cb63e24eSchristos============== 343*cb63e24eSchristos 344*cb63e24eSchristosThe SFrame Function Descriptor Entry sub-section is a sorted array of 345*cb63e24eSchristosfixed-length SFrame function descriptor entries (SFrame FDEs). Each 346*cb63e24eSchristosSFrame FDE is a packed structure which contains information to describe 347*cb63e24eSchristosa function’s stack trace information at a high-level. 348*cb63e24eSchristos 349*cb63e24eSchristos typedef struct sframe_func_desc_entry 350*cb63e24eSchristos { 351*cb63e24eSchristos int32_t sfde_func_start_address; 352*cb63e24eSchristos uint32_t sfde_func_size; 353*cb63e24eSchristos uint32_t sfde_func_start_fre_off; 354*cb63e24eSchristos uint32_t sfde_func_num_fres; 355*cb63e24eSchristos uint8_t sfde_func_info; 356*cb63e24eSchristos uint8_t sfde_func_rep_size; 357*cb63e24eSchristos uint16_t sfde_func_padding2; 358*cb63e24eSchristos } ATTRIBUTE_PACKED sframe_func_desc_entry; 359*cb63e24eSchristos 360*cb63e24eSchristos Every element of the SFrame function descriptor entry is naturally 361*cb63e24eSchristosaligned. 362*cb63e24eSchristos 363*cb63e24eSchristos ‘sfde_func_start_fre_off’ is the offset to the first SFrame FRE for 364*cb63e24eSchristosthe function. This offset is relative to the _end of the SFrame FDE_ 365*cb63e24eSchristossub-section (unlike the offsets in the SFrame header, which are relative 366*cb63e24eSchristosto the _end_ of the SFrame header). 367*cb63e24eSchristos 368*cb63e24eSchristos ‘sfde_func_info’ is the "info word", containing information on the 369*cb63e24eSchristosFRE type and the FDE type for the function *Note The SFrame FDE info 370*cb63e24eSchristosword::. 371*cb63e24eSchristos 372*cb63e24eSchristos Following table describes each component of the SFrame FDE structure: 373*cb63e24eSchristos 374*cb63e24eSchristosOffset Name Description 375*cb63e24eSchristos------------------------------------------------------------------------------------------ 376*cb63e24eSchristos0x00 ‘int32_t sfde_func_start_address’ Signed 32-bit integral field denoting the 377*cb63e24eSchristos virtual memory address of the described 378*cb63e24eSchristos function. 379*cb63e24eSchristos 380*cb63e24eSchristos0x04 ‘uint32_t sfde_func_size’ Unsigned 32-bit integral field specifying 381*cb63e24eSchristos the size of the function in bytes. 382*cb63e24eSchristos 383*cb63e24eSchristos0x08 ‘uint32_t sfde_func_start_fre_off’ Unsigned 32-bit integral field specifying 384*cb63e24eSchristos the offset in bytes of the function’s 385*cb63e24eSchristos first SFrame FRE in the SFrame section. 386*cb63e24eSchristos 387*cb63e24eSchristos0x0c ‘uint32_t sfde_func_num_fres’ Unsigned 32-bit integral field specifying 388*cb63e24eSchristos the total number of SFrame FREs used for 389*cb63e24eSchristos the function. 390*cb63e24eSchristos 391*cb63e24eSchristos0x10 ‘uint8_t sfde_func_info’ Unsigned 8-bit integral field specifying 392*cb63e24eSchristos the SFrame FDE info word. 393*cb63e24eSchristos *Note The SFrame FDE info word::. 394*cb63e24eSchristos 395*cb63e24eSchristos0x11 ‘uint8_t sfde_func_rep_size’ Unsigned 8-bit integral field specifying 396*cb63e24eSchristos the size of the repetitive code block for 397*cb63e24eSchristos which an SFrame FDE of type 398*cb63e24eSchristos SFRAME_FDE_TYPE_PCMASK is used. For 399*cb63e24eSchristos example, in AMD64, the size of a pltN 400*cb63e24eSchristos entry is 16 bytes. 401*cb63e24eSchristos 402*cb63e24eSchristos0x12 ‘uint16_t sfde_func_padding2’ Padding of 2 bytes. Currently unused 403*cb63e24eSchristos bytes. 404*cb63e24eSchristos 405*cb63e24eSchristos 406*cb63e24eSchristos* Menu: 407*cb63e24eSchristos 408*cb63e24eSchristos* The SFrame FDE info word:: 409*cb63e24eSchristos* The SFrame FDE types:: 410*cb63e24eSchristos* The SFrame FRE types:: 411*cb63e24eSchristos 412*cb63e24eSchristos 413*cb63e24eSchristosFile: sframe-spec.info, Node: The SFrame FDE info word, Next: The SFrame FDE types, Up: SFrame Function Descriptor Entries 414*cb63e24eSchristos 415*cb63e24eSchristos2.3.1 The SFrame FDE info word 416*cb63e24eSchristos------------------------------ 417*cb63e24eSchristos 418*cb63e24eSchristosThe info word is a bitfield split into three parts. From MSB to LSB: 419*cb63e24eSchristos 420*cb63e24eSchristosBit offset Name Description 421*cb63e24eSchristos---------------------------------------------------------------------------------------- 422*cb63e24eSchristos7–6 ‘unused’ Unused bits. 423*cb63e24eSchristos 424*cb63e24eSchristos5 ‘pauth_key’ Specify which key is used for signing the return addresses 425*cb63e24eSchristos in the SFrame FDE. Two possible values: 426*cb63e24eSchristos SFRAME_AARCH64_PAUTH_KEY_A (0), or 427*cb63e24eSchristos SFRAME_AARCH64_PAUTH_KEY_B (1). 428*cb63e24eSchristos 429*cb63e24eSchristos4 ‘fdetype’ Specify the SFrame FDE type. Two possible values: 430*cb63e24eSchristos SFRAME_FDE_TYPE_PCMASK (1), or 431*cb63e24eSchristos SFRAME_FDE_TYPE_PCINC (0). 432*cb63e24eSchristos *Note The SFrame FDE types::. 433*cb63e24eSchristos 434*cb63e24eSchristos0–3 ‘fretype’ Choice of three SFrame FRE types. 435*cb63e24eSchristos *Note The SFrame FRE types::. 436*cb63e24eSchristos 437*cb63e24eSchristos 438*cb63e24eSchristosFile: sframe-spec.info, Node: The SFrame FDE types, Next: The SFrame FRE types, Prev: The SFrame FDE info word, Up: SFrame Function Descriptor Entries 439*cb63e24eSchristos 440*cb63e24eSchristos2.3.2 The SFrame FDE types 441*cb63e24eSchristos-------------------------- 442*cb63e24eSchristos 443*cb63e24eSchristosSFrame format defines two types of FDE entries. The choice of which 444*cb63e24eSchristosSFrame FDE type to use is made based on the instruction patterns in the 445*cb63e24eSchristosrelevant program stub. 446*cb63e24eSchristos 447*cb63e24eSchristos An SFrame FDE of type ‘SFRAME_FDE_TYPE_PCINC’ is an indication that 448*cb63e24eSchristosthe PCs in the FREs should be treated as increments in bytes. This is 449*cb63e24eSchristosused fo the the bulk of the executable code of a program, which contains 450*cb63e24eSchristosinstructions with no specific pattern. 451*cb63e24eSchristos 452*cb63e24eSchristos In contrast, an SFrame FDE of type ‘SFRAME_FDE_TYPE_PCMASK’ is an 453*cb63e24eSchristosindication that the PCs in the FREs should be treated as masks. This 454*cb63e24eSchristostype is useful for the cases where a small pattern of instructions in a 455*cb63e24eSchristosprogram stub is used repeatedly for a specific functionality. Typical 456*cb63e24eSchristosusecases are pltN entries and trampolines. 457*cb63e24eSchristos 458*cb63e24eSchristosName of SFrame FDE Value Description 459*cb63e24eSchristostype 460*cb63e24eSchristos--------------------------------------------------------------------------- 461*cb63e24eSchristosSFRAME_FDE_TYPE_PCINC 0 Unwinders perform a 462*cb63e24eSchristos (PC >= FRE_START_ADDR) to look up a 463*cb63e24eSchristos matching FRE. 464*cb63e24eSchristos 465*cb63e24eSchristosSFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a 466*cb63e24eSchristos (PC % REP_BLOCK_SIZE 467*cb63e24eSchristos >= FRE_START_ADDR) to look up a 468*cb63e24eSchristos matching FRE. REP_BLOCK_SIZE is the 469*cb63e24eSchristos size in bytes of the repeating block of 470*cb63e24eSchristos program instructions. 471*cb63e24eSchristos 472*cb63e24eSchristos 473*cb63e24eSchristos 474*cb63e24eSchristosFile: sframe-spec.info, Node: The SFrame FRE types, Prev: The SFrame FDE types, Up: SFrame Function Descriptor Entries 475*cb63e24eSchristos 476*cb63e24eSchristos2.3.3 The SFrame FRE types 477*cb63e24eSchristos-------------------------- 478*cb63e24eSchristos 479*cb63e24eSchristosA real world application can have functions of size big and small. 480*cb63e24eSchristosSFrame format defines three types of SFrame FRE entries to represent the 481*cb63e24eSchristosstack trace information for such a variety of function sizes. These 482*cb63e24eSchristosrepresentations vary in the number of bits needed to encode the start 483*cb63e24eSchristosaddress offset in the SFrame FRE. 484*cb63e24eSchristos 485*cb63e24eSchristos The following constants are defined and used to identify the SFrame 486*cb63e24eSchristosFRE types: 487*cb63e24eSchristos 488*cb63e24eSchristosName Value Description 489*cb63e24eSchristos 490*cb63e24eSchristos-------------------------------------------------------------------------- 491*cb63e24eSchristos‘SFRAME_FRE_TYPE_ADDR1’ 0 The start address offset (in bytes) 492*cb63e24eSchristos of the SFrame FRE is an unsigned 493*cb63e24eSchristos 8-bit value. 494*cb63e24eSchristos 495*cb63e24eSchristos‘SFRAME_FRE_TYPE_ADDR2’ 1 The start address offset (in bytes) 496*cb63e24eSchristos of the SFrame FRE is an unsigned 497*cb63e24eSchristos 16-bit value. 498*cb63e24eSchristos 499*cb63e24eSchristos‘SFRAME_FRE_TYPE_ADDR4’ 2 The start address offset (in bytes) 500*cb63e24eSchristos of the SFrame FRE is an unsigned 501*cb63e24eSchristos 32-bit value. 502*cb63e24eSchristos 503*cb63e24eSchristos A single function must use the same type of SFrame FRE throughout. 504*cb63e24eSchristosAn identifier to reflect the chosen SFrame FRE type is stored in the 505*cb63e24eSchristos*Note The SFrame FDE info word::. 506*cb63e24eSchristos 507*cb63e24eSchristos 508*cb63e24eSchristosFile: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame section 509*cb63e24eSchristos 510*cb63e24eSchristos2.4 SFrame FRE 511*cb63e24eSchristos============== 512*cb63e24eSchristos 513*cb63e24eSchristosThe SFrame Frame Row Entry sub-section contains the core of the stack 514*cb63e24eSchristostrace information. 515*cb63e24eSchristos 516*cb63e24eSchristos An SFrame Frame Row Entry is a self-sufficient record containing 517*cb63e24eSchristosSFrame stack trace information for a range of contiguous addresses, 518*cb63e24eSchristosstarting at the specified offset from the start of the function. Each 519*cb63e24eSchristosSFrame Frame Row Entry is followed by S*N bytes, where: 520*cb63e24eSchristos 521*cb63e24eSchristos − ‘S’ is the size of the stack frame offset for the FRE, and 522*cb63e24eSchristos − ‘N’ is the number of stack frame offsets in the FRE 523*cb63e24eSchristos 524*cb63e24eSchristos The stack offsets, following the FRE, are interpreted in order as 525*cb63e24eSchristosfollows: 526*cb63e24eSchristos 527*cb63e24eSchristos − The first offset is always used to locate the CFA, by interpreting 528*cb63e24eSchristos it as: CFA = ‘BASE_REG’ + offset1. 529*cb63e24eSchristos − If RA is being tracked, the second offset is always used to locate 530*cb63e24eSchristos the RA, by interpreting it as: RA = CFA + offset2. If RA is _not_ 531*cb63e24eSchristos being tracked _and_ FP is being tracked, the second offset will be 532*cb63e24eSchristos used to locate the FP, by interpreting it as: FP = CFA + offset2. 533*cb63e24eSchristos − If both RA and FP are being tracked, the third offset will be used 534*cb63e24eSchristos to locate the FP, by interpreting it as FP = CFA + offset3. 535*cb63e24eSchristos 536*cb63e24eSchristos The entities ‘S’, ‘N’ and ‘BASE_REG’ are identified using the SFrame 537*cb63e24eSchristosFRE info word, a.k.a. the ‘sframe_fre_info’ *Note The SFrame FRE info 538*cb63e24eSchristosword::. 539*cb63e24eSchristos 540*cb63e24eSchristos Following are the definitions of the allowed SFrame FRE: 541*cb63e24eSchristos 542*cb63e24eSchristos typedef struct sframe_frame_row_entry_addr1 543*cb63e24eSchristos { 544*cb63e24eSchristos uint8_t sfre_start_address; 545*cb63e24eSchristos sframe_fre_info sfre_info; 546*cb63e24eSchristos } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; 547*cb63e24eSchristos 548*cb63e24eSchristos typedef struct sframe_frame_row_entry_addr2 549*cb63e24eSchristos { 550*cb63e24eSchristos uint16_t sfre_start_address; 551*cb63e24eSchristos sframe_fre_info sfre_info; 552*cb63e24eSchristos } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; 553*cb63e24eSchristos 554*cb63e24eSchristos typedef struct sframe_frame_row_entry_addr4 555*cb63e24eSchristos { 556*cb63e24eSchristos uint32_t sfre_start_address; 557*cb63e24eSchristos sframe_fre_info sfre_info; 558*cb63e24eSchristos } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; 559*cb63e24eSchristos 560*cb63e24eSchristos For ensuring compactness, SFrame frame row entries are stored 561*cb63e24eSchristosunaligned on disk. Appropriate mechanisms need to be employed, as 562*cb63e24eSchristosnecessary, by the serializing and deserializing entities, if unaligned 563*cb63e24eSchristosaccesses need to be avoided. 564*cb63e24eSchristos 565*cb63e24eSchristos ‘sfre_start_address’ is an unsigned 8-bit/16-bit/32-bit integral 566*cb63e24eSchristosfield identifies the start address of the range of program counters, for 567*cb63e24eSchristoswhich the SFrame FRE applies. The value encoded in the 568*cb63e24eSchristos‘sfre_start_address’ field is the offset in bytes of the start address 569*cb63e24eSchristosof the SFrame FRE, from the start address of the function. 570*cb63e24eSchristos 571*cb63e24eSchristos Further FRE types may be added in future. 572*cb63e24eSchristos 573*cb63e24eSchristos* Menu: 574*cb63e24eSchristos 575*cb63e24eSchristos* The SFrame FRE info word:: 576*cb63e24eSchristos 577*cb63e24eSchristos 578*cb63e24eSchristosFile: sframe-spec.info, Node: The SFrame FRE info word, Up: SFrame Frame Row Entries 579*cb63e24eSchristos 580*cb63e24eSchristos2.4.1 The SFrame FRE info word 581*cb63e24eSchristos------------------------------ 582*cb63e24eSchristos 583*cb63e24eSchristosThe SFrame FRE info word is a bitfield split into four parts. From MSB 584*cb63e24eSchristosto LSB: 585*cb63e24eSchristos 586*cb63e24eSchristosBit offset Name Description 587*cb63e24eSchristos------------------------------------------------------------------------------------- 588*cb63e24eSchristos7 ‘fre_mangled_ra_p’ Indicate whether the return address is 589*cb63e24eSchristos mangled with any authorization bits (signed 590*cb63e24eSchristos RA). 591*cb63e24eSchristos 592*cb63e24eSchristos5-6 ‘fre_offset_size’ Size of stack offsets in bytes. Valid values 593*cb63e24eSchristos are: 594*cb63e24eSchristos SFRAME_FRE_OFFSET_1B, 595*cb63e24eSchristos SFRAME_FRE_OFFSET_2B, and 596*cb63e24eSchristos SFRAME_FRE_OFFSET_4B. 597*cb63e24eSchristos 598*cb63e24eSchristos1-4 ‘fre_offset_count’ A value of upto 3 is allowed to track all 599*cb63e24eSchristos three of CFA, FP and RA. 600*cb63e24eSchristos 601*cb63e24eSchristos0 ‘fre_cfa_base_reg_id’ Distinguish between SP or FP based CFA 602*cb63e24eSchristos recovery. 603*cb63e24eSchristos 604*cb63e24eSchristos 605*cb63e24eSchristosName Value Description 606*cb63e24eSchristos 607*cb63e24eSchristos-------------------------------------------------------------------------------- 608*cb63e24eSchristos‘SFRAME_FRE_OFFSET_1B’ 0 All stack offsets following the fixed-length 609*cb63e24eSchristos FRE structure are 1 byte long. 610*cb63e24eSchristos 611*cb63e24eSchristos‘SFRAME_FRE_OFFSET_2B’ 1 All stack offsets following the fixed-length 612*cb63e24eSchristos FRE structure are 2 bytes long. 613*cb63e24eSchristos 614*cb63e24eSchristos‘SFRAME_FRE_OFFSET_4B’ 2 All stack offsets following the fixed-length 615*cb63e24eSchristos FRE structure are 4 bytes long. 616*cb63e24eSchristos 617*cb63e24eSchristos 618*cb63e24eSchristos 619*cb63e24eSchristosFile: sframe-spec.info, Node: Index, Prev: SFrame section, Up: Top 620*cb63e24eSchristos 621*cb63e24eSchristosIndex 622*cb63e24eSchristos***** 623*cb63e24eSchristos 624*cb63e24eSchristos[index] 625*cb63e24eSchristos* Menu: 626*cb63e24eSchristos 627*cb63e24eSchristos* Changes from Version 1 to Version 2: Changes from Version 1 to Version 2. 628*cb63e24eSchristos (line 6) 629*cb63e24eSchristos* endianness: SFrame endianness. (line 6) 630*cb63e24eSchristos* Introduction: Introduction. (line 6) 631*cb63e24eSchristos* Overview: Overview. (line 6) 632*cb63e24eSchristos* SFrame ABI/arch identifier: SFrame ABI/arch identifier. 633*cb63e24eSchristos (line 6) 634*cb63e24eSchristos* SFrame FDE: SFrame Function Descriptor Entries. 635*cb63e24eSchristos (line 6) 636*cb63e24eSchristos* SFrame flags: SFrame flags. (line 6) 637*cb63e24eSchristos* SFrame FRE: SFrame Frame Row Entries. 638*cb63e24eSchristos (line 6) 639*cb63e24eSchristos* SFrame header: SFrame Header. (line 6) 640*cb63e24eSchristos* SFrame preamble: SFrame Preamble. (line 6) 641*cb63e24eSchristos* SFrame section: SFrame section. (line 6) 642*cb63e24eSchristos* SFrame versions: SFrame version. (line 9) 643*cb63e24eSchristos* SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch identifier. 644*cb63e24eSchristos (line 13) 645*cb63e24eSchristos* SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch identifier. 646*cb63e24eSchristos (line 16) 647*cb63e24eSchristos* SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch identifier. 648*cb63e24eSchristos (line 18) 649*cb63e24eSchristos* SFRAME_FDE_TYPE_PCINC: The SFrame FDE types. (line 6) 650*cb63e24eSchristos* SFRAME_FDE_TYPE_PCMASK: The SFrame FDE types. (line 6) 651*cb63e24eSchristos* SFRAME_FRE_OFFSET_1B: The SFrame FRE info word. 652*cb63e24eSchristos (line 30) 653*cb63e24eSchristos* SFRAME_FRE_OFFSET_2B: The SFrame FRE info word. 654*cb63e24eSchristos (line 34) 655*cb63e24eSchristos* SFRAME_FRE_OFFSET_4B: The SFrame FRE info word. 656*cb63e24eSchristos (line 37) 657*cb63e24eSchristos* SFRAME_FRE_TYPE_ADDR1: The SFrame FRE types. (line 17) 658*cb63e24eSchristos* SFRAME_FRE_TYPE_ADDR2: The SFrame FRE types. (line 22) 659*cb63e24eSchristos* SFRAME_FRE_TYPE_ADDR4: The SFrame FRE types. (line 26) 660*cb63e24eSchristos* SFRAME_F_FDE_SORTED: SFrame flags. (line 11) 661*cb63e24eSchristos* SFRAME_F_FRAME_POINTER: SFrame flags. (line 14) 662*cb63e24eSchristos* SFRAME_MAGIC: SFrame Preamble. (line 24) 663*cb63e24eSchristos* SFRAME_VERSION_1: SFrame version. (line 9) 664*cb63e24eSchristos* The SFrame FDE info word: SFrame Function Descriptor Entries. 665*cb63e24eSchristos (line 73) 666*cb63e24eSchristos* The SFrame FRE info word: SFrame Frame Row Entries. 667*cb63e24eSchristos (line 69) 668*cb63e24eSchristos 669*cb63e24eSchristos 670*cb63e24eSchristos 671*cb63e24eSchristosTag Table: 672*cb63e24eSchristosNode: Top569 673*cb63e24eSchristosNode: Introduction1159 674*cb63e24eSchristosNode: Overview1345 675*cb63e24eSchristosNode: Changes from Version 1 to Version 22932 676*cb63e24eSchristosNode: SFrame section3709 677*cb63e24eSchristosNode: SFrame Preamble4185 678*cb63e24eSchristosNode: SFrame endianness5624 679*cb63e24eSchristosNode: SFrame version6088 680*cb63e24eSchristosNode: SFrame flags6664 681*cb63e24eSchristosNode: SFrame Header7396 682*cb63e24eSchristosNode: SFrame ABI/arch identifier12592 683*cb63e24eSchristosNode: SFrame Function Descriptor Entries13627 684*cb63e24eSchristosNode: The SFrame FDE info word17329 685*cb63e24eSchristosNode: The SFrame FDE types18504 686*cb63e24eSchristosNode: The SFrame FRE types20233 687*cb63e24eSchristosNode: SFrame Frame Row Entries21777 688*cb63e24eSchristosNode: The SFrame FRE info word24470 689*cb63e24eSchristosNode: Index26480 690*cb63e24eSchristos 691*cb63e24eSchristosEnd Tag Table 692*cb63e24eSchristos 693*cb63e24eSchristos 694*cb63e24eSchristosLocal Variables: 695*cb63e24eSchristoscoding: utf-8 696*cb63e24eSchristosEnd: 697