[11/12] doc: sframe: add details about alignment in the SFrame format
Checks
Commit Message
A portion of the SFrame stack trace format has an unaligned on-disk
representation. Add description at relevant points in the specification
to clarify the alignment related details.
---
libsframe/doc/sframe-spec.texi | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
@@ -77,6 +77,11 @@ 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
@@ -147,6 +152,8 @@ typedef struct sframe_preamble
@} 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:
@@ -258,6 +265,8 @@ typedef struct sframe_header
@} 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
@@ -384,6 +393,8 @@ typedef struct sframe_func_desc_entry
@} 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
@@ -608,6 +619,11 @@ typedef struct sframe_frame_row_entry_addr4
@} 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