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