Re: [PATCH 2/4] KVM: x86: Document APIC base address constraint for in-kernel irqchip

[Sean Christopherson]

On Mon, Jul 06, 2026, Tim Wiederhake wrote:
> When an in-kernel irqchip is enabled, vcpu creation installs a private
> 4 KiB memory slot at the default APIC base address (0xfee00000).  If a
> user memory region overlaps this slot, vcpu creation fails with EEXIST.
> The same error occurs when installing an overlapping user memory region
> after vcpu creation.
> 
> This constraint is not documented anywhere.  Add a note to the
> KVM_CREATE_IRQCHIP documentation.
> 
> Signed-off-by: Tim Wiederhake <twiederh@xxxxxxxxxx>
> ---
>  Documentation/virt/kvm/api.rst | 5 +++++
>  1 file changed, 5 insertions(+)
> 
> diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
> index ec5bf99ff8b8..da8beb80699a 100644
> --- a/Documentation/virt/kvm/api.rst
> +++ b/Documentation/virt/kvm/api.rst
> @@ -863,6 +863,11 @@ KVM_CREATE_DEVICE, which also supports creating a GICv2.  Using
>  KVM_CREATE_DEVICE is preferred over KVM_CREATE_IRQCHIP for GICv2.
>  On s390, a dummy irq routing table is created.
>  
> +On x86, when an in-kernel irqchip is enabled, KVM reserves a private memory
> +slot for the local APIC at the default APIC base address (0xfee00000).  

KVM doesn't actually do this, at least not until patches 3 and 4, as the APIC
access page is allocated if and only if any form of virtual APIC acceleration
is enabled (in practice, APICv or AVIC, but I'm being pedantic because KVM
enables TPR access accleration even if APICv isn't fully supported).

E.g. if you disable flexpriority_enabled (Intel only) and enable_apicv/avic, KVM
should let userspace create a memslot at the APIC base (I haven't actually tried
this).  The guest won't be able to access its APIC via MMIO, but vCPU creation
shouldn't fail.

Another wrinkle is that the local APIC behavior applies to KVM_CAP_SPLIT_IRQCHIP
as well, i.e. ideally that "ioctl" would call out the local APIC base interaction
too (maybe as a redirect?).

And for KVM_CREATE_IRQCHIP specifically, creating a memslot that overlays the
I/O APIC will also be problematic.  It won't lead to an explicit ioctl failure,
but like the local APIC, creating such an overlay will effectively prevent the
guest from accessing the I/O APIC (via MMIO).

> +User
> +space must not map guest memory that covers this address and must leave a 4 KiB
> +hole in the guest physical memory map at this address.
> +
>  Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled
>  before KVM_CREATE_IRQCHIP can be used.
>  
> -- 
> 2.52.0
>