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@citrix.com>
> ---
> CC: Ian Jackson <Ian.Jackson@citrix.com>
> CC: Wei Liu <wl@xen.org>
> CC: Anthony PERARD <anthony.perard@citrix.com>
>
> 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>