[RFC PATCH v2 23/31] KVM: selftests: Check that a masked higher-plane timer is no event

From: David Woodhouse

Date: Fri Nov 13 2026 - 15:05:49 EST


From: David Woodhouse <dwmw@xxxxxxxxxxxx>

A LAPIC timer that expires under a masked LVTT latches the expiry but
is never injected. A higher plane that arms its timer and then masks
LVTT must therefore not count as having a pending event, or every run
of the lower plane ends in a KVM_EXIT_HYPERV_VTL_INTERRUPT exit (or a
forced entry) with nothing for the higher plane to take.

The plane-1 twin arms a 50ms one-shot timer, masks LVTT and is
suspended like a userspace VTL switch. Once KVM_GET_LAPIC shows the
timer expired, plane 0 must run its guest code to GUEST_DONE.

Signed-off-by: David Woodhouse <dwmw@xxxxxxxxxxxx>
---
tools/testing/selftests/kvm/Makefile.kvm | 1 +
.../kvm/x86/planes_vtl_timer_mask_test.c | 177 ++++++++++++++++++
2 files changed, 178 insertions(+)
create mode 100644 tools/testing/selftests/kvm/x86/planes_vtl_timer_mask_test.c

diff --git a/tools/testing/selftests/kvm/Makefile.kvm b/tools/testing/selftests/kvm/Makefile.kvm
index 250b324d0881..c6ad866a0b0d 100644
--- a/tools/testing/selftests/kvm/Makefile.kvm
+++ b/tools/testing/selftests/kvm/Makefile.kvm
@@ -115,6 +115,7 @@ TEST_GEN_PROGS_x86 += x86/platform_info_test
TEST_GEN_PROGS_x86 += x86/plane_x86_test
TEST_GEN_PROGS_x86 += x86/planes_test
TEST_GEN_PROGS_x86 += x86/planes_vtl_entry_test
+TEST_GEN_PROGS_x86 += x86/planes_vtl_timer_mask_test
TEST_GEN_PROGS_x86 += x86/pmu_counters_test
TEST_GEN_PROGS_x86 += x86/pmu_event_filter_test
TEST_GEN_PROGS_x86 += x86/private_mem_conversions_test
diff --git a/tools/testing/selftests/kvm/x86/planes_vtl_timer_mask_test.c b/tools/testing/selftests/kvm/x86/planes_vtl_timer_mask_test.c
new file mode 100644
index 000000000000..e6b2b9eaa9c6
--- /dev/null
+++ b/tools/testing/selftests/kvm/x86/planes_vtl_timer_mask_test.c
@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Test that a higher plane's masked LAPIC timer does not hold the lower
+ * plane hostage.
+ *
+ * A LAPIC timer that expires while LVTT is masked still latches its
+ * expiry, but the interrupt is never injected. If the latched expiry
+ * counted as a pending higher-plane event, the lower plane would exit
+ * with KVM_EXIT_HYPERV_VTL_INTERRUPT on every run, and a VMM that enters
+ * the higher plane in response would find nothing to deliver.
+ *
+ * The plane-1 twin arms a one-shot timer, masks LVTT before it can fire,
+ * and is then suspended exactly like a userspace VTL switch. Once the
+ * timer has expired, plane 0 must run its guest code.
+ */
+#include <errno.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <sys/mman.h>
+#include <unistd.h>
+
+#include "test_util.h"
+#include "kvm_util.h"
+#include "processor.h"
+#include "apic.h"
+
+#ifndef KVM_EXIT_HYPERV_VTL_INTERRUPT
+#define KVM_EXIT_HYPERV_VTL_INTERRUPT 4
+#endif
+
+#define TEST_VECTOR 0xe0
+#define TWIN_SYNC_PORT 0x7e
+#define TWIN_STACK_PAGES 4
+#define TDCR_DIVIDE_BY_1 0xb
+/* 50ms at KVM's default 1GHz APIC bus: long enough to mask LVTT first. */
+#define TIMER_COUNT 50000000u
+
+static void twin_sync(uint8_t stage)
+{
+ asm volatile("outb %0, %1" :: "a"(stage), "Nd"((uint16_t)TWIN_SYNC_PORT));
+}
+
+/* Runs with IF clear; the masked timer must never interrupt it anyway. */
+static void twin_guest_code(void)
+{
+ x2apic_enable();
+ x2apic_write_reg(APIC_TDCR, TDCR_DIVIDE_BY_1);
+ x2apic_write_reg(APIC_LVTT, APIC_LVT_TIMER_ONESHOT | TEST_VECTOR);
+ x2apic_write_reg(APIC_TMICT, TIMER_COUNT);
+ x2apic_write_reg(APIC_LVTT, APIC_LVT_MASKED | APIC_LVT_TIMER_ONESHOT |
+ TEST_VECTOR);
+ for (;;)
+ twin_sync(1);
+}
+
+static void plane0_guest_code(void)
+{
+ GUEST_SYNC(0);
+ GUEST_SYNC(1);
+ GUEST_DONE();
+}
+
+static void set_plane_run_state(int vcpu_fd, u64 state)
+{
+ int r = ioctl(vcpu_fd, KVM_SET_PLANE_RUN_STATE, &state);
+
+ TEST_ASSERT(!r, "KVM_SET_PLANE_RUN_STATE(0x%lx) failed: errno %d",
+ state, errno);
+}
+
+static u32 twin_tmcct(int twin_fd)
+{
+ struct kvm_lapic_state lapic;
+ int r = ioctl(twin_fd, KVM_GET_LAPIC, &lapic);
+
+ TEST_ASSERT(!r, "KVM_GET_LAPIC on twin failed: errno %d", errno);
+ return *(u32 *)&lapic.regs[APIC_TMCCT];
+}
+
+int main(int argc, char *argv[])
+{
+ struct kvm_sregs sregs;
+ struct kvm_regs regs;
+ struct kvm_run *twin_run;
+ struct kvm_vcpu *vcpu0;
+ struct kvm_vm *vm;
+ struct ucall uc;
+ int plane_fd, twin_fd, mmap_sz, r, i;
+
+ kvm_force_split_irqchip = true;
+ vm = __vm_create(VM_SHAPE_DEFAULT, 1, 0);
+ kvm_force_split_irqchip = false;
+
+ TEST_REQUIRE(vm_check_cap(vm, KVM_CAP_PLANES) >= 1);
+ TEST_REQUIRE(__vm_enable_cap(vm, KVM_CAP_PLANES, 2) == 0);
+ TEST_REQUIRE(kvm_check_cap(KVM_CAP_HYPERV_FORWARD_HCALL) &
+ KVM_HYPERV_HCALL_VTL_CALLS);
+ /* VTL interrupt exits belong to the userspace-switch VTL contract. */
+ vm_enable_cap(vm, KVM_CAP_HYPERV_FORWARD_HCALL,
+ KVM_HYPERV_HCALL_VTL_CALLS);
+
+ vcpu0 = vm_vcpu_add(vm, 0, plane0_guest_code);
+
+ plane_fd = __vm_ioctl(vm, KVM_CREATE_PLANE, (void *)1UL);
+ TEST_ASSERT(plane_fd >= 0, "KVM_CREATE_PLANE failed: errno %d", errno);
+ twin_fd = __kvm_ioctl(plane_fd, KVM_CREATE_VCPU, NULL);
+ TEST_ASSERT(twin_fd >= 0, "KVM_CREATE_VCPU on plane 1 failed: errno %d",
+ errno);
+
+ mmap_sz = ioctl(vm->kvm_fd, KVM_GET_VCPU_MMAP_SIZE, NULL);
+ TEST_ASSERT(mmap_sz >= (int)sizeof(*twin_run),
+ "KVM_GET_VCPU_MMAP_SIZE failed");
+ twin_run = mmap(NULL, mmap_sz, PROT_READ | PROT_WRITE, MAP_SHARED,
+ twin_fd, 0);
+ TEST_ASSERT(twin_run != MAP_FAILED, "mmap of twin kvm_run failed");
+
+ /* Same mode and page tables as plane 0, own code and stack, IF clear. */
+ vcpu_sregs_get(vcpu0, &sregs);
+ r = ioctl(twin_fd, KVM_SET_SREGS, &sregs);
+ TEST_ASSERT(!r, "KVM_SET_SREGS on twin failed: errno %d", errno);
+
+ r = ioctl(twin_fd, KVM_GET_REGS, &regs);
+ TEST_ASSERT(!r, "KVM_GET_REGS on twin failed: errno %d", errno);
+ regs.rip = (unsigned long)twin_guest_code;
+ regs.rsp = vm_alloc_stack(vm, TWIN_STACK_PAGES);
+ regs.rflags = 0x2;
+ r = ioctl(twin_fd, KVM_SET_REGS, &regs);
+ TEST_ASSERT(!r, "KVM_SET_REGS on twin failed: errno %d", errno);
+
+ /* Run the twin until it has armed and masked its timer. */
+ set_plane_run_state(twin_fd, 0);
+ set_plane_run_state(vcpu0->fd, KVM_PLANE_RUN_STATE_USER_HOLD);
+ r = ioctl(vcpu0->fd, KVM_RUN, NULL);
+ TEST_ASSERT(!r, "KVM_RUN (twin runnable) failed: errno %d", errno);
+ TEST_ASSERT_EQ(twin_run->exit_reason, KVM_EXIT_IO);
+ TEST_ASSERT_EQ(twin_run->io.port, TWIN_SYNC_PORT);
+
+ /* Suspend the twin and let its masked timer expire. */
+ set_plane_run_state(twin_fd, KVM_PLANE_RUN_STATE_USER_HOLD);
+ set_plane_run_state(vcpu0->fd, 0);
+ for (i = 0; i < 100 && twin_tmcct(twin_fd); i++)
+ usleep(10000);
+ TEST_ASSERT(!twin_tmcct(twin_fd), "The twin's timer did not expire");
+
+ /*
+ * Plane 0 must make progress: the latched expiry of a masked timer
+ * is not an event of the twin's.
+ */
+ for (i = 0; i < 3; i++) {
+ vcpu_run(vcpu0);
+ /* A masked higher-plane timer must not count as an event. */
+ TEST_ASSERT(vcpu0->run->exit_reason == KVM_EXIT_IO,
+ "Plane 0 did not run: exit %u (%s), hyperv type %u",
+ vcpu0->run->exit_reason,
+ exit_reason_str(vcpu0->run->exit_reason),
+ vcpu0->run->exit_reason == KVM_EXIT_HYPERV ?
+ vcpu0->run->hyperv.type : 0);
+ switch (get_ucall(vcpu0, &uc)) {
+ case UCALL_SYNC:
+ TEST_ASSERT_EQ(uc.args[1], i);
+ break;
+ case UCALL_DONE:
+ TEST_ASSERT_EQ(i, 2);
+ break;
+ case UCALL_ABORT:
+ REPORT_GUEST_ASSERT(uc);
+ default:
+ TEST_FAIL("Unexpected ucall %lu", uc.cmd);
+ }
+ }
+
+ kvm_munmap(twin_run, mmap_sz);
+ close(twin_fd);
+ close(plane_fd);
+ kvm_vm_free(vm);
+ return 0;
+}
--
2.50.1