/* SFrame format description.
- Copyright (C) 2022 Free Software Foundation, Inc.
+ Copyright (C) 2022-2024 Free Software Foundation, Inc.
This file is part of libsframe.
/* SFrame format.
SFrame format is a simple format to represent the information needed
- for vanilla virtual stack unwinding. SFrame format keeps track of the
- minimal necessary information needed for stack unwinding:
+ for generating vanilla backtraces. SFrame format keeps track of the
+ minimal necessary information needed for stack tracing:
- Canonical Frame Address (CFA)
- Frame Pointer (FP)
- Return Address (RA)
.text.* sections in the resulting binary artifact. Each Function
Descriptor Entry specifies the start PC of a function, the size in bytes
of the function and an offset to its first Frame Row Entry (FRE). Each FDE
- additionally also specifies the type of FRE it uses to encode the unwind
- information.
+ additionally also specifies the type of FRE it uses to encode the stack
+ trace information.
- Next, the Frame Row Entry section is a list of variable size records,
- each of which represent SFrame unwind information for a set of PCs. A
- singular Frame Row Entry is a self-sufficient record with information on
- how to virtually unwind the stack for the applicable set of PCs.
+ Next, the SFrame Frame Row Entry sub-section is a list of variable size
+ records. Each entry represents stack trace information for a set of PCs
+ of the function. A singular Frame Row Entry is a self-sufficient record
+ which contains information on how to generate stack trace from the
+ applicable set of PCs.
*/
/* SFrame format versions. */
#define SFRAME_VERSION_1 1
+#define SFRAME_VERSION_2 2
/* SFrame magic number. */
#define SFRAME_MAGIC 0xdee2
/* Current version of SFrame format. */
-#define SFRAME_VERSION SFRAME_VERSION_1
+#define SFRAME_VERSION SFRAME_VERSION_2
/* Various flags for SFrame. */
/* Function Descriptor Entries are sorted on PC. */
#define SFRAME_F_FDE_SORTED 0x1
-/* Frame-pointer based unwinding. */
+/* Functions preserve frame pointer. */
#define SFRAME_F_FRAME_POINTER 0x2
#define SFRAME_CFA_FIXED_FP_INVALID 0
/* Unwinders perform a (PC >= FRE_START_ADDR) to look up a matching FRE. */
#define SFRAME_FDE_TYPE_PCINC 0
-/* Unwinders perform a (PC & FRE_START_ADDR_AS_MASK >= FRE_START_ADDR_AS_MASK)
- to look up a matching FRE. */
+/* Unwinders perform a (PC % REP_BLOCK_SIZE >= FRE_START_ADDR) to look up a
+ matching FRE. */
#define SFRAME_FDE_TYPE_PCMASK 1
typedef struct sframe_preamble
not fixed, it is set to SFRAME_CFA_FIXED_RA_INVALID, and individual
FREs provide the applicable stack frame offset, if any. */
int8_t sfh_cfa_fixed_ra_offset;
- /* Number of bytes making up the auxilliary header, if any.
+ /* Number of bytes making up the auxiliary header, if any.
Some ABI/arch, in the future, may use this space for extending the
- information in SFrame header. Auxilliary header is contained in
+ information in SFrame header. Auxiliary header is contained in
bytes sequentially following the sframe_header. */
uint8_t sfh_auxhdr_len;
/* Number of SFrame FDEs in this SFrame section. */
uint32_t sfde_func_start_fre_off;
/* Number of frame row entries for the function. */
uint32_t sfde_func_num_fres;
- /* Additional information for deciphering the unwind information for the
- function.
+ /* Additional information for stack tracing from the function:
- 4-bits: Identify the FRE type used for the function.
- 1-bit: Identify the FDE type of the function - mask or inc.
- 1-bit: PAC authorization A/B key (aarch64).
------------------------------------------------------------------------
8 6 5 4 0 */
uint8_t sfde_func_info;
+ /* Size of the block of repeating insns. Used for SFrame FDEs of type
+ SFRAME_FDE_TYPE_PCMASK. */
+ uint8_t sfde_func_rep_size;
+ uint16_t sfde_func_padding2;
} ATTRIBUTE_PACKED sframe_func_desc_entry;
/* Macros to compose and decompose function info in FDE. */
Used for both AMD64 and AARCH64.
- An SFrame Frame Row Entry is a self-sufficient record containing SFrame
- unwind info for a range of addresses, starting at the specified offset in
- the function. Each SFrame Frame Row Entry is followed by S*N bytes, where:
+ An SFrame Frame Row Entry is a self-sufficient record which contains
+ information on how to generate the stack trace for the specified range of
+ PCs. Each SFrame Frame Row Entry is followed by S*N bytes, where:
S is the size of the stack frame offset for the FRE, and
N is the number of stack frame offsets in the FRE
/* Upper limit of start address in sframe_frame_row_entry_addr1
is 0x100 (not inclusive). */
-#define SFRAME_FRE_TYPE_ADDR1_LIMIT ((SFRAME_FRE_TYPE_ADDR1 + 1) * 8)
+#define SFRAME_FRE_TYPE_ADDR1_LIMIT \
+ (1ULL << ((SFRAME_FRE_TYPE_ADDR1 + 1) * 8))
/* Used when SFRAME_FRE_TYPE_ADDR2 is specified as FRE type. */
typedef struct sframe_frame_row_entry_addr2
/* Upper limit of start address in sframe_frame_row_entry_addr2
is 0x10000 (not inclusive). */
-#define SFRAME_FRE_TYPE_ADDR2_LIMIT ((SFRAME_FRE_TYPE_ADDR2 * 2) * 8)
+#define SFRAME_FRE_TYPE_ADDR2_LIMIT \
+ (1ULL << ((SFRAME_FRE_TYPE_ADDR2 * 2) * 8))
/* Used when SFRAME_FRE_TYPE_ADDR4 is specified as FRE type. */
typedef struct sframe_frame_row_entry_addr4
/* Upper limit of start address in sframe_frame_row_entry_addr2
is 0x100000000 (not inclusive). */
-#define SFRAME_FRE_TYPE_ADDR4_LIMIT ((SFRAME_FRE_TYPE_ADDR4 * 2) * 8)
+#define SFRAME_FRE_TYPE_ADDR4_LIMIT \
+ (1ULL << ((SFRAME_FRE_TYPE_ADDR4 * 2) * 8))
#ifdef __cplusplus
}