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@xxxxxxxxxxxxx>
> > ---
> >   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
> >   ========================
>