[PATCH] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping

[PATCH] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping

[Yuhang.chen]

Add a kernel command-line option, kvm-riscv.wfi_trap_policy=trap|notrap,
that controls whether a WFI executed by a VS-mode guest traps into KVM
(HS-mode) or executes natively.

Measured results (wfi_exit_stat delta / guest wake count over 3 s):

  policy        WFI_EXITS   WAKE_CNT
  ----------    ---------   --------
  default       295         294      (== trap, no regression)
  trap          295         294
  notrap          0         298

Assisted-by: YuanSheng:deepseek-v4-pro
Co-developed-by: Quan Zhou <zhouquan@iscas.ac.cn>
Signed-off-by: Quan Zhou <zhouquan@iscas.ac.cn>
Signed-off-by: Yuhang.chen <yhchen312@gmail.com>
---
 .../admin-guide/kernel-parameters.txt         | 14 ++++++
 arch/riscv/kvm/vcpu.c                         | 44 ++++++++++++++++++-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index b5493a7f8f22..ee6603b30033 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3254,6 +3254,20 @@ Kernel parameters
 
 			notrap: clear WFI instruction trap
 
+	kvm-riscv.wfi_trap_policy=
+			[KVM,RISCV] Control when to set the WFI instruction
+			trap for KVM VMs. When set, a VS-mode WFI traps into
+			KVM and is emulated; when clear, the guest executes
+			WFI natively and blocks until a VS-mode interrupt
+			(e.g. the sstc timer) is pending.
+
+			trap: set WFI instruction trap (HSTATUS.VTW=1)
+
+			notrap: clear WFI instruction trap (HSTATUS.VTW=0)
+
+			Defaults to trap, preserving the previous
+			unconditional behavior.
+
 	kvm_cma_resv_ratio=n [PPC,EARLY]
 			Reserves given percentage from system memory area for
 			contiguous memory allocation for KVM hash pagetable
diff --git a/arch/riscv/kvm/vcpu.c b/arch/riscv/kvm/vcpu.c
index c3672513b4e9..d50b47ed280e 100644
--- a/arch/riscv/kvm/vcpu.c
+++ b/arch/riscv/kvm/vcpu.c
@@ -12,6 +12,7 @@
 #include <linux/kdebug.h>
 #include <linux/module.h>
 #include <linux/percpu.h>
+#include <linux/string.h>
 #include <linux/vmalloc.h>
 #include <linux/sched/signal.h>
 #include <linux/fs.h>
@@ -26,6 +27,42 @@
 
 static DEFINE_PER_CPU(struct kvm_vcpu *, kvm_former_vcpu);
 
+/*
+ * WFI trap policy for VS-mode guests, controllable through the
+ * kvm-riscv.wfi_trap_policy= kernel command-line option.
+ */
+enum kvm_riscv_wfi_trap_policy {
+	KVM_RISCV_WFI_TRAP,	/* Default: trap VS-mode WFI into KVM */
+	KVM_RISCV_WFI_NOTRAP,	/* Let VS-mode WFI execute natively */
+};
+
+static enum kvm_riscv_wfi_trap_policy kvm_riscv_wfi_trap_policy __read_mostly =
+	KVM_RISCV_WFI_TRAP;
+
+static int __init early_kvm_riscv_wfi_trap_policy_cfg(char *arg)
+{
+	if (!arg)
+		return -EINVAL;
+
+	if (strcmp(arg, "trap") == 0) {
+		kvm_riscv_wfi_trap_policy = KVM_RISCV_WFI_TRAP;
+		return 0;
+	}
+
+	if (strcmp(arg, "notrap") == 0) {
+		kvm_riscv_wfi_trap_policy = KVM_RISCV_WFI_NOTRAP;
+		return 0;
+	}
+
+	return -EINVAL;
+}
+early_param("kvm-riscv.wfi_trap_policy", early_kvm_riscv_wfi_trap_policy_cfg);
+
+static bool kvm_riscv_vcpu_wfi_should_trap(struct kvm_vcpu *vcpu)
+{
+	return kvm_riscv_wfi_trap_policy == KVM_RISCV_WFI_TRAP;
+}
+
 const struct kvm_stats_desc kvm_vcpu_stats_desc[] = {
 	KVM_GENERIC_VCPU_STATS(),
 	STATS_DESC_COUNTER(VCPU, ecall_exit_stat),
@@ -73,7 +110,12 @@ static void kvm_riscv_vcpu_context_reset(struct kvm_vcpu *vcpu,
 	/* Setup reset state of shadow SSTATUS and HSTATUS CSRs */
 	cntx->sstatus = SR_SPP | SR_SPIE;
 
-	cntx->hstatus |= HSTATUS_VTW;
+	/*
+	 * Trap VS-mode WFI into KVM unless the WFI trap policy lets the guest
+	 * execute it natively. See kvm_riscv_wfi_trap_policy.
+	 */
+	if (kvm_riscv_vcpu_wfi_should_trap(vcpu))
+		cntx->hstatus |= HSTATUS_VTW;
 	cntx->hstatus |= HSTATUS_SPVP;
 	cntx->hstatus |= HSTATUS_SPV;
 }
-- 
2.34.1

Re: [PATCH] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping

[sashiko-bot]

Thank you for your contribution! Sashiko AI review found 1 potential issue(s) to consider:
- [Low] The use of `early_param` causes a build failure and breaks parameter configuration when KVM is compiled as a loadable module (`CONFIG_KVM=m`).
--

--- Patch [1]: [PATCH] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping ---
commit 6cc43e03229541ce24e1b37ff0f4554294688af7
Author: Yuhang.chen <yhchen312@gmail.com>

RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping

This commit introduces a new parameter to control whether VS-mode WFI
instructions trap into KVM or execute natively.

> diff --git a/arch/riscv/kvm/vcpu.c b/arch/riscv/kvm/vcpu.c
> index cf6e231e76e25..09afbb014b47d 100644
> --- a/arch/riscv/kvm/vcpu.c
> +++ b/arch/riscv/kvm/vcpu.c

[ ... ]

> @@ -26,6 +27,42 @@
>  
>  static DEFINE_PER_CPU(struct kvm_vcpu *, kvm_former_vcpu);
>  
> +/*
> + * WFI trap policy for VS-mode guests, controllable through the
> + * kvm-riscv.wfi_trap_policy= kernel command-line option.
> + */
> +enum kvm_riscv_wfi_trap_policy {
> +	KVM_RISCV_WFI_TRAP,	/* Default: trap VS-mode WFI into KVM */
> +	KVM_RISCV_WFI_NOTRAP,	/* Let VS-mode WFI execute natively */
> +};
> +
> +static enum kvm_riscv_wfi_trap_policy kvm_riscv_wfi_trap_policy __read_mostly =
> +	KVM_RISCV_WFI_TRAP;
> +
> +static int __init early_kvm_riscv_wfi_trap_policy_cfg(char *arg)
> +{
[ ... ]
> +	if (strcmp(arg, "notrap") == 0) {
> +		kvm_riscv_wfi_trap_policy = KVM_RISCV_WFI_NOTRAP;
> +		return 0;
> +	}
> +
> +	return -EINVAL;
> +}
> +early_param("kvm-riscv.wfi_trap_policy", early_kvm_riscv_wfi_trap_policy_cfg);

[Severity: Low]
Since KVM can be compiled as a loadable module (CONFIG_KVM=m), will this
use of early_param() cause a build failure?

In include/linux/init.h, early_param() is undefined when MODULE is defined.
Additionally, since early_param() only parses the early boot command line,
this setup prevents configuring the trap policy via arguments when KVM is
loaded dynamically.

Does this need to use module_param() or similar to ensure it builds correctly
as a module and accepts runtime arguments?

-- 
Sashiko AI review · https://sashiko.dev/#/patchset/20260709115610.287420-1-yhchen312@gmail.com?part=1

Re: [PATCH] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping

[Anup Patel]

On Thu, Jul 9, 2026 at 5:26 PM Yuhang.chen <yhchen312@gmail.com> wrote:
>
> Add a kernel command-line option, kvm-riscv.wfi_trap_policy=trap|notrap,
> that controls whether a WFI executed by a VS-mode guest traps into KVM
> (HS-mode) or executes natively.
>
> Measured results (wfi_exit_stat delta / guest wake count over 3 s):
>
>   policy        WFI_EXITS   WAKE_CNT
>   ----------    ---------   --------
>   default       295         294      (== trap, no regression)
>   trap          295         294
>   notrap          0         298
>
> Assisted-by: YuanSheng:deepseek-v4-pro
> Co-developed-by: Quan Zhou <zhouquan@iscas.ac.cn>
> Signed-off-by: Quan Zhou <zhouquan@iscas.ac.cn>
> Signed-off-by: Yuhang.chen <yhchen312@gmail.com>
> ---
>  .../admin-guide/kernel-parameters.txt         | 14 ++++++
>  arch/riscv/kvm/vcpu.c                         | 44 ++++++++++++++++++-
>  2 files changed, 57 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index b5493a7f8f22..ee6603b30033 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -3254,6 +3254,20 @@ Kernel parameters
>
>                         notrap: clear WFI instruction trap
>
> +       kvm-riscv.wfi_trap_policy=
> +                       [KVM,RISCV] Control when to set the WFI instruction
> +                       trap for KVM VMs. When set, a VS-mode WFI traps into
> +                       KVM and is emulated; when clear, the guest executes
> +                       WFI natively and blocks until a VS-mode interrupt
> +                       (e.g. the sstc timer) is pending.
> +
> +                       trap: set WFI instruction trap (HSTATUS.VTW=1)
> +
> +                       notrap: clear WFI instruction trap (HSTATUS.VTW=0)
> +
> +                       Defaults to trap, preserving the previous
> +                       unconditional behavior.
> +

This would mean that for the "notrap" policy the VCPU would never
sleep and increase host CPU utilization even when VCPU is idle.
Is this expected behaviour ?

Regards,
Anup

Re: [PATCH] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control VS-mode WFI trapping

[Yuhang.Chen]

Hi Anup,

Thanks for the review.

On Tue, 28 Jul 2026, Anup Patel <anup@brainfault.org> wrote:
> This would mean that for the "notrap" policy the VCPU would never
> sleep and increase host CPU utilization even when VCPU is idle.
> Is this expected behaviour ?

No, that was not intended. With "notrap", HSTATUS.VTW is cleared
unconditionally, so a VS-mode WFI never traps and the vCPU never reaches
kvm_vcpu_halt(); since WFI is only a hint, the vCPU thread can keep
spinning even while the guest is idle - the high host CPU you point out.

v2 drops "notrap" and replaces it with "auto": HSTATUS.VTW is cleared
only when the vCPU is the sole runnable task on its CPU
(single_task_running()), otherwise WFI traps and KVM blocks the vCPU
through kvm_vcpu_halt() as before. The default stays "trap", so there
is no regression, and the policy is re-evaluated on each vcpu_load() so
a vCPU that stops being the sole runnable task switches back to
trapping.

So to answer your question: the vCPU no longer stays busy at the
expense of other tasks - it either blocks through kvm_vcpu_halt(), or
runs WFI natively only when nothing else needs the CPU. On QEMU TCG,
host CPU stays around 5% while the vCPU is the sole task and rises back
to the trap level as soon as a competitor appears.

I have posted v2 as a new thread:

  [PATCH v2] RISC-V: KVM: Add kvm-riscv.wfi_trap_policy to control
  VS-mode WFI trapping

Regards,
Yuhang