[PATCH 4/4] KVM: selftests: Add Hyper-V hypercall forwarding test
From: David Woodhouse
Date: Wed Nov 11 2026 - 16:05:25 EST
From: David Woodhouse <dwmw@xxxxxxxxxxxx>
Cover KVM_CAP_HYPERV_FORWARD_HCALL:
- the feature mask reports forwarding and RAISE_UD, and rejects bits
it does not report;
- with nothing enabled, an unknown hypercall fails in KVM;
- with forwarding enabled, it exits to userspace in memory-based and
fast form with the control value and parameters, and the guest
sees the status userspace supplies (and, for the fast form, the XMM
output userspace writes through KVM_SET_FPU);
- the result reaches the guest as the full 64-bit value userspace
wrote, bit 63 included;
- KVM_HYPERV_HCALL_UD in 'flags' fails KVM_RUN with EINVAL until
RAISE_UD is enabled, and then raises #UD at the hypercall;
- KVM reports every exit with 'flags' cleared, even after a completion
that set them;
- disabling everything restores the in-kernel failure.
Signed-off-by: David Woodhouse <dwmw@xxxxxxxxxxxx>
---
tools/testing/selftests/kvm/Makefile.kvm | 1 +
.../selftests/kvm/x86/hyperv_forward_hcall.c | 268 ++++++++++++++++++
2 files changed, 269 insertions(+)
create mode 100644 tools/testing/selftests/kvm/x86/hyperv_forward_hcall.c
diff --git a/tools/testing/selftests/kvm/Makefile.kvm b/tools/testing/selftests/kvm/Makefile.kvm
index 17a4256e9081..cc01edd07064 100644
--- a/tools/testing/selftests/kvm/Makefile.kvm
+++ b/tools/testing/selftests/kvm/Makefile.kvm
@@ -89,6 +89,7 @@ TEST_GEN_PROGS_x86 += x86/hyperv_cpuid
TEST_GEN_PROGS_x86 += x86/hyperv_evmcs
TEST_GEN_PROGS_x86 += x86/hyperv_extended_hypercalls
TEST_GEN_PROGS_x86 += x86/hyperv_features
+TEST_GEN_PROGS_x86 += x86/hyperv_forward_hcall
TEST_GEN_PROGS_x86 += x86/hyperv_ipi
TEST_GEN_PROGS_x86 += x86/hyperv_svm_test
TEST_GEN_PROGS_x86 += x86/hyperv_tlb_flush
diff --git a/tools/testing/selftests/kvm/x86/hyperv_forward_hcall.c b/tools/testing/selftests/kvm/x86/hyperv_forward_hcall.c
new file mode 100644
index 000000000000..5afc99ed533c
--- /dev/null
+++ b/tools/testing/selftests/kvm/x86/hyperv_forward_hcall.c
@@ -0,0 +1,268 @@
+// SPDX-License-Identifier: GPL-2.0-only
+/*
+ * Test KVM_CAP_HYPERV_FORWARD_HCALL: the feature mask KVM reports and
+ * accepts, Hyper-V hypercalls that KVM does not implement exiting to
+ * userspace in memory-based and fast form, with userspace supplying the
+ * result and the XMM output, and a userspace completion raising #UD
+ * through the exit's flags.
+ */
+#include "test_util.h"
+#include "kvm_util.h"
+#include "processor.h"
+#include "hyperv.h"
+
+/* A hypercall code KVM does not implement (HvCallGetVpRegisters). */
+#define HVCALL_TEST_CODE 0x50
+
+#define FAST_PARAM0 0x1122334455667788ULL
+#define FAST_PARAM1 0x99aabbccddeeff00ULL
+#define XMM_IN_MARKER 0x5157ca11c0ffee00ULL
+#define XMM_OUT_MARKER 0x0de1ba5eba5eba11ULL
+#define USERSPACE_STATUS 0x55AA
+#define FULL_RESULT (BIT_ULL(63) | USERSPACE_STATUS)
+
+enum {
+ STAGE_DISABLED = 1,
+ STAGE_MEMORY,
+ STAGE_FAST,
+ STAGE_RESULT_FULL,
+ STAGE_RAISE_UD,
+ STAGE_FLAGS_CLEARED,
+ STAGE_REDISABLED,
+};
+
+static void guest_code(gpa_t pgs_gpa)
+{
+ __sse128_u in, out;
+ u64 status;
+ u8 vector;
+
+ wrmsr(HV_X64_MSR_GUEST_OS_ID, HYPERV_LINUX_OS_ID);
+ wrmsr(HV_X64_MSR_HYPERCALL, pgs_gpa);
+
+ /* Nothing enabled: KVM fails the call itself. */
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE, pgs_gpa + PAGE_SIZE,
+ pgs_gpa + 2 * PAGE_SIZE, &status);
+ GUEST_ASSERT(!vector);
+ GUEST_ASSERT_EQ(status & 0xffff, HV_STATUS_INVALID_HYPERCALL_CODE);
+ GUEST_SYNC(STAGE_DISABLED);
+
+ /* Forwarding enabled: userspace supplies the status. */
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE, pgs_gpa + PAGE_SIZE,
+ pgs_gpa + 2 * PAGE_SIZE, &status);
+ GUEST_ASSERT(!vector);
+ GUEST_ASSERT_EQ(status, USERSPACE_STATUS);
+ GUEST_SYNC(STAGE_MEMORY);
+
+ /*
+ * Fast form: the register parameters and XMM0 reach userspace, and
+ * the XMM1 value userspace writes reaches the guest.
+ */
+ in.as_u64[0] = XMM_IN_MARKER;
+ in.as_u64[1] = XMM_IN_MARKER + 1;
+ out.as_u64[0] = 0;
+ out.as_u64[1] = 0;
+ write_sse_reg(0, &in.vec);
+ write_sse_reg(1, &out.vec);
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE | HV_HYPERCALL_FAST_BIT,
+ FAST_PARAM0, FAST_PARAM1, &status);
+ read_sse_reg(1, &out.vec);
+ GUEST_ASSERT(!vector);
+ GUEST_ASSERT_EQ(status, USERSPACE_STATUS);
+ GUEST_ASSERT_EQ(out.as_u64[0], XMM_OUT_MARKER);
+ GUEST_ASSERT_EQ(out.as_u64[1], XMM_OUT_MARKER + 1);
+ GUEST_SYNC(STAGE_FAST);
+
+ /* The result reaches the guest as all 64 bits userspace wrote. */
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE, pgs_gpa + PAGE_SIZE,
+ pgs_gpa + 2 * PAGE_SIZE, &status);
+ GUEST_ASSERT(!vector);
+ GUEST_ASSERT_EQ(status, FULL_RESULT);
+ GUEST_SYNC(STAGE_RESULT_FULL);
+
+ /* With KVM_HYPERV_HCALL_RAISE_UD, the UD flag faults the call. */
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE, pgs_gpa + PAGE_SIZE,
+ pgs_gpa + 2 * PAGE_SIZE, &status);
+ GUEST_ASSERT_EQ(vector, UD_VECTOR);
+ GUEST_SYNC(STAGE_RAISE_UD);
+
+ /* The next exit starts with the flags cleared again. */
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE, pgs_gpa + PAGE_SIZE,
+ pgs_gpa + 2 * PAGE_SIZE, &status);
+ GUEST_ASSERT(!vector);
+ GUEST_ASSERT_EQ(status, USERSPACE_STATUS);
+ GUEST_SYNC(STAGE_FLAGS_CLEARED);
+
+ /* Everything disabled again. */
+ vector = __hyperv_hypercall(HVCALL_TEST_CODE, pgs_gpa + PAGE_SIZE,
+ pgs_gpa + 2 * PAGE_SIZE, &status);
+ GUEST_ASSERT(!vector);
+ GUEST_ASSERT_EQ(status & 0xffff, HV_STATUS_INVALID_HYPERCALL_CODE);
+ GUEST_SYNC(STAGE_REDISABLED);
+
+ GUEST_DONE();
+}
+
+static void check_hcall_exit(struct kvm_vcpu *vcpu, u64 expect_control,
+ u64 expect_in, u64 expect_out)
+{
+ struct kvm_run *run = vcpu->run;
+
+ TEST_ASSERT_EQ(run->exit_reason, KVM_EXIT_HYPERV);
+ TEST_ASSERT_EQ(run->hyperv.type, KVM_EXIT_HYPERV_HCALL);
+ TEST_ASSERT_EQ(run->hyperv.u.hcall.input, expect_control);
+ TEST_ASSERT_EQ(run->hyperv.u.hcall.params[0], expect_in);
+ TEST_ASSERT_EQ(run->hyperv.u.hcall.params[1], expect_out);
+ TEST_ASSERT_EQ(run->hyperv.u.hcall.flags, 0);
+}
+
+/*
+ * Without KVM_HYPERV_HCALL_RAISE_UD, KVM_HYPERV_HCALL_UD is an unknown
+ * flag: KVM_RUN must fail with EINVAL and leave the exit pending.
+ */
+static void check_flags_refused(struct kvm_vcpu *vcpu)
+{
+ int r;
+
+ vcpu->run->hyperv.u.hcall.flags = KVM_HYPERV_HCALL_UD;
+ r = __vcpu_run(vcpu);
+ TEST_ASSERT(r == -1 && errno == EINVAL,
+ "KVM_RUN with an unenabled hcall flag: r = %d, errno = %d",
+ r, errno);
+ vcpu->run->hyperv.u.hcall.flags = 0;
+}
+
+static void handle_fast_hcall(struct kvm_vcpu *vcpu)
+{
+ struct kvm_fpu fpu;
+
+ check_hcall_exit(vcpu, HVCALL_TEST_CODE | HV_HYPERCALL_FAST_BIT,
+ FAST_PARAM0, FAST_PARAM1);
+
+ vcpu_fpu_get(vcpu, &fpu);
+ TEST_ASSERT_EQ(*(u64 *)&fpu.xmm[0][0], XMM_IN_MARKER);
+ TEST_ASSERT_EQ(*(u64 *)&fpu.xmm[0][8], XMM_IN_MARKER + 1);
+ *(u64 *)&fpu.xmm[1][0] = XMM_OUT_MARKER;
+ *(u64 *)&fpu.xmm[1][8] = XMM_OUT_MARKER + 1;
+ vcpu_fpu_set(vcpu, &fpu);
+
+ vcpu->run->hyperv.u.hcall.result = USERSPACE_STATUS;
+}
+
+static void test_feature_mask(struct kvm_vm *vm)
+{
+ u64 supported = kvm_check_cap(KVM_CAP_HYPERV_FORWARD_HCALL);
+ int r;
+
+ TEST_ASSERT(supported & KVM_HYPERV_HCALL_FORWARD_UNKNOWN,
+ "KVM_HYPERV_HCALL_FORWARD_UNKNOWN not reported");
+ TEST_ASSERT(supported & KVM_HYPERV_HCALL_RAISE_UD,
+ "KVM_HYPERV_HCALL_RAISE_UD not reported");
+
+ r = __vm_enable_cap(vm, KVM_CAP_HYPERV_FORWARD_HCALL, BIT_ULL(63));
+ TEST_ASSERT(r && errno == EINVAL,
+ "Enabling an undefined feature should fail with EINVAL");
+
+ /* Enabling nothing is allowed. */
+ vm_enable_cap(vm, KVM_CAP_HYPERV_FORWARD_HCALL, 0);
+}
+
+int main(int argc, char *argv[])
+{
+ struct kvm_vcpu *vcpu;
+ struct kvm_vm *vm;
+ gva_t hcall_page;
+ gpa_t hcall_gpa;
+ struct ucall uc;
+ int stage = STAGE_DISABLED;
+
+ TEST_REQUIRE(kvm_has_cap(KVM_CAP_HYPERV_FORWARD_HCALL));
+
+ vm = vm_create_with_one_vcpu(&vcpu, guest_code);
+ vcpu_set_hv_cpuid(vcpu);
+
+ test_feature_mask(vm);
+
+ /* Hypercall page plus an input and an output page. */
+ hcall_page = vm_alloc_pages(vm, 3);
+ memset(addr_gva2hva(vm, hcall_page), 0x0, 3 * getpagesize());
+ hcall_gpa = addr_gva2gpa(vm, hcall_page);
+
+ vcpu_args_set(vcpu, 1, hcall_gpa);
+
+ for (;;) {
+ vcpu_run(vcpu);
+
+ if (vcpu->run->exit_reason == KVM_EXIT_HYPERV) {
+ switch (stage) {
+ case STAGE_MEMORY:
+ check_hcall_exit(vcpu, HVCALL_TEST_CODE,
+ hcall_gpa + getpagesize(),
+ hcall_gpa + 2 * getpagesize());
+ vcpu->run->hyperv.u.hcall.result = USERSPACE_STATUS;
+ break;
+ case STAGE_FAST:
+ handle_fast_hcall(vcpu);
+ break;
+ case STAGE_RESULT_FULL:
+ check_hcall_exit(vcpu, HVCALL_TEST_CODE,
+ hcall_gpa + getpagesize(),
+ hcall_gpa + 2 * getpagesize());
+ check_flags_refused(vcpu);
+ vcpu->run->hyperv.u.hcall.result = FULL_RESULT;
+ break;
+ case STAGE_RAISE_UD:
+ check_hcall_exit(vcpu, HVCALL_TEST_CODE,
+ hcall_gpa + getpagesize(),
+ hcall_gpa + 2 * getpagesize());
+ vcpu->run->hyperv.u.hcall.result = USERSPACE_STATUS;
+ vcpu->run->hyperv.u.hcall.flags = KVM_HYPERV_HCALL_UD;
+ break;
+ case STAGE_FLAGS_CLEARED:
+ /* check_hcall_exit() asserts the stale UD is gone. */
+ check_hcall_exit(vcpu, HVCALL_TEST_CODE,
+ hcall_gpa + getpagesize(),
+ hcall_gpa + 2 * getpagesize());
+ vcpu->run->hyperv.u.hcall.result = USERSPACE_STATUS;
+ break;
+ default:
+ TEST_FAIL("Unexpected hypercall exit in stage %d", stage);
+ }
+ continue;
+ }
+
+ TEST_ASSERT_KVM_EXIT_REASON(vcpu, KVM_EXIT_IO);
+
+ switch (get_ucall(vcpu, &uc)) {
+ case UCALL_SYNC:
+ TEST_ASSERT_EQ(uc.args[1], stage);
+ switch (stage) {
+ case STAGE_DISABLED:
+ vm_enable_cap(vm, KVM_CAP_HYPERV_FORWARD_HCALL,
+ KVM_HYPERV_HCALL_FORWARD_UNKNOWN);
+ break;
+ case STAGE_RESULT_FULL:
+ vm_enable_cap(vm, KVM_CAP_HYPERV_FORWARD_HCALL,
+ KVM_HYPERV_HCALL_FORWARD_UNKNOWN |
+ KVM_HYPERV_HCALL_RAISE_UD);
+ break;
+ case STAGE_FLAGS_CLEARED:
+ vm_enable_cap(vm, KVM_CAP_HYPERV_FORWARD_HCALL, 0);
+ break;
+ }
+ stage++;
+ break;
+ case UCALL_ABORT:
+ REPORT_GUEST_ASSERT(uc);
+ case UCALL_DONE:
+ goto done;
+ default:
+ TEST_FAIL("Unhandled ucall: %ld", uc.cmd);
+ }
+ }
+
+done:
+ TEST_ASSERT_EQ(stage, STAGE_REDISABLED + 1);
+ kvm_vm_free(vm);
+ return 0;
+}
--
2.50.1