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

On Thu, Jun 4, 2026 at 10:04=E2=80=AFAM Andrei Vagin <[email protected]> wr=
ote:
>
> 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 <[email protected]>
> ---
>  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/x=
state.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 stat=
e
> -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 r=
estore
> +a process on a different host than where it was checkpointed. A signal f=
rame
> +created on a machine with fewer CPU features can be successfully restore=
d 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 th=
e same
> +xstate features in the xsave area, making frames incompatible between th=
em.
> diff --git a/arch/x86/include/uapi/asm/sigcontext.h b/arch/x86/include/ua=
pi/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.  Thi=
s 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 ma=
chine
> + * with a different (larger) set of features, as long as the latter supp=
orts
> + * all features present in the frame. Note that this portability is gene=
rally
> + * limited to CPUs of the same vendor, as different vendors may use diff=
erent
> + * xstate layouts.
> + *
>   * This extended area typically grows with newer CPUs that have larger a=
nd
>   * larger XSAVE areas.
>   */
> --
> 2.54.0.1032.g2f8565e1d1-goog
>
>