[PATCH 0/7] KVM: x86: Improve the handling of debug exceptions during instruction emulation

[PATCH 0/7] KVM: x86: Improve the handling of debug exceptions during instruction emulation

[Hou Wenlong]

During my testing, I found that guest debugging with 'DR6.BD' does not
work in instruction emulation, as the current code only considers the
guest's DR7. Upon reviewing the code, I also observed that the checks
for the userspace guest debugging feature and the guest's own debugging
feature are repeated in different places during instruction
emulation, but the overall logic is the same. If guest debugging
is enabled, it needs to exit to userspace; otherwise, a #DB
exception needs to be injected into the guest. Therefore, as
suggested by Jiangshan Lai, some cleanup has been done for #DB
handling in instruction emulation in this patchset. A new
function named 'kvm_inject_emulated_db()' is introduced to
consolidate all the checking logic. Moreover, I hope we can make
the #DB interception path use the same function as well.

Additionally, when I looked into the single-step #DB handling in
instruction emulation, I noticed that the interrupt shadow is toggled,
but it is not considered in the single-step #DB injection. This
oversight causes VM entry to fail on VMX (due to pending debug
exceptions checking) or breaks the 'MOV SS' suppressed #DB. For the
latter, I have kept the behavior for now in my patchset, as I need some
suggestions.

Hou Wenlong (7):
  KVM: x86: Set guest DR6 by kvm_queue_exception_p() in instruction
    emulation
  KVM: x86: Check guest debug in DR access instruction emulation
  KVM: x86: Only check effective code breakpoint in emulation
  KVM: x86: Consolidate KVM_GUESTDBG_SINGLESTEP check into the
    kvm_inject_emulated_db()
  KVM: VMX: Set 'BS' bit in pending debug exceptions during instruction
    emulation
  KVM: selftests: Verify guest debug DR7.GD checking during instruction
    emulation
  KVM: selftests: Verify 'BS' bit checking in pending debug exception
    during VM entry

 arch/x86/include/asm/kvm-x86-ops.h            |   1 +
 arch/x86/include/asm/kvm_host.h               |   1 +
 arch/x86/kvm/emulate.c                        |  14 +--
 arch/x86/kvm/kvm_emulate.h                    |   7 +-
 arch/x86/kvm/vmx/main.c                       |   9 ++
 arch/x86/kvm/vmx/vmx.c                        |  14 ++-
 arch/x86/kvm/vmx/x86_ops.h                    |   1 +
 arch/x86/kvm/x86.c                            | 109 +++++++++++-------
 arch/x86/kvm/x86.h                            |   7 ++
 .../selftests/kvm/include/x86/processor.h     |   3 +-
 tools/testing/selftests/kvm/x86/debug_regs.c  |  64 +++++++++-
 11 files changed, 167 insertions(+), 63 deletions(-)


base-commit: ecbcc2461839e848970468b44db32282e5059925
--
2.31.1

[PATCH 6/7] KVM: selftests: Verify guest debug DR7.GD checking during instruction emulation

[Hou Wenlong]

Similar to the global disable test case in x86's debug_regs test, use
'KVM_FEP' to trigger instruction emulation in order to verify the guest
debug DR7.GD checking during instruction emulation.

Signed-off-by: Hou Wenlong <houwenlong.hwl@antgroup.com>
---
 tools/testing/selftests/kvm/x86/debug_regs.c | 25 +++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/tools/testing/selftests/kvm/x86/debug_regs.c b/tools/testing/selftests/kvm/x86/debug_regs.c
index 2d814c1d1dc4..ba80b77c2869 100644
--- a/tools/testing/selftests/kvm/x86/debug_regs.c
+++ b/tools/testing/selftests/kvm/x86/debug_regs.c
@@ -19,6 +19,7 @@
 uint32_t guest_value;
 
 extern unsigned char sw_bp, hw_bp, write_data, ss_start, bd_start;
+extern unsigned char fep_bd_start;
 
 static void guest_code(void)
 {
@@ -64,6 +65,12 @@ static void guest_code(void)
 
 	/* DR6.BD test */
 	asm volatile("bd_start: mov %%dr0, %%rax" : : : "rax");
+
+	if (is_forced_emulation_enabled) {
+		/* DR6.BD test for emulation */
+		asm volatile(KVM_FEP "fep_bd_start: mov %%dr0, %%rax" : : : "rax");
+	}
+
 	GUEST_DONE();
 }
 
@@ -185,7 +192,7 @@ int main(void)
 			    target_dr6);
 	}
 
-	/* Finally test global disable */
+	/* test global disable */
 	memset(&debug, 0, sizeof(debug));
 	debug.control = KVM_GUESTDBG_ENABLE | KVM_GUESTDBG_USE_HW_BP;
 	debug.arch.debugreg[7] = 0x400 | DR7_GD;
@@ -202,6 +209,22 @@ int main(void)
 			    run->debug.arch.pc, target_rip, run->debug.arch.dr6,
 			    target_dr6);
 
+	/* test global disable in emulation */
+	if (is_forced_emulation_enabled) {
+		/* Skip the 3-bytes "mov dr0" */
+		vcpu_skip_insn(vcpu, 3);
+		vcpu_run(vcpu);
+		TEST_ASSERT(run->exit_reason == KVM_EXIT_DEBUG &&
+			    run->debug.arch.exception == DB_VECTOR &&
+			    run->debug.arch.pc == CAST_TO_RIP(fep_bd_start) &&
+			    run->debug.arch.dr6 == target_dr6,
+			    "DR7.GD: exit %d exception %d rip 0x%llx "
+			    "(should be 0x%llx) dr6 0x%llx (should be 0x%llx)",
+			    run->exit_reason, run->debug.arch.exception,
+			    run->debug.arch.pc, target_rip, run->debug.arch.dr6,
+			    target_dr6);
+	}
+
 	/* Disable all debug controls, run to the end */
 	memset(&debug, 0, sizeof(debug));
 	vcpu_guest_debug_set(vcpu, &debug);
-- 
2.31.1

Re: [PATCH 6/7] KVM: selftests: Verify guest debug DR7.GD checking during instruction emulation

[Sean Christopherson]

On Wed, Sep 10, 2025, Hou Wenlong wrote:
> Similar to the global disable test case in x86's debug_regs test, use
> 'KVM_FEP' to trigger instruction emulation in order to verify the guest
> debug DR7.GD checking during instruction emulation.
> 
> Signed-off-by: Hou Wenlong <houwenlong.hwl@antgroup.com>
> ---
>  tools/testing/selftests/kvm/x86/debug_regs.c | 25 +++++++++++++++++++-
>  1 file changed, 24 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/testing/selftests/kvm/x86/debug_regs.c b/tools/testing/selftests/kvm/x86/debug_regs.c
> index 2d814c1d1dc4..ba80b77c2869 100644
> --- a/tools/testing/selftests/kvm/x86/debug_regs.c
> +++ b/tools/testing/selftests/kvm/x86/debug_regs.c
> @@ -19,6 +19,7 @@
>  uint32_t guest_value;
>  
>  extern unsigned char sw_bp, hw_bp, write_data, ss_start, bd_start;
> +extern unsigned char fep_bd_start;
>  
>  static void guest_code(void)
>  {
> @@ -64,6 +65,12 @@ static void guest_code(void)
>  
>  	/* DR6.BD test */
>  	asm volatile("bd_start: mov %%dr0, %%rax" : : : "rax");
> +
> +	if (is_forced_emulation_enabled) {
> +		/* DR6.BD test for emulation */

Put the comment above the if-statement, that way there's no need for curly braces.
Or just drop it entirely; unless the comments more verbose, I don't think it adds
much value.

> +		asm volatile(KVM_FEP "fep_bd_start: mov %%dr0, %%rax" : : : "rax");
> +	}
> +
>  	GUEST_DONE();
>  }
>  
> @@ -185,7 +192,7 @@ int main(void)
>  			    target_dr6);
>  	}
>  
> -	/* Finally test global disable */
> +	/* test global disable */
>  	memset(&debug, 0, sizeof(debug));
>  	debug.control = KVM_GUESTDBG_ENABLE | KVM_GUESTDBG_USE_HW_BP;
>  	debug.arch.debugreg[7] = 0x400 | DR7_GD;
> @@ -202,6 +209,22 @@ int main(void)
>  			    run->debug.arch.pc, target_rip, run->debug.arch.dr6,
>  			    target_dr6);
>  
> +	/* test global disable in emulation */
> +	if (is_forced_emulation_enabled) {
> +		/* Skip the 3-bytes "mov dr0" */
> +		vcpu_skip_insn(vcpu, 3);
> +		vcpu_run(vcpu);
> +		TEST_ASSERT(run->exit_reason == KVM_EXIT_DEBUG &&
> +			    run->debug.arch.exception == DB_VECTOR &&
> +			    run->debug.arch.pc == CAST_TO_RIP(fep_bd_start) &&
> +			    run->debug.arch.dr6 == target_dr6,
> +			    "DR7.GD: exit %d exception %d rip 0x%llx "
> +			    "(should be 0x%llx) dr6 0x%llx (should be 0x%llx)",
> +			    run->exit_reason, run->debug.arch.exception,
> +			    run->debug.arch.pc, target_rip, run->debug.arch.dr6,
> +			    target_dr6);
> +	}
> +
>  	/* Disable all debug controls, run to the end */
>  	memset(&debug, 0, sizeof(debug));
>  	vcpu_guest_debug_set(vcpu, &debug);
> -- 
> 2.31.1
> 

[PATCH 7/7] KVM: selftests: Verify 'BS' bit checking in pending debug exception during VM entry

[Hou Wenlong]

In the x86's debug_regs test, add a test case to cover the scenario where
single-step with STI in VMX sets the 'BS' bit in pending debug
exceptions for #DB interception and instruction emulation in both cases.

Signed-off-by: Hou Wenlong <houwenlong.hwl@antgroup.com>
---
 .../selftests/kvm/include/x86/processor.h     |  3 +-
 tools/testing/selftests/kvm/x86/debug_regs.c  | 41 +++++++++++++++++--
 2 files changed, 40 insertions(+), 4 deletions(-)

diff --git a/tools/testing/selftests/kvm/include/x86/processor.h b/tools/testing/selftests/kvm/include/x86/processor.h
index 488d516c4f6f..f5827cca813e 100644
--- a/tools/testing/selftests/kvm/include/x86/processor.h
+++ b/tools/testing/selftests/kvm/include/x86/processor.h
@@ -34,7 +34,8 @@ extern uint64_t guest_tsc_khz;
 
 #define NMI_VECTOR		0x02
 
-#define X86_EFLAGS_FIXED	 (1u << 1)
+#define X86_EFLAGS_FIXED	(1u << 1)
+#define X86_EFLAGS_TF		(1u << 8)
 
 #define X86_CR4_VME		(1ul << 0)
 #define X86_CR4_PVI		(1ul << 1)
diff --git a/tools/testing/selftests/kvm/x86/debug_regs.c b/tools/testing/selftests/kvm/x86/debug_regs.c
index ba80b77c2869..60dea0116b21 100644
--- a/tools/testing/selftests/kvm/x86/debug_regs.c
+++ b/tools/testing/selftests/kvm/x86/debug_regs.c
@@ -15,11 +15,31 @@
 
 #define IRQ_VECTOR 0xAA
 
+#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
+
 /* For testing data access debug BP */
 uint32_t guest_value;
 
 extern unsigned char sw_bp, hw_bp, write_data, ss_start, bd_start;
-extern unsigned char fep_bd_start;
+extern unsigned char fep_bd_start, fep_sti_start, fep_sti_end;
+
+static void guest_db_handler(struct ex_regs *regs)
+{
+	static int count;
+	unsigned long target_rips[2] = {
+		CAST_TO_RIP(fep_sti_start),
+		CAST_TO_RIP(fep_sti_end),
+	};
+
+	__GUEST_ASSERT(regs->rip == target_rips[count], "STI: unexpected rip 0x%lx (should be 0x%lx)",
+		       regs->rip, target_rips[count]);
+	regs->rflags &= ~X86_EFLAGS_TF;
+	count++;
+}
+
+static void guest_irq_handler(struct ex_regs *regs)
+{
+}
 
 static void guest_code(void)
 {
@@ -69,13 +89,25 @@ static void guest_code(void)
 	if (is_forced_emulation_enabled) {
 		/* DR6.BD test for emulation */
 		asm volatile(KVM_FEP "fep_bd_start: mov %%dr0, %%rax" : : : "rax");
+
+		/* pending debug exceptions for emulation */
+		asm volatile("pushf\n\t"
+			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
+			     "popf\n\t"
+			     "sti\n\t"
+			     "fep_sti_start:"
+			     "cli\n\t"
+			     "pushf\n\t"
+			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
+			     "popf\n\t"
+			     KVM_FEP "sti\n\t"
+			     "fep_sti_end:"
+			     "cli\n\t");
 	}
 
 	GUEST_DONE();
 }
 
-#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
-
 static void vcpu_skip_insn(struct kvm_vcpu *vcpu, int insn_len)
 {
 	struct kvm_regs regs;
@@ -110,6 +142,9 @@ int main(void)
 	vm = vm_create_with_one_vcpu(&vcpu, guest_code);
 	run = vcpu->run;
 
+	vm_install_exception_handler(vm, DB_VECTOR, guest_db_handler);
+	vm_install_exception_handler(vm, IRQ_VECTOR, guest_irq_handler);
+
 	/* Test software BPs - int3 */
 	memset(&debug, 0, sizeof(debug));
 	debug.control = KVM_GUESTDBG_ENABLE | KVM_GUESTDBG_USE_SW_BP;
-- 
2.31.1

Re: [PATCH 7/7] KVM: selftests: Verify 'BS' bit checking in pending debug exception during VM entry

[Sean Christopherson]

On Wed, Sep 10, 2025, Hou Wenlong wrote:
>  #define IRQ_VECTOR 0xAA
>  
> +#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
> +
>  /* For testing data access debug BP */
>  uint32_t guest_value;
>  
>  extern unsigned char sw_bp, hw_bp, write_data, ss_start, bd_start;
> -extern unsigned char fep_bd_start;
> +extern unsigned char fep_bd_start, fep_sti_start, fep_sti_end;
> +
> +static void guest_db_handler(struct ex_regs *regs)
> +{
> +	static int count;
> +	unsigned long target_rips[2] = {
> +		CAST_TO_RIP(fep_sti_start),
> +		CAST_TO_RIP(fep_sti_end),
> +	};
> +
> +	__GUEST_ASSERT(regs->rip == target_rips[count], "STI: unexpected rip 0x%lx (should be 0x%lx)",
> +		       regs->rip, target_rips[count]);
> +	regs->rflags &= ~X86_EFLAGS_TF;
> +	count++;
> +}
> +
> +static void guest_irq_handler(struct ex_regs *regs)
> +{
> +}
>  
>  static void guest_code(void)
>  {
> @@ -69,13 +89,25 @@ static void guest_code(void)
>  	if (is_forced_emulation_enabled) {
>  		/* DR6.BD test for emulation */
>  		asm volatile(KVM_FEP "fep_bd_start: mov %%dr0, %%rax" : : : "rax");
> +
> +		/* pending debug exceptions for emulation */
> +		asm volatile("pushf\n\t"
> +			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
> +			     "popf\n\t"
> +			     "sti\n\t"
> +			     "fep_sti_start:"
> +			     "cli\n\t"
> +			     "pushf\n\t"
> +			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
> +			     "popf\n\t"
> +			     KVM_FEP "sti\n\t"
> +			     "fep_sti_end:"
> +			     "cli\n\t");
>  	}
>  
>  	GUEST_DONE();
>  }
>  
> -#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
> -
>  static void vcpu_skip_insn(struct kvm_vcpu *vcpu, int insn_len)
>  {
>  	struct kvm_regs regs;
> @@ -110,6 +142,9 @@ int main(void)
>  	vm = vm_create_with_one_vcpu(&vcpu, guest_code);
>  	run = vcpu->run;
>  
> +	vm_install_exception_handler(vm, DB_VECTOR, guest_db_handler);
> +	vm_install_exception_handler(vm, IRQ_VECTOR, guest_irq_handler);

But the IRQ should never be taken thanks to the CLI in the STI shadow.  I.e.
installing a dummy handler could mask failures, no?

> +
>  	/* Test software BPs - int3 */
>  	memset(&debug, 0, sizeof(debug));
>  	debug.control = KVM_GUESTDBG_ENABLE | KVM_GUESTDBG_USE_SW_BP;
> -- 
> 2.31.1
> 

Re: [PATCH 7/7] KVM: selftests: Verify 'BS' bit checking in pending debug exception during VM entry

[Hou Wenlong]

On Fri, Dec 05, 2025 at 10:23:42AM -0800, Sean Christopherson wrote:
> On Wed, Sep 10, 2025, Hou Wenlong wrote:
> >  #define IRQ_VECTOR 0xAA
> >  
> > +#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
> > +
> >  /* For testing data access debug BP */
> >  uint32_t guest_value;
> >  
> >  extern unsigned char sw_bp, hw_bp, write_data, ss_start, bd_start;
> > -extern unsigned char fep_bd_start;
> > +extern unsigned char fep_bd_start, fep_sti_start, fep_sti_end;
> > +
> > +static void guest_db_handler(struct ex_regs *regs)
> > +{
> > +	static int count;
> > +	unsigned long target_rips[2] = {
> > +		CAST_TO_RIP(fep_sti_start),
> > +		CAST_TO_RIP(fep_sti_end),
> > +	};
> > +
> > +	__GUEST_ASSERT(regs->rip == target_rips[count], "STI: unexpected rip 0x%lx (should be 0x%lx)",
> > +		       regs->rip, target_rips[count]);
> > +	regs->rflags &= ~X86_EFLAGS_TF;
> > +	count++;
> > +}
> > +
> > +static void guest_irq_handler(struct ex_regs *regs)
> > +{
> > +}
> >  
> >  static void guest_code(void)
> >  {
> > @@ -69,13 +89,25 @@ static void guest_code(void)
> >  	if (is_forced_emulation_enabled) {
> >  		/* DR6.BD test for emulation */
> >  		asm volatile(KVM_FEP "fep_bd_start: mov %%dr0, %%rax" : : : "rax");
> > +
> > +		/* pending debug exceptions for emulation */
> > +		asm volatile("pushf\n\t"
> > +			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
> > +			     "popf\n\t"
> > +			     "sti\n\t"
> > +			     "fep_sti_start:"
> > +			     "cli\n\t"
> > +			     "pushf\n\t"
> > +			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
> > +			     "popf\n\t"
> > +			     KVM_FEP "sti\n\t"
> > +			     "fep_sti_end:"
> > +			     "cli\n\t");
> >  	}
> >  
> >  	GUEST_DONE();
> >  }
> >  
> > -#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
> > -
> >  static void vcpu_skip_insn(struct kvm_vcpu *vcpu, int insn_len)
> >  {
> >  	struct kvm_regs regs;
> > @@ -110,6 +142,9 @@ int main(void)
> >  	vm = vm_create_with_one_vcpu(&vcpu, guest_code);
> >  	run = vcpu->run;
> >  
> > +	vm_install_exception_handler(vm, DB_VECTOR, guest_db_handler);
> > +	vm_install_exception_handler(vm, IRQ_VECTOR, guest_irq_handler);
> 
> But the IRQ should never be taken thanks to the CLI in the STI shadow.  I.e.
> installing a dummy handler could mask failures, no?
>
Yes, this also breaks the testcase regarding KVM_GUESTDBG_BLOCKIRQ.
Sorry, I forgot why I added this, as you said there should be no IRQ
delivered due to the STI shadow. :(
I'll remove it in the next version.
 
Thanks!

> > +
> >  	/* Test software BPs - int3 */
> >  	memset(&debug, 0, sizeof(debug));
> >  	debug.control = KVM_GUESTDBG_ENABLE | KVM_GUESTDBG_USE_SW_BP;
> > -- 
> > 2.31.1
> > 

Re: [PATCH 7/7] KVM: selftests: Verify 'BS' bit checking in pending debug exception during VM entry

[Hou Wenlong]

On Fri, Dec 05, 2025 at 10:23:42AM -0800, Sean Christopherson wrote:
> On Wed, Sep 10, 2025, Hou Wenlong wrote:
> >  #define IRQ_VECTOR 0xAA
> >  
> > +#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
> > +
> >  /* For testing data access debug BP */
> >  uint32_t guest_value;
> >  
> >  extern unsigned char sw_bp, hw_bp, write_data, ss_start, bd_start;
> > -extern unsigned char fep_bd_start;
> > +extern unsigned char fep_bd_start, fep_sti_start, fep_sti_end;
> > +
> > +static void guest_db_handler(struct ex_regs *regs)
> > +{
> > +	static int count;
> > +	unsigned long target_rips[2] = {
> > +		CAST_TO_RIP(fep_sti_start),
> > +		CAST_TO_RIP(fep_sti_end),
> > +	};
> > +
> > +	__GUEST_ASSERT(regs->rip == target_rips[count], "STI: unexpected rip 0x%lx (should be 0x%lx)",
> > +		       regs->rip, target_rips[count]);
> > +	regs->rflags &= ~X86_EFLAGS_TF;
> > +	count++;
> > +}
> > +
> > +static void guest_irq_handler(struct ex_regs *regs)
> > +{
> > +}
> >  
> >  static void guest_code(void)
> >  {
> > @@ -69,13 +89,25 @@ static void guest_code(void)
> >  	if (is_forced_emulation_enabled) {
> >  		/* DR6.BD test for emulation */
> >  		asm volatile(KVM_FEP "fep_bd_start: mov %%dr0, %%rax" : : : "rax");
> > +
> > +		/* pending debug exceptions for emulation */
> > +		asm volatile("pushf\n\t"
> > +			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
> > +			     "popf\n\t"
> > +			     "sti\n\t"
> > +			     "fep_sti_start:"
> > +			     "cli\n\t"
> > +			     "pushf\n\t"
> > +			     "orq $" __stringify(X86_EFLAGS_TF) ", (%rsp)\n\t"
> > +			     "popf\n\t"
> > +			     KVM_FEP "sti\n\t"
> > +			     "fep_sti_end:"
> > +			     "cli\n\t");
> >  	}
> >  
> >  	GUEST_DONE();
> >  }
> >  
> > -#define  CAST_TO_RIP(v)  ((unsigned long long)&(v))
> > -
> >  static void vcpu_skip_insn(struct kvm_vcpu *vcpu, int insn_len)
> >  {
> >  	struct kvm_regs regs;
> > @@ -110,6 +142,9 @@ int main(void)
> >  	vm = vm_create_with_one_vcpu(&vcpu, guest_code);
> >  	run = vcpu->run;
> >  
> > +	vm_install_exception_handler(vm, DB_VECTOR, guest_db_handler);
> > +	vm_install_exception_handler(vm, IRQ_VECTOR, guest_irq_handler);
> 
> But the IRQ should never be taken thanks to the CLI in the STI shadow.  I.e.
> installing a dummy handler could mask failures, no?
>
Uh, I remember why I need to install the dummy IRQ handler. There is a
single-step #DB after STI, so the #DB delivery removes the interrupt
shadow, and then the pending interrupt will be delivered after IRET.
I'll move the IRQ handler registration after the KVM_GUESTDBG_BLOCKIRQ
testcase.

> > +
> >  	/* Test software BPs - int3 */
> >  	memset(&debug, 0, sizeof(debug));
> >  	debug.control = KVM_GUESTDBG_ENABLE | KVM_GUESTDBG_USE_SW_BP;
> > -- 
> > 2.31.1
> >