[PATCH 0/6] KVM: PPC: Handle CPU compatibility mode for nested guests

[PATCH 0/6] KVM: PPC: Handle CPU compatibility mode for nested guests

[Amit Machhiwal]

On POWER systems, newer processor generations can operate in compatibility
modes corresponding to earlier generations (e.g., a Power11 system running
in Power10 compatibility mode). In such cases, the effective CPU level
exposed to guests differs from the physical processor generation.

This creates a problem for nested virtualization. When booting a nested KVM
guest (L2) inside a host KVM guest (L1) running in a compatibility mode,
userspace (e.g., QEMU) may derive the CPU model from the raw hardware PVR
and attempt to configure the nested guest accordingly. However, the L1
partition is constrained by the compatibility level negotiated with the
hypervisor (L0), and requests exceeding that level are rejected, leading to
guest boot failures such as:

  KVM-NESTEDv2: couldn't set guest wide elements

This series addresses the issue in two steps:

1. Detect and reject invalid compatibility requests early in KVM to avoid
   late failures.

2. Provide a mechanism for userspace to query the effective CPU
   compatibility modes supported by the host, so it can select an
   appropriate CPU model for nested guests.

To achieve this, the series introduces a new KVM capability and ioctl
(KVM_CAP_PPC_COMPAT_CAPS / KVM_PPC_GET_COMPAT_CAPS) that expose the
compatibility modes supported by the host.

The implementation supports both:

  - PowerVM (nested API v2), where compatibility information is obtained
    via the H_GUEST_GET_CAPABILITIES hypercall.
  - PowerNV (nested API v1), where compatibility is derived from the device
    tree ("cpu-version") representing the effective processor compatibility
    level.

This allows userspace (e.g., QEMU) to select a CPU model consistent with
the host compatibility mode, avoiding mismatches and enabling successful
nested guest boot.

Patch summary:
  [1/6] Validate arch_compat against host compatibility mode
  [2/6] Introduce KVM_CAP_PPC_COMPAT_CAPS and ioctl
  [3/6] Wire up ioctl handling
  [4/6] Implement capability retrieval for PowerVM (API v2)
  [5/6] Add PowerNV support (API v1)
  [6/6] Document the new ioctl

Tested on:
  - Power11 pSeries LPAR in Power10 compatibility mode (nested API v2)
  - Power10 PowerNV system (and QEMU TCG PowerNV 11) with nested
    virtualization (API v1) with various combinations of KVM L1/L2 guests
    in various supported compatibility modes.

With this series, nested guests boot successfully in configurations where
they previously failed due to compatibility mismatches.

Amit Machhiwal (6):
  KVM: PPC: Book3S HV: Validate arch_compat against host compatibility
    mode
  KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and
    KVM_PPC_GET_COMPAT_CAPS
  KVM: PPC: Wire up KVM_PPC_GET_COMPAT_CAPS ioctl
  KVM: PPC: Book3S HV: Implement compat CPU capability retrieval for KVM
    on PowerVM
  KVM: PPC: Book3S HV: Add support for compat CPU capabilities for KVM
    on PowerNV
  KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

 Documentation/virt/kvm/api.rst      | 35 +++++++++++++++++
 arch/powerpc/include/asm/kvm_ppc.h  |  1 +
 arch/powerpc/include/uapi/asm/kvm.h |  6 +++
 arch/powerpc/kvm/book3s_hv.c        | 58 +++++++++++++++++++++++++++++
 arch/powerpc/kvm/powerpc.c          | 19 ++++++++++
 include/uapi/linux/kvm.h            |  4 ++
 6 files changed, 123 insertions(+)


base-commit: dca922e019dd758b4c1b4bec8f1d509efddeaab4
--
2.50.1

[PATCH 6/6] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

[Amit Machhiwal]

Add documentation for the KVM_PPC_GET_COMPAT_CAPS ioctl to the KVM API
documentation.

The ioctl exposes host processor compatibility modes supported for
nested KVM guests on PowerPC systems.

Signed-off-by: Amit Machhiwal <amachhiw@linux.ibm.com>
---
 Documentation/virt/kvm/api.rst | 35 ++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 52bbbb553ce1..7a10c3c6cbf1 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -6555,6 +6555,41 @@ KVM_S390_KEYOP_SSKE
 
 .. _kvm_run:
 
+4.145 KVM_PPC_GET_COMPAT_CAPS
+-----------------------------
+:Capability: KVM_CAP_PPC_COMPAT_CAPS
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_compat_caps (out)
+:Returns:
+	0 on successful completion,
+	-EFAULT if ``struct kvm_ppc_compat_caps`` cannot be written
+
+IBM POWER system server-based processors provide a compatibility mode feature
+where an Nth generation processor can operate in modes consistent with earlier
+generations such as (N-1) and (N-2).
+
+This ioctl provides userspace with information about the CPU compatibility modes
+supported by the current host processor for booting the nested KVM guests on
+PowerNV (KVM nested APIv1) and PowerVM (KVM nested APIv2) platforms.
+
+::
+
+  struct kvm_ppc_compat_caps {
+         __u32   flags;
+         __u64   compat_capabilities;    /* Capabilities supported by the host */
+  };
+
+The ``compat_capabilities`` bit field describes the processor compatibility
+modes supported by the host. For example, the following bits indicate support
+for specific processor modes.
+
+::
+
+ bit 1: KVM guests can run in Power9 processor mode
+ bit 2: KVM guests can run in Power10 processor mode
+ bit 3: KVM guests can run in Power11 processor mode
+
 5. The kvm_run structure
 ========================
 
-- 
2.50.1

Re: [PATCH 6/6] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

[Harsh Prateek Bora]

On 30/04/26 11:19 am, Amit Machhiwal wrote:
> Add documentation for the KVM_PPC_GET_COMPAT_CAPS ioctl to the KVM API
> documentation.
> 
> The ioctl exposes host processor compatibility modes supported for
> nested KVM guests on PowerPC systems.
> 
> Signed-off-by: Amit Machhiwal <amachhiw@linux.ibm.com>
> ---
>   Documentation/virt/kvm/api.rst | 35 ++++++++++++++++++++++++++++++++++
>   1 file changed, 35 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 52bbbb553ce1..7a10c3c6cbf1 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -6555,6 +6555,41 @@ KVM_S390_KEYOP_SSKE
>   
>   .. _kvm_run:
>   
> +4.145 KVM_PPC_GET_COMPAT_CAPS
> +-----------------------------
> +:Capability: KVM_CAP_PPC_COMPAT_CAPS
> +:Architectures: powerpc
> +:Type: vm ioctl
> +:Parameters: struct kvm_ppc_compat_caps (out)
> +:Returns:
> +	0 on successful completion,
> +	-EFAULT if ``struct kvm_ppc_compat_caps`` cannot be written

-EINVAL also needs to be documented?

> +
> +IBM POWER system server-based processors provide a compatibility mode feature
> +where an Nth generation processor can operate in modes consistent with earlier
> +generations such as (N-1) and (N-2).
> +
> +This ioctl provides userspace with information about the CPU compatibility modes
> +supported by the current host processor for booting the nested KVM guests on
> +PowerNV (KVM nested APIv1) and PowerVM (KVM nested APIv2) platforms.
> +
> +::
> +
> +  struct kvm_ppc_compat_caps {
> +         __u32   flags;
> +         __u64   compat_capabilities;    /* Capabilities supported by the host */
> +  };
> +
> +The ``compat_capabilities`` bit field describes the processor compatibility
> +modes supported by the host. For example, the following bits indicate support
> +for specific processor modes.
> +
> +::
> +
> + bit 1: KVM guests can run in Power9 processor mode
> + bit 2: KVM guests can run in Power10 processor mode
> + bit 3: KVM guests can run in Power11 processor mode

May be use H_GUEST_CAP_POWER9 and friends ?

> +
>   5. The kvm_run structure
>   ========================
>   

Re: [PATCH 6/6] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

[Amit Machhiwal]

On 2026/05/05 03:25 PM, Harsh Prateek Bora wrote:
> 
> 
> On 30/04/26 11:19 am, Amit Machhiwal wrote:
> > Add documentation for the KVM_PPC_GET_COMPAT_CAPS ioctl to the KVM API
> > documentation.
> > 
> > The ioctl exposes host processor compatibility modes supported for
> > nested KVM guests on PowerPC systems.
> > 
> > Signed-off-by: Amit Machhiwal <amachhiw@linux.ibm.com>
> > ---
> >   Documentation/virt/kvm/api.rst | 35 ++++++++++++++++++++++++++++++++++
> >   1 file changed, 35 insertions(+)
> > 
> > diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> > index 52bbbb553ce1..7a10c3c6cbf1 100644
> > --- a/Documentation/virt/kvm/api.rst
> > +++ b/Documentation/virt/kvm/api.rst
> > @@ -6555,6 +6555,41 @@ KVM_S390_KEYOP_SSKE
> >   .. _kvm_run:
> > +4.145 KVM_PPC_GET_COMPAT_CAPS
> > +-----------------------------
> > +:Capability: KVM_CAP_PPC_COMPAT_CAPS
> > +:Architectures: powerpc
> > +:Type: vm ioctl
> > +:Parameters: struct kvm_ppc_compat_caps (out)
> > +:Returns:
> > +	0 on successful completion,
> > +	-EFAULT if ``struct kvm_ppc_compat_caps`` cannot be written
> 
> -EINVAL also needs to be documented?

We do not currently return -EINVAL for this ioctl, so I did not document it. As
implemented, the only explicit error documented here is -EFAULT when struct
kvm_ppc_compat_caps cannot be written. Please let me know if I am missing a case
where -EINVAL should be returned.

> 
> > +
> > +IBM POWER system server-based processors provide a compatibility mode feature
> > +where an Nth generation processor can operate in modes consistent with earlier
> > +generations such as (N-1) and (N-2).
> > +
> > +This ioctl provides userspace with information about the CPU compatibility modes
> > +supported by the current host processor for booting the nested KVM guests on
> > +PowerNV (KVM nested APIv1) and PowerVM (KVM nested APIv2) platforms.
> > +
> > +::
> > +
> > +  struct kvm_ppc_compat_caps {
> > +         __u32   flags;
> > +         __u64   compat_capabilities;    /* Capabilities supported by the host */
> > +  };
> > +
> > +The ``compat_capabilities`` bit field describes the processor compatibility
> > +modes supported by the host. For example, the following bits indicate support
> > +for specific processor modes.
> > +
> > +::
> > +
> > + bit 1: KVM guests can run in Power9 processor mode
> > + bit 2: KVM guests can run in Power10 processor mode
> > + bit 3: KVM guests can run in Power11 processor mode
> 
> May be use H_GUEST_CAP_POWER9 and friends ?

I used the bit descriptions directly since this is documenting the uAPI bitmap
layout, which felt clearer for userspace than using only H_GUEST_CAP_POWER9 and
friends. But I’m happy to mention those macros as well if you think that
improves clarity.

Thanks again for reviewing the series. I will wait a little longer for any
further feedback before posting v2.

Thanks,
Amit

> 
> > +
> >   5. The kvm_run structure
> >   ========================
>