Imagelibrary/binutils-gdb
1
0
Fork 1
mirror of https://github.com/bminor/binutils-gdb.git synced 2026-02-04 05:21:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

[WIP][RFC] sframe: doc: Spec terminology change from offset to data item

Browse Source 
This patch applies on top of the upstream branch
users/ibhagat/sframe-v3-jan14-v4.

I attempted to see what the terminology change would look like.  This
patch is my first shabby attempt.

Whats not attempted, but needs to be covered:
  - (#1) The spec defines "fre_offset_count" and "fre_offset_size"
  - (#2) There are other constants:
    SFRAME_FRE_OFFSET_1B, SFRAME_FRE_OFFSET_2B, SFRAME_FRE_OFFSET_4B.
    Changing these constants is a search-replace patch touching gas/ and
    ld/ and libsframe/, not attempted either.
  - (#3) Control/Register Word, Displacement Word does not seem to fit
    very well: The "Control/Register Word" contains the register data,
    so I kept the name as such, and not "Control Word"

What do you think ?  I do not prefer to do this last minute change
anymore; there could be more renames needed in code once we start from
(#2) above. (#1) could be addressed by renaming those to
"fre_dataitem_count", and "fre_dataitem_size", but I find the latter
even more awkward.  More misfit like feeling arises with (#3).

That said, I will reconsider if your judgement is different.  Please let
me know what you think.
This commit is contained in:
Indu Bhagat
2026-01-14 14:38:33 -08:00
parent 172e293d5a
commit 548332a43f
1 changed files with 33 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
libsframe/doc/sframe-spec.texi
View File

@@ -780,8 +780,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 bytes 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 +792,18 @@ 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 Displacements, allowing for complex recovery rules (e.g., DRAP on AMD64,
Stack Realignment). More details in @ref{Flexible FDE Type Interpretation}.
The variable-length bytes trailing each SFrame FRE are interpreted as pairs
of Control Word and Data Word, allowing for complex recovery rules (e.g.,
DRAP on AMD64, Stack 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
arch-specific FDE types. Each distinct FDE type may define a different layout,
encoding, and interpretation of the SFrame FRE offsets.
Currently, five bits are reserved in the @code{sfda_func_info2} for
indicating SFrame FDE types. In future, other ABIs/architectures may add
even arch-specific FDE types. Each distinct FDE type may define a different
layout, encoding, and interpretation of the variable-length bytes trailing
each SFrame FRE.
@node The SFrame FRE Types
@@ -852,15 +855,16 @@ 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 item in the variable-length bytes trailing
the SFrame FRE, and
@item
@code{N} is the number of stack offsets in the FRE
@code{N} is the number of data items in the respective FRE.
@end itemize
The entities @code{S}, @code{N} are encoded in the SFrame FRE info byte, via
@@ -869,10 +873,10 @@ 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.
It is important to underline here that although the canonical interpretation of
these bytes 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 stack
offsets at the tail end of each SFrame FRE. To keep the SFrame file
@@ -1155,23 +1159,23 @@ 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.
carries a pair of data items to specify the respective recovery rule.
@enumerate
@item
Offset 1 (Control/Register Data): Encodes the base register number, a
Data item 1 (Control/Register Data): Encodes the base register number, a
dereference flag, and a register-mode flag.
@item
Offset 2 (Displacement Data): Encodes the signed offset to be added to the base.
Data item 2 (Displacement 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).
Each pair of data items appears in the order: CFA, RA, FP. These data items
obey the @code{fre_offset_size} defined in the FRE info byte (i.e., they are 1,
2, or 4 bytes wide).
@subsubheading Encoding of Offset 1 (Control/Register Data)
@subsubheading Encoding of Data 1 (Control/Register Data)
The first offset of the pair is an unsigned integer of width
The first data item of the pair is an unsigned integer of width
@code{fre_offset_size}. It is used as a bitfield that describes
register/control data for the tracked entity. From LSB to MSB:
@@ -1198,15 +1202,15 @@ If 0, the value is @code{Base + Offset}.
@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
data item 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.
@subsubheading Encoding of Offset 2 (Displacement Data)
@subsubheading Encoding of Data 2 (Displacement Data)
The second offset of the pair is a signed integer of width
The second data item of the pair is a signed integer of width
@code{fre_offset_size}. It is used as a stack offset for the respective
tracked entity (CFA, FP or RA).
@@ -1384,9 +1388,9 @@ interpreting the Control Data and Displacement 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 item 1)
containing reg_p, deref_p, regnum.
// offset: The Displacement (Offset 2).
// offset: The Displacement (Data item 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.