On 5/11/26 10:57, David Woodhouse wrote:
From: David Woodhouse <[email protected]>
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 <[email protected]>
---
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
