head 1.1; branch 1.1.1; access; symbols netbsd-11-0-RC4:1.1.1.2 netbsd-11-0-RC3:1.1.1.2 gdb-17-1:1.1.1.4 netbsd-11-0-RC2:1.1.1.2 netbsd-11-0-RC1:1.1.1.2 gdb-16-3:1.1.1.3 perseant-exfatfs-base-20250801:1.1.1.2 netbsd-11:1.1.1.2.0.2 netbsd-11-base:1.1.1.2 gdb-15-1:1.1.1.2 perseant-exfatfs-base-20240630:1.1.1.1 perseant-exfatfs:1.1.1.1.0.2 perseant-exfatfs-base:1.1.1.1 gdb-13-2:1.1.1.1 FSF:1.1.1; locks; strict; comment @# @; 1.1 date 2023.07.30.22.44.39; author christos; state Exp; branches 1.1.1.1; next ; commitid HEIv4Prd74m1wSyE; 1.1.1.1 date 2023.07.30.22.44.39; author christos; state Exp; branches 1.1.1.1.2.1; next 1.1.1.2; commitid HEIv4Prd74m1wSyE; 1.1.1.2 date 2024.08.12.21.37.48; author christos; state Exp; branches; next 1.1.1.3; commitid dWD83H91pFit0AlF; 1.1.1.3 date 2025.08.27.17.29.01; author christos; state Exp; branches; next 1.1.1.4; commitid vgUAu9EQfEWNko8G; 1.1.1.4 date 2026.03.14.20.43.15; author christos; state Exp; branches; next ; commitid FYd84EijbJAv3ZxG; 1.1.1.1.2.1 date 2025.08.02.05.31.46; author perseant; state Exp; branches; next ; commitid 23j6GFaDws3O875G; desc @@ 1.1 log @Initial revision @ text @This is sframe-spec.info, produced by makeinfo version 6.8 from sframe-spec.texi. Copyright (C) 2021-2022 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 3 or any later version published by the Free Software Foundation. A copy of the license is included in the section entitled "GNU General Public License". INFO-DIR-SECTION Software development START-INFO-DIR-ENTRY * SFrame: (sframe-spec). The Simple Frame format. END-INFO-DIR-ENTRY  File: sframe-spec.info, Node: Top, Next: Overview, Up: (dir) The SFrame format ***************** This manual describes version 1 of the SFrame file format. SFrame stands for Simple Frame format. SFrame format keeps track of the minimal necessary information needed for stack unwinding: - Canonical Frame Address (CFA). - Frame Pointer (FP). - Return Address (RA). The reason for existence of the SFrame format is to support fast, online backtracing using a simple unwinder. * Menu: * Overview:: * SFrame section:: * Index::  File: sframe-spec.info, Node: Overview, Next: SFrame section, Prev: Top, Up: Top Overview ******** The SFrame unwind information is provided in a loaded section, known as the '.sframe' section. When available, the '.sframe' section appears in a new segment of its own, PT_GNU_SFRAME. The SFrame format is currently supported only for select ABIs, namely, AMD64 and AAPCS64. The contents of the SFrame section are stored in the target endianness, i.e., in the endianness of the system on which the section is targetted to be used. An SFrame section reader may use the magic number in the SFrame header to identify the endianness of the SFrame section. Addresses in this specification are expressed in bytes. The associated API to decode, probe and encode the SFrame section, provided via 'libsframe', is not accompanied here at this time. This will be added later. This document is intended to be in sync with the C code in 'sframe.h'. Please report descrepancies between the two, if any.  File: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Overview, Up: Top 1 SFrame section **************** The SFrame section consists of an SFrame header, starting with a preamble, and two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section. * Menu: * SFrame Preamble:: * SFrame Header:: * SFrame Function Descriptor Entries:: * SFrame Frame Row Entries::  File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame section 1.1 SFrame Preamble =================== The preamble is a 32-bit packed structure; the only part of the SFrame whose format cannot vary between versions. typedef struct sframe_preamble { uint16_t sfp_magic; uint8_t sfp_version; uint8_t sfp_flags; } ATTRIBUTE_PACKED sframe_preamble; All values are stored in the endianness of the target system for which the SFrame section is intended. Further details: Offset Name Description ----------------------------------------------------------------------------------------- 0x00 'uint16_t sfp_magic' The magic number for SFrame section: 0xdee2. Defined as a macro 'SFRAME_MAGIC'. 0x02 'uint8_t sfp_version' The version number of this SFrame section. *Note SFrame version::, for the set of valid values. Current version is 'SFRAME_VERSION_1'. 0x03 'uint8_t sfp_flags' Flags (section-wide) for this SFrame section. *Note SFrame flags::, for the set of valid values. * Menu: * SFrame endianness:: * SFrame version:: * SFrame flags::  File: sframe-spec.info, Node: SFrame endianness, Next: SFrame version, Up: SFrame Preamble 1.1.1 SFrame endianness ----------------------- SFrame sections are stored in the target endianness of the system that consumes them. The SFrame library ('libsframe') can, however, detect whether to endian-flip an SFrame section at decode time, by inspecting the 'sfp_magic' field in the SFrame header (If it appears as 0xe2de, endian-flipping is needed).  File: sframe-spec.info, Node: SFrame version, Next: SFrame flags, Prev: SFrame endianness, Up: SFrame Preamble 1.1.2 SFrame version -------------------- The version of the SFrame format can be determined by inspecting 'sfp_version'. The following versions are currently valid: Version Number Description ---------------------------------------------------------------- 'SFRAME_VERSION_1' 1 First version, under development. This section documents 'SFRAME_VERSION_1'.  File: sframe-spec.info, Node: SFrame flags, Prev: SFrame version, Up: SFrame Preamble 1.1.3 SFrame flags ------------------ The preamble contains bitflags in its 'sfp_flags' field that describe various section-wide properties. The following flags are currently defined. Flag Versions Value Meaning ---------------------------------------------------------------------------- 'SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries are sorted on PC. 'SFRAME_F_FRAME_POINTER' All 0x2 Functions preserve frame-pointer. Further flags may be added in future.  File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame section 1.2 SFrame Header ================= The SFrame header is the first part of an SFrame section. It begins with the SFrame preamble. All parts of it other than the preamble (*note SFrame Preamble::) can vary between SFrame file versions. It contains things that apply to the section as a whole, and offsets to the various other sub-sections defined in the format. As with the rest of the SFrame section, all values are stored in the endianness of the target system. The two sub-sections tile the SFrame section: each section runs from the offset given until the start of the next section. An explicit length is given for the last sub-section, the SFrame Frame Row Entry (SFrame FRE) sub-section. typedef struct sframe_header { sframe_preamble sfh_preamble; uint8_t sfh_abi_arch; int8_t sfh_cfa_fixed_fp_offset; int8_t sfh_cfa_fixed_ra_offset; uint8_t sfh_auxhdr_len; uint32_t sfh_num_fdes; uint32_t sfh_num_fres; uint32_t sfh_fre_len; uint32_t sfh_fdeoff; uint32_t sfh_freoff; } ATTRIBUTE_PACKED sframe_header; The sub-section offsets, namely 'sfh_fdeoff' and 'sfh_freoff', in the SFrame header are relative to the _end_ of the SFrame header; they are each an offset in bytes into the SFrame section where the SFrame FDE sub-section and the SFrame FRE sub-section respectively start. SFrame header allows specifying explicitly the fixed offsets from CFA, if any, from which FP or RA may be recovered. For example, in AMD64, the stack offset of the return address is 'CFA - 8'. Since this offset is in close vicinity with the CFA in most ABIs, 'sfh_cfa_fixed_fp_offset' and 'sfh_cfa_fixed_ra_offset' are limited to signed 8-bit integers. SFrame format has provisioned for future ABIs/architectures that it may support. The 'sframe_header' structure provides an unsigned 8-bit integral field to denote the size of an auxilliary SFrame header. The auxilliary SFrame header follows right after the 'sframe_header' structure. As for the offset calculations, the _end_ of SFrame header must be the end of the auxilliary SFrame header, if the latter is present. Tieing it all together: Offset Name Description ---------------------------------------------------------------------------------- 0x00 'sframe_preamble sfh_preamble' The SFrame preamble. *Note SFrame Preamble::. 0x04 'uint8_t sfh_abi_arch' The ABI/arch identifier. *Note SFrame ABI/arch identifier::. 0x05 'int8_t sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. 0x06 'int8_t sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. 0x07 'uint8_t sfh_auxhdr_len' Size in bytes of the auxilliary header that follows the 'sframe_header' structure. 0x08 'uint32_t sfh_num_fdes' The number of SFrame FDEs in the section. 0xc 'uint32_t sfh_num_fres' The number of SFrame FREs in the section. 0x10 'uint32_t sfh_fre_len' The length in bytes of the SFrame FRE sub-section. 0x14 'uint32_t sfh_fdeoff' The offset in bytes of the SFrame FDE sub-section. This sub-section contains 'sfh_num_fdes' number of fixed-length array elements. The array element is of type SFrame function desciptor entry, each providing a high-level function description for backtracing. *Note SFrame Function Descriptor Entries::. 0x18 'uint32_t sfh_freoff' The offset in bytes of the SFrame FRE sub-section, the core of the SFrame section, which describes the unwind information using variable-length array elements. *Note SFrame Frame Row Entries::. * Menu: * SFrame ABI/arch identifier::  File: sframe-spec.info, Node: SFrame ABI/arch identifier, Up: SFrame Header 1.2.1 SFrame ABI/arch identifier -------------------------------- SFrame header identifies the ABI/arch of the target system for which the executable and it's unwind information is intended. There are currently three identifiable ABI/arch values in the format. ABI/arch Identifier Value Description --------------------------------------------------------------------- 'SFRAME_ABI_AARCH64_ENDIAN_BIG' 1 AARCH64 big-endian 'SFRAME_ABI_AARCH64_ENDIAN_LITTLE' 2 AARCH64 little-endian 'SFRAME_ABI_AMD64_ENDIAN_LITTLE' 3 AMD64 little-endian The presence of an explicit identification of ABI/arch in SFrame may allow unwinders to make certain ABI-specific decisions.  File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame section 1.3 SFrame FDE ============== The SFrame Function Descriptor Entry sub-section is a sorted array of fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE is a packed structure which contains information to describe a function's unwind information at a high-level. typedef struct sframe_func_desc_entry { int32_t sfde_func_start_address; uint32_t sfde_func_size; uint32_t sfde_func_start_fre_off; uint32_t sfde_func_num_fres; uint8_t sfde_func_info; } ATTRIBUTE_PACKED sframe_func_desc_entry; 'sfde_func_start_fre_off' is the offset to the first SFrame FRE for the function. This offset is relative to the _end of the SFrame FDE_ sub-section (unlike the offsets in the SFrame header, which are relative to the _end_ of the SFrame header). 'sfde_func_info' is the "info word", containing information on the FRE type and the FDE type for the function *Note The SFrame FDE info word::. Following table describes each component of the SFrame FDE structure: Offset Name Description ------------------------------------------------------------------------------------ 0x00 'int32_t sfde_func_start_address' Signed 32-bit integral field denoting the virtual memory address of the described function. 0x04 'uint32_t sfde_func_size' Unsigned 32-bit integral field specifying the size of the function in bytes. 0x08 'uint32_t sfde_func_start_fre_off' Unsigned 32-bit integral field specifying the offset in bytes of the function's first SFrame FRE in the SFrame section. 0x0c 'uint32_t sfde_func_num_fres' Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. 0x10 'uint8_t sfde_func_info' The SFrame FDE info word. *Note The SFrame FDE info word::. * Menu: * The SFrame FDE info word:: * The SFrame FDE types:: * The SFrame FRE types::  File: sframe-spec.info, Node: The SFrame FDE info word, Next: The SFrame FDE types, Up: SFrame Function Descriptor Entries 1.3.1 The SFrame FDE info word ------------------------------ The info word is a bitfield split into three parts. From MSB to LSB: Bit offset Name Description ------------------------------------------------------------------------------------------ 7-5 'unused' Unused bits. 4 'fdetype' SFRAME_FDE_TYPE_PCMASK (1) or SFRAME_FDE_TYPE_PCINC (0). *Note The SFrame FDE types::. 0-3 'fretype' Choice of three SFrame FRE types. *Note The SFrame FRE types::.  File: sframe-spec.info, Node: The SFrame FDE types, Next: The SFrame FRE types, Prev: The SFrame FDE info word, Up: SFrame Function Descriptor Entries 1.3.2 The SFrame FDE types -------------------------- SFrame format defines two types of FDE entries. The choice of which SFrame FDE type to use is made based on the instruction patterns in the relevant program stub. An SFrame FDE of type 'SFRAME_FDE_TYPE_PCINC' is an indication that the PCs in the FREs should be treated as increments in bytes. This is used fo the the bulk of the executable code of a program, which contains instructions with no specific pattern. In contrast, an SFrame FDE of type 'SFRAME_FDE_TYPE_PCMASK' is an indication that the PCs in the FREs should be treated as masks. This type is useful for the cases where a small pattern of instructions in a program stub is used repeatedly for a specific functionality. Typical usecases are pltN entries and trampolines. Name of SFrame FDE type Value Description ------------------------------------------------------------------------------- SFRAME_FDE_TYPE_PCINC 0 Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE. SFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >= FRE_START_ADDR_AS_MASK) to look up a matching FRE.  File: sframe-spec.info, Node: The SFrame FRE types, Prev: The SFrame FDE types, Up: SFrame Function Descriptor Entries 1.3.3 The SFrame FRE types -------------------------- A real world application can have functions of size big and small. SFrame format defines three types of SFrame FRE entries to represent the unwind information for such a variety of function sizes. These representations vary in the number of bits needed to encode the start address offset in the SFrame FRE. The following constants are defined and used to identify the SFrame FRE types: Name Value Description -------------------------------------------------------------------------- 'SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) of the SFrame FRE is an unsigned 8-bit value. 'SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) of the SFrame FRE is an unsigned 16-bit value. 'SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) of the SFrame FRE is an unsigned 32-bit value. A single function must use the same type of FRE throughout. The choice of which SFrame FRE is used to encode the unwind information of a function, is stored in the *Note The SFrame FDE info word::.  File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame section 1.4 SFrame FRE ============== The SFrame Frame Row Entry sub-section contains the core of the unwind information. An SFrame Frame Row Entry is a self-sufficient record containing SFrame unwind info for a range of contiguous addresses, starting at the specified offset from the start of the function. Each SFrame Frame Row Entry is followed by S*N bytes, where: - 'S' is the size of the stack frame offset for the FRE, and - 'N' is the number of stack frame offsets in the FRE The stack offsets, following the FRE, are interpreted in order as follows: - The first offset is always used to locate the CFA, by interpreting it as: CFA = 'BASE_REG' + offset1. - If RA is being tracked, the second offset is always used to locate the RA, by interpreting it as: RA = CFA + offset2. If RA is _not_ being tracked _and_ FP is being tracked, the second offset will be used to locate the FP, by interpreting it as: FP = CFA + offset2. - If both RA and FP are being tracked, the third offset will be used to locate the FP, by interpreting it as FP = CFA + offset3. The entities 'S', 'N' and 'BASE_REG' are identified using the SFrame FRE info word, a.k.a. the 'sframe_fre_info' *Note The SFrame FRE info word::. Following are the definitions of the allowed SFrame FRE: typedef struct sframe_frame_row_entry_addr1 { uint8_t sfre_start_address; sframe_fre_info sfre_info; } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; typedef struct sframe_frame_row_entry_addr2 { uint16_t sfre_start_address; sframe_fre_info sfre_info; } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; typedef struct sframe_frame_row_entry_addr4 { uint32_t sfre_start_address; sframe_fre_info sfre_info; } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; 'sfre_start_address' is an unsigned 8-bit/16-bit/32-bit integral field identifies the start address of the range of program counters, for which the SFrame FRE applies. The value encoded in the 'sfre_start_address' field is the offset in bytes of the start address of the SFrame FRE, from the start address of the function. Further FRE types may be added in future. * Menu: * The SFrame FRE info word::  File: sframe-spec.info, Node: The SFrame FRE info word, Up: SFrame Frame Row Entries 1.4.1 The SFrame FRE info word ------------------------------ The SFrame FRE info word is a bitfield split into four parts. From MSB to LSB: Bit offset Name Description ------------------------------------------------------------------------------------- 7 'fre_mangled_ra_p' Indicate whether the return address is mangled with any authorization bits (signed RA). 5-6 'fre_offset_size' Size of stack offsets in bytes. Valid values are SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B, and SFRAME_FRE_OFFSET_4B. 1-4 'fre_offset_count' A value of upto 3 is allowed to track all three of CFA, FP and RA. 0 'fre_cfa_base_reg_id' Distinguish between SP or FP based CFA recovery. Name Value Description -------------------------------------------------------------------------------- 'SFRAME_FRE_OFFSET_1B' 0 All stack offsets following the fixed-length FRE structure are 1 byte long. 'SFRAME_FRE_OFFSET_2B' 1 All stack offsets following the fixed-length FRE structure are 2 bytes long. 'SFRAME_FRE_OFFSET_4B' 2 All stack offsets following the fixed-length FRE structure are 4 bytes long.  File: sframe-spec.info, Node: Index, Prev: SFrame section, Up: Top Index ***** [index] * Menu: * endianness: SFrame endianness. (line 6) * Overview: Overview. (line 6) * PT_GNU_SFRAME: Overview. (line 6) * SFrame ABI/arch identifier: SFrame ABI/arch identifier. (line 6) * SFrame FDE: SFrame Function Descriptor Entries. (line 6) * SFrame flags: SFrame flags. (line 6) * SFrame FRE: SFrame Frame Row Entries. (line 6) * SFrame header: SFrame Header. (line 6) * SFrame preamble: SFrame Preamble. (line 6) * SFrame section: SFrame section. (line 6) * SFrame versions: SFrame version. (line 9) * SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch identifier. (line 12) * SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch identifier. (line 15) * SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch identifier. (line 17) * SFRAME_FDE_TYPE_PCINC: The SFrame FDE types. (line 6) * SFRAME_FDE_TYPE_PCMASK: The SFrame FDE types. (line 6) * SFRAME_FRE_OFFSET_1B: The SFrame FRE info word. (line 29) * SFRAME_FRE_OFFSET_2B: The SFrame FRE info word. (line 33) * SFRAME_FRE_OFFSET_4B: The SFrame FRE info word. (line 36) * SFRAME_FRE_TYPE_ADDR1: The SFrame FRE types. (line 17) * SFRAME_FRE_TYPE_ADDR2: The SFrame FRE types. (line 22) * SFRAME_FRE_TYPE_ADDR4: The SFrame FRE types. (line 26) * SFRAME_F_FDE_SORTED: SFrame flags. (line 11) * SFRAME_F_FRAME_POINTER: SFrame flags. (line 14) * SFRAME_MAGIC: SFrame Preamble. (line 22) * SFRAME_VERSION_1: SFrame version. (line 9) * The SFrame FDE info word: SFrame Function Descriptor Entries. (line 59) * The SFrame FRE info word: SFrame Frame Row Entries. (line 64)  Tag Table: Node: Top564 Node: Overview1114 Node: SFrame section2135 Node: SFrame Preamble2607 Node: SFrame endianness3963 Node: SFrame version4419 Node: SFrame flags4921 Node: SFrame Header5641 Node: SFrame ABI/arch identifier10812 Node: SFrame Function Descriptor Entries11778 Node: The SFrame FDE info word14571 Node: The SFrame FDE types15296 Node: The SFrame FRE types16864 Node: SFrame Frame Row Entries18420 Node: The SFrame FRE info word20817 Node: Index22761  End Tag Table  Local Variables: coding: utf-8 End: @ 1.1.1.1 log @Import gdb-13.2 over gdb-11.0.50 May 27th, 2023: GDB 13.2 Released! The latest version of GDB, version 13.2, is available for download. This is a minor corrective release over GDB 13.1, fixing the following issues: PR testsuite/30158 (rustc testsuite fails with 13.1, apparently worked before with trunk 20230114 on i686-linux-gnu and powerpc64le-linux-gnu) PR gdb/30214 (GDB 13.1 does not compile on FreeBSD 13.1) PR gdb/30240 ((linux/aarch) thread.c:86: internal-error: inferior_thread: Assertion `current_thread_ != nullptr' failed) PR gdb/30249 ([13 regression] hookpost-extended-remote will not work) PR exp/30271 (Addresses of static thread_local fields are badly calculated sometimes) PR symtab/30357 (Segmentation fault for the 'start' command) PR symtab/30369 ([gdb/symtab] False match issue in skip_prologue_using_linetable) PR gdb/30423 (Build failures with clang 16) PR build/30450 (Build failure (linux-low.cc:5393:45: error: expected ':' before ')' token) with musl-1.2.4) See the NEWS file for a more complete and detailed list of what this release includes. Feb 19th, 2023: GDB 13.1 Released! The latest version of GDB, version 13.1, is available for download. This version of GDB includes the following changes and enhancements: Support for the following new targets has been added in both GDB and GDBserver: GNU/Linux/LoongArch (gdbserver) loongarch*-*-linux* GNU/Linux/CSKY (gdbserver) csky*-*linux* The Windows native target now supports target async. FreeBSD: Arm and AArch64: Support for Thread Local Storage (TLS) variables Hardware watchpoint support on AArch64 FreeBSD Floating-point support has now been added on LoongArch GNU/Linux. New commands: set print nibbles [on|off] show print nibbles This controls whether the 'print/t' command will display binary values in groups of four bits, known as "nibbles". The default is 'off'. Various styling-related commands. See the gdb/NEWS file for more details. Various maintenance commands. These are normally aimed at GDB experts or developers. See the gdb/NEWS file for more details. Python API improvements: New Python API for instruction disassembly. The new attribute 'locations' of gdb.Breakpoint returns a list of gdb.BreakpointLocation objects specifying the locations where the breakpoint is inserted into the debuggee. New Python type gdb.BreakpointLocation. New function gdb.format_address(ADDRESS, PROGSPACE, ARCHITECTURE) that formats ADDRESS as 'address ' New function gdb.current_language that returns the name of the current language. Unlike gdb.parameter('language'), this will never return 'auto'. New function gdb.print_options that returns a dictionary of the prevailing print options, in the form accepted by gdb.Value.format_string. New method gdb.Frame.language that returns the name of the frame's language. gdb.Value.format_string now uses the format provided by 'print', if it is called during a 'print' or other similar operation. gdb.Value.format_string now accepts the 'summary' keyword. This can be used to request a shorter representation of a value, the way that 'set print frame-arguments scalars' does. The gdb.register_window_type method now restricts the set of acceptable window names. The first character of a window's name must start with a character in the set [a-zA-Z], every subsequent character of a window's name must be in the set [-_.a-zA-Z0-9]. ` GDB/MI changes: MI version 1 is deprecated, and will be removed in GDB 14. The async record stating the stopped reason 'breakpoint-hit' now contains an optional field locno. Miscellaneous improvements: gdb now supports zstd compressed debug sections (ELFCOMPRESS_ZSTD) for ELF. New convenience variable $_inferior_thread_count contains the number of live threads in the current inferior. New convenience variables $_hit_bpnum and $_hit_locno, set to the breakpoint number and the breakpoint location number of the breakpoint last hit. The "info breakpoints" now displays enabled breakpoint locations of disabled breakpoints as in the "y-" state. The format of 'disassemble /r' and 'record instruction-history /r' has changed to match the layout of GNU objdump when disassembling. A new format "/b" has been introduce to provide the old behavior of "/r". The TUI no longer styles the source and assembly code highlighted by the current position indicator by default. You can however re-enable styling using the new "set style tui-current-position" command. It is now possible to use the "document" command to document user-defined commands. Support for memory tag data for AArch64 MTE. Support Removal notices: DBX mode has been removed. Support for building against Python version 2 has been removed. It is now only possible to build GDB against Python 3. Support for the following commands has been removed: set debug aix-solib on|off show debug aix-solib set debug solib-frv on|off show debug solib-frv Use the "set/show debug solib" commands instead. See the NEWS file for a more complete and detailed list of what this release includes. Dec 18th, 2022: GDB 13 branch created The GDB 13 branch (gdb-13-branch) has been created. To check out a copy of the branch use: git clone --branch gdb-13-branch https://sourceware.org/git/binutils-gdb.git May 1st, 2022: GDB 12.1 Released! The latest version of GDB, version 12.1, is available for download. This version of GDB includes the following changes and enhancements: New support for the following native configuration: GNU/Linux/OpenRISC or1k*-*-linux* New support for the following targets: GNU/Linux/LoongArch loongarch*-*-linux* New GDBserver support on the following configuration: GNU/Linux/OpenRISC or1k*-*-linux* Support for the following target has been removed: S+core score-*-* Multithreaded symbol loading is now enabled by default Deprecation Notices: GDB 12 is the last release of GDB that will support building against Python 2 DBX mode is deprecated, and will be removed in GDB 13 GDB/MI changes: The '-add-inferior' with no option flags now inherits the connection of the current inferior, this restores the behaviour of GDB as it was prior to GDB 10. The '-add-inferior' command now accepts a '--no-connection' option, which causes the new inferior to start without a connection. Python API enhancements: It is now possible to add GDB/MI commands implemented in Python New function gdb.Architecture.integer_type() New gdb.events.gdb_exiting event New 'gdb.events.connection_removed' event registry New gdb.TargetConnection object New gdb.Inferior.connection property New read-only attribute gdb.InferiorThread.details New gdb.RemoteTargetConnection.send_packet method New read-only attributes gdb.Type.is_scalar and gdb.Type.is_signed The gdb.Value.format_string method now takes a 'styling' argument Various new function in the "gdb" module Miscellaneous: The FreeBSD native target now supports async mode Improved C++ template support Support for disabling source highlighting through GNU of the Pygments library instead. The "print" command has been changed so as to print floating-point values with a base-modifying formats such as "/x" to display the underlying bytes of the value in the desired base. The "clone-inferior" command now ensures that the TTY, CMD and ARGS settings are copied from the original inferior to the new one. All modifications to the environment variables done using the 'set environment' or 'unset environment' commands are also copied to the new inferior. Various new commands have been introduced See the NEWS file for a more complete and detailed list of what this release includes. Mar 20th, 2022: GDB 12 branch created The GDB 12 branch (gdb-12-branch) has been created. To check out a copy of the branch use: git clone --branch gdb-12-branch https://sourceware.org/git/binutils-gdb.git January 16th, 2022: GDB 11.2 Released! The latest version of GDB, version 11.2, is available for download. This is a minor corrective release over GDB 11.1, fixing the following issues: PR sim/28302 (gdb fails to build with glibc 2.34) PR build/28318 (std::thread support configure check does not use CXX_DIALECT) PR gdb/28405 (arm-none-eabi: internal-error: ptid_t remote_target::select_thread_for_ambiguous_stop_reply(const target_waitstatus*): Assertion `first_resumed_thread != nullptr' failed) PR tui/28483 ([gdb/tui] breakpoint creation not displayed) PR build/28555 (uclibc compile failure since commit 4655f8509fd44e6efabefa373650d9982ff37fd6) PR rust/28637 (Rust characters will be encoded using DW_ATE_UTF) PR gdb/28758 (GDB 11 doesn't work correctly on binaries with a SHT_RELR (.relr.dyn) section) PR gdb/28785 (Support SHT_RELR (.relr.dyn) section) See the NEWS file for a more complete and detailed list of what this release includes. September 13th, 2021: GDB 11.1 Released! The latest version of GDB, version 11.1, is available for download. This version of GDB includes the following changes and enhancements: Support for ARM Symbian (arm*-*-symbianelf*) has been removed. Building GDB now requires GMP (The GNU Multiple Precision Arithmetic Library). New command-line options "--early-init-command" (or "-eix") and "--early-init-eval-command" (or "-eiex") GDB/MI Changes: New --qualified option for the '-break-insert' and '-dprintf-insert' commands. New --force-condition option for the '-break-insert' and '-dprintf-insert' commands. New --force option for the '-break-condition' command. The '-file-list-exec-source-files' now accepts an optional regular expression to filter the source files included in the result. The results from '-file-list-exec-source-files' now include a 'debug-fully-read' field to indicate if the corresponding source's debugging information has been partially read (false) or has been fully read (true). TUI Improvements: Mouse actions are now supported. The mouse wheel scrolls the appropriate window. Key combinations that do not have a specific action on the focused window are now passed to GDB. Python enhancements: Inferior objects now contain a read-only 'connection_num' attribute that gives the connection number as seen in 'info connections' and 'info inferiors'. New method gdb.Frame.level() which returns the stack level of the frame object. New method gdb.PendingFrame.level() which returns the stack level of the frame object. When hitting a catchpoint, the Python API will now emit a gdb.BreakpointEvent rather than a gdb.StopEvent. The gdb.Breakpoint attached to the event will have type BP_CATCHPOINT. Python TUI windows can now receive mouse click events. If the Window object implements the click method, it is called for each mouse click event in this window. New setting "python ignore-environment on|off"; if "on", causes GDB's builtin Python to ignore any environment variable that would otherwise affect how Python behaves (needs to be set during "early initialization" (see above). New setting "python dont-write-bytecode auto|on|off". Guile API enhancements: Improved support for rvalue reference values. New procedures for obtaining value variants: value-reference-value, value-rvalue-reference-value and value-const-value. New "qMemTags" and "QMemTags" remote protocol packets (associated with Memory Tagging). GDB will now look for the .gdbinit file in a config directory before looking for ~/.gdbinit. The file is searched for in the following locations: $XDG_CONFIG_HOME/gdb/gdbinit, $HOME/.config/gdb/gdbinit, $HOME/.gdbinit. On Apple hosts the search order is instead: $HOME/Library/Preferences/gdb/gdbinit, $HOME/.gdbinit. The "break [...] if CONDITION" command no longer returns an error when the condition is invalid at one or more locations. Instead, if the condition is valid at one or more locations, the locations where the condition is not valid are disabled. The behavior of the "condition" command is changed to match the new behavior of the "break" command. Support for general memory tagging functionality (currently limited to AArch64 MTE) Core file debugging now supported for x86_64 Cygwin programs. New "org.gnu.gdb.riscv.vector" feature for RISC-V targets. GDB now supports fixed point types which are described in DWARF as base types with a fixed-point encoding. Additionally, support for the DW_AT_GNU_numerator and DW_AT_GNU_denominator has also been added. Miscellaneous: New "startup-quietly on|off" setting; when "on", behaves the same as passing the "-silent" option on the command line. New "print type hex on|off" setting; when 'on', the 'ptype' command uses hexadecimal notation to print sizes and offsets of struct members. When 'off', decimal notation is used. The "inferior" command, when run without argument, prints information about the current inferior. The "ptype" command now supports "/x" and "/d", affecting the base used to print sizes and offsets. The output of the "info source" has been restructured. New "style version foreground | background | intensity" commands to control the styling of the GDB version number. Various debug and maintenance commands (mostly useful for the GDB developers) See the NEWS file for a more complete and detailed list of what this release includes. @ text @@ 1.1.1.1.2.1 log @Sync with HEAD @ text @d4 1 a4 1 Copyright (C) 2021-2024 Free Software Foundation, Inc. d18 1 a18 1 File: sframe-spec.info, Node: Top, Next: Introduction, Up: (dir) d23 1 a23 1 This manual describes version 2 of the SFrame file format. SFrame d25 1 a25 1 minimal necessary information needed for generating stack traces: d31 2 a32 2 The reason for existence of the SFrame format is to provide a simple, fast and low-overhead mechanism to generate stack traces. d36 1 a36 1 * Introduction:: d41 1 a41 12 File: sframe-spec.info, Node: Introduction, Next: SFrame section, Prev: Top, Up: Top 1 Introduction ************** * Menu: * Overview:: * Changes from Version 1 to Version 2::  File: sframe-spec.info, Node: Overview, Next: Changes from Version 1 to Version 2, Up: Introduction d43 2 a44 2 1.1 Overview ============ d46 3 a48 3 The SFrame stack trace information is provided in a loaded section, known as the '.sframe' section. When available, the '.sframe' section appears in a new segment of its own, PT_GNU_SFRAME. a52 6 A portion of the SFrame format follows an unaligned on-disk representation. Some data structures, however, (namely the SFrame header and the SFrame function descriptor entry) have elements at their natural boundaries. All data structures are packed, unless otherwise stated. a60 5 The rest of this specification describes the current version of the format, 'SFRAME_VERSION_2', in detail. Additional sections outline the major changes made to each previously published version of the SFrame stack trace format. d66 1 a66 19 'sframe.h'. Please report discrepancies between the two, if any.  File: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction 1.2 Changes from Version 1 to Version 2 ======================================= The following is a list of the changes made to the SFrame stack trace format since Version 1 was published. * SFrame Function Descriptor Entry encodes the size of the repetitive code blocks, e.g., pltN entries for which an FDE of type SFRAME_FDE_TYPE_PCMASK is used. * SFrame Function Descriptor Entry includes an explicit padding of two bytes to ensure natural alignment for its data members. * The above two imply that each SFrame Function Descriptor Entry has a fixed size of 20 bytes instead of its size of 17 bytes in SFrame format version 1. d69 1 a69 1 File: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Introduction, Up: Top d71 1 a71 1 2 SFrame section d89 1 a89 1 2.1 SFrame Preamble a101 2 Every element of the SFrame preamble is naturally aligned. d126 1 a126 1 2.1.1 SFrame endianness d138 1 a138 1 2.1.2 SFrame version d145 2 a146 3 ------------------------------------------------------------------ 'SFRAME_VERSION_1' 1 First version, obsolete. 'SFRAME_VERSION_2' 2 Current version, under development. d148 1 a148 1 This document describes 'SFRAME_VERSION_2'. d153 1 a153 1 2.1.3 SFrame flags d173 1 a173 1 2.2 SFrame Header a202 2 Every element of the SFrame header is naturally aligned. d215 7 a221 7 SFrame format has made some provisions for supporting more ABIs/architectures in the future. The 'sframe_header' structure provides an unsigned 8-bit integral field to denote the size of an auxiliary SFrame header. The auxiliary SFrame header follows right after the 'sframe_header' structure. As for the offset calculations, the _end_ of SFrame header must be the end of the auxiliary SFrame header, if the latter is present. d223 1 a223 1 Putting it all together: d226 1 a226 1 ---------------------------------------------------------------------------------------- d237 3 a239 3 0x07 'uint8_t sfh_auxhdr_len' Size in bytes of the auxiliary header that follows the 'sframe_header' structure. d241 2 a242 1 0x08 'uint32_t sfh_num_fdes' The number of SFrame FDEs in the section. d244 2 a245 1 0xc 'uint32_t sfh_num_fres' The number of SFrame FREs in the section. d247 2 a248 2 0x10 'uint32_t sfh_fre_len' The length in bytes of the SFrame FRE sub-section. d250 7 a256 6 0x14 'uint32_t sfh_fdeoff' The offset in bytes of the SFrame FDE sub-section. This sub-section contains 'sfh_num_fdes' number of fixed-length array elements. The array element is of type SFrame function desciptor entry, each providing a high-level function d260 5 a264 5 0x18 'uint32_t sfh_freoff' The offset in bytes of the SFrame FRE sub-section, the core of the SFrame section, which describes the stack trace information using variable-length array elements. d275 1 a275 1 2.2.1 SFrame ABI/arch identifier d279 2 a280 3 executable and hence, the stack trace information contained in the SFrame section, is intended. There are currently three identifiable ABI/arch values in the format. d293 1 a293 1 allow stack trace generators to make certain ABI-specific decisions. d298 1 a298 1 2.3 SFrame FDE d304 1 a304 1 a function's stack trace information at a high-level. a312 2 uint8_t sfde_func_rep_size; uint16_t sfde_func_padding2; a314 3 Every element of the SFrame function descriptor entry is naturally aligned. d327 4 a330 4 ------------------------------------------------------------------------------------------ 0x00 'int32_t sfde_func_start_address' Signed 32-bit integral field denoting the virtual memory address of the described function. d332 3 a334 2 0x04 'uint32_t sfde_func_size' Unsigned 32-bit integral field specifying the size of the function in bytes. d336 4 a339 3 0x08 'uint32_t sfde_func_start_fre_off' Unsigned 32-bit integral field specifying the offset in bytes of the function's first SFrame FRE in the SFrame section. d341 3 a343 3 0x0c 'uint32_t sfde_func_num_fres' Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. d345 1 a345 2 0x10 'uint8_t sfde_func_info' Unsigned 8-bit integral field specifying the SFrame FDE info word. a347 10 0x11 'uint8_t sfde_func_rep_size' Unsigned 8-bit integral field specifying the size of the repetitive code block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For example, in AMD64, the size of a pltN entry is 16 bytes. 0x12 'uint16_t sfde_func_padding2' Padding of 2 bytes. Currently unused bytes. d358 1 a358 1 2.3.1 The SFrame FDE info word d363 9 a371 16 Bit offset Name Description ---------------------------------------------------------------------------------------- 7-6 'unused' Unused bits. 5 'pauth_key' Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: SFRAME_AARCH64_PAUTH_KEY_A (0), or SFRAME_AARCH64_PAUTH_KEY_B (1). 4 'fdetype' Specify the SFrame FDE type. Two possible values: SFRAME_FDE_TYPE_PCMASK (1), or SFRAME_FDE_TYPE_PCINC (0). *Note The SFrame FDE types::. 0-3 'fretype' Choice of three SFrame FRE types. *Note The SFrame FRE types::. d376 1 a376 1 2.3.2 The SFrame FDE types d394 11 a404 14 Name of SFrame FDE Value Description type --------------------------------------------------------------------------- SFRAME_FDE_TYPE_PCINC 0 Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE. SFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a (PC % REP_BLOCK_SIZE >= FRE_START_ADDR) to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the repeating block of program instructions. d409 1 a409 1 2.3.3 The SFrame FRE types d414 1 a414 1 stack trace information for such a variety of function sizes. These d436 3 a438 3 A single function must use the same type of SFrame FRE throughout. An identifier to reflect the chosen SFrame FRE type is stored in the *Note The SFrame FDE info word::. d443 1 a443 1 2.4 SFrame FRE d446 2 a447 2 The SFrame Frame Row Entry sub-section contains the core of the stack trace information. d450 3 a452 3 SFrame stack trace information for a range of contiguous addresses, starting at the specified offset from the start of the function. Each SFrame Frame Row Entry is followed by S*N bytes, where: a492 5 For ensuring compactness, SFrame frame row entries are stored unaligned on disk. Appropriate mechanisms need to be employed, as necessary, by the serializing and deserializing entities, if unaligned accesses need to be avoided. d508 1 a508 1 2.4.1 The SFrame FRE info word d521 1 a521 2 are: SFRAME_FRE_OFFSET_1B, a553 2 * Changes from Version 1 to Version 2: Changes from Version 1 to Version 2. (line 6) a554 1 * Introduction: Introduction. (line 6) d556 1 d569 1 a569 1 (line 13) d571 1 a571 1 (line 16) d573 1 a573 1 (line 18) d577 1 a577 1 (line 30) d579 1 a579 1 (line 34) d581 1 a581 1 (line 37) d587 1 a587 1 * SFRAME_MAGIC: SFrame Preamble. (line 24) d590 1 a590 1 (line 73) d592 1 a592 1 (line 69) d598 15 a612 17 Node: Introduction1148 Node: Overview1334 Node: Changes from Version 1 to Version 22901 Node: SFrame section3672 Node: SFrame Preamble4148 Node: SFrame endianness5567 Node: SFrame version6023 Node: SFrame flags6583 Node: SFrame Header7303 Node: SFrame ABI/arch identifier12423 Node: SFrame Function Descriptor Entries13446 Node: The SFrame FDE info word17108 Node: The SFrame FDE types18263 Node: The SFrame FRE types19984 Node: SFrame Frame Row Entries21516 Node: The SFrame FRE info word24163 Node: Index26145 @ 1.1.1.2 log @Import gdb-15.1, previous was 13.2 ChangeLog: 2024-03-20 Simon Marchi * .pre-commit-config.yaml: Bump black hook to 24.3.0 2024-03-20 Simon Marchi * .pre-commit-config.yaml: New. 2024-03-14 Simon Marchi * Makefile.def: Add configure-gdbserver and all-gdbserver dependencies on all-libiconv. * Makefile.in: Re-generate. 2024-01-15 Nick Clifton * 2.42 branch point. 2023-11-15 Arsen Arsenović * intl: Remove directory. Replaced with out-of-tree GNU gettext. * .gitignore: Add '/gettext*'. * configure.ac (host_libs): Replace intl with gettext. (hbaseargs, bbaseargs, baseargs): Split baseargs into {h,b}baseargs. (skip_barg): New flag. Skips appending current flag to bbaseargs. : Exempt --with-libintl-{type,prefix} from target and build machine argument passing. * configure: Regenerate. * Makefile.def (host_modules): Replace intl module with gettext module. (configure-ld): Depend on configure-gettext. * Makefile.in: Regenerate. * src-release.sh: Remove references to the intl/ directory. 2023-07-03 Nick Clifton 2.41 Branch Point. 2023-06-26 Nick Clifton * Import these updates to the config scripts commit 4ad4bb7c30aca1e705448ba8d51a210bbd47bb52 Author: Paul Eggert Date: Fri Jun 23 09:55:10 2023 -0700 Quote 'like this', not `like this'. commit 63acb96f92473ceb5e21d873d7c0aee266b3d6d3 Author: Paul Eggert Date: Sat Jan 21 00:15:01 2023 -0600 Fix config.sub spelling typo for "athlon" commit 4ce12a5c9125cedc0d0ba584444a6865396923ec Author: Dmitry V. Levin Date: Sun Jan 1 08:00:00 2023 +0000 Update copyright years commit c397e2c040bce50bcdccb131f90115ba7e8bfc19 Author: Arsen Arsenovi Date: Sat Sep 17 23:34:48 2022 +0200 config.sub: add linux-mlibc targets commit 9f9f9b0b13197269848c76e3e057a3ed0680b4bf Author: Arsen Arsenovi Date: Sat Sep 17 23:34:47 2022 +0200 config.guess: support running on Managarm systems commit 87e6687749da7bb2ab158a79fa83721c19ed9246 Author: Arsen Arsenovi Date: Sat Sep 17 23:34:46 2022 +0200 config.sub: add managarm-{mlibc,kernel} targets commit 20403c5701973a4cbd7e0b4bbeb627fcd424a0f1 Author: Xiaotian Wu Date: Mon Aug 1 16:05:29 2022 +0800 Remove loongarchx32 commit 02ba26b218d3d3db6c56e014655faf463cefa983 Author: Alexander von Gluck IV Date: Wed May 25 15:43:13 2022 -0500 config.guess: Update Haiku guesses commit f56a7140386d08a531bcfd444d632b28c61a6329 Author: Bruno Haible Date: Sun May 8 19:08:08 2022 +0200 config.guess (x86_64:Linux:*:*): Detect 32-bit ABI. 2023-04-20 Nick Clifton * SECURITY.txt: New file. * src-release.sh (DEVO_SUPPORT): Add SECURITY.txt. 2022-12-31 Nick Clifton * 2.40 binutils branch created. @ text @d4 1 a4 1 Copyright (C) 2021-2024 Free Software Foundation, Inc. d18 1 a18 1 File: sframe-spec.info, Node: Top, Next: Introduction, Up: (dir) d23 1 a23 1 This manual describes version 2 of the SFrame file format. SFrame d25 1 a25 1 minimal necessary information needed for generating stack traces: d31 2 a32 2 The reason for existence of the SFrame format is to provide a simple, fast and low-overhead mechanism to generate stack traces. d36 1 a36 1 * Introduction:: d41 1 a41 12 File: sframe-spec.info, Node: Introduction, Next: SFrame section, Prev: Top, Up: Top 1 Introduction ************** * Menu: * Overview:: * Changes from Version 1 to Version 2::  File: sframe-spec.info, Node: Overview, Next: Changes from Version 1 to Version 2, Up: Introduction d43 2 a44 2 1.1 Overview ============ d46 3 a48 3 The SFrame stack trace information is provided in a loaded section, known as the '.sframe' section. When available, the '.sframe' section appears in a new segment of its own, PT_GNU_SFRAME. a52 6 A portion of the SFrame format follows an unaligned on-disk representation. Some data structures, however, (namely the SFrame header and the SFrame function descriptor entry) have elements at their natural boundaries. All data structures are packed, unless otherwise stated. a60 5 The rest of this specification describes the current version of the format, 'SFRAME_VERSION_2', in detail. Additional sections outline the major changes made to each previously published version of the SFrame stack trace format. d66 1 a66 19 'sframe.h'. Please report discrepancies between the two, if any.  File: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction 1.2 Changes from Version 1 to Version 2 ======================================= The following is a list of the changes made to the SFrame stack trace format since Version 1 was published. * SFrame Function Descriptor Entry encodes the size of the repetitive code blocks, e.g., pltN entries for which an FDE of type SFRAME_FDE_TYPE_PCMASK is used. * SFrame Function Descriptor Entry includes an explicit padding of two bytes to ensure natural alignment for its data members. * The above two imply that each SFrame Function Descriptor Entry has a fixed size of 20 bytes instead of its size of 17 bytes in SFrame format version 1. d69 1 a69 1 File: sframe-spec.info, Node: SFrame section, Next: Index, Prev: Introduction, Up: Top d71 1 a71 1 2 SFrame section d89 1 a89 1 2.1 SFrame Preamble a101 2 Every element of the SFrame preamble is naturally aligned. d126 1 a126 1 2.1.1 SFrame endianness d138 1 a138 1 2.1.2 SFrame version d145 2 a146 3 ------------------------------------------------------------------ 'SFRAME_VERSION_1' 1 First version, obsolete. 'SFRAME_VERSION_2' 2 Current version, under development. d148 1 a148 1 This document describes 'SFRAME_VERSION_2'. d153 1 a153 1 2.1.3 SFrame flags d173 1 a173 1 2.2 SFrame Header a202 2 Every element of the SFrame header is naturally aligned. d215 7 a221 7 SFrame format has made some provisions for supporting more ABIs/architectures in the future. The 'sframe_header' structure provides an unsigned 8-bit integral field to denote the size of an auxiliary SFrame header. The auxiliary SFrame header follows right after the 'sframe_header' structure. As for the offset calculations, the _end_ of SFrame header must be the end of the auxiliary SFrame header, if the latter is present. d223 1 a223 1 Putting it all together: d226 1 a226 1 ---------------------------------------------------------------------------------------- d237 3 a239 3 0x07 'uint8_t sfh_auxhdr_len' Size in bytes of the auxiliary header that follows the 'sframe_header' structure. d241 2 a242 1 0x08 'uint32_t sfh_num_fdes' The number of SFrame FDEs in the section. d244 2 a245 1 0xc 'uint32_t sfh_num_fres' The number of SFrame FREs in the section. d247 2 a248 2 0x10 'uint32_t sfh_fre_len' The length in bytes of the SFrame FRE sub-section. d250 7 a256 6 0x14 'uint32_t sfh_fdeoff' The offset in bytes of the SFrame FDE sub-section. This sub-section contains 'sfh_num_fdes' number of fixed-length array elements. The array element is of type SFrame function desciptor entry, each providing a high-level function d260 5 a264 5 0x18 'uint32_t sfh_freoff' The offset in bytes of the SFrame FRE sub-section, the core of the SFrame section, which describes the stack trace information using variable-length array elements. d275 1 a275 1 2.2.1 SFrame ABI/arch identifier d279 2 a280 3 executable and hence, the stack trace information contained in the SFrame section, is intended. There are currently three identifiable ABI/arch values in the format. d293 1 a293 1 allow stack trace generators to make certain ABI-specific decisions. d298 1 a298 1 2.3 SFrame FDE d304 1 a304 1 a function's stack trace information at a high-level. a312 2 uint8_t sfde_func_rep_size; uint16_t sfde_func_padding2; a314 3 Every element of the SFrame function descriptor entry is naturally aligned. d327 4 a330 4 ------------------------------------------------------------------------------------------ 0x00 'int32_t sfde_func_start_address' Signed 32-bit integral field denoting the virtual memory address of the described function. d332 3 a334 2 0x04 'uint32_t sfde_func_size' Unsigned 32-bit integral field specifying the size of the function in bytes. d336 4 a339 3 0x08 'uint32_t sfde_func_start_fre_off' Unsigned 32-bit integral field specifying the offset in bytes of the function's first SFrame FRE in the SFrame section. d341 3 a343 3 0x0c 'uint32_t sfde_func_num_fres' Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. d345 1 a345 2 0x10 'uint8_t sfde_func_info' Unsigned 8-bit integral field specifying the SFrame FDE info word. a347 10 0x11 'uint8_t sfde_func_rep_size' Unsigned 8-bit integral field specifying the size of the repetitive code block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For example, in AMD64, the size of a pltN entry is 16 bytes. 0x12 'uint16_t sfde_func_padding2' Padding of 2 bytes. Currently unused bytes. d358 1 a358 1 2.3.1 The SFrame FDE info word d363 9 a371 16 Bit offset Name Description ---------------------------------------------------------------------------------------- 7-6 'unused' Unused bits. 5 'pauth_key' Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: SFRAME_AARCH64_PAUTH_KEY_A (0), or SFRAME_AARCH64_PAUTH_KEY_B (1). 4 'fdetype' Specify the SFrame FDE type. Two possible values: SFRAME_FDE_TYPE_PCMASK (1), or SFRAME_FDE_TYPE_PCINC (0). *Note The SFrame FDE types::. 0-3 'fretype' Choice of three SFrame FRE types. *Note The SFrame FRE types::. d376 1 a376 1 2.3.2 The SFrame FDE types d394 11 a404 14 Name of SFrame FDE Value Description type --------------------------------------------------------------------------- SFRAME_FDE_TYPE_PCINC 0 Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE. SFRAME_FDE_TYPE_PCMASK 1 Unwinders perform a (PC % REP_BLOCK_SIZE >= FRE_START_ADDR) to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the repeating block of program instructions. d409 1 a409 1 2.3.3 The SFrame FRE types d414 1 a414 1 stack trace information for such a variety of function sizes. These d436 3 a438 3 A single function must use the same type of SFrame FRE throughout. An identifier to reflect the chosen SFrame FRE type is stored in the *Note The SFrame FDE info word::. d443 1 a443 1 2.4 SFrame FRE d446 2 a447 2 The SFrame Frame Row Entry sub-section contains the core of the stack trace information. d450 3 a452 3 SFrame stack trace information for a range of contiguous addresses, starting at the specified offset from the start of the function. Each SFrame Frame Row Entry is followed by S*N bytes, where: a492 5 For ensuring compactness, SFrame frame row entries are stored unaligned on disk. Appropriate mechanisms need to be employed, as necessary, by the serializing and deserializing entities, if unaligned accesses need to be avoided. d508 1 a508 1 2.4.1 The SFrame FRE info word d521 1 a521 2 are: SFRAME_FRE_OFFSET_1B, a553 2 * Changes from Version 1 to Version 2: Changes from Version 1 to Version 2. (line 6) a554 1 * Introduction: Introduction. (line 6) d556 1 d569 1 a569 1 (line 13) d571 1 a571 1 (line 16) d573 1 a573 1 (line 18) d577 1 a577 1 (line 30) d579 1 a579 1 (line 34) d581 1 a581 1 (line 37) d587 1 a587 1 * SFRAME_MAGIC: SFrame Preamble. (line 24) d590 1 a590 1 (line 73) d592 1 a592 1 (line 69) d598 15 a612 17 Node: Introduction1148 Node: Overview1334 Node: Changes from Version 1 to Version 22901 Node: SFrame section3672 Node: SFrame Preamble4148 Node: SFrame endianness5567 Node: SFrame version6023 Node: SFrame flags6583 Node: SFrame Header7303 Node: SFrame ABI/arch identifier12423 Node: SFrame Function Descriptor Entries13446 Node: The SFrame FDE info word17108 Node: The SFrame FDE types18263 Node: The SFrame FRE types19984 Node: SFrame Frame Row Entries21516 Node: The SFrame FRE info word24163 Node: Index26145 @ 1.1.1.3 log @Import gdb 16.3; previous was 15.1 April 20th, 2025: GDB 16.3 Released! The latest version of GDB, version 16.3, is available for download. This is a corrective release over GDB 16.2, fixing the following issues: PR symtab/32309 ([gdb/symtab, fission] gdb/dwarf2/read.h:289: internal-error: version: Assertion `m_dwarf_version != 0' failed) PR corefiles/32441 (gdb segfaults when generating a core file if target_fileio_read_alloc fails) PR tui/32623 (TUI console window doesn't update while inferior is running) PR corefiles/32634 ([gdb/corefiles] segfault in gdb.arch/i386-biarch-core.exp) PR backtrace/32757 ("Assertion `stashed' failed" when inline frame #0 is duplicated) PR tdep/32770 ([gdb/tdep, i386] FAIL: gdb.reverse/recvmsg-reverse.exp: continue to breakpoint: marker2) PR gdb/32775 ([AArch64] gdbserver crashes on SVE/SME-enabled systems) PR record/32784 ([gdb/record, aarch64] Stack smashing detected in aarch64_record_asimd_load_store) PR tui/32797 (Escape sequences to only reset foreground or background color to default fail) PR gdb/32828 (gstack regression: missing file names and line numbers) See the NEWS file for a more complete and detailed list of what this release includes. February 1st, 2025: GDB 16.2 Released! The latest version of GDB, version 16.2, is available for download. This is a corrective release over GDB 16.1, fixing the following issues: PR build/32578 (cannot build GDB 16.1 out of tree when calling the configure script with a relative path) PR tui/32592 ([gdb/tui] internal error in tui-winsource.c:340:refresh_window) PR remote/32593 (Incompatibilities between GDB's and LLDB's 'x' packet implementation) PR build/32610 (Missing #include file in darwin_nat.c) See the NEWS file for a more complete and detailed list of what this release includes. January 18th, 2025: GDB 16.1 Released! The latest version of GDB, version 16.1, is available for download. This version of GDB includes the following changes and enhancements: record/replay support now available on loongarch*-linux* GDB now supports watchpoints for tagged data pointers. MTE (Memory Tagging Extension) debugging is now supported on AArch64 baremetal. New bash script gstack uses GDB to print stack traces of running processes. Enhanced breakpoint support For breakpoints that are created in the 'pending' state, any 'thread' or 'task' keywords are parsed at the time the breakpoint is created, rather than at the time the breakpoint becomes non-pending. Thread-specific breakpoints are only inserted into the program space in which the thread of interest is running. Enhanced Intel Processor Trace support Support for printing of asynchronous events Support for printing of ptwrite payloads Changed commands The "remove-symbol-file -a ADDRESS" command now accepts a full expression as the ADDRESS. The "show configuration" command now prints the version of GNU readline that GDB is using. The "maintenance print remote-registers" now provides an "Expedited" column indicating which registers were included in the last stop reply packet received by GDB. Various command taking filenames as argument now require file names to be quoted if the argument contains white spaces or quote characters. Python API changes New module gdb.missing_objfile that facilitates dealing with missing objfiles when opening a core-file. GDB commands to query, enable and disable handlers created using this API have also been added. New event gdb.tui_enabled. Added the gdb.Symbol.is_artificial attribute. New gdb.record.clear function to clear the trace data of the current recording. The 'signed' argument to gdb.Architecture.integer_type() will no longer accept non-bool types. The gdb.MICommand.installed property can only be set to True or False. The 'qualified' argument to gdb.Breakpoint constructor will no longer accept non-bool types. Debugger Adapter Protocol changes The "scopes" request will now return a scope holding global variables from the stack frame's compilation unit. The "scopes" request will return a "returnValue" scope holding the return value from the latest "stepOut" command, when appropriate. The "launch" and "attach" requests were rewritten in accordance with some clarifications to the spec. Now they can be sent at any time after the "initialized" event, but will not take effect (or send a response) until after the "configurationDone" request has been sent. The "variables" request will not return artificial symbols. Remote Protocol New remote packet: vFile:stat New remote packet: x addr,length Miscellaneous The Ada 'Object_Size attribute is now supported. Styling now available for line numbers, GDB commands and header lines of lists. It is now possible to turn the warning emitted when specifying a language that does not match the current frame off. For ARM targets, the offset of the pc in the jmp_buf has been fixed to match glibc 2.20 and later. This should only matter when not using libc probes. This may cause breakage when using an incompatible libc, like uclibc or newlib, or an older glibc. Deprecated or removed Support for QNX Neutrino has been removed Support for Nios II targets has been removed Support for Intel MPX has been removed See the NEWS file for a more complete and detailed list of what this release includes. December 29th, 2024: GDB 16 branch created The GDB 16 branch (gdb-16-branch) has been created. To check out a copy of the branch use: git clone --branch gdb-16-branch https://sourceware.org/git/binutils-gdb.git September 29th, 2024: GDB 15.2 Released! The latest version of GDB, version 15.2, is available for download. This is a minor corrective release over GDB 15.1, fixing the following issues: PR gdb/31727 (-exec-next fails in mingw (infrun.c:2794: internal-error: resume_1: Assertion `pc_in_thread_step_range (pc, tp)' failed)) PR c++/31900 (libstdc++-prettyprinters/debug.cc print redirected fails since gdb-14-branchpoint-2123-g4e417d7bb1c) PR python/31946 (sys.exit from Python no longer exits the GDB process) PR record/31971 (Loading a saved record file asserts if we try to execute the inferior) PR gdb/32005 (frv_current_sos doesn't set solib::lm_info) PR exp/32015 (GDB crashes while printing large D array) PR gdb/32025 (Fatal error when the disassemble command is interrupted with SIGINT) PR gdb/32143 ([15 Regression] arch/amd64.c:71: internal-error: amd64_create_target_description: Assertion `!is_x32' failed) PR symtab/32158 ([gdb/symtab] enum class enumerator has incorrect parent in cooked index) PR symtab/32160 ([gdb/symtab] Parent map: die parent or scope parent?) See the NEWS file for a more complete and detailed list of what this release includes. @ text @d24 2 a25 2 stands for Simple Frame. The SFrame format keeps track of the minimal necessary information needed for generating stack traces: d37 1 a37 6 * SFrame Section:: * ABI/arch-specific Definition:: Appendices * Generating Stack Traces using SFrame:: d41 1 a41 1 File: sframe-spec.info, Node: Introduction, Next: SFrame Section, Prev: Top, Up: Top d72 1 a72 1 is targeted to be used. An SFrame section reader may use the magic d99 6 a104 8 * Add an unsigned 8-bit integral field to the SFrame function descriptor entry to encode the size of the repetitive code blocks. Such code blocks, e.g, pltN entries, use an SFrame function descriptor entry of type SFRAME_FDE_TYPE_PCMASK. * Add an unsigned 16-bit integral field to the SFrame function descriptor entry to serve as padding. This helps ensure natural alignment for the members of the data structure. * The above two imply that each SFrame function descriptor entry has a107 2 SFrame version 1 is now obsolete and should not be used. d109 1 a109 1 File: sframe-spec.info, Node: SFrame Section, Next: ABI/arch-specific Definition, Prev: Introduction, Up: Top d111 1 a111 1 2 SFrame Section d115 3 a117 3 preamble, and two other sub-sections, namely the SFrame function descriptor entry (SFrame FDE) sub-section, and the SFrame frame row entry (SFrame FRE) sub-section. d127 1 a127 1 File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame Section d133 1 a133 1 section whose format cannot vary between versions. d147 11 a157 13 Offset Type Name Description ------------------------------------------------------------------------------------- 0x00 'uint16_t' 'sfp_magic' The magic number for SFrame section: 0xdee2. Defined as a macro 'SFRAME_MAGIC'. 0x02 'uint8_t' 'sfp_version' The version number of this SFrame section. *Note SFrame Version::, for the set of valid values. Current version is 'SFRAME_VERSION_2'. 0x03 'uint8_t' 'sfp_flags' Flags (section-wide) for this SFrame section. *Note SFrame Flags::, for the set of valid values. d161 3 a163 3 * SFrame Magic Number and Endianness:: * SFrame Version:: * SFrame Flags:: d166 1 a166 1 File: sframe-spec.info, Node: SFrame Magic Number and Endianness, Next: SFrame Version, Up: SFrame Preamble d168 2 a169 2 2.1.1 SFrame Magic Number and Endianness ---------------------------------------- d172 4 a175 4 consumes them. A consumer library reading or writing SFrame sections should detect foreign-endianness by inspecting the SFrame magic number in the 'sfp_magic' field in the SFrame header. It may then provide means to endian-flip the SFrame section as necessary. d178 1 a178 1 File: sframe-spec.info, Node: SFrame Version, Next: SFrame Flags, Prev: SFrame Magic Number and Endianness, Up: SFrame Preamble d180 1 a180 1 2.1.2 SFrame Version d186 1 a186 1 Version Name Number Description d194 1 a194 1 File: sframe-spec.info, Node: SFrame Flags, Prev: SFrame Version, Up: SFrame Preamble d196 1 a196 1 2.1.3 SFrame Flags d208 2 a209 8 'SFRAME_F_FRAME_POINTER' All 0x2 All functions in the object file preserve frame pointer. The purpose of SFRAME_F_FRAME_POINTER flag is to facilitate stack tracers to reliably fallback on the frame pointer based stack tracing method, if SFrame information is not present for some function in the SFrame section. d214 1 a214 1 File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame Section a252 12 The SFrame section contains 'sfh_num_fdes' number of fixed-length array elements in the SFrame FDE sub-section. Each array element is of type SFrame function descriptor entry; each providing a high-level function description for the purpose of stack tracing. More details in a subsequent section. *Note SFrame Function Descriptor Entries::. Next, the SFrame FRE sub-section, starting at offset 'sfh_fre_off', describes the stack trace information for each function, using a total of 'sfh_num_fres' number of variable-length array elements. Each array element is of type SFrame frame row entry. *Note SFrame Frame Row Entries::. d255 2 a256 2 AMD64, the stack offset of the return address is 'CFA - 8'. Since these offsets are expected to be in close vicinity to the CFA in most ABIs, d260 7 a266 10 The SFrame format has made some provisions for supporting more ABIs/architectures in the future. One of them is the concept of the auxiliary SFrame header. Bytes in the auxiliary SFrame header may be used to convey further ABI-specific information. The 'sframe_header' structure provides an unsigned 8-bit integral field to denote the size (in bytes) of an auxiliary SFrame header. The auxiliary SFrame header follows right after the 'sframe_header' structure. As for the calculation of the sub-section offsets, namely 'sfh_fdeoff' and 'sfh_freoff', the _end_ of SFrame header must be the end of the auxiliary SFrame header, if the latter is present. d270 39 a308 31 Offset Type Name Description ------------------------------------------------------------------------------------- 0x00 'sframe_ 'sfh_preamble' The SFrame preamble. preamble' *Note SFrame Preamble::. 0x04 'uint8_t' 'sfh_abi_arch' The ABI/arch identifier. *Note SFrame ABI/arch Identifier::. 0x05 'int8_t' 'sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. 0x06 'int8_t' 'sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. 0x07 'uint8_t' 'sfh_auxhdr_len' Size in bytes of the auxiliary header that follows the 'sframe_header' structure. 0x08 'uint32_t' 'sfh_num_fdes' The number of SFrame FDEs in the section. 0x0c 'uint32_t' 'sfh_num_fres' The number of SFrame FREs in the section. 0x10 'uint32_t' 'sfh_fre_len' The length in bytes of the SFrame FRE sub-section. 0x14 'uint32_t' 'sfh_fdeoff' The offset in bytes to the SFrame FDE sub-section. 0x18 'uint32_t' 'sfh_freoff' The offset in bytes to the SFrame FRE sub-section. d312 1 a312 1 * SFrame ABI/arch Identifier:: d315 1 a315 1 File: sframe-spec.info, Node: SFrame ABI/arch Identifier, Up: SFrame Header d317 1 a317 1 2.2.1 SFrame ABI/arch Identifier d336 1 a336 2 allow stack trace generators to make certain ABI/arch-specific decisions. d339 1 a339 1 File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame Section d344 1 a344 1 The SFrame function descriptor entry sub-section is an array of the a348 7 The array of SFrame FDEs is sorted on the 'sfde_func_start_address' if the SFrame section header flag 'sfp_flags' has 'SFRAME_F_FDE_SORTED' set. Typically (as is the case with GNU ld) a linked object or executable will have the 'SFRAME_F_FDE_SORTED' set. This makes the job of a stack tracer easier as it may then employ binary search schemes to look for the pertinent SFrame FDE. d365 2 a366 2 sub-section (unlike the sub-section offsets in the SFrame header, which are relative to the _end_ of the SFrame header). d368 3 a370 8 'sfde_func_info' is the SFrame FDE "info word", containing information on the FRE type and the FDE type for the function *Note The SFrame FDE Info Word::. Apart from the 'sfde_func_padding2', the SFrame FDE has some currently unused bits in the SFrame FDE info word, *Note The SFrame FDE Info Word::, that may be used for the purpose of extending the SFrame file format specification for future ABIs. d374 31 a404 31 Offset Type Name Description ---------------------------------------------------------------------------------------------- 0x00 'int32_t' 'sfde_func_start_address' Signed 32-bit integral field denoting the virtual memory address of the described function. 0x04 'uint32_t' 'sfde_func_size' Unsigned 32-bit integral field specifying the size of the function in bytes. 0x08 'uint32_t' 'sfde_func_start_fre_off' Unsigned 32-bit integral field specifying the offset in bytes of the function's first SFrame FRE in the SFrame section. 0x0c 'uint32_t' 'sfde_func_num_fres' Unsigned 32-bit integral field specifying the total number of SFrame FREs used for the function. 0x10 'uint8_t' 'sfde_func_info' Unsigned 8-bit integral field specifying the SFrame FDE info word. *Note The SFrame FDE Info Word::. 0x11 'uint8_t' 'sfde_func_rep_size' Unsigned 8-bit integral field specifying the size of the repetitive code block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For example, in AMD64, the size of a pltN entry is 16 bytes. 0x12 'uint16_t' 'sfde_func_padding2' Padding of 2 bytes. Currently unused bytes. d408 3 a410 3 * The SFrame FDE Info Word:: * The SFrame FDE Types:: * The SFrame FRE Types:: d413 1 a413 1 File: sframe-spec.info, Node: The SFrame FDE Info Word, Next: The SFrame FDE Types, Up: SFrame Function Descriptor Entries d415 1 a415 1 2.3.1 The SFrame FDE Info Word d424 2 a425 2 5 'pauth_key' (For AARCH64) Specify which key is used for signing the return addresses in the SFrame FDE. Two possible values: a427 1 Ununsed in AMD64. d432 1 a432 1 *Note The SFrame FDE Types::. d435 1 a435 1 *Note The SFrame FRE Types::. d438 1 a438 1 File: sframe-spec.info, Node: The SFrame FDE Types, Next: The SFrame FRE Types, Prev: The SFrame FDE Info Word, Up: SFrame Function Descriptor Entries d440 1 a440 1 2.3.2 The SFrame FDE Types d443 1 a443 1 The SFrame format defines two types of FDE entries. The choice of which d461 1 a461 1 SFRAME_FDE_TYPE_PCINC 0 Stacktracers perform a d465 1 a465 1 SFRAME_FDE_TYPE_PCMASK 1 Stacktracers perform a d470 1 a470 2 program instructions and is encoded via 'sfde_func_rep_size' in the SFrame FDE. d474 1 a474 1 File: sframe-spec.info, Node: The SFrame FRE Types, Prev: The SFrame FDE Types, Up: SFrame Function Descriptor Entries d476 1 a476 1 2.3.3 The SFrame FRE Types d480 4 a483 4 SFrame format defines three types of SFrame FRE entries to effeciently encode the stack trace information for such a variety of function sizes. These representations vary in the number of bits needed to encode the start address offset in the SFrame FRE. d490 4 a493 3 ------------------------------------------------------------------------------- 'SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) of the SFrame FRE is an unsigned 8-bit value. d495 3 a497 2 'SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) of the SFrame FRE is an unsigned 16-bit value. d499 3 a501 2 'SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) of the SFrame FRE is an unsigned 32-bit value. d504 2 a505 3 The identifier to reflect the chosen SFrame FRE type is stored in the 'fretype' bits in the SFrame FDE info word, *Note The SFrame FDE Info Word::. d508 1 a508 1 File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame Section d513 2 a514 31 The SFrame frame row entry sub-section contains the core of the stack trace information. An SFrame frame row entry (FRE) is a self-sufficient record containing SFrame stack trace information for a range of contiguous (instruction) addresses, starting at the specified offset from the start of the function. Each SFrame FRE encodes the stack offsets to recover the CFA, FP and RA (where applicable) for the respective instruction addresses. To encode this information, each SFrame FRE is followed by S*N bytes, where: - 'S' is the size of a stack offset for the FRE, and - 'N' is the number of stack offsets in the FRE The entities 'S', 'N' are encoded in the SFrame FRE info word, via the 'fre_offset_size' and the 'fre_offset_count' respectively. More information about the precise encoding and range of values for 'S' and 'N' is provided later in the *Note The SFrame FRE Info Word::. It is important to underline here that although the canonical interpretation of these bytes is as stack offsets (to recover CFA, FP and RA), these bytes _may_ be used by future ABIs/architectures to convey other information on a per SFrame FRE basis. In summary, SFrame file format, by design, supports a variable number of stack offsets at the tail end of each SFrame FRE. To keep the SFrame file format specification flexible yet extensible, the interpretation of the stack offsets is ABI/arch-specific. The precise interpretation of the FRE stack offsets in the currently supported ABIs/architectures is covered in the ABI/arch-specific definition of the SFrame file format, *Note ABI/arch-specific Definition::. d516 25 a540 1 Next, the definitions of the three SFrame FRE types are as follows: d571 1 a571 1 Further SFrame FRE types may be added in future. d575 1 a575 1 * The SFrame FRE Info Word:: d578 1 a578 1 File: sframe-spec.info, Node: The SFrame FRE Info Word, Up: SFrame Frame Row Entries d580 1 a580 1 2.4.1 The SFrame FRE Info Word d598 2 a599 3 1-4 'fre_offset_count' A max value of 15 is allowed. Typically, a value of upto 3 is sufficient for most ABIs to track all three of CFA, FP and RA. d619 1 a619 163 File: sframe-spec.info, Node: ABI/arch-specific Definition, Next: Generating Stack Traces using SFrame, Prev: SFrame Section, Up: Top 3 ABI/arch-specific Definition ****************************** This section covers the ABI/arch-specific definition of the SFrame file format. Currently, the only part of the SFrame file format definition that is ABI/arch-specific is the interpretation of the variable number of bytes at the tail end of each SFrame FRE. Currently, these bytes are only used for representing stack offsets (for all the currently supported ABIs). It is recommended to peruse this section along with *Note SFrame Frame Row Entries:: for clarity of context. Future ABIs must specify the algorithm for identifying the appropriate SFrame FRE stack offsets in this chapter. This should inevitably include the blueprint for interpreting the variable number of bytes at the tail end of the SFrame FRE for the specific ABI/arch. Any further provisions, e.g., using the auxiliary SFrame header, etc., if used, must also be outlined here. * Menu: * AMD64:: * AArch64::  File: sframe-spec.info, Node: AMD64, Next: AArch64, Up: ABI/arch-specific Definition 3.1 AMD64 ========= Irrespective of the ABI, the first stack offset is always used to locate the CFA, by interpreting it as: CFA = 'BASE_REG' + offset1. The identification of the 'BASE_REG' is done by using the 'fre_cfa_base_reg_id' field in the SFrame FRE info word. In AMD64, the return address (RA) is always saved on stack when a function call is executed. Further, AMD64 ABI mandates that the RA be saved at a 'fixed offset' from the CFA when entering a new function. This means that the RA does not need to be tracked per SFrame FRE. The fixed offset is encoded in the SFrame file format in the field 'sfh_cfa_fixed_ra_offset' in the SFrame header. *Note SFrame Header::. Hence, the second stack offset (in the SFrame FRE), when present, will be used to locate the FP, by interpreting it as: FP = CFA + offset2. Hence, in summary: Offset ID Interpretation in AMD64 ----------------------------------------------- 1 CFA = 'BASE_REG' + offset1 2 FP = CFA + offset2  File: sframe-spec.info, Node: AArch64, Prev: AMD64, Up: ABI/arch-specific Definition 3.2 AArch64 =========== Irrespective of the ABI, the first stack offset is always used to locate the CFA, by interpreting it as: CFA = 'BASE_REG' + offset1. The identification of the 'BASE_REG' is done by using the 'fre_cfa_base_reg_id' field in the SFrame FRE info word. In AARCH64, the AAPCS64 standard specifies that the Frame Record saves both FP and LR (a.k.a the RA). However, the standard does not mandate the precise location in the function where the frame record is created, if at all. Hence the need to track RA in the SFrame stack trace format. As RA is being tracked in this ABI, the second stack offset is always used to locate the RA, by interpreting it as: RA = CFA + offset2. The third stack offset will be used to locate the FP, by interpreting it as: FP = CFA + offset3. Given the nature of things, the number of stack offsets seen on AARCH64 per SFrame FRE is either 1 or 3. Hence, in summary: Offset ID Interpretation in AArch64 --------------------------------------------- 1 CFA = 'BASE_REG' + offset1 2 RA = CFA + offset2 3 FP = CFA + offset3  File: sframe-spec.info, Node: Generating Stack Traces using SFrame, Next: Index, Prev: ABI/arch-specific Definition, Up: Top Appendix A Generating Stack Traces using SFrame *********************************************** Using some C-like pseudocode, this section highlights how SFrame provides a simple, fast and low-overhead mechanism to generate stack traces. Needless to say that for generating accurate and useful stack traces, several other aspects will need attention: finding and decoding bits of SFrame section(s) in the program binary, symbolization of addresses, to name a few. In the current context, a 'frame' is the abstract construct that encapsulates the following information: - program counter (PC), - stack pointer (SP), and - frame pointer (FP) With that said, establishing the first 'frame' should be trivial: // frame 0 frame->pc = current_IP; frame->sp = get_reg_value (REG_SP); frame->fp = get_reg_value (REG_FP); where 'REG_SP' and 'REG_FP' are are ABI-designated stack pointer and frame pointer registers respectively. Next, given frame N, generating stack trace needs us to get frame N+1. This can be done as follows: // Get the PC, SP, and FP for frame N. pc = frame->pc; sp = frame->sp; fp = frame->fp; // Populate frame N+1. int err = get_next_frame (&next_frame, pc, sp, fp); where given the values of the program counter, stack pointer and frame pointer from frame N, 'get_next_frame' populates the provided 'next_frame' object and returns the error code, if any. In the following pseudocode for 'get_next_frame', the 'sframe_*' functions fetch information from the SFrame section. fre = sframe_find_fre (pc); if (fre) // Whether the base register for CFA tracking is REG_FP. base_reg_val = sframe_fre_base_reg_fp_p (fre) ? fp : sp; // Get the CFA stack offset from the FRE. cfa_offset = sframe_fre_get_cfa_offset (fre); // Get the fixed RA offset or FRE stack offset as applicable. ra_offset = sframe_fre_get_ra_offset (fre); // Get the fixed FP offset or FRE stack offset as applicable. fp_offset = sframe_fre_get_fp_offset (fre); cfa = base_reg_val + cfa_offset; next_frame->sp = cfa; ra_stack_loc = cfa + ra_offset; // Get the address stored in the stack location. next_frame->pc = read_value (ra_stack_loc); if (fp_offset is VALID) fp_stack_loc = cfa + fp_offset; // Get the value stored in the stack location. next_frame->fp = read_value (fp_stack_loc); else // Continue to use the value of fp as it has not // been clobbered by the current frame yet. next_frame->fp = fp; else ret = ERR_NO_SFRAME_FRE;  File: sframe-spec.info, Node: Index, Prev: Generating Stack Traces using SFrame, Up: Top a626 2 * ABI/arch-specific Definition: ABI/arch-specific Definition. (line 6) d629 1 a629 2 * endianness: SFrame Magic Number and Endianness. (line 6) d632 1 a632 6 * Provisions for future ABIs: SFrame Header. (line 59) * Provisions for future ABIs <1>: SFrame Function Descriptor Entries. (line 41) * Provisions for future ABIs <2>: SFrame Frame Row Entries. (line 25) * SFrame ABI/arch Identifier: SFrame ABI/arch Identifier. d636 1 a636 1 * SFrame Flags: SFrame Flags. (line 6) a639 2 * SFrame magic number: SFrame Magic Number and Endianness. (line 6) d641 3 a643 3 * SFrame Section: SFrame Section. (line 6) * SFrame versions: SFrame Version. (line 9) * SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch Identifier. d645 1 a645 1 * SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch Identifier. d647 1 a647 1 * SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch Identifier. d649 13 a661 13 * SFRAME_FDE_TYPE_PCINC: The SFrame FDE Types. (line 6) * SFRAME_FDE_TYPE_PCMASK: The SFrame FDE Types. (line 6) * SFRAME_FRE_OFFSET_1B: The SFrame FRE Info Word. (line 31) * SFRAME_FRE_OFFSET_2B: The SFrame FRE Info Word. (line 35) * SFRAME_FRE_OFFSET_4B: The SFrame FRE Info Word. (line 38) * SFRAME_FRE_TYPE_ADDR1: The SFrame FRE Types. (line 17) * SFRAME_FRE_TYPE_ADDR2: The SFrame FRE Types. (line 21) * SFRAME_FRE_TYPE_ADDR4: The SFrame FRE Types. (line 24) * SFRAME_F_FDE_SORTED: SFrame Flags. (line 11) * SFRAME_F_FRAME_POINTER: SFrame Flags. (line 14) d663 5 a667 5 * SFRAME_VERSION_1: SFrame Version. (line 9) * The SFrame FDE Info Word: SFrame Function Descriptor Entries. (line 85) * The SFrame FRE Info Word: SFrame Frame Row Entries. (line 74) d673 17 a689 21 Node: Introduction1232 Node: Overview1418 Node: Changes from Version 1 to Version 22984 Node: SFrame Section3955 Node: SFrame Preamble4454 Node: SFrame Magic Number and Endianness6021 Node: SFrame Version6553 Node: SFrame Flags7130 Node: SFrame Header8145 Node: SFrame ABI/arch Identifier13571 Node: SFrame Function Descriptor Entries14599 Node: The SFrame FDE Info Word19043 Node: The SFrame FDE Types20257 Node: The SFrame FRE Types22079 Node: SFrame Frame Row Entries23567 Node: The SFrame FRE Info Word26619 Node: ABI/arch-specific Definition28697 Node: AMD6429792 Node: AArch6430892 Node: Generating Stack Traces using SFrame32101 Node: Index35122 @ 1.1.1.4 log @Import gdb-17.1, previous was 16.3 This version of GDB includes the following changes and enhancements: * x86-64 CET shadow stack support * Debugging Linux programs that use AArch64 Guarded Control Stacks * GDB record feature now supports rv64gc architectures * 'info threads' command support for two new options '-stopped' and '-running' to limit the list of displayed threads. * On Linux and FreeBSD, the addresses shown by the 'info sharedlibrary' command are now for the full memory range allocated to the shared library. * Linux checkpoints now work with multiple inferiors * Improved linker namespace support * Warnings and error messages now start with an emoji (warning sign, or cross mark) if supported by the host charset. Configurable. * Built-in support for TLS on Linux as backup when libthread_db is not available. Supported on the x86_64, aarch64, ppc64, s390x, and riscv architectures, when compiled with GLIBC or MUSL. * New command "set riscv numeric-register-names" to display risc-v registers using their numeric names instead of their ABI names. * The Alpha target now supports target descriptions. Python API enhancements: * New class gdb.Color for dealing with colors, and new constant gdb.PARAM_COLOR * New gdb.ParameterPrefix class, to create new 'set/show' command prefixes. * New attribute gdb.Value.is_unavailable, this checks for unavailability like gdb.Value.is_optimized_out checks for optimized out values. * New gdb.warning() function to print a warning message, with GDB's standard 'warning' prefix (see emoji support entry below) * gdb.execute has an additional 'styling' argument. * Prefix commands (gdb.Command sub-classes) that don't have an invoke method now behave like builtin prefix commands when invoked without a sub-command name. * Setting the documentation string (__doc__) of a gdb.Parameter sub-class to the empty string, means GDB will only display the set_doc or show_doc strings in the set/show help output. Guile API enhancements: * New type for dealing with colors and constant PARAM_COLOR * Prefix commands (using make-command) that don't have a #:invoke property will now behave like builtin prefix commands when invoked without a sub-command name. * Eliding the #:doc string from make-parameter now means that GDB will use a default documentation string. * Setting #:doc to the empty string for make-parameter means GDB will only display the #:set_doc or #:show_doc strings in the set/show help output. Debugger Adapter Protocol changes: * GDB now supports the "completions" request. * New "--binary-output" command line option to disable LF translations (Windows only) New convenience variables: * $_colorsupport providing a comma-separated list of color space names supported by the terminal. * $linker_namespace_count and $_linker_namespace provide the list of active linker namespaces. Remote package additions and changes: * New 'binary-upload+' value in qSupported reply * The 'vFile:stat' command implementation has been corrected to use stat rather than lstat. * New vFile:lstat packet, useful for handling symbolic links * Support for the "id_str" attribute in 'qXfer:threads:read' XML answer. GDB/MI changes: * The =library-unloaded event now includes the 'ranges' field and the 'still-in-use' field. Configure changes: * Ability to select which file formats to include support for * New option --disable-gdb-compile to disable support for the compile subsystem. * New option --disable-gdb-dwarf-support to disable support for DWARF debug information in GDB. * New option --disable-gdb-mdebug-support to disable support for mdebug/ecoff debug information. Incompatible changes: * Support for Python versions older than 3.4 has been removed * Support for stabs debugging format and the a.out/dbx object format is deprecated, and will be removed in GDB 18. * UST (static tracepoint) gdbserver support has been removed @ text @d4 1 a4 1 Copyright (C) 2021-2025 Free Software Foundation, Inc. d23 3 a25 3 This manual describes version 2 (errata 1) of the SFrame file format. SFrame stands for Simple Frame. The SFrame format keeps track of the minimal necessary information needed for generating stack traces: d64 1 a64 2 appears in segment of type PT_GNU_SFRAME. An ELF SFrame section will have the type SHT_GNU_SFRAME. d67 1 a67 1 namely, AMD64, AAPCS64, and s390x. a113 37 * [Errata 1] Add a new flag SFRAME_F_FDE_FUNC_START_PCREL, as an erratum to SFrame Version 2, to indicate the encoding of the SFrame FDE function start address field: - if set, 'sfde_func_start_address' field contains the offset in bytes to the start PC of the associated function from the field itself. - if unset, 'sfde_func_start_address' field contains the offset in bytes to the start PC of the associated function from the start of the SFrame section. * [Errata 1] Add a new ABI/arch identifier SFRAME_ABI_S390X_ENDIAN_BIG for the s390 architecture (64-bit) s390x ABI. Other s390x-specific backward compatible changes including the following helper definitions have been incrementally added to SFrame version 2 only: - SFRAME_S390X_SP_VAL_OFFSET: SP value offset from CFA. - SFRAME_V2_S390X_OFFSET_IS_REGNUM: Test whether FP/RA offset is an encoded DWARF register number. - SFRAME_V2_S390X_OFFSET_ENCODE_REGNUM: Encode a DWARF register number as an FP/RA offset. - SFRAME_V2_S390X_OFFSET_DECODE_REGNUM: Decode a DWARF register number from an FP/RA offset. - SFRAME_FRE_RA_OFFSET_INVALID: Invalid RA offset value (like SFRAME_CFA_FIXED_RA_INVALID). Used on s390x as padding offset to represent FP without RA saved. - SFRAME_S390X_CFA_OFFSET_ADJUSTMENT: CFA offset (from CFA base register) adjustment value. Used to enable use of 8-bit SFrame offsets on s390x. - SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR: CFA offset alignment factor. Used to scale down the CFA offset to improve the use of 8-bit SFrame offsets. - SFRAME_V2_S390X_CFA_OFFSET_ENCODE: Encode CFA offset (i.e., apply CFA offset adjustment and then scale down by CFA offset alignment factor). - SFRAME_V2_S390X_CFA_OFFSET_DECODE: Decode CFA offset (i.e., scale up by CFA offset alignment factor and then revert CFA offset adjustment). * [Errata 1] An ELF SFrame section has the type SHT_GNU_SFRAME. d215 7 a221 14 Flag Version Value Meaning -------------------------------------------------------------------------------------- 'SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries are sorted on PC. 'SFRAME_F_FRAME_POINTER' All 0x2 All functions in the object file preserve frame pointer. 'SFRAME_F_FDE_FUNC_START_PCREL'2 0x4 The 'sfde_func_start_address' field in the SFrame FDE is an offset in bytes to the function's start address, from the field itself. If unset, the 'sfde_func_start_address' field in the SFrame FDE is an offset in bytes to the function's start address, from the start of the SFrame section. d228 1 a228 2 Further flags may be added in future. Bits corresponding to the currently undefined flags must be set to zero. a357 2 'SFRAME_ABI_S390X_ENDIAN_BIG' 4 s390x big-endian d415 1 a415 9 function, for which the SFrame FDE applies. If the flag 'SFRAME_F_FDE_FUNC_START_PCREL', *Note SFrame Flags::, in the SFrame header is set, the value encoded in the 'sfde_func_start_address' field is the offset in bytes to the function's start address, from the SFrame 'sfde_func_start_address' field. d608 1 a608 1 field denoting the start address of a range of program counters, for d610 2 a611 2 'sfre_start_address' field is the offset in bytes of the range's start address, from the start address of the function. d672 4 a675 5 at the tail end of each SFrame FRE. Currently, these bytes are used for representing stack offsets (for AMD64 and AARCH64 ABIs). For s390x ABI, the interpretation of these bytes may be stack offsets or even register numbers. It is recommended to peruse this section along with *Note SFrame Frame Row Entries:: for clarity of context. a687 1 * s390x:: d719 1 a719 1 File: sframe-spec.info, Node: AArch64, Next: s390x, Prev: AMD64, Up: ABI/arch-specific Definition a749 73 File: sframe-spec.info, Node: s390x, Prev: AArch64, Up: ABI/arch-specific Definition 3.3 s390x ========= A stack tracer implementation must initialize the SP to the designated SP register value, the FP to the preferred FP register value, and the RA to the designated RA register value in the topmost stack frame of the callchain. This is required, as either the SP or FP is used as CFA base register and as the FP and/or RA are not necessarily saved on the stack. For RA this may only be the case in the topmost stack frame of the callchain. For FP this may be the case in any stack frame. Irrespective of the ABI, the first stack offset is always used to locate the CFA. On s390x the value of the offset is stored adjusted by the s390x-specific 'SFRAME_S390X_CFA_OFFSET_ADJUSTMENT' and scaled down by the s390x-specific 'SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR', to enable and improve the use of signed 8-bit offsets on s390x. s390x-specific helpers 'SFRAME_V2_S390X_CFA_OFFSET_ENCODE' and 'SFRAME_V2_S390X_CFA_OFFSET_DECODE' are provided to perform or undo the adjustment and scaling. The CFA offset can therefore be interpreted as: CFA = 'BASE_REG' + offset1 - 'SFRAME_S390X_CFA_OFFSET_ADJUSTMENT' or CFA = 'BASE_REG' + (offset1 * 'SFRAME_S390X_CFA_OFFSET_ALIGNMENT_FACTOR') - 'SFRAME_S390X_CFA_OFFSET_ADJUSTMENT'. The identification of the 'BASE_REG' is done by using the 'fre_cfa_base_reg_id' field in the SFrame FRE info word. The (64-bit) s390x ELF ABI does not mandate the precise location in a function where the return address (RA) and frame pointer (FP) are saved, if at all. Hence the need to track RA in the SFrame stack trace format. As RA is being tracked in this ABI, the second stack offset is always used to locate the RA stack slot, by interpreting it as: RA = CFA + offset2, unless the offset has a value of 'SFRAME_FRE_RA_OFFSET_INVALID'. RA remains unchanged, if the offset is not available or has a value of 'SFRAME_FRE_RA_OFFSET_INVALID'. Stack tracers are recommended to validate that the "unchanged RA" pattern, when present, is seen only for the topmost stack frame. The third stack offset is used to locate the FP stack slot, by interpreting it as: FP = CFA + offset3. FP remains unchanged, if the offset is not available. In leaf functions the RA and FP may be saved in other registers, such as floating-point registers (FPRs), instead of on the stack. To represent this in the SFrame stack trace format the DWARF register number is encoded as RA/FP offset using the least-significant bit (LSB) as indication: offset = (regnum << 1) | 1. A LSB of zero indicates a stack slot offset. A LSB of one indicates a DWARF register number, which is interpreted as: regnum = offset >> 1. Given the nature of leaf functions, this can only occur in the topmost frame during stack tracing. It is recommended that a stack tracer implementation performs the required checks to ensure that restoring FP and RA from the said register locations is done only for topmost stack frame in the callchain. Given the nature of things, the number of stack offsets and/or register numbers seen on s390x per SFrame FRE is either 1, 2, or 3. Hence, in summary: Offset ID Interpretation in s390x -------------------------------------------------------------------------- 1 CFA = 'BASE_REG' + offset1 2 RA stack slot = CFA + offset2, if (offset2 & 1 == 0) RA register number = offset2 >> 1, if (offset2 & 1 == 1) RA not saved if (offset2 == 'SFRAME_FRE_RA_OFFSET_INVALID') 3 FP stack slot = CFA + offset3, if (offset3 & 1 == 0) FP register number = offset3 >> 1, if (offset3 & 1 == 1) The s390x ELF ABI defines the CFA as stack pointer (SP) at call site +160. The SP can therefore be obtained using the SP value offset from CFA 'SFRAME_S390X_SP_VAL_OFFSET' of -160 as follows: SP = CFA + 'SFRAME_S390X_SP_VAL_OFFSET'  d806 1 a806 1 next_frame->sp = cfa [+ SFRAME_S390X_SP_VAL_OFFSET on s390x]; a863 2 * SFRAME_ABI_S390X_ENDIAN_BIG: SFrame ABI/arch Identifier. (line 20) a874 1 * SFRAME_F_FDE_FUNC_START_PCREL: SFrame Flags. (line 16) d880 1 a880 1 (line 93) d888 21 a908 22 Node: Introduction1242 Node: Overview1428 Node: Changes from Version 1 to Version 23049 Node: SFrame Section6184 Node: SFrame Preamble6683 Node: SFrame Magic Number and Endianness8250 Node: SFrame Version8782 Node: SFrame Flags9359 Node: SFrame Header11057 Node: SFrame ABI/arch Identifier16483 Node: SFrame Function Descriptor Entries17615 Node: The SFrame FDE Info Word22752 Node: The SFrame FDE Types23966 Node: The SFrame FRE Types25788 Node: SFrame Frame Row Entries27276 Node: The SFrame FRE Info Word30314 Node: ABI/arch-specific Definition32392 Node: AMD6433580 Node: AArch6434680 Node: s390x35903 Node: Generating Stack Traces using SFrame39835 Node: Index42896 @