* [PATCH] docs: clarify KVM related kernel parameters' descriptions @ 2023-05-02 11:25 Yan-Jie Wang 2023-05-02 17:12 ` Sean Christopherson 2023-05-03 8:15 ` [PATCH v2] " Yan-Jie Wang 0 siblings, 2 replies; 5+ messages in thread From: Yan-Jie Wang @ 2023-05-02 11:25 UTC (permalink / raw) To: linux-doc, linux-kernel Cc: Jonathan Corbet, Sean Christopherson, Paolo Bonzini, Randy Dunlap, Andre Przywara, Avi Kivity, Yan-Jie Wang, Ching-Chun Huang, trivial, kvm 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 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH] docs: clarify KVM related kernel parameters' descriptions 2023-05-02 11:25 [PATCH] docs: clarify KVM related kernel parameters' descriptions Yan-Jie Wang @ 2023-05-02 17:12 ` Sean Christopherson 2023-05-03 7:15 ` Yan-Jie Wang 2023-05-03 8:15 ` [PATCH v2] " Yan-Jie Wang 1 sibling, 1 reply; 5+ messages in thread From: Sean Christopherson @ 2023-05-02 17:12 UTC (permalink / raw) To: Yan-Jie Wang Cc: linux-doc, linux-kernel, Jonathan Corbet, Paolo Bonzini, Randy Dunlap, Andre Przywara, Avi Kivity, Ching-Chun Huang, trivial, kvm 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 > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH] docs: clarify KVM related kernel parameters' descriptions 2023-05-02 17:12 ` Sean Christopherson @ 2023-05-03 7:15 ` Yan-Jie Wang 0 siblings, 0 replies; 5+ messages in thread From: Yan-Jie Wang @ 2023-05-03 7:15 UTC (permalink / raw) To: Sean Christopherson Cc: linux-doc, linux-kernel, Jonathan Corbet, Paolo Bonzini, Randy Dunlap, Andre Przywara, Avi Kivity, Ching-Chun Huang, trivial, kvm 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 > > ^ permalink raw reply [flat|nested] 5+ messages in thread
* [PATCH v2] docs: clarify KVM related kernel parameters' descriptions 2023-05-02 11:25 [PATCH] docs: clarify KVM related kernel parameters' descriptions Yan-Jie Wang 2023-05-02 17:12 ` Sean Christopherson @ 2023-05-03 8:15 ` Yan-Jie Wang 2023-05-19 14:56 ` Jonathan Corbet 1 sibling, 1 reply; 5+ messages in thread From: Yan-Jie Wang @ 2023-05-03 8:15 UTC (permalink / raw) To: linux-doc, linux-kernel Cc: Jonathan Corbet, Sean Christopherson, Paolo Bonzini, Randy Dunlap, Andre Przywara, Avi Kivity, Yan-Jie Wang, Ching-Chun Huang, trivial, kvm 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 ^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH v2] docs: clarify KVM related kernel parameters' descriptions 2023-05-03 8:15 ` [PATCH v2] " Yan-Jie Wang @ 2023-05-19 14:56 ` Jonathan Corbet 0 siblings, 0 replies; 5+ messages in thread From: Jonathan Corbet @ 2023-05-19 14:56 UTC (permalink / raw) To: Yan-Jie Wang, linux-doc, linux-kernel Cc: Sean Christopherson, Paolo Bonzini, Randy Dunlap, Andre Przywara, Avi Kivity, Yan-Jie Wang, Ching-Chun Huang, trivial, kvm 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2023-05-19 14:56 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2023-05-02 11:25 [PATCH] docs: clarify KVM related kernel parameters' descriptions Yan-Jie Wang 2023-05-02 17:12 ` Sean Christopherson 2023-05-03 7:15 ` Yan-Jie Wang 2023-05-03 8:15 ` [PATCH v2] " Yan-Jie Wang 2023-05-19 14:56 ` Jonathan Corbet
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox