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

[Borislav Petkov]

On Mon, Aug 17, 2026 at 04:20:41AM +0000, Andrei Vagin wrote:
> 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/.

I think this sentence is enough to be your commit message if you're going to
repeat the same text from documentation here too.

> 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 <alexander@xxxxxxxxxxxxx>
> Signed-off-by: Andrei Vagin <avagin@xxxxxxxxxx>
> ---
>  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).

Definitely split into paragraphs as Chang suggests and perhaps that text is
better located in the xstate.rst doc too with a reference to it from here
because it would be more accessible there and it reads more like
a documentation text than code comment...

Thx.

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette