[PATCH 1/8] x86/fpu: Document signal frame portability

The x86 signal frame is designed to be self-describing, with the
'xstate_size' field in the software-reserved bytes indicating the actual
size of the context. This design is required for portability, allowing a
signal frame created on a system with a specific set of xstate features
to be restored on a machine with a different (larger) set of features.

Document this contract in the uapi headers and Documentation/. This
requirement is critical for checkpoint/restore tools like CRIU, which
should be able to migrate processes across machines with heterogeneous
FPU capabilities.

Note that portability is constrained by the architectural XSAVE layout
(component offsets and sizes); the destination machine must share
matching component layouts for all features present in the frame. While
layouts are consistent across CPUs from the same vendor for active
features, differences can occur across vendors or if the XSAVE space of
a deprecated feature (e.g. MPX) is repurposed for a newer feature
(e.g. APX).

Reviewed-by: Alexander Mikhalitsyn <[email protected]>
Signed-off-by: Andrei Vagin <[email protected]>
---
 Documentation/arch/x86/xstate.rst      | 16 ++++++++++++++++
 arch/x86/include/uapi/asm/sigcontext.h | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/Documentation/arch/x86/xstate.rst b/Documentation/arch/x86/xstate.rst
index cec05ac464c1..0b4d541ab6f8 100644
--- a/Documentation/arch/x86/xstate.rst
+++ b/Documentation/arch/x86/xstate.rst
@@ -172,3 +172,19 @@ are extended to control the guest permission:
 
 Note that some VMMs may have already established a set of supported state
 components. These options are not presumed to support any particular VMM.
+
+Signal Frame Portability
+------------------------
+
+The signal frame is designed to be self-describing and portable. This is
+especially important for checkpoint/restore tools like CRIU, which may restore
+a process on a different host than where it was checkpointed. A signal frame
+created on a machine with fewer CPU features can be successfully restored on a
+machine with more CPU features.
+
+Note that signal frame portability is constrained by the architectural XSAVE
+layout. Restoration is supported only if the destination host supports all
+features present in the frame and uses matching component offsets and sizes for
+them. While layout compatibility is generally maintained across CPUs from the
+same vendor, differences can occur across vendors or if the XSAVE space of a
+deprecated feature (e.g. MPX) is repurposed for a newer feature (e.g. APX).
diff --git a/arch/x86/include/uapi/asm/sigcontext.h b/arch/x86/include/uapi/asm/sigcontext.h
index d0d9b331d3a1..c01f55f1fc12 100644
--- a/arch/x86/include/uapi/asm/sigcontext.h
+++ b/arch/x86/include/uapi/asm/sigcontext.h
@@ -34,6 +34,23 @@
  * fpstate+extended_size-FP_XSTATE_MAGIC2_SIZE address) is set to
  * FP_XSTATE_MAGIC2 so that you can sanity check your size calculations.)
  *
+ * The xstate_size field indicates the actual size of the xstate context
+ * (including the 512-byte FXSAVE area and the 64-byte XSAVE header
+ * struct _header). This size is used in conjunction with the pointer to
+ * the xstate context to locate FP_XSTATE_MAGIC2. Note that in 32-bit signal
+ * frames (including 32-bit compat tasks on 64-bit kernels), the fpstate
+ * pointer points to a legacy 112-byte FPU environment (struct _fpstate_32)
+ * that precedes the xstate context, so the xstate context starts at
+ * fpstate + 112. This makes the signal frame self-describing and portable:
+ * a signal frame created on a machine with a certain set of xstate features
+ * can be restored on a machine with a different (larger) set of features,
+ * as long as the destination supports all features present in the frame
+ * and shares matching XSAVE component offsets and sizes for those features.
+ * Note that portability is constrained by the architectural XSAVE layout
+ * and is not guaranteed across different vendors or if space from
+ * deprecated features (e.g. MPX) is repurposed for newer features
+ * (e.g. APX).
+ *
  * This extended area typically grows with newer CPUs that have larger and
  * larger XSAVE areas.
  */
-- 
2.55.0.691.gc56d675ccc-goog