docs/xl.cfg: Rewrite cpuid= section

This is partly to adjust the description of 'k' and 's' seeing as they have
changed, but mostly restructuring the information for clarity.

In particular, use indentation to clearly separate the areas discussing libxl
format from xend format.  In addition, extend the xend format section to
discuss subleaf notation.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in
index c9bc181a9534cacad92c8f8a4b4883e1b98ef278..0532739c1fff933015b10a77970125c2bbeb653f 100644 (file)
--- a/docs/man/xl.cfg.5.pod.in
+++ b/docs/man/xl.cfg.5.pod.in
@@ -1977,26 +1977,42 @@ This option is disabled by default.
 Configure the value returned when a guest executes the CPUID instruction.
 Two versions of config syntax are recognized: libxl and xend.
 
-The libxl syntax is a comma separated list of key=value pairs, preceded by the
-word "host". A few keys take a numerical value, all others take a single
-character which describes what to do with the feature bit.
-
-Possible values for a single feature bit:
+Both formats use a common notation for specifying a single feature bit.
+Possible values are:
   '1' -> force the corresponding bit to 1
   '0' -> force to 0
   'x' -> Get a safe value (pass through and mask with the default policy)
-  'k' -> pass through the host bit value
-  's' -> as 'k' but preserve across save/restore and migration (not implemented)
+  'k' -> pass through the host bit value (at boot only - value preserved on migrate)
+  's' -> legacy alias for 'k'
 
-Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group)
-only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the
-rest are ignored (these 8 bits signify maximum number of hypervisor leaves).
+B<Libxl format>:
+
+=over 4
+
+The libxl format is a single string, starting with the word "host", and
+followed by a comma separated list of key=value pairs.  A few keys take a
+numerical value, all others take a single character which describes what to do
+with the feature bit.  e.g.:
+
+=over 4
+
+cpuid="host,tm=0,sse3=0"
+
+=back
 
 List of keys taking a value:
+
+=over 4
+
 apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc
 proccount procpkg stepping
 
+=back
+
 List of keys taking a character:
+
+=over 4
+
 3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8 apic arat avx avx2
 avx512-4fmaps avx512-4vnniw avx512bw avx512cd avx512dq avx512er avx512f
 avx512ifma avx512pf avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
@@ -2010,21 +2026,37 @@ ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt svm_tscrate
 svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc tsc-deadline tsc_adjust
 umip vme vmx wdt x2apic xop xsave xtpr
 
+=back
+
+=back
+
+B<Xend format>:
 
-The xend syntax is a list of values in the form of
-'leafnum:register=bitstring,register=bitstring'
-  "leafnum" is the requested function,
-  "register" is the response register to modify
-  "bitstring" represents all bits in the register, its length must be 32 chars.
-  Each successive character represent a lesser-significant bit, possible values
-  are listed above in the libxl section.
+=over 4
 
-Example to hide two features from the guest: 'tm', which is bit #29 in EDX, and
-'pni' (SSE3), which is bit #0 in ECX:
+Xend format consists of an array of one or more strings of the form
+"leaf:reg=bitstring,...".  e.g. (matching the libxl example above):
 
-xend: [ "1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ]
+=over 4
 
-libxl: "host,tm=0,sse3=0"
+cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx", ...]
+
+=back
+
+"leaf" is an integer, either decimal or hex with a "0x" prefix.  e.g. to
+specify something in the AMD feature leaves, use "0x80000001:ecx=...".
+
+Some leaves have subleaves which can be specified as "leaf,subleaf".  e.g. for
+the Intel structured feature leaf, use "7,0:ebx=..."
+
+The bitstring represents all bits in the register, its length must be 32
+chars.  Each successive character represent a lesser-significant bit.
+
+=back
+
+Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group)
+only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the
+rest are ignored (these 8 bits signify maximum number of hypervisor leaves).
 
 More info about the CPUID instruction can be found in the processor manuals,
 and on Wikipedia: L<https://en.wikipedia.org/wiki/CPUID>