[Xen-changelog] [xen staging] docs/cmdline: Rewrite the cpuid_mask_* section

[patchbot@xxxxxxx]

commit a3a99df44e5405d2092ec59087681765fa4cdee7
Author:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
AuthorDate: Fri Dec 7 13:43:27 2018 +0000
Commit:     Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CommitDate: Mon Dec 10 15:56:06 2018 +0000

    docs/cmdline: Rewrite the cpuid_mask_* section
    
    A large amount of the information here is obsolete since Xen 4.7
    
    To being with, however, this patch marks a change in style for section
    headings, due to how HTML anchors are generated.  Having more than one
    parameter per heading makes an awkward anchor, especially when brace 
globbing
    is used.  Furthermore, the misc suffixes such as (AMD only) get included, as
    do the escaping for the underscores.
    
    Markdown doesn't require escaped underscores in headings (I'm not entirely
    sure how we ended up with that style), so remove them and fully expand the
    glob syntax.  Also adjust com1,com2 while at it, which is the only other
    multi-parameter heading.  Move the misc suffixes into an "Applicability:" 
note
    alongside the information about defaults.
    
    This results in the headings being unadorned, and identical to how they are
    expressed on the command line and in code.
    
    For cpuid_mask_cpu option, collapse the long line of almost identical 
strings
    using [] globbing.  The result is much shorter and clearer to read.  Add a
    warning that this option no longer masks all features on Fam15h and above, 
due
    to not making use of the leaf 7 masks.
    
    For the remainder of the cpuid_mask_* options, collapse them all together 
into
    a single description.
    
    Finally, leave an explicit note explaining that people should not be using
    these options for migration safety.
    
    Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
    Acked-by: Jan Beulich <jbeulich@xxxxxxxx>
---
 docs/misc/xen-command-line.markdown | 60 +++++++++++++++++++------------------
 1 file changed, 31 insertions(+), 29 deletions(-)

diff --git a/docs/misc/xen-command-line.markdown 
b/docs/misc/xen-command-line.markdown
index 9b7688d0e8..805a04b6c1 100644
--- a/docs/misc/xen-command-line.markdown
+++ b/docs/misc/xen-command-line.markdown
@@ -277,7 +277,8 @@ Interrupts.  Specifying zero disables CMCI handling.
 Flag to indicate whether to probe for a CMOS Real Time Clock irrespective of
 ACPI indicating none to be there.
 
-### com1,com2
+### com1
+### com2
 > `= 
 > <baud>[/<base-baud>][,[DPS][,[<io-base>|pci|amt][,[<irq>|msi][,[<port-bdf>][,[<bridge-bdf>]]]]]]`
 
 Both option `com1` and `com2` follow the same format.
@@ -467,44 +468,45 @@ The Speculation Control hardware features `ibrsb`, 
`stibp`, `ibpb`,
 be ignored, e.g. `no-ibrsb`, at which point Xen won't use them itself, and
 won't offer them to guests.
 
-### cpuid\_mask\_cpu (AMD only)
-> `= fam_0f_rev_c | fam_0f_rev_d | fam_0f_rev_e | fam_0f_rev_f | fam_0f_rev_g 
| fam_10_rev_b | fam_10_rev_c | fam_11_rev_b`
+### cpuid_mask_cpu
+> `= fam_0f_rev_[cdefg] | fam_10_rev_[bc] | fam_11_rev_b`
 
-If the other **cpuid\_mask\_{,ext\_,thermal\_,l7s0\_}e{a,b,c,d}x**
-options are fully set (unspecified on the command line), specify a
-pre-canned cpuid mask to mask the current processor down to appear as
-the specified processor. It is important to ensure that all hosts in a
-pool appear the same to guests to allow successful live migration.
+> Applicability: AMD
 
-### cpuid\_mask\_{{,ext\_}ecx,edx} (x86)
-> `= <integer>`
+If none of the other **cpuid\_mask\_\*** options are given, Xen has a set of
+pre-configured masks to make the current processor appear to be
+family/revision specified.
 
-> Default: `~0` (all bits set)
+See below for general information on masking.
 
-These four command line parameters are used to specify cpuid masks to
-help with cpuid levelling across a pool of hosts.  Setting a bit in
-the mask indicates that the feature should be enabled, while clearing
-a bit in the mask indicates that the feature should be disabled.  It
-is important to ensure that all hosts in a pool appear the same to
-guests to allow successful live migration.
+**Warning: This option is not fully effective on Family 15h processors or
+later.**
 
-### cpuid\_mask\_xsave\_eax (Intel only)
+### cpuid_mask_ecx
+### cpuid_mask_edx
+### cpuid_mask_ext_ecx
+### cpuid_mask_ext_edx
+### cpuid_mask_l7s0_eax
+### cpuid_mask_l7s0_ebx
+### cpuid_mask_thermal_ecx
+### cpuid_mask_xsave_eax
 > `= <integer>`
 
-> Default: `~0` (all bits set)
-
-This command line parameter is also used to specify a cpuid mask to
-help with cpuid levelling across a pool of hosts.  See the description
-of the other respective options above.
+> Applicability: x86.  Default: `~0` (all bits set)
 
-### cpuid\_mask\_{l7s0\_{eax,ebx},thermal\_ecx} (AMD only)
-> `= <integer>`
+The availability of these options are model specific.  Some processors don't
+support any of them, and no processor supports all of them.  Xen will ignore
+options on processors which are lacking support.
 
-> Default: `~0` (all bits set)
+These options can be used to alter the features visible via the `CPUID`
+instruction.  Settings applied here take effect globally, including for Xen
+and all guests.
 
-These three command line parameters are also used to specify cpuid
-masks to help with cpuid levelling across a pool of hosts.  See the
-description of the other respective options above.
+Note: Since Xen 4.7, it is no longer necessary to mask a host to create
+migration safety in heterogeneous scenarios.  All necessary CPUID settings
+should be provided in the VM configuration file.  Furthermore, it is
+recommended not to use this option, as doing so causes an unnecessary
+reduction of features at Xen's disposal to manage guests.
 
 ### cpuidle (x86)
 > `= <boolean>`
--
generated by git-patchbot for /home/xen/git/xen.git#staging

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxxx
https://lists.xenproject.org/xen-changelog