[PATCH v2 0/2] KVM: x86: Document APIC base memory hole constraint

[PATCH v2 0/2] KVM: x86: Document APIC base memory hole constraint

[Tim Wiederhake]

When virtual APIC access acceleration is enabled on x86 (APICv on
Intel, AVIC on AMD), vcpu creation installs a private memory slot at
the default APIC base address (0xfee00000).  If user space maps a
memory region covering that address, vcpu creation fails with -EEXIST.
This is not documented and very puzzling when it happens.

This series documents two undocumented constraints:

  1/2  KVM_CREATE_IRQCHIP must precede vcpu creation
  2/2  APIC base address memory hole when APIC acceleration is enabled

Thanks to Sean Christopherson for the thorough review of v1.

Changes since v1:
  - Dropped enforcement patches (3/4, 4/4) per review feedback.
  - Patch 1/2: Reworded to avoid implying that KVM_CREATE_IRQCHIP is
    mandatory.
  - Patch 2/2: Reworded to reflect that the APIC access page is not
    installed in every case. Added note about KVM_CAP_SPLIT_IRQCHIP
    having the same constraint.

v1: https://lore.kernel.org/kvm/20260706092021.3625908-2-twiederh@redhat.com/

Tim Wiederhake (2):
  KVM: x86: Document that KVM_CREATE_IRQCHIP must precede vcpu creation
  KVM: x86: Document APIC base address constraint for in-kernel irqchip

 Documentation/virt/kvm/api.rst | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

-- 
2.52.0

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

[Tim Wiederhake]

The kernel rejects KVM_CREATE_IRQCHIP with -EINVAL if any vcpus have
already been created, but the API documentation does not mention this
constraint.  Add a note.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
---
 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..270c3f0d668f 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 can only be
+called before creating any 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

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

[Tim Wiederhake]

When virtual APIC access acceleration is enabled (APICv on Intel, AVIC
on AMD), vcpu creation installs a private memory slot at the default
APIC base address (0xfee00000).  If a user memory region overlaps this
address, vcpu creation fails with EEXIST.  The same error occurs when
installing an overlapping user memory region after vcpu creation.

This also applies when using KVM_CAP_SPLIT_IRQCHIP.

This constraint is not documented anywhere.  Add a note to the
KVM_CREATE_IRQCHIP and KVM_CAP_SPLIT_IRQCHIP documentation.

Signed-off-by: Tim Wiederhake <twiederh@redhat.com>
---
 Documentation/virt/kvm/api.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 270c3f0d668f..8a6210b4cd56 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -863,6 +863,14 @@ 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, vcpu creation may install a private 4 KiB memory slot at the default
+APIC base address (0xfee00000).  User memory regions must not overlap this
+address; doing so will cause vcpu creation to fail with ``EEXIST``, or the
+memory region to be rejected if created after the vcpu.  This occurs when
+APIC access acceleration is enabled (APICv on Intel, AVIC on AMD), which is
+the default on supported hardware.  The same constraint applies when using
+``KVM_CAP_SPLIT_IRQCHIP``.
+
 Note that on s390 the KVM_CAP_S390_IRQCHIP vm capability needs to be enabled
 before KVM_CREATE_IRQCHIP can be used.
 
@@ -7921,6 +7929,10 @@ used in the IRQ routing table.  The first args[0] MSI routes are reserved
 for the IOAPIC pins.  Whenever the LAPIC receives an EOI for these routes,
 a KVM_EXIT_IOAPIC_EOI vmexit will be reported to userspace.
 
+As with ``KVM_CREATE_IRQCHIP``, vcpu creation may install a private memory
+slot at the APIC base address (0xfee00000) that must not overlap user memory
+regions.  See ``KVM_CREATE_IRQCHIP`` for details.
+
 Fails if VCPU has already been created, or if the irqchip is already in the
 kernel (i.e. KVM_CREATE_IRQCHIP has already been called).
 
-- 
2.52.0