[PATCH] Documentation: KVM: Fix the GICv5 KVM_IRQ_LINE PPI range

[PATCH] Documentation: KVM: Fix the GICv5 KVM_IRQ_LINE PPI range

[Karl Mehltretter]

KVM rejects GICv5 PPI irq_id values above 63, while the documented
range extends to 127. KVM also rejects PPIs not present in the
KVM_DEV_ARM_VGIC_USERSPACE_PPIS mask. That mask is populated by
KVM_DEV_ARM_VGIC_CTRL_INIT; reading it beforehand currently succeeds
but returns all zeroes.

Correct the range, document the mask restriction, and require the mask
to be queried after VGIC initialization.

Fixes: b88d05a893cb ("KVM: arm64: gic-v5: Support GICv5 interrupts with KVM_IRQ_LINE")
Assisted-by: Claude:claude-fable-5
Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
---
 Documentation/virt/kvm/api.rst                  | 4 +++-
 Documentation/virt/kvm/devices/arm-vgic-v5.rst | 3 +++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index e3003a241d5b0..6d8fd74174492 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -912,7 +912,9 @@ The irq_type field has the following values:
 	       in-kernel GICv5: SPI, irq_id between 0 and 65535 (incl.)
 - KVM_ARM_IRQ_TYPE_PPI:
 	       in-kernel GICv2/GICv3: PPI, irq_id between 16 and 31 (incl.)
-	       in-kernel GICv5: PPI, irq_id between 0 and 127 (incl.)
+	       in-kernel GICv5: PPI, irq_id between 0 and 63 (incl.), and
+	       only if present in the mask returned by the
+	       KVM_DEV_ARM_VGIC_USERSPACE_PPIS attribute
 
 (The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
 
diff --git a/Documentation/virt/kvm/devices/arm-vgic-v5.rst b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
index d328cf1e22c1f..e24aed0c4afcd 100644
--- a/Documentation/virt/kvm/devices/arm-vgic-v5.rst
+++ b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
@@ -35,6 +35,9 @@ Groups:
       populated with the userspace PPI mask. The lower __u64 contains the mask
       for the lower 64 PPIS, with the remaining 64 being in the second __u64.
 
+      Userspace must query this attribute after initializing the VGIC with
+      KVM_DEV_ARM_VGIC_CTRL_INIT.
+
       This is a read-only attribute, and cannot be set. Attempts to set it are
       rejected.
 
-- 
2.53.0

Re: [PATCH] Documentation: KVM: Fix the GICv5 KVM_IRQ_LINE PPI range

[Marc Zyngier]

On Sat, 15 Aug 2026 10:25:37 +0100,
Karl Mehltretter <kmehltretter@gmail.com> wrote:
> 
> KVM rejects GICv5 PPI irq_id values above 63, while the documented
> range extends to 127. KVM also rejects PPIs not present in the

This is on purpose, and that's not a bug.

> KVM_DEV_ARM_VGIC_USERSPACE_PPIS mask. That mask is populated by
> KVM_DEV_ARM_VGIC_CTRL_INIT; reading it beforehand currently succeeds
> but returns all zeroes.
> 
> Correct the range, document the mask restriction, and require the mask
> to be queried after VGIC initialization.
> 
> Fixes: b88d05a893cb ("KVM: arm64: gic-v5: Support GICv5 interrupts with KVM_IRQ_LINE")
> Assisted-by: Claude:claude-fable-5
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
>  Documentation/virt/kvm/api.rst                  | 4 +++-
>  Documentation/virt/kvm/devices/arm-vgic-v5.rst | 3 +++
>  2 files changed, 6 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index e3003a241d5b0..6d8fd74174492 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -912,7 +912,9 @@ The irq_type field has the following values:
>  	       in-kernel GICv5: SPI, irq_id between 0 and 65535 (incl.)
>  - KVM_ARM_IRQ_TYPE_PPI:
>  	       in-kernel GICv2/GICv3: PPI, irq_id between 16 and 31 (incl.)
> -	       in-kernel GICv5: PPI, irq_id between 0 and 127 (incl.)
> +	       in-kernel GICv5: PPI, irq_id between 0 and 63 (incl.), and

No. Please understand the difference between *implementation* and
*architecture*.

Also, the GICv5 architecture mandates which PPI is used for which
device for the range 0-63. This is not a carbon copy of the previous
versions.

> +	       only if present in the mask returned by the
> +	       KVM_DEV_ARM_VGIC_USERSPACE_PPIS attribute

Which, if you look carefully enough, returns a 128bit mask, as per the
architecture.

>  
>  (The irq_id field thus corresponds nicely to the IRQ ID in the ARM GIC specs)
>  
> diff --git a/Documentation/virt/kvm/devices/arm-vgic-v5.rst b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
> index d328cf1e22c1f..e24aed0c4afcd 100644
> --- a/Documentation/virt/kvm/devices/arm-vgic-v5.rst
> +++ b/Documentation/virt/kvm/devices/arm-vgic-v5.rst
> @@ -35,6 +35,9 @@ Groups:
>        populated with the userspace PPI mask. The lower __u64 contains the mask
>        for the lower 64 PPIS, with the remaining 64 being in the second __u64.
>  
> +      Userspace must query this attribute after initializing the VGIC with
> +      KVM_DEV_ARM_VGIC_CTRL_INIT.
> +

Must? Why? Userspace can perfectly live with ever querying this.

	M.

-- 
Without deviation from the norm, progress is not possible.

Re: [PATCH] Documentation: KVM: Fix the GICv5 KVM_IRQ_LINE PPI range

[Karl Mehltretter]

On Sat, Aug 15, 2026 at 11:57:24AM +0100, Marc Zyngier wrote:
> > +	       in-kernel GICv5: PPI, irq_id between 0 and 63 (incl.), and
> 
> No. Please understand the difference between *implementation* and
> *architecture*.

Got it. That distinction could perhaps be clearer in api.rst, but 0-127
is intentional, not a missed doc update.

> > +      Userspace must query this attribute after initializing the VGIC with
> > +      KVM_DEV_ARM_VGIC_CTRL_INIT.
> > +
> 
> Must? Why? Userspace can perfectly live with ever querying this.

Hah, yes. I meant "if you query this, you must do so after init
to get anything other than zero"

Please consider this patch withdrawn.

Thanks,
Karl