[PATCH 0/4] KVM: x86: Document and enforce APIC base memory hole

[PATCH 0/4] KVM: x86: Document and enforce APIC base memory hole

[Tim Wiederhake]

When an in-kernel irqchip is enabled on x86, KVM installs a private
memory slot at the default APIC base address (0xfee00000) during vcpu
creation.  If user space has already mapped a memory region covering
that address, vcpu creation fails with -EEXIST.  The same happens in
reverse: mapping memory over the APIC base after vcpu creation also
fails with -EEXIST.

None of this is documented, and the error is reported far from where
the actual conflict is introduced.  A VMM developer hitting this has
to trace through KVM internals to understand what went wrong.

This series documents the two undocumented constraints (irqchip before
vcpu, APIC base memory hole) and adds early checks so the error is
reported at the ioctl that actually violates the constraint.

Patches 1-2 are documentation only.  Patches 3-4 add early validation
that turns a confusing -EEXIST at vcpu creation into an explicit error
at the point where the conflict is introduced.

Tested with a reproducer that exercises all six orderings of
{irqchip, memory, vcpu} creation against both overlapping and
non-overlapping memory regions.

Tim Wiederhake (4):
  KVM: x86: Document that KVM_CREATE_IRQCHIP must precede vcpu creation
  KVM: x86: Document APIC base address constraint for in-kernel irqchip
  KVM: x86: Reject KVM_CREATE_IRQCHIP if APIC base is already mapped
  KVM: x86: Reject user memory regions covering the APIC base

 Documentation/virt/kvm/api.rst |  8 +++++++-
 arch/x86/kvm/x86.c             | 11 +++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

-- 
2.52.0

[PATCH 1/4] 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
requirement.  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..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.
 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

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@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..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
> 

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

[Tim Wiederhake]

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@redhat.com>
---
 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).  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

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@redhat.com>
> ---
>  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
> 

[syzbot ci] Re: KVM: x86: Document and enforce APIC base memory hole

[syzbot ci]

syzbot ci has tested the following series

[v1] KVM: x86: Document and enforce APIC base memory hole
https://lore.kernel.org/all/20260706092021.3625908-2-twiederh@redhat.com
* [PATCH 1/4] KVM: x86: Document that KVM_CREATE_IRQCHIP must precede vcpu creation
* [PATCH 2/4] KVM: x86: Document APIC base address constraint for in-kernel irqchip
* [PATCH 3/4] KVM: x86: Reject KVM_CREATE_IRQCHIP if APIC base is already mapped
* [PATCH 4/4] KVM: x86: Reject user memory regions covering the APIC base

and found the following issue:
WARNING: suspicious RCU usage in gfn_to_memslot

Full report is available here:
https://ci.syzbot.org/series/b02ae7eb-bae2-492f-88f2-fa1b511c93cf

***

WARNING: suspicious RCU usage in gfn_to_memslot

tree:      kvm-next
URL:       https://kernel.googlesource.com/pub/scm/virt/kvm/kvm/
base:      8cd9520d35a6c38db6567e97dd93b1f11f185dc6
arch:      amd64
compiler:  Debian clang version 22.1.6 (++20260514074242+fc4aad7b5db3-1~exp1~20260514074407.73), Debian LLD 22.1.6
config:    https://ci.syzbot.org/builds/2e25da54-5ae8-4f08-889d-30a90ffbe688/config
syz repro: https://ci.syzbot.org/findings/707c5fee-46af-42c3-9700-7fc53ef58eb2/syz_repro

=============================
WARNING: suspicious RCU usage
syzkaller #0 Not tainted
-----------------------------
./include/linux/kvm_host.h:1084 suspicious rcu_dereference_check() usage!

other info that might help us debug this:


rcu_scheduler_active = 2, debug_locks = 1
1 lock held by syz.0.17/5871:
 #0: ffff888113334b40 (&kvm->lock){+.+.}-{4:4}, at: kvm_arch_vm_ioctl+0x8d1/0x1990 arch/x86/kvm/x86.c:7320

stack backtrace:
CPU: 0 UID: 0 PID: 5871 Comm: syz.0.17 Not tainted syzkaller #0 PREEMPT(full) 
Hardware name: QEMU Standard PC (Q35 + ICH9, 2009), BIOS 1.16.2-debian-1.16.2-1 04/01/2014
Call Trace:
 <TASK>
 dump_stack_lvl+0xe8/0x150 lib/dump_stack.c:120
 lockdep_rcu_suspicious+0x13f/0x1d0 kernel/locking/lockdep.c:6876
 __kvm_memslots include/linux/kvm_host.h:1082 [inline]
 kvm_memslots include/linux/kvm_host.h:1089 [inline]
 gfn_to_memslot+0x3df/0x420 virt/kvm/kvm_main.c:2630
 kvm_arch_vm_ioctl+0x1590/0x1990 arch/x86/kvm/x86.c:7340
 kvm_vm_ioctl+0x8f7/0xd30 virt/kvm/kvm_main.c:5381
 vfs_ioctl fs/ioctl.c:51 [inline]
 __do_sys_ioctl fs/ioctl.c:597 [inline]
 __se_sys_ioctl+0xfc/0x170 fs/ioctl.c:583
 do_syscall_x64 arch/x86/entry/syscall_64.c:63 [inline]
 do_syscall_64+0x174/0x580 arch/x86/entry/syscall_64.c:94
 entry_SYSCALL_64_after_hwframe+0x77/0x7f
RIP: 0033:0x7fd744b9ce59
Code: ff c3 66 2e 0f 1f 84 00 00 00 00 00 0f 1f 44 00 00 48 89 f8 48 89 f7 48 89 d6 48 89 ca 4d 89 c2 4d 89 c8 4c 8b 4c 24 08 0f 05 <48> 3d 01 f0 ff ff 73 01 c3 48 c7 c1 e8 ff ff ff f7 d8 64 89 01 48
RSP: 002b:00007fd7459b7028 EFLAGS: 00000246 ORIG_RAX: 0000000000000010
RAX: ffffffffffffffda RBX: 00007fd744e15fa0 RCX: 00007fd744b9ce59
RDX: 0000000000000000 RSI: 000000000000ae60 RDI: 0000000000000004
RBP: 00007fd744c32e6f R08: 0000000000000000 R09: 0000000000000000
R10: 0000000000000000 R11: 0000000000000246 R12: 0000000000000000
R13: 00007fd744e16038 R14: 00007fd744e15fa0 R15: 00007ffe5f70a5a8
 </TASK>


***

If these findings have caused you to resend the series or submit a
separate fix, please add the following tag to your commit message:
  Tested-by: syzbot@syzkaller.appspotmail.com

---
This report is generated by a bot. It may contain errors.
syzbot ci engineers can be reached at syzkaller@googlegroups.com.

To test a patch for this bug, please reply with `#syz test`
(should be on a separate line).

The patch should be attached to the email.
Note: arguments like custom git repos and branches are not supported.

Re: [PATCH 0/4] KVM: x86: Document and enforce APIC base memory hole

[Sean Christopherson]

On Mon, Jul 06, 2026, Tim Wiederhake wrote:
> When an in-kernel irqchip is enabled on x86, KVM installs a private
> memory slot at the default APIC base address (0xfee00000) during vcpu
> creation.  If user space has already mapped a memory region covering
> that address, vcpu creation fails with -EEXIST.  The same happens in
> reverse: mapping memory over the APIC base after vcpu creation also
> fails with -EEXIST.
> 
> None of this is documented, and the error is reported far from where
> the actual conflict is introduced.  A VMM developer hitting this has
> to trace through KVM internals to understand what went wrong.
> 
> This series documents the two undocumented constraints (irqchip before
> vcpu, APIC base memory hole) and adds early checks so the error is
> reported at the ioctl that actually violates the constraint.
> 
> Patches 1-2 are documentation only.  Patches 3-4 add early validation
> that turns a confusing -EEXIST at vcpu creation into an explicit error
> at the point where the conflict is introduced.

I'm 100% in favor of documenting the behavior, but I'm not exactly excited about
the enforcement.  It's not needed for KVM's safety, and while I appreciate that
such a goof would be somewhat annoying to debug, I have a hard time believing it's
a common failure.  I.e. I'm not convinced carrying the code is worth the marginal
benefits it provides.

Re: [PATCH 0/4] KVM: x86: Document and enforce APIC base memory hole

[Tim Wiederhake]

On Mon, 2026-07-06 at 15:26 -0700, Sean Christopherson wrote:
> On Mon, Jul 06, 2026, Tim Wiederhake wrote:
> > When an in-kernel irqchip is enabled on x86, KVM installs a private
> > memory slot at the default APIC base address (0xfee00000) during
> > vcpu
> > creation.  If user space has already mapped a memory region
> > covering
> > that address, vcpu creation fails with -EEXIST.  The same happens
> > in
> > reverse: mapping memory over the APIC base after vcpu creation also
> > fails with -EEXIST.
> > 
> > None of this is documented, and the error is reported far from
> > where
> > the actual conflict is introduced.  A VMM developer hitting this
> > has
> > to trace through KVM internals to understand what went wrong.
> > 
> > This series documents the two undocumented constraints (irqchip
> > before
> > vcpu, APIC base memory hole) and adds early checks so the error is
> > reported at the ioctl that actually violates the constraint.
> > 
> > Patches 1-2 are documentation only.  Patches 3-4 add early
> > validation
> > that turns a confusing -EEXIST at vcpu creation into an explicit
> > error
> > at the point where the conflict is introduced.
> 
> I'm 100% in favor of documenting the behavior, but I'm not exactly
> excited about
> the enforcement.  It's not needed for KVM's safety, and while I
> appreciate that
> such a goof would be somewhat annoying to debug, I have a hard time
> believing it's
> a common failure.  I.e. I'm not convinced carrying the code is worth
> the marginal
> benefits it provides.

FWIW, I did run into this exact issue myself and debugging it was
indeed quite a ride. The EEXIST from vcpu creation led me completely
astray and I was very close to just giving up. If I had, I wouldn't
have written this patch, and the failure would be perceived as even
less common.

I don't mind dropping patches 3 and 4 (the actual "enforcement"
patches) for v2, the documentation is more important in my opinion.
Still, if there is interest, I'd be more than happy to rework these
patches for eventual inclusion.

Thanks for the review,
Tim

Re: [PATCH 0/4] KVM: x86: Document and enforce APIC base memory hole

[Sean Christopherson]

On Wed, Jul 08, 2026, Tim Wiederhake wrote:
> On Mon, 2026-07-06 at 15:26 -0700, Sean Christopherson wrote:
> > On Mon, Jul 06, 2026, Tim Wiederhake wrote:
> > > When an in-kernel irqchip is enabled on x86, KVM installs a private
> > > memory slot at the default APIC base address (0xfee00000) during
> > > vcpu
> > > creation.  If user space has already mapped a memory region
> > > covering
> > > that address, vcpu creation fails with -EEXIST.  The same happens
> > > in
> > > reverse: mapping memory over the APIC base after vcpu creation also
> > > fails with -EEXIST.
> > > 
> > > None of this is documented, and the error is reported far from
> > > where
> > > the actual conflict is introduced.  A VMM developer hitting this
> > > has
> > > to trace through KVM internals to understand what went wrong.
> > > 
> > > This series documents the two undocumented constraints (irqchip
> > > before
> > > vcpu, APIC base memory hole) and adds early checks so the error is
> > > reported at the ioctl that actually violates the constraint.
> > > 
> > > Patches 1-2 are documentation only.  Patches 3-4 add early
> > > validation
> > > that turns a confusing -EEXIST at vcpu creation into an explicit
> > > error
> > > at the point where the conflict is introduced.
> > 
> > I'm 100% in favor of documenting the behavior, but I'm not exactly
> > excited about
> > the enforcement.  It's not needed for KVM's safety, and while I
> > appreciate that
> > such a goof would be somewhat annoying to debug, I have a hard time
> > believing it's
> > a common failure.  I.e. I'm not convinced carrying the code is worth
> > the marginal
> > benefits it provides.
> 
> FWIW, I did run into this exact issue myself and debugging it was

What were you doing (or trying to do?) when you ran afoul of this?  I ask because
maybe there's a way to help developers without impacting KVM's uABI.

> indeed quite a ride. The EEXIST from vcpu creation led me completely
> astray and I was very close to just giving up. If I had, I wouldn't
> have written this patch, and the failure would be perceived as even
> less common.
> 
> I don't mind dropping patches 3 and 4 (the actual "enforcement"
> patches) for v2, the documentation is more important in my opinion.
> Still, if there is interest, I'd be more than happy to rework these
> patches for eventual inclusion.
> 
> Thanks for the review,
> Tim
> 

Re: [PATCH 0/4] KVM: x86: Document and enforce APIC base memory hole

[Tim Wiederhake]

On Wed, 2026-07-08 at 06:41 -0700, Sean Christopherson wrote:
> On Wed, Jul 08, 2026, Tim Wiederhake wrote:
> > On Mon, 2026-07-06 at 15:26 -0700, Sean Christopherson wrote:
> > > On Mon, Jul 06, 2026, Tim Wiederhake wrote:
> > > > When an in-kernel irqchip is enabled on x86, KVM installs a
> > > > private
> > > > memory slot at the default APIC base address (0xfee00000)
> > > > during
> > > > vcpu
> > > > creation.  If user space has already mapped a memory region
> > > > covering
> > > > that address, vcpu creation fails with -EEXIST.  The same
> > > > happens
> > > > in
> > > > reverse: mapping memory over the APIC base after vcpu creation
> > > > also
> > > > fails with -EEXIST.
> > > > 
> > > > None of this is documented, and the error is reported far from
> > > > where
> > > > the actual conflict is introduced.  A VMM developer hitting
> > > > this
> > > > has
> > > > to trace through KVM internals to understand what went wrong.
> > > > 
> > > > This series documents the two undocumented constraints (irqchip
> > > > before
> > > > vcpu, APIC base memory hole) and adds early checks so the error
> > > > is
> > > > reported at the ioctl that actually violates the constraint.
> > > > 
> > > > Patches 1-2 are documentation only.  Patches 3-4 add early
> > > > validation
> > > > that turns a confusing -EEXIST at vcpu creation into an
> > > > explicit
> > > > error
> > > > at the point where the conflict is introduced.
> > > 
> > > I'm 100% in favor of documenting the behavior, but I'm not
> > > exactly
> > > excited about
> > > the enforcement.  It's not needed for KVM's safety, and while I
> > > appreciate that
> > > such a goof would be somewhat annoying to debug, I have a hard
> > > time
> > > believing it's
> > > a common failure.  I.e. I'm not convinced carrying the code is
> > > worth
> > > the marginal
> > > benefits it provides.
> > 
> > FWIW, I did run into this exact issue myself and debugging it was
> 
> What were you doing (or trying to do?) when you ran afoul of this?  I
> ask because
> maybe there's a way to help developers without impacting KVM's uABI.
> 

Experimenting, mostly with pmode code. For simplicity, I use a single
memory slot at 0x0. Due to an off-by-one error, I gave the VM only 2 GB
instead of 4 GB as intended. When I fixed that, suddenly vcpu creation
failed.

> > indeed quite a ride. The EEXIST from vcpu creation led me
> > completely
> > astray and I was very close to just giving up. If I had, I wouldn't
> > have written this patch, and the failure would be perceived as even
> > less common.
> > 
> > I don't mind dropping patches 3 and 4 (the actual "enforcement"
> > patches) for v2, the documentation is more important in my opinion.
> > Still, if there is interest, I'd be more than happy to rework these
> > patches for eventual inclusion.
> > 
> > Thanks for the review,
> > Tim
> >