1This is sframe-spec.info, produced by makeinfo version 6.8 from 2sframe-spec.texi. 3 4Copyright (C) 2021-2022 Free Software Foundation, Inc. 5 6 Permission is granted to copy, distribute and/or modify this document 7under the terms of the GNU General Public License, Version 3 or any 8later version published by the Free Software Foundation. A copy of the 9license is included in the section entitled "GNU General Public 10License". 11 12INFO-DIR-SECTION Software development 13START-INFO-DIR-ENTRY 14* SFrame: (sframe-spec). The Simple Frame format. 15END-INFO-DIR-ENTRY 16 17 18File: sframe-spec.info, Node: Top, Next: Overview, Up: (dir) 19 20The SFrame format 21***************** 22 23This manual describes version 1 of the SFrame file format. SFrame 24stands for Simple Frame format. SFrame format keeps track of the 25minimal necessary information needed for stack unwinding: 26 27 - Canonical Frame Address (CFA). 28 - Frame Pointer (FP). 29 - Return Address (RA). 30 31 The reason for existence of the SFrame format is to support fast, 32online backtracing using a simple unwinder. 33 34* Menu: 35 36* Overview:: 37* SFrame section:: 38* Index:: 39 40 41File: sframe-spec.info, Node: Overview, Next: SFrame section, Prev: Top, Up: Top 42 43Overview 44******** 45 46The SFrame unwind information is provided in a loaded section, known as 47the '.sframe' section. When available, the '.sframe' section appears in 48a new segment of its own, PT_GNU_SFRAME. 49 50 The SFrame format is currently supported only for select ABIs, 51namely, AMD64 and AAPCS64. 52 53 The contents of the SFrame section are stored in the target 54endianness, i.e., in the endianness of the system on which the section 55is targetted to be used. An SFrame section reader may use the magic 56number in the SFrame header to identify the endianness of the SFrame 57section. 58 59 Addresses in this specification are expressed in bytes. 60 61 The associated API to decode, probe and encode the SFrame section, 62provided via 'libsframe', is not accompanied here at this time. This 63will be added later. 64 65 This document is intended to be in sync with the C code in 66'sframe.h'. Please report descrepancies between the two, if any. 67 68 69File: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Overview, Up: Top 70 711 SFrame section 72**************** 73 74The SFrame section consists of an SFrame header, starting with a 75preamble, and two other sub-sections, namely the SFrame Function 76Descriptor Entry (SFrame FDE) sub-section, and the SFrame Frame Row 77Entry (SFrame FRE) sub-section. 78 79* Menu: 80 81* SFrame Preamble:: 82* SFrame Header:: 83* SFrame Function Descriptor Entries:: 84* SFrame Frame Row Entries:: 85 86 87File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame section 88 891.1 SFrame Preamble 90=================== 91 92The preamble is a 32-bit packed structure; the only part of the SFrame 93whose format cannot vary between versions. 94 95 typedef struct sframe_preamble 96 { 97 uint16_t sfp_magic; 98 uint8_t sfp_version; 99 uint8_t sfp_flags; 100 } ATTRIBUTE_PACKED sframe_preamble; 101 102 All values are stored in the endianness of the target system for 103which the SFrame section is intended. Further details: 104 105Offset Name Description 106----------------------------------------------------------------------------------------- 1070x00 'uint16_t sfp_magic' The magic number for SFrame section: 0xdee2. Defined 108 as a macro 'SFRAME_MAGIC'. 109 1100x02 'uint8_t sfp_version' The version number of this SFrame section. 111 *Note SFrame version::, for the set of valid values. 112 Current version is 'SFRAME_VERSION_1'. 113 1140x03 'uint8_t sfp_flags' Flags (section-wide) for this SFrame section. 115 *Note SFrame flags::, for the set of valid values. 116 117* Menu: 118 119* SFrame endianness:: 120* SFrame version:: 121* SFrame flags:: 122 123 124File: sframe-spec.info, Node: SFrame endianness, Next: SFrame version, Up: SFrame Preamble 125 1261.1.1 SFrame endianness 127----------------------- 128 129SFrame sections are stored in the target endianness of the system that 130consumes them. The SFrame library ('libsframe') can, however, detect 131whether to endian-flip an SFrame section at decode time, by inspecting 132the 'sfp_magic' field in the SFrame header (If it appears as 0xe2de, 133endian-flipping is needed). 134 135 136File: sframe-spec.info, Node: SFrame version, Next: SFrame flags, Prev: SFrame endianness, Up: SFrame Preamble 137 1381.1.2 SFrame version 139-------------------- 140 141The version of the SFrame format can be determined by inspecting 142'sfp_version'. The following versions are currently valid: 143 144Version Number Description 145---------------------------------------------------------------- 146'SFRAME_VERSION_1' 1 First version, under development. 147 148 This section documents 'SFRAME_VERSION_1'. 149 150 151File: sframe-spec.info, Node: SFrame flags, Prev: SFrame version, Up: SFrame Preamble 152 1531.1.3 SFrame flags 154------------------ 155 156The preamble contains bitflags in its 'sfp_flags' field that describe 157various section-wide properties. 158 159 The following flags are currently defined. 160 161Flag Versions Value Meaning 162---------------------------------------------------------------------------- 163'SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries 164 are sorted on PC. 165'SFRAME_F_FRAME_POINTER' All 0x2 Functions preserve 166 frame-pointer. 167 168 Further flags may be added in future. 169 170 171File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame section 172 1731.2 SFrame Header 174================= 175 176The SFrame header is the first part of an SFrame section. It begins 177with the SFrame preamble. All parts of it other than the preamble 178(*note SFrame Preamble::) can vary between SFrame file versions. It 179contains things that apply to the section as a whole, and offsets to the 180various other sub-sections defined in the format. As with the rest of 181the SFrame section, all values are stored in the endianness of the 182target system. 183 184 The two sub-sections tile the SFrame section: each section runs from 185the offset given until the start of the next section. An explicit 186length is given for the last sub-section, the SFrame Frame Row Entry 187(SFrame FRE) sub-section. 188 189 typedef struct sframe_header 190 { 191 sframe_preamble sfh_preamble; 192 uint8_t sfh_abi_arch; 193 int8_t sfh_cfa_fixed_fp_offset; 194 int8_t sfh_cfa_fixed_ra_offset; 195 uint8_t sfh_auxhdr_len; 196 uint32_t sfh_num_fdes; 197 uint32_t sfh_num_fres; 198 uint32_t sfh_fre_len; 199 uint32_t sfh_fdeoff; 200 uint32_t sfh_freoff; 201 } ATTRIBUTE_PACKED sframe_header; 202 203 The sub-section offsets, namely 'sfh_fdeoff' and 'sfh_freoff', in the 204SFrame header are relative to the _end_ of the SFrame header; they are 205each an offset in bytes into the SFrame section where the SFrame FDE 206sub-section and the SFrame FRE sub-section respectively start. 207 208 SFrame header allows specifying explicitly the fixed offsets from 209CFA, if any, from which FP or RA may be recovered. For example, in 210AMD64, the stack offset of the return address is 'CFA - 8'. Since this 211offset is in close vicinity with the CFA in most ABIs, 212'sfh_cfa_fixed_fp_offset' and 'sfh_cfa_fixed_ra_offset' are limited to 213signed 8-bit integers. 214 215 SFrame format has provisioned for future ABIs/architectures that it 216may support. The 'sframe_header' structure provides an unsigned 8-bit 217integral field to denote the size of an auxilliary SFrame header. The 218auxilliary SFrame header follows right after the 'sframe_header' 219structure. As for the offset calculations, the _end_ of SFrame header 220must be the end of the auxilliary SFrame header, if the latter is 221present. 222 223 Tieing it all together: 224 225Offset Name Description 226---------------------------------------------------------------------------------- 2270x00 'sframe_preamble sfh_preamble' The SFrame preamble. 228 *Note SFrame Preamble::. 229 2300x04 'uint8_t sfh_abi_arch' The ABI/arch identifier. 231 *Note SFrame ABI/arch identifier::. 232 2330x05 'int8_t sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. 234 2350x06 'int8_t sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. 236 2370x07 'uint8_t sfh_auxhdr_len' Size in bytes of the auxilliary 238 header that follows the 239 'sframe_header' structure. 240 2410x08 'uint32_t sfh_num_fdes' The number of SFrame FDEs in the 242 section. 243 2440xc 'uint32_t sfh_num_fres' The number of SFrame FREs in the 245 section. 246 2470x10 'uint32_t sfh_fre_len' The length in bytes of the SFrame 248 FRE sub-section. 249 2500x14 'uint32_t sfh_fdeoff' The offset in bytes of the SFrame 251 FDE sub-section. This sub-section 252 contains 'sfh_num_fdes' number of 253 fixed-length array elements. The 254 array element is of type SFrame 255 function desciptor entry, each 256 providing a high-level function 257 description for backtracing. 258 *Note SFrame Function Descriptor Entries::. 259 2600x18 'uint32_t sfh_freoff' The offset in bytes of the SFrame 261 FRE sub-section, the core of the 262 SFrame section, which describes the 263 unwind information using 264 variable-length array elements. 265 *Note SFrame Frame Row Entries::. 266 267 268* Menu: 269 270* SFrame ABI/arch identifier:: 271 272 273File: sframe-spec.info, Node: SFrame ABI/arch identifier, Up: SFrame Header 274 2751.2.1 SFrame ABI/arch identifier 276-------------------------------- 277 278SFrame header identifies the ABI/arch of the target system for which the 279executable and it's unwind information is intended. There are currently 280three identifiable ABI/arch values in the format. 281 282ABI/arch Identifier Value Description 283 284--------------------------------------------------------------------- 285'SFRAME_ABI_AARCH64_ENDIAN_BIG' 1 AARCH64 big-endian 286 287'SFRAME_ABI_AARCH64_ENDIAN_LITTLE' 2 AARCH64 little-endian 288 289'SFRAME_ABI_AMD64_ENDIAN_LITTLE' 3 AMD64 little-endian 290 291 292 The presence of an explicit identification of ABI/arch in SFrame may 293allow unwinders to make certain ABI-specific decisions. 294 295 296File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame section 297 2981.3 SFrame FDE 299============== 300 301The SFrame Function Descriptor Entry sub-section is a sorted array of 302fixed-length SFrame function descriptor entries (SFrame FDEs). Each 303SFrame FDE is a packed structure which contains information to describe 304a function's unwind information at a high-level. 305 306 typedef struct sframe_func_desc_entry 307 { 308 int32_t sfde_func_start_address; 309 uint32_t sfde_func_size; 310 uint32_t sfde_func_start_fre_off; 311 uint32_t sfde_func_num_fres; 312 uint8_t sfde_func_info; 313 } ATTRIBUTE_PACKED sframe_func_desc_entry; 314 315 'sfde_func_start_fre_off' is the offset to the first SFrame FRE for 316the function. This offset is relative to the _end of the SFrame FDE_ 317sub-section (unlike the offsets in the SFrame header, which are relative 318to the _end_ of the SFrame header). 319 320 'sfde_func_info' is the "info word", containing information on the 321FRE type and the FDE type for the function *Note The SFrame FDE info 322word::. 323 324 Following table describes each component of the SFrame FDE structure: 325 326Offset Name Description 327------------------------------------------------------------------------------------ 3280x00 'int32_t sfde_func_start_address' Signed 32-bit integral field 329 denoting the virtual memory address 330 of the described function. 331 3320x04 'uint32_t sfde_func_size' Unsigned 32-bit integral field 333 specifying the size of the function 334 in bytes. 335 3360x08 'uint32_t sfde_func_start_fre_off' Unsigned 32-bit integral field 337 specifying the offset in bytes of 338 the function's first SFrame FRE in 339 the SFrame section. 340 3410x0c 'uint32_t sfde_func_num_fres' Unsigned 32-bit integral field 342 specifying the total number of 343 SFrame FREs used for the function. 344 3450x10 'uint8_t sfde_func_info' The SFrame FDE info word. 346 *Note The SFrame FDE info word::. 347 348 349* Menu: 350 351* The SFrame FDE info word:: 352* The SFrame FDE types:: 353* The SFrame FRE types:: 354 355 356File: sframe-spec.info, Node: The SFrame FDE info word, Next: The SFrame FDE types, Up: SFrame Function Descriptor Entries 357 3581.3.1 The SFrame FDE info word 359------------------------------ 360 361The info word is a bitfield split into three parts. From MSB to LSB: 362 363Bit offset Name Description 364------------------------------------------------------------------------------------------ 3657-5 'unused' Unused bits. 366 3674 'fdetype' SFRAME_FDE_TYPE_PCMASK (1) or SFRAME_FDE_TYPE_PCINC (0). 368 *Note The SFrame FDE types::. 369 3700-3 'fretype' Choice of three SFrame FRE types. 371 *Note The SFrame FRE types::. 372 373 374File: sframe-spec.info, Node: The SFrame FDE types, Next: The SFrame FRE types, Prev: The SFrame FDE info word, Up: SFrame Function Descriptor Entries 375 3761.3.2 The SFrame FDE types 377-------------------------- 378 379SFrame format defines two types of FDE entries. The choice of which 380SFrame FDE type to use is made based on the instruction patterns in the 381relevant program stub. 382 383 An SFrame FDE of type 'SFRAME_FDE_TYPE_PCINC' is an indication that 384the PCs in the FREs should be treated as increments in bytes. This is 385used fo the the bulk of the executable code of a program, which contains 386instructions with no specific pattern. 387 388 In contrast, an SFrame FDE of type 'SFRAME_FDE_TYPE_PCMASK' is an 389indication that the PCs in the FREs should be treated as masks. This 390type is useful for the cases where a small pattern of instructions in a 391program stub is used repeatedly for a specific functionality. Typical 392usecases are pltN entries and trampolines. 393 394Name of SFrame FDE type Value Description 395 396------------------------------------------------------------------------------- 397SFRAME_FDE_TYPE_PCINC 0 Unwinders perform a (PC >= FRE_START_ADDR) 398 to look up a matching FRE. 399 400SFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a (PC & 401 FRE_START_ADDR_AS_MASK >= 402 FRE_START_ADDR_AS_MASK) to look up a 403 matching FRE. 404 405 406 407File: sframe-spec.info, Node: The SFrame FRE types, Prev: The SFrame FDE types, Up: SFrame Function Descriptor Entries 408 4091.3.3 The SFrame FRE types 410-------------------------- 411 412A real world application can have functions of size big and small. 413SFrame format defines three types of SFrame FRE entries to represent the 414unwind information for such a variety of function sizes. These 415representations vary in the number of bits needed to encode the start 416address offset in the SFrame FRE. 417 418 The following constants are defined and used to identify the SFrame 419FRE types: 420 421Name Value Description 422 423-------------------------------------------------------------------------- 424'SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) 425 of the SFrame FRE is an unsigned 426 8-bit value. 427 428'SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) 429 of the SFrame FRE is an unsigned 430 16-bit value. 431 432'SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) 433 of the SFrame FRE is an unsigned 434 32-bit value. 435 436 A single function must use the same type of FRE throughout. The 437choice of which SFrame FRE is used to encode the unwind information of a 438function, is stored in the *Note The SFrame FDE info word::. 439 440 441File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame section 442 4431.4 SFrame FRE 444============== 445 446The SFrame Frame Row Entry sub-section contains the core of the unwind 447information. 448 449 An SFrame Frame Row Entry is a self-sufficient record containing 450SFrame unwind info for a range of contiguous addresses, starting at the 451specified offset from the start of the function. Each SFrame Frame Row 452Entry is followed by S*N bytes, where: 453 454 - 'S' is the size of the stack frame offset for the FRE, and 455 - 'N' is the number of stack frame offsets in the FRE 456 457 The stack offsets, following the FRE, are interpreted in order as 458follows: 459 460 - The first offset is always used to locate the CFA, by interpreting 461 it as: CFA = 'BASE_REG' + offset1. 462 - If RA is being tracked, the second offset is always used to locate 463 the RA, by interpreting it as: RA = CFA + offset2. If RA is _not_ 464 being tracked _and_ FP is being tracked, the second offset will be 465 used to locate the FP, by interpreting it as: FP = CFA + offset2. 466 - If both RA and FP are being tracked, the third offset will be used 467 to locate the FP, by interpreting it as FP = CFA + offset3. 468 469 The entities 'S', 'N' and 'BASE_REG' are identified using the SFrame 470FRE info word, a.k.a. the 'sframe_fre_info' *Note The SFrame FRE info 471word::. 472 473 Following are the definitions of the allowed SFrame FRE: 474 475 typedef struct sframe_frame_row_entry_addr1 476 { 477 uint8_t sfre_start_address; 478 sframe_fre_info sfre_info; 479 } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; 480 481 typedef struct sframe_frame_row_entry_addr2 482 { 483 uint16_t sfre_start_address; 484 sframe_fre_info sfre_info; 485 } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; 486 487 typedef struct sframe_frame_row_entry_addr4 488 { 489 uint32_t sfre_start_address; 490 sframe_fre_info sfre_info; 491 } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; 492 493 'sfre_start_address' is an unsigned 8-bit/16-bit/32-bit integral 494field identifies the start address of the range of program counters, for 495which the SFrame FRE applies. The value encoded in the 496'sfre_start_address' field is the offset in bytes of the start address 497of the SFrame FRE, from the start address of the function. 498 499 Further FRE types may be added in future. 500 501* Menu: 502 503* The SFrame FRE info word:: 504 505 506File: sframe-spec.info, Node: The SFrame FRE info word, Up: SFrame Frame Row Entries 507 5081.4.1 The SFrame FRE info word 509------------------------------ 510 511The SFrame FRE info word is a bitfield split into four parts. From MSB 512to LSB: 513 514Bit offset Name Description 515------------------------------------------------------------------------------------- 5167 'fre_mangled_ra_p' Indicate whether the return address is 517 mangled with any authorization bits (signed 518 RA). 519 5205-6 'fre_offset_size' Size of stack offsets in bytes. Valid values 521 are SFRAME_FRE_OFFSET_1B, 522 SFRAME_FRE_OFFSET_2B, and 523 SFRAME_FRE_OFFSET_4B. 524 5251-4 'fre_offset_count' A value of upto 3 is allowed to track all 526 three of CFA, FP and RA. 527 5280 'fre_cfa_base_reg_id' Distinguish between SP or FP based CFA 529 recovery. 530 531 532Name Value Description 533 534-------------------------------------------------------------------------------- 535'SFRAME_FRE_OFFSET_1B' 0 All stack offsets following the fixed-length 536 FRE structure are 1 byte long. 537 538'SFRAME_FRE_OFFSET_2B' 1 All stack offsets following the fixed-length 539 FRE structure are 2 bytes long. 540 541'SFRAME_FRE_OFFSET_4B' 2 All stack offsets following the fixed-length 542 FRE structure are 4 bytes long. 543 544 545 546File: sframe-spec.info, Node: Index, Prev: SFrame section, Up: Top 547 548Index 549***** 550 551[index] 552* Menu: 553 554* endianness: SFrame endianness. (line 6) 555* Overview: Overview. (line 6) 556* PT_GNU_SFRAME: Overview. (line 6) 557* SFrame ABI/arch identifier: SFrame ABI/arch identifier. 558 (line 6) 559* SFrame FDE: SFrame Function Descriptor Entries. 560 (line 6) 561* SFrame flags: SFrame flags. (line 6) 562* SFrame FRE: SFrame Frame Row Entries. 563 (line 6) 564* SFrame header: SFrame Header. (line 6) 565* SFrame preamble: SFrame Preamble. (line 6) 566* SFrame section: SFrame section. (line 6) 567* SFrame versions: SFrame version. (line 9) 568* SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch identifier. 569 (line 12) 570* SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch identifier. 571 (line 15) 572* SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch identifier. 573 (line 17) 574* SFRAME_FDE_TYPE_PCINC: The SFrame FDE types. (line 6) 575* SFRAME_FDE_TYPE_PCMASK: The SFrame FDE types. (line 6) 576* SFRAME_FRE_OFFSET_1B: The SFrame FRE info word. 577 (line 29) 578* SFRAME_FRE_OFFSET_2B: The SFrame FRE info word. 579 (line 33) 580* SFRAME_FRE_OFFSET_4B: The SFrame FRE info word. 581 (line 36) 582* SFRAME_FRE_TYPE_ADDR1: The SFrame FRE types. (line 17) 583* SFRAME_FRE_TYPE_ADDR2: The SFrame FRE types. (line 22) 584* SFRAME_FRE_TYPE_ADDR4: The SFrame FRE types. (line 26) 585* SFRAME_F_FDE_SORTED: SFrame flags. (line 11) 586* SFRAME_F_FRAME_POINTER: SFrame flags. (line 14) 587* SFRAME_MAGIC: SFrame Preamble. (line 22) 588* SFRAME_VERSION_1: SFrame version. (line 9) 589* The SFrame FDE info word: SFrame Function Descriptor Entries. 590 (line 59) 591* The SFrame FRE info word: SFrame Frame Row Entries. 592 (line 64) 593 594 595 596Tag Table: 597Node: Top564 598Node: Overview1114 599Node: SFrame section2135 600Node: SFrame Preamble2607 601Node: SFrame endianness3963 602Node: SFrame version4419 603Node: SFrame flags4921 604Node: SFrame Header5641 605Node: SFrame ABI/arch identifier10812 606Node: SFrame Function Descriptor Entries11778 607Node: The SFrame FDE info word14571 608Node: The SFrame FDE types15296 609Node: The SFrame FRE types16864 610Node: SFrame Frame Row Entries18420 611Node: The SFrame FRE info word20817 612Node: Index22761 613 614End Tag Table 615 616 617Local Variables: 618coding: utf-8 619End: 620