[PATCH 11/12] doc: sframe: add details about alignment in the SFrame format

[Indu Bhagat <indu.bhagat@oracle.com>]

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(+)

diff --git a/libsframe/doc/sframe-spec.texi b/libsframe/doc/sframe-spec.texi
index 68f465e2aa7..8a59aa76f52 100644
--- a/libsframe/doc/sframe-spec.texi
+++ b/libsframe/doc/sframe-spec.texi
@@ -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
-- 
2.39.2