Skip to contentSkip to conversation

KVM: PPC: Expose CPU compatibility modes for nested guests

PATCH Superseded Amit Machhiwal 3 participants 12 messages Aug 7 – Aug 8

Subsystems (4)

v8 of 9 Superseded Latest is v9 →

lore
Share & tools
lore
#0 lore raw

v8 cover KVM: PPC: Expose CPU compatibility modes for nested guests

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 provides 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.

Why a new UAPI?
===============
While cpu-version is available in /proc/device-tree/cpus/<cpu#>/cpu-version on both L1 booted on PowerNV and PowerVM LPARs, the UAPI approach is preferable for several reasons:

1. pHYP (L0) capabilities: On PowerVM, we need to rely on capabilities negotiated with pHYP in KVM, not just device tree properties. The cpu-version property depicts the current compat mode but doesn't point to what all compat modes are supported for the nested guest.

2. procfs dependency: Not all systems run with procfs enabled (CONFIG_PROC_FS is optional). Minimal configurations like buildroot might disable it, but KVM ioctl works regardless since it accesses kernel data structures directly.

3. Kernel validation: The kernel validates and normalizes the compatibility information, ensuring userspace gets validated, consistent data.

4. Abstraction & stability: /proc/device-tree is an implementation detail. The UAPI provides a stable interface that won't break if the underlying mechanism changes.

5. Semantic clarity: KVM_PPC_GET_COMPAT_CAPS clearly expresses what compatibility modes can be used for KVM guests, vs. parsing device tree which requires understanding the semantic meaning of cpu-version.

The implementation supports both:

- KVM on PowerVM (nested API v2), where compatibility information is served from the cached nested_capabilities value, originally obtained via the H_GUEST_GET_CAPABILITIES hypercall at module init.
- KVM on 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.

Note: This series is built on top of patch [1] which must be applied first. Patch [1] ensures arch_compat is validated against the host compatibility mode before this series adds the capability query mechanism. Commit e4de1b9cb3b5 ("powerpc/dt_cpu_ftrs: Set CPU_FTR_P11_PVR for Power11 and later processors") which was also a prerequisite has been merged upstream.

Changes in v8:
- Add PAGE_SIZE guard after get_user() to bound the check_zeroed_user() scan in the usize > ksize path [Ritesh]
- Drop the manual usize > sizeof(host_caps) pre-check; delegate the usize > ksize path entirely to copy_struct_from_user(), which succeeds when trailing bytes are zero (valid forward-compat) and returns -E2BIG only when they are non-zero. Handle -E2BIG by writing back ksize with proper -EFAULT escalation if put_user() fails. [Ritesh]
- Fix host_caps.size writeback on success path: use min_t(u64, usize, sizeof(host_caps)) instead of sizeof(host_caps) to avoid reporting a larger size than the kernel actually populated when new userspace passes a larger struct with zero trailing bytes. [Ritesh]
- Update documentation to reflect the corrected three-case versioning contract and the revised E2BIG semantics. [Ritesh]

Patch summary:
[1/4] Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl [2/4] Implement capability retrieval for KVM on PowerVM (API v2) [3/4] Add KVM on PowerNV support (API v1)
[4/4] Document the new ioctl

Testing (with QEMU v5 patches and on top of patch [1]):

KVM APIv1 Testing
=================
On P10 PowerNV machine (L0)
---------------------------
- P10 L1 KVM guest -> works
- P10 nested L2 KVM guest -> works
- P9 compat nested L2 KVM guest -> works
- P9 compat L1 KVM guest -> works
- P9 nested L2 KVM guest -> works

On Powernv11 TCG Guest (L0)
---------------------------
- P11 PowerNV TCG L0 guest -> works
- P11 L1 KVM guest -> works
- P11 L2 KVM guest -> works
- P10 compat L1 KVM guest -> works
- P10 L2 KVM guest -> works
- P9 compat L1 KVM guest -> works
- P9 L2 KVM guest -> works

KVM APIv2 Testing
=================
On P11 PowerVM LPAR (L1)
------------------------
- P11 L2 KVM guest -> works
- P10 compat L2 KVM guest -> works
- P9 compat L2 KVM guest fails to boot as expected
- Without QEMU patches but Linux patches
- P11 L2 KVM guest -> works
- P10 compat L2 KVM guest -> works
- P9 compat L2 KVM guest fails to boot as expected
- Without Linux patches but QEMU patches
- P11 L2 KVM guest -> works
- P10 compat L2 KVM guest -> works

On P11 LPAR in P10 compat (L1)
------------------------------
- P10 (host compat) L2 KVM guest -> works
- Without QEMU patch but Linux patches
- P10 guest fails to boot as expected (error: kvm run failed Invalid argument)
- Without Linux patch but QEMU patches
- P10 guest fails to boot as expected (KVM: unknown exit, hardware reason ffffffffffffffea)

On P10 PowerVM LPAR (L1)
------------------------
- P10 L2 KVM guest -> works
- P9 compat L2 KVM guest fails to boot as expected

TCG pSeries Guest
=================
- P11 (default) pSeries guest boots fine

ABI Extensibility Testing (struct size 32, extra member)
=========================================================
- Newer struct on QEMU, older kernel -> works (kernel returns -E2BIG, QEMU retries with correct size)
- New struct on Linux kernel, older QEMU -> works (kernel zero-pads trailing fields, QEMU gets correct data)

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

Related QEMU series:
====================
QEMU v5 series:
https://lore.kernel.org/all/[email protected]/

Previous QEMU versions:
v4: https://lore.kernel.org/all/[email protected]/
v3: https://lore.kernel.org/all/[email protected]/
v2: https://lore.kernel.org/all/[email protected]/
v1: https://lore.kernel.org/all/[email protected]/

Previous versions:
==================
v7: https://lore.kernel.org/linuxppc-dev/[email protected]/
v6: https://lore.kernel.org/linuxppc-dev/[email protected]/
v5: https://lore.kernel.org/linuxppc-dev/[email protected]/
v4: https://lore.kernel.org/linuxppc-dev/[email protected]/
v3: https://lore.kernel.org/linuxppc-dev/[email protected]/
v2: https://lore.kernel.org/linuxppc-dev/[email protected]/
v1: https://lore.kernel.org/linuxppc-dev/[email protected]/

References:
===========
[1] https://lore.kernel.org/all/[email protected]/

Amit Machhiwal (4):
KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up 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      | 89 +++++++++++++++++++++++++++++
 arch/powerpc/include/asm/kvm_ppc.h  |  1 +
 arch/powerpc/include/uapi/asm/kvm.h | 18 ++++++
 arch/powerpc/kvm/book3s_hv.c        | 56 ++++++++++++++++++
 arch/powerpc/kvm/powerpc.c          | 78 +++++++++++++++++++++++++
 include/uapi/linux/kvm.h            |  3 +
 6 files changed, 245 insertions(+)

base-commit: f9a2394a23482bfd330911e9c8295b71724feacd
prerequisite-patch-id: 7755786f0e4f415e47065ff1972765008727fe10

Signature · 1 line
2.50.1 (Apple Git-155)
#1 lore raw

PATCH v8 1/4 KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl

Introduce a new capability and ioctl to expose CPU compatibility modes supported by the host processor for nested guests.

On IBM POWER systems, newer processor generations (N) can operate in compatibility modes corresponding to earlier generations, like (N-1) and (N-2). This is particularly relevant for nested virtualization, where nested KVM guests may need to run with a specific processor compatibility level.

Introduce KVM_CAP_PPC_COMPAT_CAPS capability and the corresponding KVM_PPC_GET_COMPAT_CAPS vm ioctl. The ioctl returns a bitmap describing the compatibility modes supported by the host in respective bit numbers, allowing userspace (e.g., QEMU) to select an appropriate compatibility level when configuring nested KVM guests.

The ioctl handling is added in kvm_arch_vm_ioctl() and retrieves host CPU compatibility capabilities via a PowerPC-specific backend implementation when available.

The struct kvm_ppc_compat_caps places the 'size' field first so it can be read alone via get_user() before copy_struct_from_user() is called, avoiding pointer arithmetic to locate the size field.

The ioctl is defined using _IO so the ioctl number remains stable even if the struct grows in future versions. It uses copy_struct_from_user() and copy_struct_to_user() to provide forward- and backward-compatible
extensibility: older userspace passing a smaller struct to a newer kernel gets zero-padded trailing fields. Newer userspace passing a larger struct to an older kernel (usize > ksize) succeeds if trailing bytes are zero (the kernel reports back min(usize, ksize) as the filled size); if trailing bytes are non-zero, the kernel writes back ksize into host_caps.size and returns -E2BIG so userspace can retry with the correct size.

KVM_PPC_COMPAT_CAPS_SIZE_VER0 is defined as a frozen integer constant
(24) marking the size of the initial struct version, used as the minimum floor for size field validation, similar to other versioned struct interfaces in the kernel.

The 'flags' field is reserved for future use. The kernel rejects any call where flags is non-zero with -EINVAL, preventing garbage values from being baked into ABI permanently.

The ioctl returns appropriate error codes: E2BIG if usize exceeds PAGE_SIZE, or if new userspace provides a larger struct with non-zero trailing bytes (with ksize written back into host_caps.size for the retry); EINVAL for an invalid size or non-zero reserved fields; EFAULT for failed copy operations; and ENOTTY if the backend doesn't implement get_compat_caps.

---
Changes in this version:
- Add PAGE_SIZE guard after get_user() to bound the check_zeroed_user() scan in the usize > ksize path [Ritesh]
- Drop manual usize > sizeof(host_caps) pre-check; delegate entirely to copy_struct_from_user() which succeeds on zero trailing bytes and returns -E2BIG only on non-zero trailing bytes; handle -E2BIG with ksize writeback and -EFAULT escalation if put_user() fails [Ritesh]
- Fix host_caps.size on success path: use min_t(u64, usize, sizeof(host_caps)) so new userspace with zero trailing bytes gets back the number of bytes the kernel actually populated, not usize [Ritesh]

 arch/powerpc/include/asm/kvm_ppc.h  |  1 +
 arch/powerpc/include/uapi/asm/kvm.h |  8 +++
 arch/powerpc/kvm/powerpc.c          | 78 +++++++++++++++++++++++++++++
 include/uapi/linux/kvm.h            |  3 ++
 4 files changed, 90 insertions(+)
arch/powerpc/include/asm/kvm_ppc.h +1 -0
index 0953f2daa466..169ea6a7fbad 100644
@@ -319,6 +319,7 @@ struct kvmppc_ops {
 	bool (*hash_v3_possible)(void);
 	int (*create_vm_debugfs)(struct kvm *kvm);
 	int (*create_vcpu_debugfs)(struct kvm_vcpu *vcpu, struct dentry *debugfs_dentry);
+	int (*get_compat_caps)(struct kvm_ppc_compat_caps *host_caps);
 };
 
 extern struct kvmppc_ops *kvmppc_hv_ops;
arch/powerpc/include/uapi/asm/kvm.h +8 -0
index 077c5437f521..19e53d5ae540 100644
@@ -437,6 +437,14 @@ struct kvm_ppc_cpu_char {
 	__u64	behaviour_mask;		/* valid bits in behaviour */
 };
 
+/* For KVM_PPC_GET_COMPAT_CAPS */
+struct kvm_ppc_compat_caps {
+	__u64	size;			/* Size of this structure */
+	__u64	flags;			/* Reserved for future use */
+	__u64	compat_capabilities;	/* Capabilities supported by the host */
+};
+#define KVM_PPC_COMPAT_CAPS_SIZE_VER0	24 /* sizeof first published struct */
+
 /*
  * Values for character and character_mask.
  * These are identical to the values used by H_GET_CPU_CHARACTERISTICS.
arch/powerpc/kvm/powerpc.c +78 -0

90 lines not on this page · raw message

include/uapi/linux/kvm.h +3 -0
index 419011097fa8..70e36e6a0ad4 100644
@@ -997,6 +997,7 @@ struct kvm_enable_cap {
 #define KVM_CAP_S390_KEYOP 247
 #define KVM_CAP_S390_VSIE_ESAMODE 248
 #define KVM_CAP_S390_HPAGE_2G 249
+#define KVM_CAP_PPC_COMPAT_CAPS 250
 
 struct kvm_irq_routing_irqchip {
 	__u32 irqchip;
@@ -1341,6 +1342,8 @@ struct kvm_s390_keyop {
 /* Available with KVM_CAP_COUNTER_OFFSET */
 #define KVM_ARM_SET_COUNTER_OFFSET _IOW(KVMIO,  0xb5, struct kvm_arm_counter_offset)
 #define KVM_ARM_GET_REG_WRITABLE_MASKS _IOR(KVMIO,  0xb6, struct reg_mask_range)
+/* Available with KVM_CAP_PPC_COMPAT_CAPS */
+#define KVM_PPC_GET_COMPAT_CAPS	_IO(KVMIO,  0xb8)
 
 /* ioctl for vm fd */
 #define KVM_CREATE_DEVICE	  _IOWR(KVMIO,  0xe0, struct kvm_create_device)
Signature · 1 line
2.50.1 (Apple Git-155)
#2 lore raw

Re: [PATCH v8 1/4] KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider: - [High] KVM_CAP_PPC_COMPAT_CAPS is advertised as supported on pSeries HV KVM, but the…

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [High] KVM_CAP_PPC_COMPAT_CAPS is advertised as supported on pSeries HV KVM, but the KVM_PPC_GET_COMPAT_CAPS ioctl backend implementation is missing, leading to unconditional -ENOTTY failure. --

--- Patch [1]: [PATCH v8 1/4] KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl --- commit 3fd26ec35303a5e885f7551c23267fe626ae5e16
Author: Amit Machhiwal <[email protected]>

KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl

This commit introduces the KVM_CAP_PPC_COMPAT_CAPS capability and the KVM_PPC_GET_COMPAT_CAPS ioctl to expose CPU compatibility modes. It routes the ioctl to a backend-specific get_compat_caps implementation.

Quoted 5 lines
arch/powerpc/kvm/powerpc.c +0 -0
index 00302399fc37b..2fe4ea0ca4ff1 100644
@@ -697,6 +697,13 @@ int kvm_vm_ioctl_check_extension(struct kvm *kvm, long ext)

[ ... ]

arch/powerpc/kvm/powerpc.c int kvm_vm_ioctl_check_extension(struct kvm *kvm, long ext) · line 712

Quoted 7 lines
arch/powerpc/kvm/powerpc.c +7 -0
+#if defined(CONFIG_KVM_BOOK3S_HV_POSSIBLE)
+	case KVM_CAP_PPC_COMPAT_CAPS:
+		r = 0;
+		if (hv_enabled && kvmhv_on_pseries())
+			r = 1;
+		break;
+#endif /* CONFIG_KVM_BOOK3S_HV_POSSIBLE */

[Severity: High]
Since kvm_vm_ioctl_check_extension() advertises this capability as supported solely based on platform checks, will userspace expect the ioctl to work?

Looking at the ioctl implementation below, it seems to fail if the backend is missing. Should this capability check also verify that kvm->arch.kvm_ops->get_compat_caps is implemented so that it doesn't advertise a capability the kernel cannot fulfill?

[ ... ]

Quoted 1 line
arch/powerpc/kvm/powerpc.c +0 -0
@@ -2463,6 +2470,77 @@ int kvm_arch_vm_ioctl(struct file *filp, unsigned int ioctl, unsigned long arg)

[ ... ]

arch/powerpc/kvm/powerpc.c int kvm_arch_vm_ioctl(struct file *filp, unsigned int ioctl, unsigned long arg) · line 2538

Quoted 12 lines
arch/powerpc/kvm/powerpc.c +12 -0
+		/* Reserved fields must be zero */
+		r = -EINVAL;
+		if (host_caps.flags)
+			goto out;
+
+		r = -ENOTTY;
+		if (!kvm->arch.kvm_ops->get_compat_caps)
+			goto out;
+
+		r = kvm->arch.kvm_ops->get_compat_caps(&host_caps);
+		if (r)
+			goto out;

[Severity: High]
Does this ioctl currently return -ENOTTY on all platforms?

I don't see any backend implementing get_compat_caps in this patch. If userspace probes KVM_CAP_PPC_COMPAT_CAPS and gets a positive result, won't it be unexpectedly broken by receiving -ENOTTY when attempting to use the ioctl?

Would it be safer to introduce the capability advertisement in the same patch that wires up the actual backend implementation?

Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=1
reviewer Reviewed-by on v8 1/4
#3 lore raw

Re: [PATCH v8 1/4] KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl

In reply to Amit Machhiwal
Quoted 54 lines · Amit Machhiwal

Introduce a new capability and ioctl to expose CPU compatibility modes supported by the host processor for nested guests.

On IBM POWER systems, newer processor generations (N) can operate in compatibility modes corresponding to earlier generations, like (N-1) and (N-2). This is particularly relevant for nested virtualization, where nested KVM guests may need to run with a specific processor compatibility level.

Introduce KVM_CAP_PPC_COMPAT_CAPS capability and the corresponding KVM_PPC_GET_COMPAT_CAPS vm ioctl. The ioctl returns a bitmap describing the compatibility modes supported by the host in respective bit numbers, allowing userspace (e.g., QEMU) to select an appropriate compatibility level when configuring nested KVM guests.

The ioctl handling is added in kvm_arch_vm_ioctl() and retrieves host CPU compatibility capabilities via a PowerPC-specific backend implementation when available.

The struct kvm_ppc_compat_caps places the 'size' field first so it can be read alone via get_user() before copy_struct_from_user() is called, avoiding pointer arithmetic to locate the size field.

The ioctl is defined using _IO so the ioctl number remains stable even if the struct grows in future versions. It uses copy_struct_from_user() and copy_struct_to_user() to provide forward- and backward-compatible
extensibility: older userspace passing a smaller struct to a newer kernel gets zero-padded trailing fields. Newer userspace passing a larger struct to an older kernel (usize > ksize) succeeds if trailing bytes are zero (the kernel reports back min(usize, ksize) as the filled size); if trailing bytes are non-zero, the kernel writes back ksize into host_caps.size and returns -E2BIG so userspace can retry with the correct size.

KVM_PPC_COMPAT_CAPS_SIZE_VER0 is defined as a frozen integer constant
(24) marking the size of the initial struct version, used as the minimum floor for size field validation, similar to other versioned struct interfaces in the kernel.

The 'flags' field is reserved for future use. The kernel rejects any call where flags is non-zero with -EINVAL, preventing garbage values from being baked into ABI permanently.

The ioctl returns appropriate error codes: E2BIG if usize exceeds PAGE_SIZE, or if new userspace provides a larger struct with non-zero trailing bytes (with ksize written back into host_caps.size for the retry); EINVAL for an invalid size or non-zero reserved fields; EFAULT for failed copy operations; and ENOTTY if the backend doesn't implement get_compat_caps.

Quoted 12 lines

---
Changes in this version:
- Add PAGE_SIZE guard after get_user() to bound the check_zeroed_user() scan in the usize > ksize path [Ritesh]
- Drop manual usize > sizeof(host_caps) pre-check; delegate entirely to copy_struct_from_user() which succeeds on zero trailing bytes and returns -E2BIG only on non-zero trailing bytes; handle -E2BIG with ksize writeback and -EFAULT escalation if put_user() fails [Ritesh]
- Fix host_caps.size on success path: use min_t(u64, usize, sizeof(host_caps)) so new userspace with zero trailing bytes gets back the number of bytes the kernel actually populated, not usize [Ritesh]

Thanks for addressing them!
The only remaining comments from Sashiko now are because, it cannot find the implementation of ->get_compat_caps() since it is in the next patch.

So as for this patch, the changes looks good to me. Please feel free to add:

Quoted 5 lines
 arch/powerpc/include/asm/kvm_ppc.h  |  1 +
 arch/powerpc/include/uapi/asm/kvm.h |  8 +++
 arch/powerpc/kvm/powerpc.c          | 78 +++++++++++++++++++++++++++++
 include/uapi/linux/kvm.h            |  3 ++
 4 files changed, 90 insertions(+)
#4 lore raw

Re: [PATCH v8 1/4] KVM: PPC: Introduce KVM_CAP_PPC_COMPAT_CAPS and wire up ioctl

Quoted 69 lines · Ritesh Harjani
Quoted 54 lines · Amit Machhiwal

Introduce a new capability and ioctl to expose CPU compatibility modes supported by the host processor for nested guests.

On IBM POWER systems, newer processor generations (N) can operate in compatibility modes corresponding to earlier generations, like (N-1) and (N-2). This is particularly relevant for nested virtualization, where nested KVM guests may need to run with a specific processor compatibility level.

Introduce KVM_CAP_PPC_COMPAT_CAPS capability and the corresponding KVM_PPC_GET_COMPAT_CAPS vm ioctl. The ioctl returns a bitmap describing the compatibility modes supported by the host in respective bit numbers, allowing userspace (e.g., QEMU) to select an appropriate compatibility level when configuring nested KVM guests.

The ioctl handling is added in kvm_arch_vm_ioctl() and retrieves host CPU compatibility capabilities via a PowerPC-specific backend implementation when available.

The struct kvm_ppc_compat_caps places the 'size' field first so it can be read alone via get_user() before copy_struct_from_user() is called, avoiding pointer arithmetic to locate the size field.

The ioctl is defined using _IO so the ioctl number remains stable even if the struct grows in future versions. It uses copy_struct_from_user() and copy_struct_to_user() to provide forward- and backward-compatible
extensibility: older userspace passing a smaller struct to a newer kernel gets zero-padded trailing fields. Newer userspace passing a larger struct to an older kernel (usize > ksize) succeeds if trailing bytes are zero (the kernel reports back min(usize, ksize) as the filled size); if trailing bytes are non-zero, the kernel writes back ksize into host_caps.size and returns -E2BIG so userspace can retry with the correct size.

KVM_PPC_COMPAT_CAPS_SIZE_VER0 is defined as a frozen integer constant
(24) marking the size of the initial struct version, used as the minimum floor for size field validation, similar to other versioned struct interfaces in the kernel.

The 'flags' field is reserved for future use. The kernel rejects any call where flags is non-zero with -EINVAL, preventing garbage values from being baked into ABI permanently.

The ioctl returns appropriate error codes: E2BIG if usize exceeds PAGE_SIZE, or if new userspace provides a larger struct with non-zero trailing bytes (with ksize written back into host_caps.size for the retry); EINVAL for an invalid size or non-zero reserved fields; EFAULT for failed copy operations; and ENOTTY if the backend doesn't implement get_compat_caps.

Quoted 12 lines

---
Changes in this version:
- Add PAGE_SIZE guard after get_user() to bound the check_zeroed_user() scan in the usize > ksize path [Ritesh]
- Drop manual usize > sizeof(host_caps) pre-check; delegate entirely to copy_struct_from_user() which succeeds on zero trailing bytes and returns -E2BIG only on non-zero trailing bytes; handle -E2BIG with ksize writeback and -EFAULT escalation if put_user() fails [Ritesh]
- Fix host_caps.size on success path: use min_t(u64, usize, sizeof(host_caps)) so new userspace with zero trailing bytes gets back the number of bytes the kernel actually populated, not usize [Ritesh]

Quoted 3 lines

Thanks for addressing them!
The only remaining comments from Sashiko now are because, it cannot find the implementation of ->get_compat_caps() since it is in the next patch.

Yes, correct.

Quoted 5 lines

So as for this patch, the changes looks good to me. Please feel free to add:

Thanks for the review, Ritesh! Will carry the Reviewed-by in v9.

~Amit

#5 lore raw

PATCH v8 2/4 KVM: PPC: Book3S HV: Implement compat CPU capability retrieval for KVM on PowerVM

In reply to Amit Machhiwal

On POWER systems, the host CPU may run in a compatibility mode (e.g., a Power11 processor operating in Power10 compatibility mode). In such cases, the effective CPU level exposed to guests differs from the physical processor generation.

When running nested KVM guests, QEMU derives the host CPU type using mfpvr(), which reflects the physical processor version. This can result in a mismatch between the CPU model selected by QEMU and the compatibility mode enforced by the host, leading to guest boot failures.

For example, booting a nested guest on a Power11 LPAR configured in Power10 compatibility mode fails with:

KVM-NESTEDv2: couldn't set guest wide elements
[..KVM reg dump..]

This occurs because QEMU selects a CPU model corresponding to the physical processor (via mfpvr()), while the host operates in a lower compatibility mode. As a result, KVM rejects the requested compatibility level during guest initialization.

On pseries nestedv2 systems, add support for retrieving host CPU compatibility capabilities for nested guests on PowerVM. The capability bitmap reflects the processor modes negotiated between the Power hypervisor (L0) and the host partition (L1) via the H_GUEST_GET_CAPABILITIES hcall, but is retrieved from the cached nested_capabilities value populated during module initialization, avoiding repeated hypervisor calls. A WARN_ON_ONCE() flags the unexpected case where nested_capabilities is zero on a nestedv2 system. The implementation defines KVM-specific capability constants (KVM_PPC_COMPAT_CAP_POWER9/10/11), masks unsupported bits, and exposes the result through the KVM_PPC_GET_COMPAT_CAPS ioctl.

Hook the implementation into the Book3S HV kvmppc_ops so that it can be invoked by the generic KVM ioctl handling code.

---
 arch/powerpc/include/uapi/asm/kvm.h | 10 ++++++++++
 arch/powerpc/kvm/book3s_hv.c        | 20 ++++++++++++++++++++
 2 files changed, 30 insertions(+)
arch/powerpc/include/uapi/asm/kvm.h +10 -0
index 19e53d5ae540..913a64b901a3 100644
@@ -445,6 +445,16 @@ struct kvm_ppc_compat_caps {
 };
 #define KVM_PPC_COMPAT_CAPS_SIZE_VER0	24 /* sizeof first published struct */
 
+/*
+ * Capability bits for compat_capabilities field in kvm_ppc_compat_caps.
+ * These bits indicate which processor compatibility modes are supported.
+ */
+#define KVM_PPC_COMPAT_CAP_POWER9	(1ULL << 62)
+#define KVM_PPC_COMPAT_CAP_POWER10	(1ULL << 61)
+#define KVM_PPC_COMPAT_CAP_POWER11	(1ULL << 60)
+#define KVM_PPC_COMPAT_BITMASK		(KVM_PPC_COMPAT_CAP_POWER9 | \
+					 KVM_PPC_COMPAT_CAP_POWER10 | \
+					 KVM_PPC_COMPAT_CAP_POWER11)
 /*
  * Values for character and character_mask.
  * These are identical to the values used by H_GET_CPU_CHARACTERISTICS.
arch/powerpc/kvm/book3s_hv.c +20 -0
index f9380ef65750..152cd08a5b38 100644
@@ -6523,6 +6523,25 @@ static bool kvmppc_hash_v3_possible(void)
 	return true;
 }
 
+
+static int kvmppc_get_compat_caps(struct kvm_ppc_compat_caps *host_caps)
+{
+	unsigned long capabilities = 0;
+	long rc = -EINVAL;
+
+	if (kvmhv_on_pseries()) {
+		if (kvmhv_is_nestedv2()) {
+			WARN_ON_ONCE(!nested_capabilities);
+			capabilities = nested_capabilities;
+			rc = 0;
+		}
+	}
+
+	host_caps->compat_capabilities = capabilities & KVM_PPC_COMPAT_BITMASK;
+
+	return rc;
+}
+
 static struct kvmppc_ops kvm_ops_hv = {
 	.get_sregs = kvm_arch_vcpu_ioctl_get_sregs_hv,
 	.set_sregs = kvm_arch_vcpu_ioctl_set_sregs_hv,
@@ -6565,6 +6584,7 @@ static struct kvmppc_ops kvm_ops_hv = {
 	.hash_v3_possible = kvmppc_hash_v3_possible,
 	.create_vcpu_debugfs = kvmppc_arch_create_vcpu_debugfs_hv,
 	.create_vm_debugfs = kvmppc_arch_create_vm_debugfs_hv,
+	.get_compat_caps = kvmppc_get_compat_caps,
 };
 
 static int kvm_init_subcore_bitmap(void)
Signature · 1 line
2.50.1 (Apple Git-155)
#6 lore raw

Re: [PATCH v8 2/4] KVM: PPC: Book3S HV: Implement compat CPU capability retrieval for KVM on PowerVM

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider: - [High] KVM_CAP_PPC_COMPAT_CAPS is unconditionally advertised on all pseries hosts, but the corresponding…

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:
- [High] KVM_CAP_PPC_COMPAT_CAPS is unconditionally advertised on all pseries hosts, but the corresponding ioctl fails on non-nestedv2 hosts.
- [Medium] kvmppc_get_compat_caps returns -EINVAL for unsupported configurations instead of -ENOTTY or -EOPNOTSUPP.
--

--- Patch [2]: [PATCH v8 2/4] KVM: PPC: Book3S HV: Implement compat CPU capability retrieval for KVM on PowerVM --- commit 73749763b436fd33b42f2ac5536c1c5a4bf826ad
Author: Amit Machhiwal <[email protected]>

KVM: PPC: Book3S HV: Implement compat CPU capability retrieval for KVM on PowerVM

This commit implements the retrieval of host CPU compatibility capabilities for nested KVM guests on PowerVM. It defines KVM-specific capability constants and exposes the cached nested capabilities via the KVM_PPC_GET_COMPAT_CAPS ioctl.

arch/powerpc/kvm/book3s_hv.c static bool kvmppc_hash_v3_possible(void) · line 6517

Quoted 13 lines
arch/powerpc/kvm/book3s_hv.c +5 -0
index 61dbeea317f3b..8799124b80960 100644
@@ -6510,6 +6510,25 @@ static bool kvmppc_hash_v3_possible(void)
 	return true;
 }
 
+
+static int kvmppc_get_compat_caps(struct kvm_ppc_compat_caps *host_caps)
+{
+	unsigned long capabilities = 0;
+	long rc = -EINVAL;

[Severity: Medium]
Should this return -ENOTTY or -EOPNOTSUPP instead of -EINVAL when the configuration is unsupported?

-EINVAL conventionally indicates invalid userspace arguments rather than a lack of host support. This might complicate graceful fallback logic if userspace cannot differentiate between malformed requests and missing features.

arch/powerpc/kvm/book3s_hv.c static bool kvmppc_hash_v3_possible(void) · line 6533

Quoted 3 lines
arch/powerpc/kvm/book3s_hv.c +3 -0
+
+	if (kvmhv_on_pseries()) {
+		if (kvmhv_is_nestedv2()) {

[Severity: High]
If KVM_CAP_PPC_COMPAT_CAPS returns 1 for all pseries hosts (including nestedv1) in kvm_vm_ioctl_check_extension(), will failing this ioctl here on non-nestedv2 hosts break userspace?

Userspace might rely on the capability advertisement and fail unexpectedly when the ioctl returns an error instead of succeeding with empty or base capabilities.

Quoted 10 lines
arch/powerpc/kvm/book3s_hv.c +10 -0
+			WARN_ON_ONCE(!nested_capabilities);
+			capabilities = nested_capabilities;
+			rc = 0;
+		}
+	}
+
+	host_caps->compat_capabilities = capabilities & KVM_PPC_COMPAT_BITMASK;
+
+	return rc;
+}
Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=2
#7 lore raw

PATCH v8 3/4 KVM: PPC: Book3S HV: Add support for compat CPU capabilities for KVM on PowerNV

In reply to Amit Machhiwal

Currently, when booting a compatibility-mode KVM guest (L1) on a PowerNV hypervisor (L0), the guest runs with the expected processor compatibility level. However, when booting a nested KVM guest (L2) inside the L1, QEMU derives the CPU model from the raw host PVR and attempts to run the nested guest at that level, instead of honoring the compatibility mode of the L1.

Extend host CPU compatibility capability reporting to support nested virtualization on PowerNV systems (PAPR nested API v1).

For nested API v2 (PowerVM), compatibility capabilities are served from the cached nested_capabilities value (populated at module init via kvmhv_nested_init() using the H_GUEST_GET_CAPABILITIES hcall). This information is not available on PowerNV systems.

For nested API v1, derive the compatibility capabilities from the L1 guest by reading the "cpu-version" property from the device tree, which reflects the effective (logical) processor compatibility level. Map this value to the corresponding compatibility capability bitmap using KVM-specific constants.

The mapping is cumulative: a system running at a given compatibility level is assumed to also support older generations down the supported chain. Note that unlike KVM on PowerVM (nested API v2), KVM on PowerNV currently does not strictly enforce older generation compatibility modes for nested guests - the reported capabilities reflect what the host CPU can present, not what the hypervisor independently validates.

Introduce a helper kvmppc_map_compat_capabilities() to translate CPU version values into KVM_PPC_COMPAT_CAP bits using a fallthrough switch, and integrate it into kvmppc_get_compat_caps(). The implementation applies masking to ensure only supported processor modes are exposed.

This allows userspace to query host CPU compatibility modes on both KVM on PowerVM and on PowerNV platforms via the KVM_PPC_GET_COMPAT_CAPS ioctl.

---
 arch/powerpc/kvm/book3s_hv.c | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
arch/powerpc/kvm/book3s_hv.c +36 -0
index 152cd08a5b38..4d0307f55e06 100644
@@ -6523,20 +6523,56 @@ static bool kvmppc_hash_v3_possible(void)
 	return true;
 }
 
+static int kvmppc_map_compat_capabilities(u32 cpu_version,
+					  unsigned long *capabilities)
+{
+	switch (cpu_version) {
+	case PVR_ARCH_31_P11:
+		*capabilities |= KVM_PPC_COMPAT_CAP_POWER11;
+		fallthrough;
+	case PVR_ARCH_31:
+		*capabilities |= KVM_PPC_COMPAT_CAP_POWER10;
+		fallthrough;
+	case PVR_ARCH_300:
+		*capabilities |= KVM_PPC_COMPAT_CAP_POWER9;
+		break;
+	default:
+		return -EINVAL;
+	}
+
+	return 0;
+}
 
 static int kvmppc_get_compat_caps(struct kvm_ppc_compat_caps *host_caps)
 {
+	struct device_node *np;
 	unsigned long capabilities = 0;
 	long rc = -EINVAL;
+	u32 cpu_version = 0;
 
 	if (kvmhv_on_pseries()) {
 		if (kvmhv_is_nestedv2()) {
 			WARN_ON_ONCE(!nested_capabilities);
 			capabilities = nested_capabilities;
 			rc = 0;
+		} else {
+			for_each_node_by_type(np, "cpu") {
+				if (!of_property_read_u32(np, "cpu-version",
+							  &cpu_version)) {
+					of_node_put(np);
+					break;
+				}
+			}
+			if (!cpu_version)
+				return -EINVAL;
+			rc = kvmppc_map_compat_capabilities(cpu_version,
+							    &capabilities);
 		}
 	}
 
+	if (rc < 0)
+		return rc;
+
 	host_caps->compat_capabilities = capabilities & KVM_PPC_COMPAT_BITMASK;
 
 	return rc;
Signature · 1 line
2.50.1 (Apple Git-155)
#8 lore raw

PATCH v8 4/4 KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

In reply to 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. The documentation covers error code descriptions including E2BIG for forward compatibility, the extensible size-based versioning contract using KVM_PPC_COMPAT_CAPS_SIZE_VER0, the rationale for rejecting non-zero reserved fields to prevent ABI ambiguity, bit numbering clarification for IBM MSB-0 convention, and KVM-specific capability bit constants.

---
Changes in this version:
- Update E2BIG description: document PAGE_SIZE guard as first case; -E2BIG for usize > ksize is only returned when trailing bytes are non-zero; zero trailing bytes now succeed [Ritesh]
- Rewrite versioning paragraph as three explicit cases to match the corrected copy_struct_from_user() / copy_struct_to_user() contract, including the usize > ksize zero-trailing-bytes success path [Ritesh]

 Documentation/virt/kvm/api.rst | 89 ++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
Documentation/virt/kvm/api.rst +89 -0
index e3003a241d5b..e656d117cd0b 100644
@@ -6566,6 +6566,95 @@ KVM_S390_KEYOP_SSKE
   Sets the storage key for the guest address ``guest_addr`` to the key
   specified in ``key``, returning the previous value in ``key``.
 
+4.145 KVM_PPC_GET_COMPAT_CAPS
+-----------------------------
+:Capability: KVM_CAP_PPC_COMPAT_CAPS
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_compat_caps (in/out)
+:Returns: 0 on success, negative value on failure
+
+Errors include:
+
+  ======== ============================================================
+  EFAULT   if ``struct kvm_ppc_compat_caps`` cannot be read from or
+           written to userspace
+  EINVAL   if the ``size`` field is smaller than
+           ``KVM_PPC_COMPAT_CAPS_SIZE_VER0``, if the ``flags`` field
+           is non-zero, or if the backend fails to retrieve or map
+           CPU compatibility capabilities
+  E2BIG    if ``size`` exceeds ``PAGE_SIZE`` (pathological input guard),
+           or if ``size`` is larger than the kernel's struct size and
+           the unknown trailing bytes are non-zero (new userspace on
+           old kernel with non-default fields set); in the latter case
+           the kernel writes back its own struct size into the ``size``
+           field so userspace can retry with the correct size
+  ENOTTY   if the backend does not implement the ``get_compat_caps``
+           operation (e.g., on non-HV KVM implementations where the
+           required KVM operations are not available)
+  ======== ============================================================
+
+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
+KVM on PowerNV (nested API v1) and KVM on PowerVM (nested API v2) platforms.
+
+::
+
+  struct kvm_ppc_compat_caps {
+	__u64	size;			/* Size of this structure */
+	__u64	flags;			/* Reserved for future use, must be 0 */
+	__u64	compat_capabilities;	/* Capabilities supported by the host */
+  };
+
+Before calling this ioctl, userspace must set the ``size`` field to
+``sizeof(struct kvm_ppc_compat_caps)`` and zero the ``flags`` field.
+The kernel rejects non-zero ``flags`` with ``-EINVAL`` to prevent
+uninitialized stack values from being silently accepted, keeping the
+field available for future use without ABI ambiguity.
+
+The ioctl uses ``copy_struct_from_user()`` and ``copy_struct_to_user()``
+to support extensible versioning across three cases:
+
+- If ``size`` is smaller than the kernel's struct size (old userspace,
+  new kernel), the kernel zero-pads the unknown trailing fields before
+  returning, and writes back ``size`` unchanged so userspace knows how
+  many bytes were filled.
+- If ``size`` equals the kernel's struct size, the struct is copied
+  verbatim.
+- If ``size`` is larger than the kernel's struct size (new userspace,
+  old kernel) and the unknown trailing bytes are all zero, the call
+  succeeds as if the sizes matched. If any trailing bytes are non-zero,
+  the kernel returns ``-E2BIG`` and writes back its own struct size into
+  the ``size`` field so userspace can retry with the correct size.
+
+``KVM_PPC_COMPAT_CAPS_SIZE_VER0`` (24) is a frozen constant marking the
+size of the initial struct version.
+
+The ``compat_capabilities`` bit field describes the processor compatibility
+modes supported by the host. The following bits indicate support for specific
+processor modes (using IBM's MSB-0 convention where bit 0 is the most
+significant bit):
+
+- ``KVM_PPC_COMPAT_CAP_POWER9``  (bit 1) -- KVM guests can run in Power9 processor mode
+- ``KVM_PPC_COMPAT_CAP_POWER10`` (bit 2) -- KVM guests can run in Power10 processor mode
+- ``KVM_PPC_COMPAT_CAP_POWER11`` (bit 3) -- KVM guests can run in Power11 processor mode
+
+.. note::
+
+   The bit numbering above uses IBM's MSB-0 convention (bit 0 is the most
+   significant bit). In the actual implementation, these are defined as:
+
+   - ``KVM_PPC_COMPAT_CAP_POWER9``  = ``(1ULL << 62)``
+   - ``KVM_PPC_COMPAT_CAP_POWER10`` = ``(1ULL << 61)``
+   - ``KVM_PPC_COMPAT_CAP_POWER11`` = ``(1ULL << 60)``
+
+   Userspace should use the defined constants from ``<linux/kvm.h>`` rather
+   than hardcoding bit positions.
+
 .. _kvm_run:
 
 5. The kvm_run structure
Signature · 1 line
2.50.1 (Apple Git-155)
#9 lore raw

Re: [PATCH v8 4/4] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:

Thank you for your contribution! Sashiko AI review found 2 potential issue(s) to consider:

New issues:
- [Medium] The documentation inaccurately describes how the extensible struct versioning handles trailing fields and truncation.

Pre-existing issues:
- [High] A userspace-reachable WARN_ON_ONCE in kvmppc_get_compat_caps allows unprivileged users to panic the host if panic_on_warn is set. --

--- Patch [4]: [PATCH v8 4/4] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl --- commit 991bf5faa645caad474f6369b275de7617351fd0
Author: Amit Machhiwal <[email protected]>

KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

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. The documentation covers error code descriptions including E2BIG for forward compatibility.

Documentation/virt/kvm/api.rst KVM_S390_KEYOP_SSKE · line 6570

Quoted 10 lines
Documentation/virt/kvm/api.rst +2 -0
index e3003a241d5b0..e656d117cd0b1 100644
@@ -6566,6 +6566,95 @@ KVM_S390_KEYOP_SSKE
   Sets the storage key for the guest address ``guest_addr`` to the key
   specified in ``key``, returning the previous value in ``key``.
 
+4.145 KVM_PPC_GET_COMPAT_CAPS
+-----------------------------

[Severity: High]
This is a pre-existing issue, but does this ioctl handler allow unprivileged users to panic the host?

Looking at kvmppc_get_compat_caps() in arch/powerpc/kvm/book3s_hv.c:

arch/powerpc/kvm/book3s_hv.c:kvmppc_get_compat_caps() {
	if (kvmhv_on_pseries()) {
		if (kvmhv_is_nestedv2()) {
			WARN_ON_ONCE(!nested_capabilities);
			capabilities = nested_capabilities;
			[ ... ]
}

An unprivileged user with access to /dev/kvm can open a VM file descriptor and call the KVM_PPC_GET_COMPAT_CAPS ioctl. If the system is a nested guest (kvmhv_is_nestedv2() is true) but the parent hypervisor advertised no capabilities (nested_capabilities is 0), the ioctl handler directly triggers a WARN_ON_ONCE(!nested_capabilities).

This can occur naturally if plpar_guest_set_capabilities(0, 0) succeeds during kvmhv_nested_init(). This directly violates the KVM subsystem guidelines which explicitly forbid userspace-reachable WARN_ON assertions, as it can cause a host kernel panic (Denial of Service) if panic_on_warn is set.

[ ... ]

Documentation/virt/kvm/api.rst KVM_S390_KEYOP_SSKE · line 6625

Quoted 7 lines
Documentation/virt/kvm/api.rst +7 -0
+The ioctl uses ``copy_struct_from_user()`` and ``copy_struct_to_user()``
+to support extensible versioning across three cases:
+
+- If ``size`` is smaller than the kernel's struct size (old userspace,
+  new kernel), the kernel zero-pads the unknown trailing fields before
+  returning, and writes back ``size`` unchanged so userspace knows how
+  many bytes were filled.

[Severity: Medium]
Does this documentation accurately reflect the UAPI contract for struct padding and truncation on the return path?

The documentation incorrectly states that if the userspace struct is smaller, the kernel "zero-pads the unknown trailing fields before returning". This misleadingly implies it pads the userspace buffer (which would be a buffer overflow). In reality, the kernel strictly truncates trailing fields on output to userspace using copy_struct_to_user().

Additionally, it fails to document that when userspace provides a larger struct with zeroed trailing bytes, the kernel actively mutates the userspace 'size' field on success (via host_caps.size = min_t(...)) to reflect the kernel's smaller struct size.

Signature · 1 line
Sashiko AI review · https://sashiko.dev/#/patchset/[email protected]?part=4
reviewer Reviewed-by on v8 4/4
#10 lore raw

Re: [PATCH v8 4/4] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

In reply to Amit Machhiwal
Quoted 82 lines · 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. The documentation covers error code descriptions including E2BIG for forward compatibility, the extensible size-based versioning contract using KVM_PPC_COMPAT_CAPS_SIZE_VER0, the rationale for rejecting non-zero reserved fields to prevent ABI ambiguity, bit numbering clarification for IBM MSB-0 convention, and KVM-specific capability bit constants.

---
Changes in this version:
- Update E2BIG description: document PAGE_SIZE guard as first case; -E2BIG for usize > ksize is only returned when trailing bytes are non-zero; zero trailing bytes now succeed [Ritesh]
- Rewrite versioning paragraph as three explicit cases to match the corrected copy_struct_from_user() / copy_struct_to_user() contract, including the usize > ksize zero-trailing-bytes success path [Ritesh]

 Documentation/virt/kvm/api.rst | 89 ++++++++++++++++++++++++++++++++++
 1 file changed, 89 insertions(+)
Documentation/virt/kvm/api.rst +47 -0
index e3003a241d5b..e656d117cd0b 100644
@@ -6566,6 +6566,95 @@ KVM_S390_KEYOP_SSKE
   Sets the storage key for the guest address ``guest_addr`` to the key
   specified in ``key``, returning the previous value in ``key``.
 
+4.145 KVM_PPC_GET_COMPAT_CAPS
+-----------------------------
+:Capability: KVM_CAP_PPC_COMPAT_CAPS
+:Architectures: powerpc
+:Type: vm ioctl
+:Parameters: struct kvm_ppc_compat_caps (in/out)
+:Returns: 0 on success, negative value on failure
+
+Errors include:
+
+  ======== ============================================================
+  EFAULT   if ``struct kvm_ppc_compat_caps`` cannot be read from or
+           written to userspace
+  EINVAL   if the ``size`` field is smaller than
+           ``KVM_PPC_COMPAT_CAPS_SIZE_VER0``, if the ``flags`` field
+           is non-zero, or if the backend fails to retrieve or map
+           CPU compatibility capabilities
+  E2BIG    if ``size`` exceeds ``PAGE_SIZE`` (pathological input guard),
+           or if ``size`` is larger than the kernel's struct size and
+           the unknown trailing bytes are non-zero (new userspace on
+           old kernel with non-default fields set); in the latter case
+           the kernel writes back its own struct size into the ``size``
+           field so userspace can retry with the correct size
+  ENOTTY   if the backend does not implement the ``get_compat_caps``
+           operation (e.g., on non-HV KVM implementations where the
+           required KVM operations are not available)
+  ======== ============================================================
+
+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
+KVM on PowerNV (nested API v1) and KVM on PowerVM (nested API v2) platforms.
+
+::
+
+  struct kvm_ppc_compat_caps {
+	__u64	size;			/* Size of this structure */
+	__u64	flags;			/* Reserved for future use, must be 0 */
+	__u64	compat_capabilities;	/* Capabilities supported by the host */
+  };
+
+Before calling this ioctl, userspace must set the ``size`` field to
+``sizeof(struct kvm_ppc_compat_caps)`` and zero the ``flags`` field.
+The kernel rejects non-zero ``flags`` with ``-EINVAL`` to prevent

Documentation/virt/kvm/api.rst KVM_S390_KEYOP_SSKE · line 6625

Quoted 10 lines
Documentation/virt/kvm/api.rst +10 -0
+uninitialized stack values from being silently accepted, keeping the
+field available for future use without ABI ambiguity.
+
+The ioctl uses ``copy_struct_from_user()`` and ``copy_struct_to_user()``
+to support extensible versioning across three cases:
+
+- If ``size`` is smaller than the kernel's struct size (old userspace,
+  new kernel), the kernel zero-pads the unknown trailing fields before
+  returning, and writes back ``size`` unchanged so userspace knows how
+  many bytes were filled.

I agree with Sashiko comment here. This para is slightly misleading. This sounds like we are zero padding to userspace struct before returning. Whereas what we intend to say here is, when we copy user struct into kernel (copy_struct_from_user()), we zero pad the trailing bytes in kernel's struct.

Documentation/virt/kvm/api.rst KVM_S390_KEYOP_SSKE · line 6659

Quoted 8 lines
Documentation/virt/kvm/api.rst +7 -0
+- If ``size`` equals the kernel's struct size, the struct is copied
+  verbatim.
+- If ``size`` is larger than the kernel's struct size (new userspace,
+  old kernel) and the unknown trailing bytes are all zero, the call
+  succeeds as if the sizes matched. If any trailing bytes are non-zero,
+  the kernel returns ``-E2BIG`` and writes back its own struct size into
+  the ``size`` field so userspace can retry with the correct size.
 

BTW - I anyway feel this is too much. We can get rid of all 3 points which explains how struct copying is working. We have more than enough documentation around how copy_struct_{from|to}_user() works and we have also added the comments around the code. So I think this is just unnecessary.

We can just say:
+The ioctl uses ``copy_struct_from_user()`` and ``copy_struct_to_user()`` +to support extensible versioning.

With that taken care, please feel free to add:

#11 lore raw

Re: [PATCH v8 4/4] KVM: PPC: Document KVM_PPC_GET_COMPAT_CAPS ioctl

Quoted 4 lines · Ritesh Harjani
Quoted 2 lines · Amit Machhiwal

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

<snip>

Quoted 24 lines

Documentation/virt/kvm/api.rst KVM_S390_KEYOP_SSKE · line 6625

Quoted 8 lines
Documentation/virt/kvm/api.rst +8 -0
+
+The ioctl uses ``copy_struct_from_user()`` and ``copy_struct_to_user()``
+to support extensible versioning across three cases:
+
+- If ``size`` is smaller than the kernel's struct size (old userspace,
+  new kernel), the kernel zero-pads the unknown trailing fields before
+  returning, and writes back ``size`` unchanged so userspace knows how
+  many bytes were filled.

I agree with Sashiko comment here. This para is slightly misleading. This sounds like we are zero padding to userspace struct before returning. Whereas what we intend to say here is, when we copy user struct into kernel (copy_struct_from_user()), we zero pad the trailing bytes in kernel's struct.

Documentation/virt/kvm/api.rst KVM_S390_KEYOP_SSKE · line 6632

Quoted 8 lines

+- If ``size`` equals the kernel's struct size, the struct is copied

Documentation/virt/kvm/api.rst +6 -0
+  verbatim.
+- If ``size`` is larger than the kernel's struct size (new userspace,
+  old kernel) and the unknown trailing bytes are all zero, the call
+  succeeds as if the sizes matched. If any trailing bytes are non-zero,
+  the kernel returns ``-E2BIG`` and writes back its own struct size into
+  the ``size`` field so userspace can retry with the correct size.
Quoted 5 lines

BTW - I anyway feel this is too much. We can get rid of all 3 points which explains how struct copying is working. We have more than enough documentation around how copy_struct_{from|to}_user() works and we have also added the comments around the code. So I think this is just unnecessary.

Agreed on both counts. I'll drop the three-bullet block in the next version - v9 is on the way!

Quoted 4 lines

We can just say:
+The ioctl uses ``copy_struct_from_user()`` and ``copy_struct_to_user()`` +to support extensible versioning.

Sure, makes sense.

Quoted 4 lines

With that taken care, please feel free to add:

Thanks again for the detailed reviews on the series. Will carry the R-b in v9.

~Amit