[PATCH 1/5] sframe: doc: terminology change from offset to data word
Jens Remus
jremus@linux.ibm.com
Thu Jan 22 10:26:33 GMT 2026
On 1/20/2026 11:28 AM, Indu Bhagat wrote:
> ChangeLog:
> * libsframe/doc/sframe-spec.texi
> ---
> libsframe/doc/sframe-spec.texi | 140 ++++++++++++++++++---------------
> 1 file changed, 78 insertions(+), 62 deletions(-)
> diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi
> index 4448ad3b9b8..27cff9eda61 100644
> --- a/libsframe/doc/sframe-spec.texi
> +++ b/libsframe/doc/sframe-spec.texi
> @@ -129,6 +129,10 @@ Terminology improvements and renames for readability
> Type (i.e., @code{SFRAME_FDE_PCTYPE_MASK}, @code{SFRAME_FDE_PCTYPE_INC}).
> @item Instead of using the term `info word', use a more precise term `info
> byte' in specification for the info bytes in SFrame FDE and SFrame FRE.
> + @item Use term `data word' instead of `offset' to convey the functional role
> + of the variable-length array of bytes trailing the SFrame FRE header. With the
> + introduction of flexible FDE type, the interpretation of those bytes is not
> + always as an offset.
> @end itemize
> @item
> Reorganize the SFrame function descriptor entry into two distinct structures:
> @@ -780,8 +784,9 @@ signed offset. Return Address (RA) and Frame Pointer (FP) are recovered using
> the CFA plus a signed offset (or a fixed register for specific
> architectures like s390x).
>
> -The variable-length stack offsets are interpreted according to the ABI/arch-specific
> -rules for the target architecture. More details in @ref{Default FDE Type Interpretation}.
> +The variable-length data words trailing each SFrame FRE are interpreted
> +according to the ABI/arch-specific rules for the target architecture. More
> +details in @ref{Default FDE Type Interpretation}.
>
> @tindex SFRAME_FDE_TYPE_FLEX
> @item @code{SFRAME_FDE_TYPE_FLEX}
> @@ -791,16 +796,17 @@ Used for complex cases such as stack realignment (DRAP), non-standard CFA base
> registers, or when RA/FP recovery requires dereferencing or non-CFA base
> registers.
>
> -The variable-length stack offsets are interpreted as pairs of Control Data
> -and Offset Data, allowing for complex recovery rules (e.g., DRAP on AMD64,
> -Stack Realignment). More details in @ref{Flexible FDE Type Interpretation}.
> +The variable-length data words are interpreted as pairs of Control Data and
> +Offset Data, allowing for complex recovery rules (e.g., DRAP on AMD64, Stack
I preferred "Control/Register Data", although it is longer. But both is fine.
> +Realignment). More details in @ref{Flexible FDE Type Interpretation}.
> @end multitable
>
> @cindex Provisions for future ABIs
> -Currently, five bits are reserved in the @code{sfda_func_info2} for indicating
> -SFrame FDE types. In future, other ABIs/architectures may add even
> +Currently, five bits are reserved in the @code{sfda_func_info2} for
> +indicating SFrame FDE types. In future, other ABIs/architectures may add even
Nit: Random re-wrap?
> arch-specific FDE types. Each distinct FDE type may define a different layout,
> -encoding, and interpretation of the SFrame FRE offsets.
> +encoding, and interpretation of the variable-length data words trailing each
> +SFrame FRE.
>
>
> @node The SFrame FRE Types
> @@ -852,35 +858,37 @@ containing SFrame stack trace information for a range of contiguous
> (instruction) addresses, starting at the specified offset from the start of the
> function.
>
> -Each SFrame FRE encodes the stack offsets to recover the CFA, FP and RA (as
> +Each SFrame FRE encodes the information to recover the CFA, FP and RA (as
> specified by the ABI or the FDE type) for the respective instruction addresses.
> To encode this information, each SFrame FRE is followed by S*N bytes, where:
>
> @itemize @minus
> @item
> -@code{S} is the size of a stack offset for the FRE, and
> +@code{S} is the size of each data word in the variable-length array of data
> +words trailing the SFrame FRE, and
> @item
> -@code{N} is the number of stack offsets in the FRE
> +@code{N} is the number of data words trailing the SFrame FRE.
> @end itemize
>
> +@strong{N.B.:} The use of keyword "word" in "data word" in this document is
> +colloquial. It does not mean machine word or a datatype with a specific width.
> +
> The entities @code{S}, @code{N} are encoded in the SFrame FRE info byte, via
> -the @code{fre_offset_size} and the @code{fre_offset_count} respectively. More
> -information about the precise encoding and range of values for @code{S} and
> -@code{N} is provided later in the @ref{The SFrame FRE Info Word}.
> +the @code{fre_dataword_width} and the @code{fre_dataword_count} respectively.
s/@code{fre_dataword_width}/@code{fre_dataword_size}/
> +More information about the precise encoding and range of values for @code{S}
> +and @code{N} is provided later in the @ref{The SFrame FRE Info Word}.
>
> @cindex Provisions for future ABIs
> -It is important to underline here that although the canonical interpretation
> -of these bytes is as stack offsets (to recover CFA, FP and RA), these bytes
> -@emph{may} be used by future ABIs/architectures to convey other information on
> -a per SFrame FRE basis.
> -
> -In summary, SFrame file format, by design, supports a variable number of stack
> -offsets at the tail end of each SFrame FRE. To keep the SFrame file
> -format specification flexible yet extensible, the interpretation of the stack
> -offsets is ABI/arch-specific. The precise interpretation of the FRE stack
> -offsets in the currently supported ABIs/architectures is covered in the
> -ABI/arch-specific definition of the SFrame file format,
> -@xref{Interpretation of SFrame FREs}.
> +It is important to underline here that although the canonical interpretation of
> +these data words is as stack offsets (to recover CFA, FP and RA) for default
> +FDE type, these bytes @emph{may} be used by future ABIs/architectures to convey
> +other information on a per SFrame FRE basis.
> +
> +In summary, SFrame file format, by design, supports a variable number of bytes
> +at the tail end of each SFrame FRE. To keep the SFrame file format
> +specification flexible yet extensible, the interpretation of these bytes is
> +specific to ABI/arch or FDE type. The precise interpretation of these FRE
> +varlen bytes is covered in the section @ref{Interpretation of SFrame FREs}.
Better use "variable number of bytes" instead of "FRE varlen bytes".
>
> Next, the definitions of the three SFrame FRE types are as follows:
>
> @@ -931,21 +939,21 @@ Further SFrame FRE types may be added in future.
>
> The SFrame FRE info byte 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 are valid}
> +@multitable {Bit offset} {@code{fre_cfa_base_reg_id}} {Size of data words in bytes. Valid values are valid}
Unrelated to this patch: "Valid values are valid" seems logical.
> @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: @*
> +@tab @code{fre_dataword_size}
> +@tab Size of data word in bytes. Valid values are: @*
> @code{SFRAME_FRE_OFFSET_1B}, @*
> @code{SFRAME_FRE_OFFSET_2B}, and @*
> @code{SFRAME_FRE_OFFSET_4B}.
>
> @item 1-4
> -@tab @code{fre_offset_count}
> +@tab @code{fre_dataword_count}
> @tab Being a 4-bit sized field, a max value of 15 is allowed. Typically, a
> value of up to 3 is sufficient for most ABIs to track all three of CFA, FP and
> RA. A value of zero indicates that the return address (RA) is undefined. A
> @@ -964,19 +972,19 @@ reached and the stack trace is complete.
> @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
> +@tab All data words 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
> +@tab All data words 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
> +@tab All data words following the fixed-length FRE structure are 4 bytes
> long.
>
> @end multitable
> @@ -1001,7 +1009,7 @@ used to represent stack tracing information for the function.
>
> If the FDE type is @code{SFRAME_FDE_TYPE_DEFAULT}, the interpretation of the
> FRE bytes is ABI/arch-specific. Typically, these bytes are interpreted as a
> -sequence of stack offsets.
> +sequence of (signed integer) stack offsets.
>
> The following sections describe the specific interpretation rules for currently
> supported architectures.
> @@ -1154,25 +1162,33 @@ transiently saved in a general-purpose register and/or requires a dereference
> rule.
> @end itemize
>
> -In a flexible FDE type, for each tracked entity (CFA, RA, FP), the SFrame FRE
> -carries a pair of offsets to specify the respective recovery rule.
> +For flexible FDE types, the variable-length bytes trailing an SFrame FRE can be
> +interpreted as one of the following:
>
> @enumerate
> -@item
> -Offset 1 (Control/Register Data): Encodes the base register number, a
> -dereference flag, and a register-mode flag.
> -@item
> -Offset 2 (Offset Data): Encodes the signed offset to be added to the base.
> +@item Control Data: Encodes the base register number, a dereference flag, and a
> +register-mode flag. A value of 0 is reserved as the @emph{padding data word}.
> +@item Offset Data: Encodes the signed offset to be added to the base.
> @end enumerate
>
> -The offsets appear in the order: CFA, RA, FP. These offsets obey the
> -@code{fre_offset_size} defined in the FRE info byte (i.e., they are 1, 2, or 4
> -bytes wide).
> +For each tracked entity (CFA, RA, FP), the SFrame FRE carries a pair of data
> +words to specify the respective recovery rule. The pair of data words appear
> +in the order: CFA, RA, FP. These data words obey the @code{fre_dataword_size}
> +defined in the FRE info byte (i.e., they are 1, 2, or 4 bytes wide).
> +
> +Given the nature of things, since CFA is always tracked, the first two data
> +words pertain to CFA recovery. If RA recovery rule is unspecified (because the
> +RA can be recovered from its default location), a padding data word is used
> +instead of the Control Word if FP recovery rule is to be specified using the
> +subsequent data words.
Maybe: "a single padding data word is used instead of the pair of Control Data
and Offset Data"?
> +
> +Following is the order of information for specifying the recovery rule for a
> +tracked entity in a flexible FDE.
>
> -@subsubheading Encoding of Offset 1 (Control/Register Data)
> +@subsubheading Encoding of Data Word 1 (Control Data)
>
> -The first offset of the pair is an unsigned integer of width
> -@code{fre_offset_size}. It is used as a bitfield that describes
> +The first data word of the pair is an unsigned integer of size
> +@code{fre_dataword_size}. It is used as a bitfield that describes
> register/control data for the tracked entity. From LSB to MSB:
>
> @multitable {Bit Offset} {@code{deref_p}} {If 1, the base is a DWARF register (encoded in bits 3+}
> @@ -1197,17 +1213,17 @@ If 0, the value is @code{Base + Offset}.
> @code{reg_p} is 1.
> @end multitable
>
> -A value of 0 in the Control/Register Data is used to indicate that no further
> -offset data follows for the tracked entity. Using the value of 0 in
> -Control/Register Data (i.e., regnum = 0, deref_p = 0, reg_p = 0) to designate
> -invalid tracking info does mean that currently, e.g., for RA, the rule RA = CFA
> -+ 0 cannot be encoded. NB: RA = CFA + 0 is distinct from RA = *(CFA + 0). The
> -former should not be needed for any ABI, and the latter is representable.
> +A value of 0 in the Control Data is used to indicate that no further data words
> +follow for the tracked entity. Using the value of 0 in Control/Register Data
s|Control/Register Data|Control Data| if you stay with "Control Data".
> +(i.e., regnum = 0, deref_p = 0, reg_p = 0) to designate invalid tracking info
I am confused by "to designate invalid tracking info". Invalid reads
as if it would be an explicit error indication. Maybe "unavailable
tracking info"?
Maybe explain that in case of unavailable FP/RA tracking info the
fixed FP/RA tracking info is to be used? If that is "INVALID" (bad
naming choice btw.) the FP/RA value is preserved from one to the
other frame.
> +does mean that currently, e.g., for RA, the rule RA = CFA + 0 cannot be
> +encoded. NB: RA = CFA + 0 is distinct from RA = *(CFA + 0). The former should
> +not be needed for any ABI, and the latter is representable.
>
> -@subsubheading Encoding of Offset 2 (Offset Data)
> +@subsubheading Encoding of Data Word 2 (Offset Data)
>
> -The second offset of the pair is a signed integer of width
> -@code{fre_offset_size}. It is used as a stack offset for the respective
> +The second data word of the pair is a signed integer of width
> +@code{fre_dataword_size}. It is used as a stack offset for the respective
s/stack offset/offset/ as it does not necessarily represent a stack
offset?
> tracked entity (CFA, FP or RA).
>
> @subsubheading Recovery Rules
> @@ -1297,7 +1313,7 @@ object and returns the error code, if any.
>
> In the following pseudocode for @code{get_next_frame}, the @code{sframe_*}
> functions fetch information from the SFrame section. Note that the stack tracer
> -must retrieve the FDE type to decide how to interpret the FRE offsets.
> +must retrieve the FDE type to decide how to interpret the FRE data words.
>
> @example
> fre = sframe_find_fre (pc, &fde_type);
> @@ -1328,8 +1344,8 @@ must retrieve the FDE type to decide how to interpret the FRE offsets.
> next_frame->fp = fp;
> @end example
>
> -For SFrame FDE of type @code{SFRAME_FDE_TYPE_FLEX}, read the set of offsets and
> -apply the recovery rules accordingly.
> +For SFrame FDE of type @code{SFRAME_FDE_TYPE_FLEX}, read the set of data words
> +and apply the recovery rules accordingly.
>
> @example
> if (fre && fde_type == SFRAME_FDE_TYPE_FLEX)
> @@ -1339,7 +1355,7 @@ apply the recovery rules accordingly.
> cfa_offset = sframe_fre_get_offset (fre, 1);
>
> // Get the RA reg, offset, and deref_p.
> - // The third FRE offset (index 2) is the RA Control Data.
> + // The third FRE data word (index 2) is the RA Control Data.
> ra_reg_data = sframe_fre_get_udata (fre, 2);
> if (ra_reg_data != SFRAME_FRE_RA_OFFSET_INVALID)
> ra_offset = sframe_fre_get_offset (fre, 3);
> @@ -1384,9 +1400,9 @@ interpreting the Control Data and Offset Data pair for flexible FDEs:
>
> @example
> // Apply SFrame V3 Flex FDE recovery rule.
> - // reg_data: The Control Data (Offset 1)
> + // reg_data: The Control Data (Data word 1)
> containing reg_p, deref_p, regnum.
> - // offset: The Displacement (Offset 2).
> + // offset: The Offset (Data word 2).
> // cfa: The current CFA value (used as base if reg_p is 0).
> // cfa_p: Bool indicating if we are currently recovering the
> CFA itself.
Regards,
Jens
--
Jens Remus
Linux on Z Development (D3303)
jremus@de.ibm.com / jremus@linux.ibm.com
IBM Deutschland Research & Development GmbH; Vorsitzender des Aufsichtsrats: Wolfgang Wendt; Geschäftsführung: David Faller; Sitz der Gesellschaft: Ehningen; Registergericht: Amtsgericht Stuttgart, HRB 243294
IBM Data Privacy Statement: https://www.ibm.com/privacy/
More information about the Binutils
mailing list