Re: Ping [PATCH v2 17/17] docs/xl.cfg: Rewrite cpuid= section

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 27/01/2020 14:34, Andrew Cooper wrote:
> 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@xxxxxxxxxx>
> ---
> CC: Ian Jackson <Ian.Jackson@xxxxxxxxxx>
> CC: Wei Liu <wl@xxxxxxx>
> CC: Anthony PERARD <anthony.perard@xxxxxxxxxx>
>
> v2:
>  * New
> ---
>  docs/man/xl.cfg.5.pod.in | 74 
> ++++++++++++++++++++++++++++++++++--------------
>  1 file changed, 53 insertions(+), 21 deletions(-)
>
> diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in
> index 245d3f9472..1da68c4a07 100644
> --- a/docs/man/xl.cfg.5.pod.in
> +++ b/docs/man/xl.cfg.5.pod.in
> @@ -1964,26 +1964,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
> @@ -1997,21 +2013,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>