Re: [PATCH 1/4] KVM: x86: Document that KVM_CREATE_IRQCHIP must precede vcpu creation

[Sean Christopherson]

On Mon, Jul 06, 2026, Tim Wiederhake wrote:
> The kernel rejects KVM_CREATE_IRQCHIP with -EINVAL if any vcpus have
> already been created, but the API documentation does not mention this
> requirement.  Add a note.
> 
> Signed-off-by: Tim Wiederhake <twiederh@xxxxxxxxxx>
> ---
>  Documentation/virt/kvm/api.rst | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index 52bbbb553ce1..ec5bf99ff8b8 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -856,7 +856,8 @@ Writes the floating point state to the vcpu.
>  Creates an interrupt controller model in the kernel.
>  On x86, creates a virtual ioapic, a virtual PIC (two PICs, nested), and sets up
>  future vcpus to have a local APIC.  IRQ routing for GSIs 0-15 is set to both
> -PIC and IOAPIC; GSI 16-23 only go to the IOAPIC.
> +PIC and IOAPIC; GSI 16-23 only go to the IOAPIC.  This ioctl must be called
> +before creating any vcpus.

I would say instead "This ioctl can only be called before creating any vCPUs",
because a reasonable reading of "must be called before" is that userpace must
*always* call KVM_CREATE_IRQCHIP before creating vCPUs.

>  On arm64, a GICv2 is created. Any other GIC versions require the usage of
>  KVM_CREATE_DEVICE, which also supports creating a GICv2.  Using
>  KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2.
> -- 
> 2.52.0
>