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