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

[Andrei Vagin]

On Thu, Jun 4, 2026 at 10:04 AM Andrei Vagin <avagin@xxxxxxxxxx> 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 uabi 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 generally limited to CPUs
> from the same vendor (e.g., Intel vs. AMD) due to potential differences
> in xstate layouts.
>
> Signed-off-by: Andrei Vagin <avagin@xxxxxxxxxx>
> ---
>  Documentation/arch/x86/xstate.rst      | 14 ++++++++++++--
>  arch/x86/include/uapi/asm/sigcontext.h | 10 ++++++++++
>  2 files changed, 22 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/arch/x86/xstate.rst b/Documentation/arch/x86/xstate.rst
> index cec05ac464c1..e27e779bae44 100644
> --- a/Documentation/arch/x86/xstate.rst
> +++ b/Documentation/arch/x86/xstate.rst
> @@ -170,5 +170,15 @@ are extended to control the guest permission:
>   is going to be rejected. So, the permission has to be requested before the
>   first VCPU creation.
>
> -Note that some VMMs may have already established a set of supported state
> -components. These options are not presumed to support any particular VMM.

My bad, I accidentally deleted those lines. Please ignore that and review
the other changes.

>
> +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 generally guaranteed only between CPUs
> +from the same vendor. Different vendors may use different offsets for the same
> +xstate features in the xsave area, making frames incompatible between them.
> diff --git a/arch/x86/include/uapi/asm/sigcontext.h b/arch/x86/include/uapi/asm/sigcontext.h
> index d0d9b331d3a1..3ea63c29c3d7 100644
> --- a/arch/x86/include/uapi/asm/sigcontext.h
> +++ b/arch/x86/include/uapi/asm/sigcontext.h
> @@ -34,6 +34,16 @@
>   * 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 fxregs_state and xstate_header). This size is used in
> + * conjunction with the fpstate pointer to locate FP_XSTATE_MAGIC2.  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 latter supports
> + * all features present in the frame. Note that this portability is generally
> + * limited to CPUs of the same vendor, as different vendors may use different
> + * xstate layouts.
> + *
>   * This extended area typically grows with newer CPUs that have larger and
>   * larger XSAVE areas.
>   */
> --
> 2.54.0.1032.g2f8565e1d1-goog
>
>