mirror of
https://sourceware.org/git/binutils-gdb.git
synced 2024-12-27 04:52:05 +08:00
fd67aa1129
Adds two new external authors to etc/update-copyright.py to cover bfd/ax_tls.m4, and adds gprofng to dirs handled automatically, then updates copyright messages as follows: 1) Update cgen/utils.scm emitted copyrights. 2) Run "etc/update-copyright.py --this-year" with an extra external author I haven't committed, 'Kalray SA.', to cover gas testsuite files (which should have their copyright message removed). 3) Build with --enable-maintainer-mode --enable-cgen-maint=yes. 4) Check out */po/*.pot which we don't update frequently.
698 lines
22 KiB
Plaintext
698 lines
22 KiB
Plaintext
\input texinfo @c -*- Texinfo -*-
|
|
@setfilename sframe-spec.info
|
|
@settitle The SFrame Format
|
|
|
|
@copying
|
|
Copyright @copyright{} 2021-2024 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU General Public License, Version 3 or any
|
|
later version published by the Free Software Foundation. A copy of the
|
|
license is included in the section entitled ``GNU General Public
|
|
License''.
|
|
|
|
@end copying
|
|
|
|
@dircategory Software development
|
|
@direntry
|
|
* SFrame: (sframe-spec). The Simple Frame format.
|
|
@end direntry
|
|
|
|
@titlepage
|
|
@title The SFrame Format
|
|
@subtitle Version 2
|
|
@author Indu Bhagat
|
|
|
|
@page
|
|
@vskip 0pt plus 1filll
|
|
@insertcopying
|
|
@end titlepage
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top The SFrame format
|
|
|
|
This manual describes version 2 of the SFrame file format. SFrame stands for
|
|
Simple Frame format. SFrame format keeps track of the minimal necessary
|
|
information needed for generating stack traces:
|
|
|
|
@itemize @minus
|
|
@item
|
|
Canonical Frame Address (CFA).
|
|
@item
|
|
Frame Pointer (FP).
|
|
@item
|
|
Return Address (RA).
|
|
@end itemize
|
|
|
|
The reason for existence of the SFrame format is to provide a simple, fast and
|
|
low-overhead mechanism to generate stack traces.
|
|
|
|
@menu
|
|
* Introduction::
|
|
* SFrame section::
|
|
* Index::
|
|
@end menu
|
|
|
|
@end ifnottex
|
|
|
|
@node Introduction
|
|
@chapter Introduction
|
|
@cindex Introduction
|
|
|
|
@menu
|
|
* Overview::
|
|
* Changes from Version 1 to Version 2::
|
|
@end menu
|
|
|
|
@node Overview
|
|
@section Overview
|
|
@cindex Overview
|
|
|
|
The SFrame stack trace information is provided in a loaded section, known as the
|
|
@code{.sframe} section. When available, the @code{.sframe} section appears in
|
|
a new segment of its own, PT_GNU_SFRAME.
|
|
|
|
The SFrame format is currently supported only for select ABIs, namely, AMD64
|
|
and AAPCS64.
|
|
|
|
A portion of the SFrame format follows an unaligned on-disk representation.
|
|
Some data structures, however, (namely the SFrame header and the SFrame
|
|
function descriptor entry) have elements at their natural boundaries. All data
|
|
structures are packed, unless otherwise stated.
|
|
|
|
The contents of the SFrame section are stored in the target endianness, i.e.,
|
|
in the endianness of the system on which the section is targetted to be used.
|
|
An SFrame section reader may use the magic number in the SFrame header to
|
|
identify the endianness of the SFrame section.
|
|
|
|
Addresses in this specification are expressed in bytes.
|
|
|
|
The rest of this specification describes the current version of the format,
|
|
@code{SFRAME_VERSION_2}, in detail. Additional sections outline the major
|
|
changes made to each previously published version of the SFrame stack trace
|
|
format.
|
|
|
|
The associated API to decode, probe and encode the SFrame section, provided via
|
|
@code{libsframe}, is not accompanied here at this time. This will be added
|
|
later.
|
|
|
|
This document is intended to be in sync with the C code in @file{sframe.h}.
|
|
Please report discrepancies between the two, if any.
|
|
|
|
@node Changes from Version 1 to Version 2
|
|
@section Changes from Version 1 to Version 2
|
|
@cindex Changes from Version 1 to Version 2
|
|
|
|
The following is a list of the changes made to the SFrame stack trace format
|
|
since Version 1 was published.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
SFrame Function Descriptor Entry encodes the size of the repetitive code
|
|
blocks, e.g., pltN entries for which an FDE of type SFRAME_FDE_TYPE_PCMASK is
|
|
used.
|
|
@item
|
|
SFrame Function Descriptor Entry includes an explicit padding of two bytes to
|
|
ensure natural alignment for its data members.
|
|
@item
|
|
The above two imply that each SFrame Function Descriptor Entry has a fixed size
|
|
of 20 bytes instead of its size of 17 bytes in SFrame format version 1.
|
|
@end itemize
|
|
|
|
@node SFrame section
|
|
@chapter SFrame section
|
|
@cindex SFrame section
|
|
|
|
The SFrame section consists of an SFrame header, starting with a preamble, and
|
|
two other sub-sections, namely the SFrame Function Descriptor Entry (SFrame
|
|
FDE) sub-section, and the SFrame Frame Row Entry (SFrame FRE) sub-section.
|
|
|
|
@menu
|
|
* SFrame Preamble::
|
|
* SFrame Header::
|
|
* SFrame Function Descriptor Entries::
|
|
* SFrame Frame Row Entries::
|
|
@end menu
|
|
|
|
@node SFrame Preamble
|
|
@section SFrame Preamble
|
|
@cindex SFrame preamble
|
|
|
|
The preamble is a 32-bit packed structure; the only part of the SFrame whose
|
|
format cannot vary between versions.
|
|
|
|
@example
|
|
typedef struct sframe_preamble
|
|
@{
|
|
uint16_t sfp_magic;
|
|
uint8_t sfp_version;
|
|
uint8_t sfp_flags;
|
|
@} ATTRIBUTE_PACKED sframe_preamble;
|
|
@end example
|
|
|
|
Every element of the SFrame preamble is naturally aligned.
|
|
|
|
All values are stored in the endianness of the target system for which the
|
|
SFrame section is intended. Further details:
|
|
|
|
@multitable {Offset} {@code{uint8_t sfp_version}} {The magic number for SFrame section: 0xdee2. Defined}
|
|
@headitem Offset @tab Name @tab Description
|
|
@item 0x00
|
|
@tab @code{uint16_t sfp_magic}
|
|
@tab The magic number for SFrame section: 0xdee2. Defined as a macro @code{SFRAME_MAGIC}.
|
|
@tindex SFRAME_MAGIC
|
|
|
|
@item 0x02
|
|
@tab @code{uint8_t sfp_version}
|
|
@tab The version number of this SFrame section. @xref{SFrame version}, for the
|
|
set of valid values. Current version is
|
|
@code{SFRAME_VERSION_1}.
|
|
|
|
@item 0x03
|
|
@tab @code{uint8_t sfp_flags}
|
|
@tab Flags (section-wide) for this SFrame section. @xref{SFrame flags}, for the
|
|
set of valid values.
|
|
@end multitable
|
|
|
|
@menu
|
|
* SFrame endianness::
|
|
* SFrame version::
|
|
* SFrame flags::
|
|
@end menu
|
|
|
|
@node SFrame endianness
|
|
@subsection SFrame endianness
|
|
|
|
@cindex endianness
|
|
SFrame sections are stored in the target endianness of the system that consumes
|
|
them. The SFrame library (@code{libsframe}) can, however, detect whether to
|
|
endian-flip an SFrame section at decode time, by inspecting the
|
|
@code{sfp_magic} field in the SFrame header (If it appears as 0xe2de,
|
|
endian-flipping is needed).
|
|
|
|
@node SFrame version
|
|
@subsection SFrame version
|
|
|
|
The version of the SFrame format can be determined by inspecting
|
|
@code{sfp_version}. The following versions are currently valid:
|
|
|
|
@tindex SFRAME_VERSION_1
|
|
@cindex SFrame versions
|
|
@multitable {SFRAME_VERSION_2} {Number} {Current version, under development.}
|
|
@headitem Version @tab Number @tab Description
|
|
@item @code{SFRAME_VERSION_1}
|
|
@tab 1 @tab First version, obsolete.
|
|
@item @code{SFRAME_VERSION_2}
|
|
@tab 2 @tab Current version, under development.
|
|
@end multitable
|
|
|
|
This document describes @code{SFRAME_VERSION_2}.
|
|
|
|
@node SFrame flags
|
|
@subsection SFrame flags
|
|
@cindex SFrame flags
|
|
@comment @vindex sfp_flags
|
|
@comment @vindex SFrame section-wide flags
|
|
@comment @subsection SFrame section-wide flags
|
|
|
|
The preamble contains bitflags in its @code{sfp_flags} field that
|
|
describe various section-wide properties.
|
|
|
|
The following flags are currently defined.
|
|
|
|
@multitable {@code{SFRAME_F_FRAME_POINTER}} {Versions} {Value} {Function Descriptor Entries}
|
|
@headitem Flag @tab Versions @tab Value @tab Meaning
|
|
@tindex SFRAME_F_FDE_SORTED
|
|
@item @code{SFRAME_F_FDE_SORTED} @tab All @tab 0x1 @tab Function Descriptor
|
|
Entries are sorted on PC.
|
|
@tindex SFRAME_F_FRAME_POINTER
|
|
@item @code{SFRAME_F_FRAME_POINTER} @tab All @tab 0x2
|
|
@tab Functions preserve frame-pointer.
|
|
@end multitable
|
|
|
|
Further flags may be added in future.
|
|
|
|
@node SFrame Header
|
|
@section SFrame Header
|
|
@cindex SFrame header
|
|
|
|
The SFrame header is the first part of an SFrame section. It begins with the
|
|
SFrame preamble. All parts of it other than the preamble
|
|
(@pxref{SFrame Preamble}) can vary between SFrame file versions. It contains
|
|
things that apply to the section as a whole, and offsets to the various other
|
|
sub-sections defined in the format. As with the rest of the SFrame section,
|
|
all values are stored in the endianness of the target system.
|
|
|
|
The two sub-sections tile the SFrame section: each section runs from the offset
|
|
given until the start of the next section. An explicit length is given for the
|
|
last sub-section, the SFrame Frame Row Entry (SFrame FRE) sub-section.
|
|
|
|
@example
|
|
typedef struct sframe_header
|
|
@{
|
|
sframe_preamble sfh_preamble;
|
|
uint8_t sfh_abi_arch;
|
|
int8_t sfh_cfa_fixed_fp_offset;
|
|
int8_t sfh_cfa_fixed_ra_offset;
|
|
uint8_t sfh_auxhdr_len;
|
|
uint32_t sfh_num_fdes;
|
|
uint32_t sfh_num_fres;
|
|
uint32_t sfh_fre_len;
|
|
uint32_t sfh_fdeoff;
|
|
uint32_t sfh_freoff;
|
|
@} ATTRIBUTE_PACKED sframe_header;
|
|
@end example
|
|
|
|
Every element of the SFrame header is naturally aligned.
|
|
|
|
The sub-section offsets, namely @code{sfh_fdeoff} and @code{sfh_freoff}, in the
|
|
SFrame header are relative to the @emph{end} of the SFrame header; they are
|
|
each an offset in bytes into the SFrame section where the SFrame FDE
|
|
sub-section and the SFrame FRE sub-section respectively start.
|
|
|
|
SFrame header allows specifying explicitly the fixed offsets from CFA, if any,
|
|
from which FP or RA may be recovered. For example, in AMD64, the stack offset
|
|
of the return address is @code{CFA - 8}. Since this offset is in close
|
|
vicinity with the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset} and
|
|
@code{sfh_cfa_fixed_ra_offset} are limited to signed 8-bit integers.
|
|
|
|
SFrame format has made some provisions for supporting more ABIs/architectures
|
|
in the future. The @code{sframe_header} structure provides an unsigned 8-bit
|
|
integral field to denote the size of an auxiliary SFrame header. The
|
|
auxiliary SFrame header follows right after the @code{sframe_header}
|
|
structure. As for the offset calculations, the @emph{end} of SFrame header
|
|
must be the end of the auxiliary SFrame header, if the latter is present.
|
|
|
|
Putting it all together:
|
|
|
|
@multitable {Offset} {@code{int8_t sfh_cfa_fixed_fp_offset}} {The number of SFrame FREs in the section.}
|
|
@headitem Offset @tab Name @tab Description
|
|
@item 0x00
|
|
@tab @code{sframe_preamble sfh_preamble}
|
|
@tab The SFrame preamble. @xref{SFrame Preamble}.
|
|
|
|
@item 0x04
|
|
@tab @code{uint8_t sfh_abi_arch}
|
|
@tab The ABI/arch identifier. @xref{SFrame ABI/arch identifier}.
|
|
|
|
@item 0x05
|
|
@tab @code{int8_t sfh_cfa_fixed_fp_offset}
|
|
@tab The CFA fixed FP offset, if any.
|
|
|
|
@item 0x06
|
|
@tab @code{int8_t sfh_cfa_fixed_ra_offset}
|
|
@tab The CFA fixed RA offset, if any.
|
|
|
|
@item 0x07
|
|
@tab @code{uint8_t sfh_auxhdr_len}
|
|
@tab Size in bytes of the auxiliary header that follows the
|
|
@code{sframe_header} structure.
|
|
|
|
@item 0x08
|
|
@tab @code{uint32_t sfh_num_fdes}
|
|
@tab The number of SFrame FDEs in the section.
|
|
|
|
@item 0xc
|
|
@tab @code{uint32_t sfh_num_fres}
|
|
@tab The number of SFrame FREs in the section.
|
|
|
|
@item 0x10
|
|
@tab @code{uint32_t sfh_fre_len}
|
|
@tab The length in bytes of the SFrame FRE sub-section.
|
|
|
|
@item 0x14
|
|
@tab @code{uint32_t sfh_fdeoff}
|
|
@tab The offset in bytes of the SFrame FDE sub-section. This sub-section
|
|
contains @code{sfh_num_fdes} number of fixed-length array elements. The array
|
|
element is of type SFrame function desciptor entry, each providing a
|
|
high-level function description for backtracing.
|
|
@xref{SFrame Function Descriptor Entries}.
|
|
|
|
@item 0x18
|
|
@tab @code{uint32_t sfh_freoff}
|
|
@tab The offset in bytes of the SFrame FRE sub-section, the core of the SFrame
|
|
section, which describes the stack trace information using variable-length array
|
|
elements. @xref{SFrame Frame Row Entries}.
|
|
|
|
@end multitable
|
|
|
|
@menu
|
|
* SFrame ABI/arch identifier::
|
|
@end menu
|
|
|
|
@node SFrame ABI/arch identifier
|
|
@subsection SFrame ABI/arch identifier
|
|
@cindex SFrame ABI/arch identifier
|
|
|
|
SFrame header identifies the ABI/arch of the target system for which the
|
|
executable and hence, the stack trace information contained in the SFrame
|
|
section, is intended. There are currently three identifiable ABI/arch values
|
|
in the format.
|
|
|
|
@multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 little-endian}}
|
|
@headitem ABI/arch Identifier @tab Value @tab Description
|
|
|
|
@tindex SFRAME_ABI_AARCH64_ENDIAN_BIG
|
|
@item @code{SFRAME_ABI_AARCH64_ENDIAN_BIG}
|
|
@tab 1 @tab AARCH64 big-endian
|
|
|
|
@tindex SFRAME_ABI_AARCH64_ENDIAN_LITTLE
|
|
@item @code{SFRAME_ABI_AARCH64_ENDIAN_LITTLE}
|
|
@tab 2 @tab AARCH64 little-endian
|
|
|
|
@tindex SFRAME_ABI_AMD64_ENDIAN_LITTLE
|
|
@item @code{SFRAME_ABI_AMD64_ENDIAN_LITTLE}
|
|
@tab 3 @tab AMD64 little-endian
|
|
|
|
@end multitable
|
|
|
|
The presence of an explicit identification of ABI/arch in SFrame may allow
|
|
stack trace generators to make certain ABI-specific decisions.
|
|
|
|
@node SFrame Function Descriptor Entries
|
|
@section SFrame FDE
|
|
@cindex SFrame FDE
|
|
|
|
The SFrame Function Descriptor Entry sub-section is a sorted array of
|
|
fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE
|
|
is a packed structure which contains information to describe a function's stack
|
|
trace information at a high-level.
|
|
|
|
@example
|
|
typedef struct sframe_func_desc_entry
|
|
@{
|
|
int32_t sfde_func_start_address;
|
|
uint32_t sfde_func_size;
|
|
uint32_t sfde_func_start_fre_off;
|
|
uint32_t sfde_func_num_fres;
|
|
uint8_t sfde_func_info;
|
|
uint8_t sfde_func_rep_size;
|
|
uint16_t sfde_func_padding2;
|
|
@} ATTRIBUTE_PACKED sframe_func_desc_entry;
|
|
@end example
|
|
|
|
Every element of the SFrame function descriptor entry is naturally aligned.
|
|
|
|
@code{sfde_func_start_fre_off} is the offset to the first SFrame FRE for the
|
|
function. This offset is relative to the @emph{end of the SFrame FDE}
|
|
sub-section (unlike the offsets in the SFrame header, which are relative to the
|
|
@emph{end} of the SFrame header).
|
|
|
|
@code{sfde_func_info} is the "info word", containing information on the FRE
|
|
type and the FDE type for the function @xref{The SFrame FDE info word}.
|
|
|
|
Following table describes each component of the SFrame FDE structure:
|
|
|
|
@multitable {Offset} {@code{uint32_t sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the}
|
|
@headitem Offset @tab Name @tab Description
|
|
@item 0x00
|
|
@tab @code{int32_t sfde_func_start_address}
|
|
@tab Signed 32-bit integral field denoting the virtual memory address of the
|
|
described function.
|
|
|
|
@item 0x04
|
|
@tab @code{uint32_t sfde_func_size}
|
|
@tab Unsigned 32-bit integral field specifying the size of the function in
|
|
bytes.
|
|
|
|
@item 0x08
|
|
@tab @code{uint32_t sfde_func_start_fre_off}
|
|
@tab Unsigned 32-bit integral field specifying the offset in bytes of the
|
|
function's first SFrame FRE in the SFrame section.
|
|
|
|
@item 0x0c
|
|
@tab @code{uint32_t sfde_func_num_fres}
|
|
@tab Unsigned 32-bit integral field specifying the total number of SFrame FREs
|
|
used for the function.
|
|
|
|
@item 0x10
|
|
@tab @code{uint8_t sfde_func_info}
|
|
@tab Unsigned 8-bit integral field specifying the SFrame FDE info word.
|
|
@xref{The SFrame FDE info word}.
|
|
|
|
@item 0x11
|
|
@tab @code{uint8_t sfde_func_rep_size}
|
|
@tab Unsigned 8-bit integral field specifying the size of the repetitive code
|
|
block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For
|
|
example, in AMD64, the size of a pltN entry is 16 bytes.
|
|
|
|
@item 0x12
|
|
@tab @code{uint16_t sfde_func_padding2}
|
|
@tab Padding of 2 bytes. Currently unused bytes.
|
|
|
|
@end multitable
|
|
|
|
@menu
|
|
* The SFrame FDE info word::
|
|
* The SFrame FDE types::
|
|
* The SFrame FRE types::
|
|
@end menu
|
|
|
|
@cindex The SFrame FDE info word
|
|
@node The SFrame FDE info word
|
|
@subsection The SFrame FDE info word
|
|
|
|
The info word is a bitfield split into three parts. From MSB to LSB:
|
|
|
|
@multitable {Bit offset} {@code{pauth_key}} {Specify which key is used for signing the return addresses}
|
|
@headitem Bit offset @tab Name @tab Description
|
|
@item 7--6
|
|
@tab @code{unused}
|
|
@tab Unused bits.
|
|
|
|
@item 5
|
|
@tab @code{pauth_key}
|
|
@tab Specify which key is used for signing the return addresses in the SFrame
|
|
FDE. Two possible values: @*
|
|
SFRAME_AARCH64_PAUTH_KEY_A (0), or @*
|
|
SFRAME_AARCH64_PAUTH_KEY_B (1).
|
|
|
|
@item 4
|
|
@tab @code{fdetype}
|
|
@tab Specify the SFrame FDE type. Two possible values: @*
|
|
SFRAME_FDE_TYPE_PCMASK (1), or @*
|
|
SFRAME_FDE_TYPE_PCINC (0). @*
|
|
@xref{The SFrame FDE types}.
|
|
|
|
@item 0--3
|
|
@tab @code{fretype}
|
|
@tab Choice of three SFrame FRE types. @xref{The SFrame FRE types}.
|
|
@end multitable
|
|
|
|
@node The SFrame FDE types
|
|
@subsection The SFrame FDE types
|
|
@tindex SFRAME_FDE_TYPE_PCMASK
|
|
@tindex SFRAME_FDE_TYPE_PCINC
|
|
|
|
SFrame format defines two types of FDE entries. The choice of which SFrame FDE
|
|
type to use is made based on the instruction patterns in the relevant program
|
|
stub.
|
|
|
|
An SFrame FDE of type @code{SFRAME_FDE_TYPE_PCINC} is an indication that the PCs in the
|
|
FREs should be treated as increments in bytes. This is used fo the the bulk of
|
|
the executable code of a program, which contains instructions with no specific
|
|
pattern.
|
|
|
|
In contrast, an SFrame FDE of type @code{SFRAME_FDE_TYPE_PCMASK} is an
|
|
indication that the PCs in the FREs should be treated as masks. This type is
|
|
useful for the cases where a small pattern of instructions in a program stub is
|
|
used repeatedly for a specific functionality. Typical usecases are pltN
|
|
entries and trampolines.
|
|
|
|
@multitable {SFRAME_FDE_TYPE_PCMASK} {Value} {Unwinders perform a Unwinders perform a}
|
|
@headitem Name of SFrame FDE type @tab Value @tab Description
|
|
|
|
@item SFRAME_FDE_TYPE_PCINC
|
|
@tab 0 @tab Unwinders perform a @*
|
|
(PC >= FRE_START_ADDR) to look up a matching FRE.
|
|
|
|
@item SFRAME_FDE_TYPE_PCMASK
|
|
@tab 1 @tab Unwinders perform a @*
|
|
(PC % REP_BLOCK_SIZE @*
|
|
>= FRE_START_ADDR)
|
|
to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the
|
|
repeating block of program instructions.
|
|
|
|
@end multitable
|
|
|
|
@node The SFrame FRE types
|
|
@subsection The SFrame FRE types
|
|
|
|
A real world application can have functions of size big and small. SFrame
|
|
format defines three types of SFrame FRE entries to represent the stack trace
|
|
information for such a variety of function sizes. These representations vary
|
|
in the number of bits needed to encode the start address offset in the SFrame
|
|
FRE.
|
|
|
|
The following constants are defined and used to identify the SFrame FRE types:
|
|
|
|
@multitable {SFRAME_FRE_TYPE_ADDR1} {@code{Value}} {The start address offset of FRE is an}
|
|
@headitem Name @tab Value @tab Description
|
|
|
|
@tindex SFRAME_FRE_TYPE_ADDR1
|
|
@item @code{SFRAME_FRE_TYPE_ADDR1}
|
|
@tab 0
|
|
@tab The start address offset (in bytes) of the SFrame FRE is an unsigned
|
|
8-bit value.
|
|
|
|
@tindex SFRAME_FRE_TYPE_ADDR2
|
|
@item @code{SFRAME_FRE_TYPE_ADDR2}
|
|
@tab 1
|
|
@tab The start address offset (in bytes) of the SFrame FRE is an unsigned
|
|
16-bit value.
|
|
|
|
@tindex SFRAME_FRE_TYPE_ADDR4
|
|
@item @code{SFRAME_FRE_TYPE_ADDR4}
|
|
@tab 2
|
|
@tab The start address offset (in bytes) of the SFrame FRE is an unsigned
|
|
32-bit value.
|
|
@end multitable
|
|
|
|
A single function must use the same type of SFrame FRE throughout. An
|
|
identifier to reflect the chosen SFrame FRE type is stored in the
|
|
@xref{The SFrame FDE info word}.
|
|
|
|
@node SFrame Frame Row Entries
|
|
@section SFrame FRE
|
|
@cindex SFrame FRE
|
|
|
|
The SFrame Frame Row Entry sub-section contains the core of the stack trace
|
|
information.
|
|
|
|
An SFrame Frame Row Entry is a self-sufficient record containing SFrame stack
|
|
trace information for a range of contiguous addresses, starting at the
|
|
specified offset from the start of the function. Each SFrame Frame Row Entry
|
|
is followed by S*N bytes, where:
|
|
|
|
@itemize @minus
|
|
@item
|
|
@code{S} is the size of the stack frame offset for the FRE, and
|
|
@item
|
|
@code{N} is the number of stack frame offsets in the FRE
|
|
@end itemize
|
|
|
|
The stack offsets, following the FRE, are interpreted in order as follows:
|
|
|
|
@itemize @minus
|
|
@item
|
|
The first offset is always used to locate the CFA, by interpreting it as:
|
|
CFA = @code{BASE_REG} + offset1.
|
|
@item
|
|
If RA is being tracked, the second offset is always used to locate the RA, by
|
|
interpreting it as: RA = CFA + offset2. If RA is @emph{not} being tracked
|
|
@emph{and} FP is being tracked, the second offset will be used to locate the
|
|
FP, by interpreting it as: FP = CFA + offset2.
|
|
@item
|
|
If both RA and FP are being tracked, the third offset will be used to locate
|
|
the FP, by interpreting it as FP = CFA + offset3.
|
|
@end itemize
|
|
|
|
The entities @code{S}, @code{N} and @code{BASE_REG} are identified using the
|
|
SFrame FRE info word, a.k.a. the @code{sframe_fre_info}
|
|
@xref{The SFrame FRE info word}.
|
|
|
|
Following are the definitions of the allowed SFrame FRE:
|
|
|
|
@example
|
|
typedef struct sframe_frame_row_entry_addr1
|
|
@{
|
|
uint8_t sfre_start_address;
|
|
sframe_fre_info sfre_info;
|
|
@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr1;
|
|
@end example
|
|
|
|
@example
|
|
typedef struct sframe_frame_row_entry_addr2
|
|
@{
|
|
uint16_t sfre_start_address;
|
|
sframe_fre_info sfre_info;
|
|
@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr2;
|
|
@end example
|
|
|
|
@example
|
|
typedef struct sframe_frame_row_entry_addr4
|
|
@{
|
|
uint32_t sfre_start_address;
|
|
sframe_fre_info sfre_info;
|
|
@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr4;
|
|
@end example
|
|
|
|
For ensuring compactness, SFrame frame row entries are stored unaligned on
|
|
disk. Appropriate mechanisms need to be employed, as necessary, by the
|
|
serializing and deserializing entities, if unaligned accesses need to be
|
|
avoided.
|
|
|
|
@code{sfre_start_address} is an unsigned 8-bit/16-bit/32-bit integral field
|
|
identifies the start address of the range of program counters, for which the
|
|
SFrame FRE applies. The value encoded in the @code{sfre_start_address} field
|
|
is the offset in bytes of the start address of the SFrame FRE, from the start
|
|
address of the function.
|
|
|
|
Further FRE types may be added in future.
|
|
|
|
@menu
|
|
* The SFrame FRE info word::
|
|
@end menu
|
|
|
|
@cindex The SFrame FRE info word
|
|
@node The SFrame FRE info word
|
|
@subsection The SFrame FRE info word
|
|
|
|
The SFrame FRE info word is a bitfield split into four parts. From MSB to LSB:
|
|
|
|
@multitable {Bit offset} {@code{fre_cfa_base_reg_id}} {Size of stack offsets in bytes. Valid values}
|
|
@headitem Bit offset @tab Name @tab Description
|
|
@item 7
|
|
@tab @code{fre_mangled_ra_p}
|
|
@tab Indicate whether the return address is mangled with any authorization bits (signed RA).
|
|
|
|
@item 5-6
|
|
@tab @code{fre_offset_size}
|
|
@tab Size of stack offsets in bytes. Valid values are: @*
|
|
SFRAME_FRE_OFFSET_1B, @*
|
|
SFRAME_FRE_OFFSET_2B, and @*
|
|
SFRAME_FRE_OFFSET_4B.
|
|
|
|
@item 1-4
|
|
@tab @code{fre_offset_count}
|
|
@tab A value of upto 3 is allowed to track all three of CFA, FP and RA.
|
|
|
|
@item 0
|
|
@tab @code{fre_cfa_base_reg_id}
|
|
@tab Distinguish between SP or FP based CFA recovery.
|
|
|
|
@end multitable
|
|
|
|
@multitable {SFRAME_FRE_OFFSET_4B} {@code{Value}} {All stack offsets following the fixed-length}
|
|
@headitem Name @tab Value @tab Description
|
|
|
|
@tindex SFRAME_FRE_OFFSET_1B
|
|
@item @code{SFRAME_FRE_OFFSET_1B}
|
|
@tab 0
|
|
@tab All stack offsets following the fixed-length FRE structure are 1 byte
|
|
long.
|
|
|
|
@tindex SFRAME_FRE_OFFSET_2B
|
|
@item @code{SFRAME_FRE_OFFSET_2B}
|
|
@tab 1
|
|
@tab All stack offsets following the fixed-length FRE structure are 2 bytes
|
|
long.
|
|
|
|
@tindex SFRAME_FRE_OFFSET_4B
|
|
@item @code{SFRAME_FRE_OFFSET_4B}
|
|
@tab 2
|
|
@tab All stack offsets following the fixed-length FRE structure are 4 bytes
|
|
long.
|
|
|
|
@end multitable
|
|
|
|
@node Index
|
|
@unnumbered Index
|
|
|
|
@syncodeindex tp cp
|
|
@printindex cp
|
|
|
|
@bye
|