* [PATCH 2 of 2] docs: flesh out xl.cfg documentation, correct typos, reorganize
2012-09-08 8:59 [PATCH 0 of 2] improve xmdomain.cfg and xl.cfg documentation Matt Wilson
2012-09-08 8:59 ` [PATCH 1 of 2] docs: correct formatting errors in xmdomain.cfg Matt Wilson
@ 2012-09-08 8:59 ` Matt Wilson
2012-09-10 10:14 ` Ian Campbell
1 sibling, 1 reply; 6+ messages in thread
From: Matt Wilson @ 2012-09-08 8:59 UTC (permalink / raw)
To: Ian Campbell, Ian Jackson; +Cc: xen-devel
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>
diff -r 8218753a8e3f -r 9c9981ddbfd5 docs/man/xl.cfg.pod.5
--- a/docs/man/xl.cfg.pod.5 Sat Sep 08 01:43:36 2012 -0700
+++ b/docs/man/xl.cfg.pod.5 Sat Sep 08 01:54:46 2012 -0700
@@ -17,7 +17,7 @@
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,21 +80,14 @@
=back
-=head2 Global Options
+=head2 General Options
The following options apply to guests of any type.
+=head3 CPU Allocation
+
=over 4
-=item B<uuid="UUID">
-
-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
-
=item B<pool="CPUPOOLNAME">
Put the guest's vcpus into the named cpu pool.
@@ -138,6 +131,12 @@
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 @@
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 @@
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 @@
=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 @@
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 @@
=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 authorty 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 @@
(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 @@
=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 @@
=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 @@
=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 @@
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,12 +430,27 @@
=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.
+
+=item B<pci_msitranslate=BOOLEAN>
+
+Changes the default value of 'msitranslate' for all PCI devices passed
+through to this VM. See L<msitranslate|/"msitranslate_boolean"> above.
+
+=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>
+
+(HVM only) Enable graphic device PCI passthrough. If a system's
+primary graphics adapter PCI device is specified in the
+L<pci|/"pci_pci_spec_string_pci_spec_string"> section above, enabling
+this option will cause the device to be used as the primary graphics
+adapter in the guest. 0 by default.
=back
@@ -447,12 +499,12 @@
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
@@ -576,6 +628,16 @@
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
@@ -613,6 +675,54 @@
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
@@ -656,8 +766,6 @@
=back
-=back
-
Please see F<docs/misc/tscmode.txt> for more information on this option.
=item B<localtime=BOOLEAN>
@@ -668,6 +776,50 @@
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)
@@ -733,6 +885,10 @@
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.
@@ -758,7 +914,7 @@
(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>
@@ -770,7 +926,7 @@
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>
@@ -854,28 +1010,7 @@
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
@@ -950,105 +1085,6 @@
=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. XXX which device is passed through ?
-
-=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
@@ -1083,9 +1119,9 @@
=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.
+further documentation and which are generally incomplete. However all
+supported 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
^ permalink raw reply [flat|nested] 6+ messages in thread