docs: flesh out xl.cfg documentation, correct typos, reorganize

Some highlights:
 * Correct some markup errors:
       Around line 663:
           '=item' outside of any '=over'
       Around line 671:
           You forgot a '=back' before '=head3'
 * Add documentation for msitranslate, power_mgnt, acpi_s3, aspi_s4,
   gfx_passthru, nomigrate, etc.
 * Reorganize items in "unclassified" sections like cpuid,
   gfx_passthru to where they belong
 * Correct link L<> references so they can be resolved within the
   document
 * Remove placeholders for deprecated options device_model and vif2
 * Remove placeholder for "sched" and "node", as these are options for
   cpupool configuration. Perhaps cpupool configuration deserves
   a section in this document.
 * Rename "global" options to "general"
 * Add section headers to group general VM options.

Signed-off-by: Matt Wilson <msw@amazon.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Campbell <ian.campbell@citrix.com>

1 files changed, 256 insertions, 230 deletions

diff --git a/docs/man/xl.cfg.pod.5 b/docs/man/xl.cfg.pod.5
index a8b635b539..013270d735 100644
--- a/docs/man/xl.cfg.pod.5
+++ b/docs/man/xl.cfg.pod.5
@@ -17,7 +17,7 @@ domain.
 
 A domain config file consists of a series of C<KEY=VALUE> pairs.
 
-Some C<KEY>s are mandatory, others are global options which apply to
+Some C<KEY>s are mandatory, others are general options which apply to
 any guest type while others relate only to specific guest types
 (e.g. PV or HVM guests).
 
@@ -80,20 +80,13 @@ operating systems.
 
 =back
 
-=head2 Global Options
+=head2 General Options
 
 The following options apply to guests of any type.
 
-=over 4
-
-=item B<uuid="UUID">
+=head3 CPU Allocation
 
-Specifies the UUID of the domain.  If not specified, a fresh unique
-UUID will be generated.
-
-=item B<vncviewer=BOOLEAN>
-
-Automatically spawn a vncviewer when creating/restoring a guest
+=over 4
 
 =item B<pool="CPUPOOLNAME">
 
@@ -138,6 +131,12 @@ node) by pinning it to the cpus of those nodes. A heuristic approach is
 utilized with the goals of maximizing performance for the domain and, at
 the same time, achieving efficient utilization of the host's CPUs and RAM.
 
+=back
+
+=head3 CPU Scheduling
+
+=over 4
+
 =item B<cpu_weight=WEIGHT>
 
 A domain with a weight of 512 will get twice as much CPU as a domain
@@ -176,6 +175,12 @@ Honoured by the sedf scheduler.
 Flag for allowing domain to run in extra time.
 Honoured by the sedf scheduler.
 
+=back
+
+=head3 Memory Allocation
+
+=over 4
+
 =item B<memory=MBYTES>
 
 Start the guest with MBYTES megabytes of RAM.
@@ -190,6 +195,12 @@ if the values of B<memory=> and B<maxmem=> differ.
 A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver
 it will crash.
 
+=back
+
+=head3 Event Actions
+
+=over 4
+
 =item B<on_poweroff="ACTION">
 
 Specifies what should be done with the domain if it shuts itself down.
@@ -200,12 +211,12 @@ The C<ACTION>s are:
 =item B<destroy>
 
 destroy the domain
-     
+
 =item B<restart>
 
 destroy the domain and immediately create a new domain with the same
 configuration
-        
+
 =item B<rename-restart>
 
 rename the domain which terminated, and then immediately create a new
@@ -244,10 +255,28 @@ Default is C<destroy>.
 
 Action to take if the domain crashes.  Default is C<destroy>.
 
+=back
+
+=head3 Other Options
+
+=over 4
+
+=item B<uuid="UUID">
+
+Specifies the UUID of the domain.  If not specified, a fresh unique
+UUID will be generated.
+
 =item B<seclabel="LABEL">
 
 Assign an XSM security label to this domain.
 
+=item B<nomigrate=BOOLEAN>
+
+Disable migration of this domain.  This enables certain other features
+which are incompatible with migration. Currently this is limited to
+enabling the invariant TSC feature flag in cpuid results when TSC is
+not emulated.
+
 =back
 
 =head2 Devices
@@ -309,7 +338,20 @@ Specifies the password for the VNC server.
 =item C<sdl=BOOLEAN>
 
 Specifies that the display should be presented via an X window (using
-Simple DirectMedia Layer). The default is to not enable this mode
+Simple DirectMedia Layer). The default is to not enable this mode.
+
+=item C<display=DISPLAY>
+
+Specifies the X Window display that should be used when the sdl option
+is used. Note: passing this value to the device-model is not currently
+implemented, so providing this option will have no effect.
+
+=item C<xauthority=XAUTHORITY>
+
+Specifies the path to the X authority file that should be used to
+connect to the X server when the sdl option is used. Note: passing
+this value to the device-model is not currently implemented, so
+providing this option will have no effect.
 
 =item C<opengl=BOOLEAN>
 
@@ -324,19 +366,9 @@ display. If the input method does not easily support raw keycodes
 (e.g. this is often the case when using VNC) then this allows us to
 correctly map the input keys into keycodes seen by the guest. The
 specific values which are accepted are defined by the version of the
-device-model which you are using. See L<Keymaps> below or consult the
+device-model which you are using. See L</"Keymaps"> below or consult the
 L<qemu(1)> manpage. The default is B<en-us>.
 
-=item C<display=XXX>
-
-XXX written to xenstore backend for vfb but does not appear to be used
-anywhere?
-
-=item C<authority=XXX>
-
-XXX written to xenstore backend for vfb but does not appear to be used
-anywhere?
-
 =back
 
 =item B<pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ... ]>
@@ -348,7 +380,7 @@ has the form C<[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...> where:
 
 =item B<DDDD:BB:DD.F>
 
-identifies the PCI device from the host perspective in domain
+Identifies the PCI device from the host perspective in domain
 (B<DDDD>), Bus (B<BB>), Device (B<DD>) and Function (B<F>) syntax. This is
 the same scheme as used in the output of C<lspci> for the device in
 question. Note: By default C<lspci> will omit the domain (B<DDDD>) if it
@@ -357,9 +389,9 @@ is zero and it is optional here also. You may specify the function
 
 =item B<@VSLOT>
 
-specifies the virtual device where the guest will see this
+Specifies the virtual device where the guest will see this
 device. This is equivalent to the B<DD> which the guest sees. In a
-guest B<DDDD> and B<BB> are C<0000:00>. XXX how does this really work?
+guest B<DDDD> and B<BB> are C<0000:00>.
 
 =item B<KEY=VALUE>
 
@@ -367,14 +399,6 @@ Possible B<KEY>s are:
 
 =over 4
 
-=item B<msitranslate=BOOLEAN>
-
-XXX
-
-=item B<power_mgmt=BOOLEAN>
-
-XXX
-
 =item B<permissive=BOOLEAN>
 
 (PV only) By default pciback only allows PV guests to write "known
@@ -386,6 +410,19 @@ caution: it gives the guest much more control over the device, which
 may have security or stability implications.  It is recommended to
 enable this option only for trusted VMs under administrator control.
 
+=item B<msitranslate=BOOLEAN>
+
+Specifies that MSI-INTx translation should be turned on for the PCI
+device. When enabled, MSI-INTx translation will always enable MSI on
+the PCI device regardless whether the guest uses INTx or MSI. Some
+device drivers, such as NVIDIA's, detect an inconsistency and do not
+function when this option is enabled. Therefore the default is 0.
+
+=item B<power_mgmt=BOOLEAN>
+
+(HVM only) Specifies that the VM should be able to program the
+D0-D3hot power management states for the PCI device. 0 by default.
+
 =back
 
 =back
@@ -393,18 +430,64 @@ enable this option only for trusted VMs under administrator control.
 =item B<pci_permissive=BOOLEAN>
 
 (PV only) Changes the default value of 'permissive' for all PCI
-devices for this VM.  This can still be overridden on a per-device
-basis. This option should be enabled with caution: it gives the guest
-much more control over the device, which may have security or
-stability implications.  It is recommended to enable this option only
-for trusted VMs under administrator control.  See the "pci=" section
-for more information on the "permissive" flag.
+devices passed through to this VM. See L<permissive|/"permissive_boolean">
+above.
 
-=back
+=item B<pci_msitranslate=BOOLEAN>
 
-=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ... ]>
+Changes the default value of 'msitranslate' for all PCI devices passed
+through to this VM. See L<msitranslate|/"msitranslate_boolean"> above.
 
-=over 4
+=item B<pci_power_mgmt=BOOLEAN>
+
+(HVM only) Changes the default value of 'power_mgmt' for all PCI
+devices passed through to this VM. See L<power_mgt|/"power_mgmt_boolean">
+above.
+
+=item B<gfx_passthru=BOOLEAN>
+
+Enable graphics device PCI passthrough. This option makes an assigned
+PCI graphics card become primary graphics card in the VM. The QEMU
+emulated graphics adapter is disabled and the VNC console for the VM
+will not have any graphics output. All graphics output, including boot
+time QEMU BIOS messages from the VM, will go to the physical outputs
+of the passedthrough physical graphics card.
+
+The graphics card PCI device to passthrough is chosen with B<pci>
+option, exactly in the same way as normal Xen PCI device
+passthrough/assignment is done.  Note that gfx_passthru does not do
+any kind of sharing of the GPU, so you can only assign the GPU to one
+single VM at a time.
+
+gfx_passthru also enables various legacy VGA memory ranges, BARs, MMIOs,
+and ioports to be passed thru to the VM, since those are required
+for correct operation of things like VGA BIOS, text mode, VBE, etc.
+
+Enabling gfx_passthru option also copies the physical graphics card
+video BIOS to the guest memory, and executes the VBIOS in the guest
+to initialize the graphics card.
+
+Most graphics adapters require vendor specific tweaks for properly
+working graphics passthrough. See the XenVGAPassthroughTestedAdapters
+L<http://wiki.xen.org/wiki/XenVGAPassthroughTestedAdapters> wiki page
+for currently supported graphics cards for gfx_passthru.
+
+gfx_passthru is currently only supported with the qemu-xen-traditional
+device-model. Upstream qemu-xen device-model currently does not have
+support for gfx_passthru.
+
+Note that some graphics adapters (AMD/ATI cards, for example) do not
+necessarily require gfx_passthru option, so you can use the normal Xen
+PCI passthrough to assign the graphics card as a secondary graphics
+card to the VM. The QEMU-emulated graphics card remains the primary
+graphics card, and VNC output is available from the QEMU-emulated
+primary adapter.
+
+More information about Xen gfx_passthru feature is available
+on the XenVGAPassthrough L<http://wiki.xen.org/wiki/XenVGAPassthrough>
+wiki page.
+
+=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ... ]>
 
 Allow guest to access specific legacy I/O ports. Each B<IOPORT_RANGE>
 is given in hexadecimal and may either a span e.g. C<2f8-2ff>
@@ -413,12 +496,8 @@ is given in hexadecimal and may either a span e.g. C<2f8-2ff>
 It is recommended to use this option only for trusted VMs under
 administrator control.
 
-=back
-
 =item B<irqs=[ NUMBER, NUMBER, ... ]>
 
-=over 4
-
 Allow a guest to access specific physical IRQs.
 
 It is recommended to use this option only for trusted VMs under
@@ -471,12 +550,12 @@ address space consists of a single contiguous RAM region. When this
 option is specified the virtual e820 instead reflects the host e820
 and contains the same PCI holes. The total amount of RAM represented
 by the memory map is always the same, this option configures only how
-it is layed out.
+it is laid out.
 
 Exposing the host e820 to the guest gives the guest kernel the
 opportunity to set aside the required part of its pseudo-physical
 address space in order to provide address space to map passedthrough
-PCI devices. It is guest Operating System dependant whether this
+PCI devices. It is guest Operating System dependent whether this
 option is required, specifically it is required when using a mainline
 Linux ("pvops") kernel. This option defaults to true if any PCI
 passthrough devices are configured and false otherwise. If you do not
@@ -600,6 +679,16 @@ by most modern guest Operating Systems. This option is enabled by
 default and usually you should omit it. However it may be necessary to
 disable ACPI for compatibility with some guest Operating Systems.
 
+=item B<acpi_s3=BOOLEAN>
+
+Include the S3 (suspend-to-ram) power state in the virtual firmware
+ACPI table. 1 by default.
+
+=item B<acpi_s4=BOOLEAN>
+
+Include S4 (suspend-to-disk) power state in the virtual firmware ACPI
+table. 1 by default.
+
 =item B<apic=BOOLEAN>
 
 Include information regarding APIC (Advanced Programmable Interrupt
@@ -637,6 +726,54 @@ of Xen) within a Xen guest or to support a guest Operating System
 which uses hardware virtualisation extensions (e.g. Windows XP
 compatibility mode on more modern Windows OS).
 
+=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
+
+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>
+
 =back 
 
 =head3 Guest Virtual Time Controls
@@ -680,8 +817,6 @@ frequency changes.
 
 =back
 
-=back
-
 Please see F<docs/misc/tscmode.txt> for more information on this option.
 
 =item B<localtime=BOOLEAN>
@@ -692,6 +827,50 @@ Set the real time clock to local time or to UTC. 0 by default, i.e. set to UTC.
 
 Set the real time clock offset in seconds. 0 by default.
 
+
+=item B<vpt_align=BOOLEAN>
+
+Specifies that periodic Virtual Platform Timers should be aligned to
+reduce guest interrupts. Enabling this option can reduce power
+consumption, especially when a guest uses a high timer interrupt
+frequency (HZ) values. The default is 1.
+
+=item B<timer_mode=MODE>
+
+Specifies the mode for Virtual Timers. The valid values are as follows:
+
+=over 4
+
+=item B<"delay_for_missed_ticks">
+
+Delay for missed ticks. Do not advance a vcpu's time beyond the
+correct delivery time for interrupts that have been missed due to
+preemption. Deliver missed interrupts when the vcpu is rescheduled and
+advance the vcpu's virtual time stepwise for each one.
+
+=item B<"no_delay_for_missed_ticks">
+
+No delay for missed ticks. As above, missed interrupts are delivered,
+but guest time always tracks wallclock (i.e., real) time while doing
+so.
+
+=item B<"no_missed_ticks_pending">
+
+No missed interrupts are held pending. Instead, to ensure ticks are
+delivered at some non-zero rate, if we detect missed ticks then the
+internal tick alarm is not disabled if the VCPU is preempted during
+the next tick period.
+
+=item B<"one_missed_tick_pending">
+
+One missed tick pending. Missed interrupts are collapsed
+together and delivered as one 'late tick'.  Guest time always tracks
+wallclock (i.e., real) time.
+
+=back
+
+=back
+
 =head3 Support for Paravirtualisation of HVM Guests
 
 The following options allow Paravirtualised features (such as devices)
@@ -719,10 +898,11 @@ compatible enlightenments to the guest.  These can improve performance
 of Microsoft Windows guests from Windows Vista and Windows 2008
 onwards and setting this option for such guests is strongly
 recommended. This option should be harmless for other versions of
-Windows (although it won't give any benefit) and the majority of other
-non-Windows OSes. However it is known to be incompatible with some
-other Operating Systems and in some circumstance can prevent Xen's own
-paravirtualisation interfaces for HVM guests from being used.
+Windows (although it will not give any benefit) and the majority of
+other non-Windows OSes. However it is known to be incompatible with
+some other Operating Systems and in some circumstance can prevent
+Xen's own paravirtualisation interfaces for HVM guests from being
+used.
 
 =back
 
@@ -750,8 +930,8 @@ for 1024x768 at 32 bpp.
 
 videoram option is currently only available when using the
 qemu-xen-traditional device-model. Upstream qemu-xen device-model
-currently doesn't support changing the amount of video memory
-for the emulated graphics device.
+currently does not support changing the amount of video memory for the
+emulated graphics device.
 
 =item B<stdvga=BOOLEAN>
 
@@ -766,6 +946,10 @@ stdvga supports more video ram and bigger resolutions than Cirrus.
 Allow access to the display via the VNC protocol.  This enables the
 other VNC-related settings.  The default is to enable this.
 
+=item B<vncviewer=BOOLEAN>
+
+Automatically spawn a vncviewer when creating/restoring a guest.
+
 =item B<vnclisten="ADDRESS[:DISPLAYNUM]">
 
 Specifies the IP address, and optionally VNC display number, to use.
@@ -791,7 +975,7 @@ display. If the input method does not easily support raw keycodes
 (e.g. this is often the case when using VNC) then this allows us to
 correctly map the input keys into keycodes seen by the guest. The
 specific values which are accepted are defined by the version of the
-device-model which you are using. See L<Keymaps> below of consult the
+device-model which you are using. See L</"Keymaps"> below or consult the
 L<qemu(1)> manpage. The default is B<en-us>.
 
 =item B<sdl=BOOLEAN>
@@ -803,7 +987,7 @@ Simple DirectMedia Layer). The default is not to enable this mode.
 
 Enable OpenGL acceleration of the SDL display. Only effects machines
 using B<device_model_version="qemu-xen-traditional"> and only if the
-device-model was compiled with OpenGL support. Disabled by default.
+device-model was compiled with OpenGL support. 0 by default.
 
 =item B<nographic=BOOLEAN>
 
@@ -843,8 +1027,8 @@ have not been supported.
 
 =item B<spicedisable_ticketing=BOOLEAN>
 
-Enable client connection without password. The default is false. If
-it's false (set to 0), spicepasswd must be set.
+Enable client connection without password. When disabled, spicepasswd
+must be set. The default is 0.
 
 =item B<spicepasswd="PASSWORD">
 
@@ -887,28 +1071,7 @@ which adds pointer device using absolute coordinates. Such devices
 function better than relative coordinate devices (such as a standard
 mouse) since many methods of exporting guest graphics (such as VNC)
 work better in this mode. Note that this is independent of the actual
-pointer device you are using on the host/client side. XXX should/could
-be a list of devices.
-
-=back
-
-=head3 Unclassified HVM Specific Options
-
-These HVM specific options have not yet been documented or
-classified. They almost certainly belong in a more appropriate
-section.
-
-=over 4
-
-=item B<vpt_align=BOOLEAN>
-
-Align the Virtual Platform Timer ??? XXX Reduces interrupts?
-
-=item B<timer_mode=NUMBER>
-
-Set mode for Virtual Timers XXX ??? should be an enum of particular
-values. See C<HVM_PARAM_TIMER_MODE> in
-F<xen/include/public/hvm/params.h>.
+pointer device you are using on the host/client side.
 
 =back
 
@@ -936,7 +1099,7 @@ device-model is currently the default.
 
 =item B<qemu-xen>
 
-use the device-model merged into the upstream Qemu project.  This
+use the device-model merged into the upstream QEMU project.  This
 device-model will become the default in a future version of Xen.
 
 =back
@@ -983,142 +1146,6 @@ option to the device-model.
 
 =back
 
-=head2 Unclassified General Options
-
-These have not yet been fully documented or classified. They almost
-certainly belong in a more appropriate section.
-
-=over 4
-
-=item B<gfx_passthru=BOOLEAN>
-
-Enable graphics device PCI passthrough. This option makes the passthru
-graphics card become primary graphics card in the VM, so the Qemu emulated
-graphics adapter is disabled, and the VNC console for the VM won't have
-any graphics output. All graphics output, including boot time Qemu BIOS
-messages from the VM, will go to the physical outputs of the passed thru
-physical graphics card.
-
-Graphics card PCI device to passthru is chosen with B<pci> option,
-exactly in the same way as normal Xen PCI device passthru/assignment is done.
-Note that gfx_passthru doesn't do any kind of sharing
-of the GPU, so you can only assign the GPU to one single VM at a time.
-
-gfx_passthru also enables various legacy VGA memory ranges, BARs, MMIOs,
-and ioports to be passed thru to the VM, since those are required
-for correct operation of things like VGA BIOS, text mode, VBE, etc.
-
-Enabling gfx_passthru option also copies the physical graphics card
-video BIOS to the guest memory, and executes the VBIOS in the guest
-to get the graphics card initialized.
-
-Most graphics adapters require vendor specific tweaks for properly
-working graphics passthru. See the XenVGAPassthroughTestedAdapters
-L<http://wiki.xen.org/wiki/XenVGAPassthroughTestedAdapters>
-wiki page for currently supported graphics cards for gfx_passthru.
-
-gfx_passthru is currently only supported with the qemu-xen-traditional
-device-model. Upstream qemu-xen device-model currently doesn't have
-support for gfx_passthru.
-
-Note that some graphics adapters (AMD/ATI cards, for example) don't
-necessarily require gfx_passthru option, so you can use the normal
-Xen PCI passthru to assign the graphics card as a secondary graphics card
-to the VM. Qemu emulated graphics card stays as the primary graphics card,
-and you get VNC output from the Qemu-emulated primary adapter.
-
-More information about Xen gfx_passthru feature is available
-on the XenVGAPassthrough L<http://wiki.xen.org/wiki/XenVGAPassthrough>
-wiki page.
-
-=item B<nomigrate=BOOLEAN>
-
-Disable migration of this domain.  This enables certain other features
-which are incompatible with migration (currently certain TSC modes XXX
-?).
-
-=item B<pci_msitranslate=BOOLEAN>
-
-XXX
-
-=item B<pci_power_mgmt=BOOLEAN>
-
-XXX
-
-=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
-
-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>
-
-XXX
-
-=item B<acpi_s3=BOOLEAN>
-
-XXX
-
-=item B<nodes=XXX>
-
-XXX
-
-=item B<sched=XXX>
-
-XXX
-
-=item B<device_model=XXX>
-
-XXX deprecated
-
-=item B<vif2=XXX>
-
-XXX deprecated
-
-=back
-
 =head2 Keymaps
 
 The keymaps available are defined by the device-model which you are
@@ -1138,27 +1165,26 @@ See L<qemu(1)> for more information.
 
 =item L<xl(1)>
 
+=item L<xlcpupool.cfg(5)>
+
 =item F<xl-disk-configuration>
 
 =item F<xl-network-configuration>
 
+=item F<docs/misc/tscmode.txt>
+
 =back
 
 =head1 FILES
 
 F</etc/xen/NAME.cfg>
 F</var/xen/dump/NAME>
-F<docs/misc/tscmode.txt>
 
 =head1 BUGS
 
-This document is a work in progress and contains items which require
-further documentation and which are generally incomplete (marked with
-XXX).  However all options are included here whether or not they are
-fully documented.
-
-Patches to improve incomplete items (or any other item) would be
-gratefully received on the xen-devel@lists.xen.org mailing
+This document may contain items which require further
+documentation. Patches to improve incomplete items (or any other item)
+are gratefully received on the xen-devel@lists.xen.org mailing
 list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
 information on how to submit a patch to Xen.