| \input texinfo @c -*- Texinfo -*- | |
| @setfilename sframe-spec.info | |
| @settitle The SFrame Format | |
| @copying | |
| Copyright @copyright{} 2021-2023 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 |