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