[PATCH 2/4] KVM: x86: hyper-v: Let userspace fault a forwarded hypercall

From: David Woodhouse

Date: Wed Nov 11 2026 - 16:04:03 EST


From: David Woodhouse <dwmw@xxxxxxxxxxxx>

The TLFS specifies that some hypercalls raise #UD at the hypercall
instruction when they are invalid in the caller's state, rather than
completing with an error status. A VMM implementing such a hypercall
behind KVM_EXIT_HYPERV_HCALL can only return a status, which writes
RAX, advances RIP and completes the call.

Give the hcall member of struct kvm_hyperv_exit a 'flags' field after
the parameters, and add KVM_HYPERV_HCALL_RAISE_UD to
KVM_CAP_HYPERV_FORWARD_HCALL. With it enabled, a completion with
KVM_HYPERV_HCALL_UD set in 'flags' queues a #UD at the unadvanced RIP
and ignores 'result'. It applies to every KVM_EXIT_HYPERV_HCALL
completion, not only to forwarded hypercalls, and 'result' stays a
plain 64-bit value.

KVM zeroes 'flags' when it reports the exit, so a VMM that has never
heard of the field leaves it alone. A completion with any other bit set,
or with KVM_HYPERV_HCALL_UD set while RAISE_UD is not enabled, fails
KVM_RUN with -EINVAL and leaves the completion pending for userspace to
correct. The new field fits within the existing union, whose largest
member is still syndbg, so struct kvm_run does not change size.

Signed-off-by: David Woodhouse <dwmw@xxxxxxxxxxxx>
---
Documentation/virt/kvm/api.rst | 16 ++++++++++++++++
arch/x86/kvm/hyperv.c | 30 +++++++++++++++++++++++++++++-
arch/x86/kvm/hyperv.h | 3 ++-
include/uapi/linux/kvm.h | 3 +++
4 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst
index 092f6f9ad8a0..25ed1027fb08 100644
--- a/Documentation/virt/kvm/api.rst
+++ b/Documentation/virt/kvm/api.rst
@@ -7286,6 +7286,8 @@ EOI was received.
__u64 input;
__u64 result;
__u64 params[2];
+ #define KVM_HYPERV_HCALL_UD (1ULL << 0)
+ __u64 flags;
} hcall;
struct {
__u32 msr;
@@ -7323,6 +7325,12 @@ and memory-based extended hypercalls exit this way;
KVM_CAP_HYPERV_FORWARD_HCALL (see section 7.48) adds the hypercalls KVM
does not implement.

+KVM sets 'flags' to zero when it reports the exit. With that
+capability's KVM_HYPERV_HCALL_RAISE_UD feature enabled, userspace may set
+KVM_HYPERV_HCALL_UD there to raise #UD at the hypercall instruction
+instead of completing the hypercall. KVM_RUN fails with EINVAL, leaving
+the exit pending, if 'flags' holds any other bit.
+
- KVM_EXIT_HYPERV_SYNDBG -- synchronously notify user-space about

Hyper-V Synthetic debugger state change. Notification is used to either update
@@ -9210,6 +9218,7 @@ features it was written for and learn which ones the kernel lacks.
The defined bits are::

#define KVM_HYPERV_HCALL_FORWARD_UNKNOWN (1ULL << 0)
+ #define KVM_HYPERV_HCALL_RAISE_UD (1ULL << 1)

KVM_HYPERV_HCALL_FORWARD_UNKNOWN: a hypercall that KVM would otherwise
fail with HV_STATUS_INVALID_HYPERCALL_CODE exits to userspace with
@@ -9230,6 +9239,13 @@ KVM_GET_FPU/KVM_SET_FPU) before the vCPU is resumed. Hypercalls that
KVM implements itself, and the CPUID-enforcement checks KVM applies
before dispatching a hypercall, are unaffected.

+KVM_HYPERV_HCALL_RAISE_UD: userspace may complete a KVM_EXIT_HYPERV_HCALL
+exit with KVM_HYPERV_HCALL_UD set in 'flags', and KVM then raises #UD at
+the hypercall instruction instead of completing the hypercall, ignoring
+'result'. This is for hypercalls that the TLFS specifies to fault
+rather than fail with a status. When enabled, it applies to every
+KVM_EXIT_HYPERV_HCALL completion, forwarded or not.
+
8. Other capabilities.
======================

diff --git a/arch/x86/kvm/hyperv.c b/arch/x86/kvm/hyperv.c
index e72539f9acc9..2a2bc54775fe 100644
--- a/arch/x86/kvm/hyperv.c
+++ b/arch/x86/kvm/hyperv.c
@@ -2430,7 +2430,34 @@ static int kvm_hv_hypercall_complete(struct kvm_vcpu *vcpu, u64 result)

static int kvm_hv_hypercall_complete_userspace(struct kvm_vcpu *vcpu)
{
- return kvm_hv_hypercall_complete(vcpu, vcpu->run->hyperv.u.hcall.result);
+ u64 result = vcpu->run->hyperv.u.hcall.result;
+ u64 flags = vcpu->run->hyperv.u.hcall.flags;
+ u64 valid = 0;
+
+ if (kvm_hv_hcall_feature(vcpu->kvm, KVM_HYPERV_HCALL_RAISE_UD))
+ valid |= KVM_HYPERV_HCALL_UD;
+
+ /*
+ * Fail KVM_RUN on flags KVM does not know (or that were not enabled),
+ * and leave the completion pending so that userspace can fix them.
+ */
+ if (flags & ~valid) {
+ vcpu->arch.complete_userspace_io =
+ kvm_hv_hypercall_complete_userspace;
+ return -EINVAL;
+ }
+
+ /*
+ * The VMM judged the hypercall to fault rather than return a
+ * status: leave RIP at the hypercall instruction and raise #UD
+ * there.
+ */
+ if (flags & KVM_HYPERV_HCALL_UD) {
+ kvm_queue_exception(vcpu, UD_VECTOR);
+ return 1;
+ }
+
+ return kvm_hv_hypercall_complete(vcpu, result);
}

static u16 kvm_hvcall_signal_event(struct kvm_vcpu *vcpu, struct kvm_hv_hcall *hc)
@@ -2716,6 +2743,7 @@ int kvm_hv_hypercall(struct kvm_vcpu *vcpu)
vcpu->run->hyperv.u.hcall.input = hc.param;
vcpu->run->hyperv.u.hcall.params[0] = hc.ingpa;
vcpu->run->hyperv.u.hcall.params[1] = hc.outgpa;
+ vcpu->run->hyperv.u.hcall.flags = 0;
vcpu->arch.complete_userspace_io = kvm_hv_hypercall_complete_userspace;
return 0;
}
diff --git a/arch/x86/kvm/hyperv.h b/arch/x86/kvm/hyperv.h
index 20d40261c75b..7c6a21f02d71 100644
--- a/arch/x86/kvm/hyperv.h
+++ b/arch/x86/kvm/hyperv.h
@@ -206,7 +206,8 @@ static inline bool kvm_hv_hypercall_enabled(struct kvm_vcpu *vcpu)
}

/* Features reported and accepted by KVM_CAP_HYPERV_FORWARD_HCALL. */
-#define KVM_HYPERV_HCALL_SUPPORTED KVM_HYPERV_HCALL_FORWARD_UNKNOWN
+#define KVM_HYPERV_HCALL_SUPPORTED (KVM_HYPERV_HCALL_FORWARD_UNKNOWN | \
+ KVM_HYPERV_HCALL_RAISE_UD)

static inline bool kvm_hv_hcall_feature(struct kvm *kvm, u64 feature)
{
diff --git a/include/uapi/linux/kvm.h b/include/uapi/linux/kvm.h
index 7194c213a742..09b8b8c84380 100644
--- a/include/uapi/linux/kvm.h
+++ b/include/uapi/linux/kvm.h
@@ -113,6 +113,8 @@ struct kvm_hyperv_exit {
__u64 input;
__u64 result;
__u64 params[2];
+#define KVM_HYPERV_HCALL_UD (1ULL << 0)
+ __u64 flags;
} hcall;
struct {
__u32 msr;
@@ -128,6 +130,7 @@ struct kvm_hyperv_exit {

/* KVM_CAP_HYPERV_FORWARD_HCALL feature bits */
#define KVM_HYPERV_HCALL_FORWARD_UNKNOWN (1ULL << 0)
+#define KVM_HYPERV_HCALL_RAISE_UD (1ULL << 1)

struct kvm_xen_exit {
#define KVM_EXIT_XEN_HCALL 1
--
2.50.1