[PATCH] Documentation: KVM: Document guest-visible compatibility expectations

[Paolo Bonzini]

On 5/11/26 10:57, David Woodhouse wrote:
> From: David Woodhouse <dwmw at amazon.co.uk>
> 
> Document the expectation that KVM maintains guest-visible compatibility
> across host kernel upgrades and rollbacks.  Specifically:
> 
>   - State saved/restored via KVM ioctls must be sufficient for live
>     migration (and live update) between kernel versions.
> 
>   - Where a new kernel introduces a guest-visible change, it provides a
>     mechanism for userspace to select the previous behaviour.
> 
>   - This allows both forward migration (upgrade) and backward migration
>     (rollback) of guests.
> 
> These expectations have been implicitly required on x86 but were not
> explicitly documented. Harmonise the expectations across all of KVM.

One big part of achieving this on x86 is the handling of CPUID.  Despite 
all the mess that KVM_SET_CPUID2 is (and sometimes the underlying 
architecture too, as Jim Mattson would certainly agree), KVM is 
generally able to provide a consistent view of its configuration to the 
guest.  This doesn't quite extend to compatibility across vendors, but 
it does work across processor generations from either Intel or AMD.

I understand that Arm traditionally had much more trouble than x86 with 
vendor-specified behavior that goes beyond the set of architectural 
features, so we may need to tune the expectations.  However, I agree 
with David that this is needed at least as long as the host CPU does not 
change.

Thanks,

Paolo

> Signed-off-by: David Woodhouse <dwmw at amazon.co.uk>
> ---
>   Documentation/virt/kvm/api.rst              | 14 ++++++++++++++
>   Documentation/virt/kvm/review-checklist.rst | 20 ++++++++++++++------
>   2 files changed, 28 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 269970221797..864f3daa7acb 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -97,6 +97,20 @@ Instead, kvm defines extension identifiers and a facility to query
>   whether a particular extension identifier is available.  If it is, a
>   set of ioctls is available for application use.
>   
> +KVM will ensure that the state that can be saved and restored via the
> +KVM ioctls is sufficient to allow migration of a running guest between
> +host kernels while maintaining full compatibility of the guest-visible
> +device model.  This includes migration to newer kernels (upgrade) and
> +to older kernels (rollback), provided that the older kernel supports
> +the set of features exposed to the guest.  Where a new kernel version
> +introduces a guest-visible change, it will provide a mechanism (such
> +as a capability or a device attribute) that allows userspace to select
> +the previous behaviour.  This serves two purposes: guests migrated
> +from an older kernel can continue to run with their original
> +observable environment, and new guests launched on the newer kernel
> +can be configured to match the feature set of the older kernel, so
> +that they remain migratable to the older kernel in case of rollback.
> +
>   
>   4. API description
>   ==================
> diff --git a/Documentation/virt/kvm/review-checklist.rst b/Documentation/virt/kvm/review-checklist.rst
> index 053f00c50d66..f0fbe1577a90 100644
> --- a/Documentation/virt/kvm/review-checklist.rst
> +++ b/Documentation/virt/kvm/review-checklist.rst
> @@ -18,22 +18,30 @@ Review checklist for kvm patches
>   5.  New features must default to off (userspace should explicitly request them).
>       Performance improvements can and should default to on.
>   
> -6.  New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2,
> +6.  Guest-visible changes must not break migration compatibility.  A guest
> +    migrated from an older kernel must be able to run with its original
> +    observable environment, and a guest launched on a newer kernel must be
> +    configurable to match the older kernel's feature set for rollback.
> +    Where a change alters guest-visible behaviour, provide a mechanism
> +    (capability, device attribute, etc.) for userspace to select the
> +    previous behaviour.
> +
> +7.  New cpu features should be exposed via KVM_GET_SUPPORTED_CPUID2,
>       or its equivalent for non-x86 architectures
>   
> -7.  The feature should be testable (see below).
> +8.  The feature should be testable (see below).
>   
> -8.  Changes should be vendor neutral when possible.  Changes to common code
> +9.  Changes should be vendor neutral when possible.  Changes to common code
>       are better than duplicating changes to vendor code.
>   
> -9.  Similarly, prefer changes to arch independent code than to arch dependent
> +10. Similarly, prefer changes to arch independent code than to arch dependent
>       code.
>   
> -10. User/kernel interfaces and guest/host interfaces must be 64-bit clean
> +11. User/kernel interfaces and guest/host interfaces must be 64-bit clean
>       (all variables and sizes naturally aligned on 64-bit; use specific types
>       only - u64 rather than ulong).
>   
> -11. New guest visible features must either be documented in a hardware manual
> +12. New guest visible features must either be documented in a hardware manual
>       or be accompanied by documentation.
>   
>   Testing of KVM code