[PATCH] docs: clarify KVM related kernel parameters' descriptions

[PATCH] docs: clarify KVM related kernel parameters' descriptions

[Yan-Jie Wang]

The descriptions of certain KVM related kernel parameters can be
ambiguous and confusing. They state 'Disable ...,' which implies that
setting them to 1 would disable the associated features or options,
when in fact the opposite is true.

This commit addresses this issue by revising the descriptions of these
parameters to make their intended behavior clear.

Signed-off-by: Yan-Jie Wang <yanjiewtw@gmail.com>
---
 Documentation/admin-guide/kernel-parameters.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 9e5bab29685f..cc5abb3d54b9 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -2552,10 +2552,10 @@
 			on the ratio, such that a page is zapped after 1 hour on average.
 
 	kvm-amd.nested=	[KVM,AMD] Allow nested virtualization in KVM/SVM.
-			Default is 1 (enabled)
+			Default is 1 (allow)
 
-	kvm-amd.npt=	[KVM,AMD] Disable nested paging (virtualized MMU)
-			for all guests.
+	kvm-amd.npt=	[KVM,AMD] Enable nested paging (virtualized MMU)
+			for all guests on capable AMD chips.
 			Default is 1 (enabled) if in 64-bit or 32-bit PAE mode.
 
 	kvm-arm.mode=
@@ -2602,12 +2602,12 @@
 			Format: <integer>
 			Default: 5
 
-	kvm-intel.ept=	[KVM,Intel] Disable extended page tables
+	kvm-intel.ept=	[KVM,Intel] Enable extended page tables
 			(virtualized MMU) support on capable Intel chips.
 			Default is 1 (enabled)
 
 	kvm-intel.emulate_invalid_guest_state=
-			[KVM,Intel] Disable emulation of invalid guest state.
+			[KVM,Intel] Enable emulation of invalid guest state.
 			Ignored if kvm-intel.enable_unrestricted_guest=1, as
 			guest state is never invalid for unrestricted guests.
 			This param doesn't apply to nested guests (L2), as KVM
@@ -2615,7 +2615,7 @@
 			Default is 1 (enabled)
 
 	kvm-intel.flexpriority=
-			[KVM,Intel] Disable FlexPriority feature (TPR shadow).
+			[KVM,Intel] Enable FlexPriority feature (TPR shadow).
 			Default is 1 (enabled)
 
 	kvm-intel.nested=
@@ -2623,7 +2623,7 @@
 			Default is 0 (disabled)
 
 	kvm-intel.unrestricted_guest=
-			[KVM,Intel] Disable unrestricted guest feature
+			[KVM,Intel] Enable unrestricted guest feature
 			(virtualized real and unpaged mode) on capable
 			Intel chips. Default is 1 (enabled)
 
@@ -2639,7 +2639,7 @@
 
 			Default is cond (do L1 cache flush in specific instances)
 
-	kvm-intel.vpid=	[KVM,Intel] Disable Virtual Processor Identification
+	kvm-intel.vpid=	[KVM,Intel] Enable Virtual Processor Identification
 			feature (tagged TLBs) on capable Intel chips.
 			Default is 1 (enabled)
 

base-commit: 865fdb08197e657c59e74a35fa32362b12397f58
-- 
2.34.1

Re: [PATCH] docs: clarify KVM related kernel parameters' descriptions

[Sean Christopherson]

On Tue, May 02, 2023, Yan-Jie Wang wrote:
> The descriptions of certain KVM related kernel parameters can be
> ambiguous and confusing. They state 'Disable ...,' which implies that
> setting them to 1 would disable the associated features or options,
> when in fact the opposite is true.
> 
> This commit addresses this issue by revising the descriptions of these
> parameters to make their intended behavior clear.

Less wrong perhaps, but IMO the actual behavior is still not captured, and from
a certain perspective the existing "Disable" verbiage better reflects how/when
most users would actually want to explicitly set a param.

Rather than commit one way or the other, what about reworking the descriptions
using this as a template?  E.g. state that the param controls something, state
the default and use that to communicate that 1==enabled, and then, when appropriate,
clarify that KVM disables (or in some cases ignores) params if hardware doesn't
support the related feature(s).

	kvm-intel.ept=	[KVM,Intel] Control KVM's use of Extended Page Tables,
			a.k.a. Two-Dimensional Page Tables.  Default is 1
			(enabled).  Disabled by KVM if hardware lacks support
			for EPT.

> 
> Signed-off-by: Yan-Jie Wang <yanjiewtw@gmail.com>
> ---
>  Documentation/admin-guide/kernel-parameters.txt | 16 ++++++++--------
>  1 file changed, 8 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> index 9e5bab29685f..cc5abb3d54b9 100644
> --- a/Documentation/admin-guide/kernel-parameters.txt
> +++ b/Documentation/admin-guide/kernel-parameters.txt
> @@ -2552,10 +2552,10 @@
>  			on the ratio, such that a page is zapped after 1 hour on average.
>  
>  	kvm-amd.nested=	[KVM,AMD] Allow nested virtualization in KVM/SVM.

Eh, I don't see any reason to have this one say "allow" instead of "enable/disable".

> -			Default is 1 (enabled)
> +			Default is 1 (allow)
>  
> -	kvm-amd.npt=	[KVM,AMD] Disable nested paging (virtualized MMU)
> -			for all guests.
> +	kvm-amd.npt=	[KVM,AMD] Enable nested paging (virtualized MMU)
> +			for all guests on capable AMD chips.
>  			Default is 1 (enabled) if in 64-bit or 32-bit PAE mode.
>  
>  	kvm-arm.mode=
> @@ -2602,12 +2602,12 @@
>  			Format: <integer>
>  			Default: 5
>  
> -	kvm-intel.ept=	[KVM,Intel] Disable extended page tables
> +	kvm-intel.ept=	[KVM,Intel] Enable extended page tables
>  			(virtualized MMU) support on capable Intel chips.
>  			Default is 1 (enabled)
>  
>  	kvm-intel.emulate_invalid_guest_state=
> -			[KVM,Intel] Disable emulation of invalid guest state.
> +			[KVM,Intel] Enable emulation of invalid guest state.
>  			Ignored if kvm-intel.enable_unrestricted_guest=1, as
>  			guest state is never invalid for unrestricted guests.
>  			This param doesn't apply to nested guests (L2), as KVM
> @@ -2615,7 +2615,7 @@
>  			Default is 1 (enabled)
>  
>  	kvm-intel.flexpriority=
> -			[KVM,Intel] Disable FlexPriority feature (TPR shadow).
> +			[KVM,Intel] Enable FlexPriority feature (TPR shadow).
>  			Default is 1 (enabled)
>  
>  	kvm-intel.nested=
> @@ -2623,7 +2623,7 @@
>  			Default is 0 (disabled)

Heh, kvm-intel.nested has been enabled by default for quite some time.  Can you
fix that up too?

>  
>  	kvm-intel.unrestricted_guest=
> -			[KVM,Intel] Disable unrestricted guest feature
> +			[KVM,Intel] Enable unrestricted guest feature
>  			(virtualized real and unpaged mode) on capable
>  			Intel chips. Default is 1 (enabled)
>  
> @@ -2639,7 +2639,7 @@
>  
>  			Default is cond (do L1 cache flush in specific instances)
>  
> -	kvm-intel.vpid=	[KVM,Intel] Disable Virtual Processor Identification
> +	kvm-intel.vpid=	[KVM,Intel] Enable Virtual Processor Identification
>  			feature (tagged TLBs) on capable Intel chips.
>  			Default is 1 (enabled)
>  
> 
> base-commit: 865fdb08197e657c59e74a35fa32362b12397f58
> -- 
> 2.34.1
> 

Re: [PATCH] docs: clarify KVM related kernel parameters' descriptions

[Yan-Jie Wang]

Thank you, Sean.

I will revise the patch accordingly and submit a new version as well
as update the description of kvm-intel.nested to reflect that it is
enabled by default.

On Wed, May 3, 2023 at 1:12 AM Sean Christopherson <seanjc@google.com> wrote:
>
> On Tue, May 02, 2023, Yan-Jie Wang wrote:
> > The descriptions of certain KVM related kernel parameters can be
> > ambiguous and confusing. They state 'Disable ...,' which implies that
> > setting them to 1 would disable the associated features or options,
> > when in fact the opposite is true.
> >
> > This commit addresses this issue by revising the descriptions of these
> > parameters to make their intended behavior clear.
>
> Less wrong perhaps, but IMO the actual behavior is still not captured, and from
> a certain perspective the existing "Disable" verbiage better reflects how/when
> most users would actually want to explicitly set a param.
>
> Rather than commit one way or the other, what about reworking the descriptions
> using this as a template?  E.g. state that the param controls something, state
> the default and use that to communicate that 1==enabled, and then, when appropriate,
> clarify that KVM disables (or in some cases ignores) params if hardware doesn't
> support the related feature(s).
>
>         kvm-intel.ept=  [KVM,Intel] Control KVM's use of Extended Page Tables,
>                         a.k.a. Two-Dimensional Page Tables.  Default is 1
>                         (enabled).  Disabled by KVM if hardware lacks support
>                         for EPT.
>
> >
> > Signed-off-by: Yan-Jie Wang <yanjiewtw@gmail.com>
> > ---
> >  Documentation/admin-guide/kernel-parameters.txt | 16 ++++++++--------
> >  1 file changed, 8 insertions(+), 8 deletions(-)
> >
> > diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
> > index 9e5bab29685f..cc5abb3d54b9 100644
> > --- a/Documentation/admin-guide/kernel-parameters.txt
> > +++ b/Documentation/admin-guide/kernel-parameters.txt
> > @@ -2552,10 +2552,10 @@
> >                       on the ratio, such that a page is zapped after 1 hour on average.
> >
> >       kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM.
>
> Eh, I don't see any reason to have this one say "allow" instead of "enable/disable".
>
> > -                     Default is 1 (enabled)
> > +                     Default is 1 (allow)
> >
> > -     kvm-amd.npt=    [KVM,AMD] Disable nested paging (virtualized MMU)
> > -                     for all guests.
> > +     kvm-amd.npt=    [KVM,AMD] Enable nested paging (virtualized MMU)
> > +                     for all guests on capable AMD chips.
> >                       Default is 1 (enabled) if in 64-bit or 32-bit PAE mode.
> >
> >       kvm-arm.mode=
> > @@ -2602,12 +2602,12 @@
> >                       Format: <integer>
> >                       Default: 5
> >
> > -     kvm-intel.ept=  [KVM,Intel] Disable extended page tables
> > +     kvm-intel.ept=  [KVM,Intel] Enable extended page tables
> >                       (virtualized MMU) support on capable Intel chips.
> >                       Default is 1 (enabled)
> >
> >       kvm-intel.emulate_invalid_guest_state=
> > -                     [KVM,Intel] Disable emulation of invalid guest state.
> > +                     [KVM,Intel] Enable emulation of invalid guest state.
> >                       Ignored if kvm-intel.enable_unrestricted_guest=1, as
> >                       guest state is never invalid for unrestricted guests.
> >                       This param doesn't apply to nested guests (L2), as KVM
> > @@ -2615,7 +2615,7 @@
> >                       Default is 1 (enabled)
> >
> >       kvm-intel.flexpriority=
> > -                     [KVM,Intel] Disable FlexPriority feature (TPR shadow).
> > +                     [KVM,Intel] Enable FlexPriority feature (TPR shadow).
> >                       Default is 1 (enabled)
> >
> >       kvm-intel.nested=
> > @@ -2623,7 +2623,7 @@
> >                       Default is 0 (disabled)
>
> Heh, kvm-intel.nested has been enabled by default for quite some time.  Can you
> fix that up too?
>
> >
> >       kvm-intel.unrestricted_guest=
> > -                     [KVM,Intel] Disable unrestricted guest feature
> > +                     [KVM,Intel] Enable unrestricted guest feature
> >                       (virtualized real and unpaged mode) on capable
> >                       Intel chips. Default is 1 (enabled)
> >
> > @@ -2639,7 +2639,7 @@
> >
> >                       Default is cond (do L1 cache flush in specific instances)
> >
> > -     kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification
> > +     kvm-intel.vpid= [KVM,Intel] Enable Virtual Processor Identification
> >                       feature (tagged TLBs) on capable Intel chips.
> >                       Default is 1 (enabled)
> >
> >
> > base-commit: 865fdb08197e657c59e74a35fa32362b12397f58
> > --
> > 2.34.1
> >

[PATCH v2] docs: clarify KVM related kernel parameters' descriptions

[Yan-Jie Wang]

The descriptions of certain KVM related kernel parameters can be
confusing. They state "Disable ...," which may make people think that
setting them to 1 will disable the associated feature when in fact the
opposite is true.

This commit addresses this issue by revising the descriptions of these
parameters by using "Control..." rather than "Enable/Disable...".
1==enabled or 0==disabled can be communicated by the description of
default value such as "1 (enabled)" or "0 (disabled)".

Also update the description of KVM's default value for kvm-intel.nested
as it is enabled by default.

Signed-off-by: Yan-Jie Wang <yanjiewtw@gmail.com>
---
Changes in v2:
- Revise the descriptions based on Sean's suggesstion.
- Fix the wrong default value of kvm-intel.nested
---
 .../admin-guide/kernel-parameters.txt         | 53 ++++++++++---------
 1 file changed, 29 insertions(+), 24 deletions(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 9e5bab29685f..450c9d3af3ed 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -2551,12 +2551,13 @@
 			If the value is 0 (the default), KVM will pick a period based
 			on the ratio, such that a page is zapped after 1 hour on average.
 
-	kvm-amd.nested=	[KVM,AMD] Allow nested virtualization in KVM/SVM.
-			Default is 1 (enabled)
+	kvm-amd.nested=	[KVM,AMD] Control nested virtualization feature in
+			KVM/SVM. Default is 1 (enabled).
 
-	kvm-amd.npt=	[KVM,AMD] Disable nested paging (virtualized MMU)
-			for all guests.
-			Default is 1 (enabled) if in 64-bit or 32-bit PAE mode.
+	kvm-amd.npt=	[KVM,AMD] Control KVM's use of Nested Page Tables,
+			a.k.a. Two-Dimensional Page Tables. Default is 1
+			(enabled). Disable by KVM if hardware lacks support
+			for NPT.
 
 	kvm-arm.mode=
 			[KVM,ARM] Select one of KVM/arm64's modes of operation.
@@ -2602,30 +2603,33 @@
 			Format: <integer>
 			Default: 5
 
-	kvm-intel.ept=	[KVM,Intel] Disable extended page tables
-			(virtualized MMU) support on capable Intel chips.
-			Default is 1 (enabled)
+	kvm-intel.ept=	[KVM,Intel] Control KVM's use of Extended Page Tables,
+			a.k.a. Two-Dimensional Page Tables.  Default is 1
+			(enabled). Disable by KVM if hardware lacks support
+			for EPT.
 
 	kvm-intel.emulate_invalid_guest_state=
-			[KVM,Intel] Disable emulation of invalid guest state.
-			Ignored if kvm-intel.enable_unrestricted_guest=1, as
-			guest state is never invalid for unrestricted guests.
-			This param doesn't apply to nested guests (L2), as KVM
-			never emulates invalid L2 guest state.
-			Default is 1 (enabled)
+			[KVM,Intel] Control whether to emulate invalid guest
+			state. Ignored if kvm-intel.enable_unrestricted_guest=1,
+			as guest state is never invalid for unrestricted
+			guests. This param doesn't apply to nested guests (L2),
+			as KVM never emulates invalid L2 guest state.
+			Default is 1 (enabled).
 
 	kvm-intel.flexpriority=
-			[KVM,Intel] Disable FlexPriority feature (TPR shadow).
-			Default is 1 (enabled)
+			[KVM,Intel] Control KVM's use of FlexPriority feature
+			(TPR shadow). Default is 1 (enabled). Disalbe by KVM if
+			hardware lacks support for it.
 
 	kvm-intel.nested=
-			[KVM,Intel] Enable VMX nesting (nVMX).
-			Default is 0 (disabled)
+			[KVM,Intel] Control nested virtualization feature in
+			KVM/VMX. Default is 1 (enabled).
 
 	kvm-intel.unrestricted_guest=
-			[KVM,Intel] Disable unrestricted guest feature
-			(virtualized real and unpaged mode) on capable
-			Intel chips. Default is 1 (enabled)
+			[KVM,Intel] Control KVM's use of unrestricted guest
+			feature (virtualized real and unpaged mode). Default
+			is 1 (enabled). Disable by KVM if EPT is disabled or
+			hardware lacks support for it.
 
 	kvm-intel.vmentry_l1d_flush=[KVM,Intel] Mitigation for L1 Terminal Fault
 			CVE-2018-3620.
@@ -2639,9 +2643,10 @@
 
 			Default is cond (do L1 cache flush in specific instances)
 
-	kvm-intel.vpid=	[KVM,Intel] Disable Virtual Processor Identification
-			feature (tagged TLBs) on capable Intel chips.
-			Default is 1 (enabled)
+	kvm-intel.vpid=	[KVM,Intel] Control KVM's use of Virtual Processor
+			Identification feature (tagged TLBs). Default is 1
+			(enabled). Disable by KVM if hardware lacks support
+			for it.
 
 	l1d_flush=	[X86,INTEL]
 			Control mitigation for L1D based snooping vulnerability.

base-commit: 865fdb08197e657c59e74a35fa32362b12397f58
-- 
2.34.1

Re: [PATCH v2] docs: clarify KVM related kernel parameters' descriptions

[Jonathan Corbet]

Yan-Jie Wang <yanjiewtw@gmail.com> writes:

> The descriptions of certain KVM related kernel parameters can be
> confusing. They state "Disable ...," which may make people think that
> setting them to 1 will disable the associated feature when in fact the
> opposite is true.
>
> This commit addresses this issue by revising the descriptions of these
> parameters by using "Control..." rather than "Enable/Disable...".
> 1==enabled or 0==disabled can be communicated by the description of
> default value such as "1 (enabled)" or "0 (disabled)".
>
> Also update the description of KVM's default value for kvm-intel.nested
> as it is enabled by default.
>
> Signed-off-by: Yan-Jie Wang <yanjiewtw@gmail.com>
> ---
> Changes in v2:
> - Revise the descriptions based on Sean's suggesstion.
> - Fix the wrong default value of kvm-intel.nested
> ---
>  .../admin-guide/kernel-parameters.txt         | 53 ++++++++++---------
>  1 file changed, 29 insertions(+), 24 deletions(-)

Applied, thanks.

jon