[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

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

[Marc Zyngier]

On Sat, 15 Aug 2026 14:07:38 +0100,
Karl Mehltretter <kmehltretter@gmail.com> wrote:
> 
> 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.

This is on purpose.

We are not going to go and update the documentation each time
something change in KVM (such as a new interrupt being controllable
from the VMM). So by describing everything in architectural terms and
giving the interfaces for userspace to introspect the implementation,
we avoid having to disclose all the decisions that we make when
implementing the hypervisor.

This is valid for the whole of KVM/arm64, not just the GIC, and
represent the intent of the ARM architecture.

Thanks,

	M.

-- 
Jazz isn't dead. It just smells funny.