[PATCH] xl.cfg: document the cpuid= option

[PATCH] xl.cfg: document the cpuid= option

[Olaf Hering]

# HG changeset patch
# User Olaf Hering <olaf@aepfle.de>
# Date 1338572607 -7200
# Node ID 3da83ff08d6b6431c104a431d6617ccb5977643b
# Parent  fde8ad0252ee6ddb8d71dda869db3b20b3d9ca62
xl.cfg: document the cpuid= option

Signed-off-by: Olaf Hering <olaf@aepfle.de>

diff -r fde8ad0252ee -r 3da83ff08d6b docs/man/xl.cfg.pod.5
--- a/docs/man/xl.cfg.pod.5
+++ b/docs/man/xl.cfg.pod.5
@@ -969,9 +969,47 @@ XXX
 
 XXX
 
-=item B<cpuid=XXX>
+=item B<cpuid="STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
 
-XXX
+Configure guest CPUID responses. Two config versions of config syntax are
+recognized: xend and libxl.
+
+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 a bit in the register, its length must be exactly 32 chars.
+  Each successive character represent a lesser-significant bit:
+   '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)
+
+The libxl syntax is a comma separated list of key=value pairs, preceded by the
+word "host". Some keys take a numerical value, all others take a single
+character just as in the "bitstring" list above.
+
+List of keys taking a value:
+apicidsize brandid clflush family localapicid maxleaf model nc proccount procpkg
+stepping
+
+List of keys taking a character:
+3dnow 3dnowext 3dnowprefetch abm acpi aes altmovcr8 apic avx clfsh cmov
+cmplegacy cmpxchg16 cmpxchg8 cntxid dca de ds dscpl dtes64 est extapic f16c
+ffxsr fma4 fpu fxsr htt hypervisor ia64 ibs lahfsahf lm lwp mca mce misalignsse
+mmx mmxext monitor movbe msr mtrr nodeid nx osvw osxsave pae page1gb pat pbe
+pclmulqdq pdcm pge popcnt pse pse36 psn rdtscp skinit smx ss sse sse2 sse3
+sse4.1 sse4.2 sse4a ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips
+svm_pausefilt svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc
+vme vmx wdt x2apic xop xsave xtpr
+
+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: [ '1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' ]
+
+libxl: 'host,tm=0,sse3=0'
 
 =item B<acpi_s3=BOOLEAN>

Re: [PATCH] xl.cfg: document the cpuid= option

[George Dunlap]

On Fri, Jun 1, 2012 at 6:48 PM, Olaf Hering <olaf@aepfle.de> wrote:
> # HG changeset patch
> # User Olaf Hering <olaf@aepfle.de>
> # Date 1338572607 -7200
> # Node ID 3da83ff08d6b6431c104a431d6617ccb5977643b
> # Parent  fde8ad0252ee6ddb8d71dda869db3b20b3d9ca62
> xl.cfg: document the cpuid= option
>
> Signed-off-by: Olaf Hering <olaf@aepfle.de>
>
> diff -r fde8ad0252ee -r 3da83ff08d6b docs/man/xl.cfg.pod.5
> --- a/docs/man/xl.cfg.pod.5
> +++ b/docs/man/xl.cfg.pod.5
> @@ -969,9 +969,47 @@ XXX
>
>  XXX
>
> -=item B<cpuid=XXX>
> +=item B<cpuid="STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
>
> -XXX
> +Configure guest CPUID responses.

I think I would say, "Configure the value returned when a guest
executes CPUID instruction".  ("Response" is a technical term that
doesn't really seem to fit here, I think.)

> Two config versions of config syntax are
> +recognized: xend and libxl.

It's not clear from this text -- will libxl understand the xend format?

Other than that, the explanation and the example look really good.
(NB, I haven't reviewed for accuracy.)

 -George

Re: [PATCH] xl.cfg: document the cpuid= option

[Ian Campbell]

On Wed, 2012-06-06 at 10:20 +0100, George Dunlap wrote:
> On Fri, Jun 1, 2012 at 6:48 PM, Olaf Hering <olaf@aepfle.de> wrote:
> > # HG changeset patch
> > # User Olaf Hering <olaf@aepfle.de>
> > # Date 1338572607 -7200
> > # Node ID 3da83ff08d6b6431c104a431d6617ccb5977643b
> > # Parent  fde8ad0252ee6ddb8d71dda869db3b20b3d9ca62
> > xl.cfg: document the cpuid= option
> >
> > Signed-off-by: Olaf Hering <olaf@aepfle.de>
> >
> > diff -r fde8ad0252ee -r 3da83ff08d6b docs/man/xl.cfg.pod.5
> > --- a/docs/man/xl.cfg.pod.5
> > +++ b/docs/man/xl.cfg.pod.5
> > @@ -969,9 +969,47 @@ XXX
> >
> >  XXX
> >
> > -=item B<cpuid=XXX>
> > +=item B<cpuid="STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
> >
> > -XXX
> > +Configure guest CPUID responses.
> 
> I think I would say, "Configure the value returned when a guest
> executes CPUID instruction".  ("Response" is a technical term that
> doesn't really seem to fit here, I think.)
> 
> > Two config versions of config syntax are
> > +recognized: xend and libxl.
> 
> It's not clear from this text -- will libxl understand the xend format?

Yes, although for clarity the xl one ought to be preferred IMHO and
therefore made more prominent than the xend one i.e. be described first
and completely rather than referencing to the xend syntax (which can
refer to the xl stuff if necessary).

> 
> Other than that, the explanation and the example look really good.
> (NB, I haven't reviewed for accuracy.)
> 
>  -George
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> http://lists.xen.org/xen-devel

Re: [PATCH] xl.cfg: document the cpuid= option

[Olaf Hering]

On Wed, Jun 06, Ian Campbell wrote:

> On Wed, 2012-06-06 at 10:20 +0100, George Dunlap wrote:
> > On Fri, Jun 1, 2012 at 6:48 PM, Olaf Hering <olaf@aepfle.de> wrote:

> > > Two config versions of config syntax are
> > > +recognized: xend and libxl.
> > It's not clear from this text -- will libxl understand the xend format?
> 
> Yes, although for clarity the xl one ought to be preferred IMHO and
> therefore made more prominent than the xend one i.e. be described first
> and completely rather than referencing to the xend syntax (which can
> refer to the xl stuff if necessary).

Thanks for the input. I sent out a second version of this patch.

Olaf

[PATCH] xl.cfg: document the cpuid= option

[Olaf Hering]

# HG changeset patch
# User Olaf Hering <olaf@aepfle.de>
# Date 1338998032 -7200
# Node ID 0e4a303989d132ca49c77ff6b7cbebb8f501efaa
# Parent  b5411db463770c9e11ac687fd80b0947b11fa5ca
xl.cfg: document the cpuid= option

v2:
 - describe libxl syntax before xend syntax
 - add wikipedia link

Signed-off-by: Olaf Hering <olaf@aepfle.de>

diff -r b5411db46377 -r 0e4a303989d1 docs/man/xl.cfg.pod.5
--- a/docs/man/xl.cfg.pod.5
+++ b/docs/man/xl.cfg.pod.5
@@ -969,9 +969,53 @@ XXX
 
 XXX
 
-=item B<cpuid=XXX>
+=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
 
-XXX
+Configure the value returned when a guest executes 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:
+  '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)
+
+List of keys taking a value:
+apicidsize brandid clflush family localapicid maxleaf model nc proccount procpkg
+stepping
+
+List of keys taking a character:
+3dnow 3dnowext 3dnowprefetch abm acpi aes altmovcr8 apic avx clfsh cmov
+cmplegacy cmpxchg16 cmpxchg8 cntxid dca de ds dscpl dtes64 est extapic f16c
+ffxsr fma4 fpu fxsr htt hypervisor ia64 ibs lahfsahf lm lwp mca mce misalignsse
+mmx mmxext monitor movbe msr mtrr nodeid nx osvw osxsave pae page1gb pat pbe
+pclmulqdq pdcm pge popcnt pse pse36 psn rdtscp skinit smx ss sse sse2 sse3
+sse4.1 sse4.2 sse4a ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips
+svm_pausefilt svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc
+vme vmx wdt x2apic xop xsave xtpr
+
+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.
+
+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: [ '1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' ]
+
+libxl: 'host,tm=0,sse3=0'
+
+More info about the CPUID instruction can be found in the processor manuals, and
+in Wikipedia: L<http://en.wikipedia.org/wiki/CPUID>
 
 =item B<acpi_s3=BOOLEAN>

Re: [PATCH] xl.cfg: document the cpuid= option [and 1 more messages]

[Ian Jackson]

Olaf Hering writes ("[Xen-devel] [PATCH] xl.cfg: document the cpuid= option"):
> xl.cfg: document the cpuid= option

Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>