Documentation updates

diff -r dbdc840f8f62 -r 14a8af47bf11 README
@@ -59,10 +59,10 @@ provided by your OS distributor:
 Second, you need to acquire a suitable kernel for use in domain 0. If
 possible you should use a kernel provided by your OS distributor. If
 no suitable kernel is available from your OS distributor then refer to
-http://wiki.xen.org/xenwiki/XenDom0Kernels for suggestions for
+http://wiki.xen.org/wiki/XenDom0Kernels for suggestions for
 suitable kernels to use.
 If you are looking to compile a Dom0 kernel from source, please refer to
-http://wiki.xensource.com/xenwiki/XenParavirtOps.
+http://wiki.xensource.com/wiki/XenParavirtOps.
 
 [NB. Unless noted otherwise, all the following steps should be
 performed with root privileges.]

diff -r dbdc840f8f62 -r 14a8af47bf11 docs/misc/vtd.txt
@@ -184,7 +184,7 @@ http://www.dell.com/content/products/cat
 - HP Compaq:  DC7800
 http://h10010.www1.hp.com/wwpc/us/en/en/WF04a/12454-12454-64287-321860-3328898.html
 
-For more information, pls refer to http://wiki.xensource.com/xenwiki/VTdHowTo.
+For more information, pls refer to http://wiki.xensource.com/wiki/VTdHowTo.
 
 
 Assigning devices to HVM domains

diff -r dbdc840f8f62 -r 14a8af47bf11 docs/misc/xl-network-configuration.markdown
@@ -123,4 +123,4 @@ defaults to domain 0. Specifying another
 driver domain which is outside the scope of this document.
 
 [oui]: http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier
-[net]: http://wiki.xen.org/xenwiki/HostConfiguration/Networking
+[net]: http://wiki.xen.org/wiki/HostConfiguration/Networking

diff -r dbdc840f8f62 -r 14a8af47bf11 docs/src/interface.tex
@@ -1579,7 +1579,7 @@ This contains links to the latest versio
 documentation, including the latest version of the FAQ.
 
 Information regarding Xen is also available at the Xen Wiki at
-\begin{quote} {\tt http://wiki.xensource.com/xenwiki/}\end{quote}
+\begin{quote} {\tt http://wiki.xensource.com/wiki/}\end{quote}
 The Xen project uses Bugzilla as its bug tracking system. You'll find
 the Xen Bugzilla at http://bugzilla.xensource.com/bugzilla/.
 

diff -r dbdc840f8f62 -r 14a8af47bf11 docs/src/user.tex
@@ -2349,7 +2349,7 @@ This contains links to the latest versio
 documentation, including the latest version of the FAQ.
 
 Information regarding Xen is also available at the Xen Wiki at
-\begin{quote} {\tt http://wiki.xensource.com/xenwiki/}\end{quote}
+\begin{quote} {\tt http://wiki.xensource.com/wiki/}\end{quote}
 The Xen project uses Bugzilla as its bug tracking system. You'll find
 the Xen Bugzilla at http://bugzilla.xensource.com/bugzilla/.
 

diff -r 14a8af47bf11 -r 5e3e5757de0f tools/examples/xlexample.hvm
@@ -5,6 +5,9 @@
 # This is a fairly minimal example of what is required for an
 # HVM guest. For a more complete guide see <XXX Document TBD>
 
+# This configures an HVM rather than PV guest
+builder = "hvm"
+
 # Guest name
 name = "example.hvm"

diff -r 5e3e5757de0f -r e8f0094323d0 README
@@ -55,6 +55,7 @@ provided by your OS distributor:
     * GNU gettext
     * 16-bit x86 assembler, loader and compiler (dev86 rpm or bin86 & bcc debs)
     * ACPI ASL compiler (iasl)
+    * markdown
 
 Second, you need to acquire a suitable kernel for use in domain 0. If
 possible you should use a kernel provided by your OS distributor. If

diff -r e8f0094323d0 -r f3fc909a083d docs/Docs.mk
@@ -5,6 +5,8 @@ FIG2DEV		:= fig2dev
 LATEX2HTML	:= latex2html
 DOXYGEN		:= doxygen
 POD2MAN		:= pod2man
+POD2HTML	:= pod2html
+POD2TEXT	:= pod2text
 DOT		:= dot
 NEATO		:= neato
 MARKDOWN	:= markdown

diff -r e8f0094323d0 -r f3fc909a083d docs/Makefile
@@ -15,9 +15,13 @@ DOC_MARKDOWN	:= $(wildcard misc/*.markdo
 DOC_PS		:= $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX))
 DOC_PDF		:= $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX))
 DOC_HTML	:= $(patsubst src/%.tex,html/%/index.html,$(DOC_TEX)) \
-		   $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN))
+		   $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN)) \
+		   $(patsubst man/%.pod.1,html/man/%.1.html,$(DOC_MAN1SRC)) \
+		   $(patsubst man/%.pod.5,html/man/%.5.html,$(DOC_MAN5SRC))
 DOC_TXT         := $(patsubst %.txt,txt/%.txt,$(wildcard misc/*.txt)) \
-		   $(patsubst %.markdown,txt/%.txt,$(DOC_MARKDOWN))
+		   $(patsubst %.markdown,txt/%.txt,$(DOC_MARKDOWN)) \
+		   $(patsubst man/%.pod.1,txt/man/%.1.txt,$(DOC_MAN1SRC)) \
+		   $(patsubst man/%.pod.5,txt/man/%.5.txt,$(DOC_MAN5SRC))
 
 GFX = $(patsubst %.fig, %.eps, $(wildcard figs/*.fig))
 

@@ -76,7 +80,7 @@ clean:
 	$(MAKE) -C xen-api clean
 	rm -rf .word_count *.aux *.dvi *.bbl *.blg *.glo *.idx *~ 
 	rm -rf *.ilg *.log *.ind *.toc *.bak core
-	rm -rf $(GFX) ps pdf html
+	rm -rf $(GFX) ps pdf html txt
 	rm -rf api
 	rm -rf man5
 	rm -rf man1

@@ -132,6 +136,16 @@ html/%.html: %.markdown
 	$(call move-if-changed,[email protected],$@) ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
+html/man/%.1.html: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2HTML) --infile=$< [email protected]
+	$(call move-if-changed,[email protected],$@)
+
+html/man/%.5.html: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2HTML) --infile=$< [email protected]
+	$(call move-if-changed,[email protected],$@)
+
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
 	cp $< [email protected]

@@ -141,3 +155,14 @@ txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
 	cp $< [email protected]
 	$(call move-if-changed,[email protected],$@)
+
+txt/man/%.1.txt: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2TEXT) $< [email protected]
+	$(call move-if-changed,[email protected],$@)
+
+txt/man/%.5.txt: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2TEXT) $< [email protected]
+	$(call move-if-changed,[email protected],$@)
+

diff -r f3fc909a083d -r c88ff1ac2417 docs/man/xl.cfg.pod.5
@@ -0,0 +1,844 @@
+=head1 NAME
+
+xl.cfg - XL Domain Configuration File Syntax
+
+=head1 SYNOPSIS
+
+ /etc/xen/xldomain
+
+=head1 DESCRIPTION
+
+To create a VM (a domain in Xen terminology, sometimes called a guest)
+with xl requires the provision of a domain config file.  Typically
+these live in `/etc/xen/DOMAIN.cfg` where DOMAIN is the name of the
+domain.
+
+=head1 SYNTAX
+
+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
+any guest type while others relate only to specific guest types
+(e.g. PV or HVM guests).
+
+A value C<VALUE> is one of:
+
+=over 4
+
+=item B<"STRING">
+
+A string, surrounded by either single or double quotes.
+
+=item B<NUMBER>
+
+A number, in either decimal, octal (using a C<0> prefix) or
+hexadecimal (using an C<0x> prefix).
+
+=item B<BOOLEAN>
+
+A C<NUMBER> interpreted as C<False> (C<0>) or C<True> (any other
+value).
+
+=item B<[ VALUE, VALUE, ... ]>
+
+A list of C<VALUES> of the above types. Lists are homogeneous and are
+not nested.
+
+=back
+
+The semantics of each C<KEY> defines which form of C<VALUE> is required.
+
+=head1 OPTIONS
+
+=head2 Mandatory Configuration Items
+
+The following key is mandatory for any guest type:
+
+=over 4
+
+=item B<name="NAME">
+
+Specifies the name of the domain.  Names of domains existing on a
+single host must be unique.
+
+=back
+
+=head2 Selecting Guest Type
+
+=over 4
+
+=item B<builder="generic">
+
+Specifies that this is to be a PV domain. This is the default.
+
+=item B<builder="hvm">
+
+Specifies that this is to be an HVM domain.  That is, a fully
+virtualised computer with emulated BIOS, disk and network peripherals,
+etc.  The default is a PV domain, suitable for hosting Xen-aware guest
+operating systems.
+
+=back
+
+=head2 Global Options
+
+The following options apply to guests of any type.
+
+=over 4
+
+=item B<uuid="UUID">
+
+Specifies the UUID of the domain.  If not specified, a fresh unique
+UUID will be generated.
+
+=item B<pool="CPUPOOLNAME">
+
+Put the guest's vcpus into the named cpu pool.
+
+=item B<vcpus=N>
+
+Start the guest with N vcpus initially online.
+
+=item B<maxvcpus=M>
+
+Allow the guest to bring up a maximum of M vcpus. At start of day if
+`vcpus=N` is less than `maxvcpus=M` then the first `N` vcpus will be
+created online and the remainder will be offline.
+
+=item B<memory=MBYTES>
+
+Start the guest with MBYTES megabytes of RAM.
+
+=item B<on_poweroff="ACTION">
+
+Specifies what should be done with the domain if it shuts itself down.
+The C<ACTION>s are:
+
+=over 4
+
+=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 thenimmediately create a new
+domain with the same configuration as the original
+
+=item B<preserve>
+
+keep the domain.  It can be examined, and later destroyed with `xl
+destroy`.
+
+=item B<coredump-destroy>
+
+write a "coredump" of the domain to F</var/xen/dump/NAME> and then
+destroy the domain.
+
+=item B<coredump-restart>
+
+write a "coredump" of the domain to F</var/xen/dump/NAME> and then
+restart the domain.
+
+=back
+
+The default for C<on_poweroff> is C<destroy>.
+
+=item B<on_reboot="ACTION">
+
+Action to take if the domain shuts down with a reason code requesting
+a reboot.  Default is C<restart>.
+
+=item B<on_watchdog="ACTION">
+
+Action to take if the domain shuts down due to a Xen watchdog timeout.
+Default is C<destroy>.
+
+=item B<on_crash="ACTION">
+
+Action to take if the domain crashes.  Default is C<destroy>.
+
+=item B<seclabel="LABEL">
+
+Assign an XSM security label to this domain.
+
+=back
+
+=head2 Devices
+
+The following options define the paravirtual, emulated and physical
+devices which the guest will contain.
+
+=over 4
+
+=item B<disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]>
+
+Specifies the disks (both emulated disks and Xen virtual block
+devices) which are to be provided to the guest, and what objects on
+the they should map to.  See F<docs/misc/xl-disk-configuration.txt>.
+
+=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
+
+Specifies the networking provision (both emulated network adapters,
+and Xen virtual interfaces) to provided to the guest.  See
+F<docs/misc/xl-network-configuration.markdown>.
+
+=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]>
+
+Specifies the paravirtual framebuffer devices which should be supplied
+to the domain.
+
+This options does not control the emulated graphics card presented to
+an HVM guest. See L<Emulated VGA Graphics Device> below for how to
+configure the emulated device.
+
+Each B<VFB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings, from the following list:
+
+=over 4
+
+=item C<vnc=BOOLEAN>
+
+Allow access to the display via the VNC protocol.  This enables the
+other VNC-related settings.  The default is to enable this.
+
+=item C<vnclisten="ADDRESS[:DISPLAYNUM]">
+
+Specifies the IP address, and optionally VNC display number, to use.
+
+=item C<vncdisplay=DISPLAYNUM>
+
+Specifies the VNC display number to use.  The actual TCP port number
+will be DISPLAYNUM+5900.
+
+=item C<vncunused=BOOLEAN>
+
+Requests that the VNC display setup search for a free TCP port to use.
+The actual display used can be accessed with C<xl vncviewer>.
+
+=item C<vncpasswd="PASSWORD">
+
+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
+
+=item C<opengl=BOOLEAN>
+
+Enable OpenGL acceleration of the SDL display. Only effects machines
+using C<device_model_version="qemu-xen-traditonal"> and only if the
+device-model was compiled with OpenGL support. Disabled by default.
+
+=item C<keymap="LANG">
+
+Configure the keymap to use for the keyboard associated with this
+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
+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", ... ]>
+
+Specifies the host PCI devices to passthrough to this guest. Each B<PCI_SPEC_STRING>
+has the form C<[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...> where:
+
+=over 4
+
+=item B<DDDD:BB:DD.F>
+
+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
+is zero and it is optional here also. You may specify the function
+(B<F>) as B<*> to indicate all functions.
+
+=item B<@VSLOT>
+
+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?
+
+=item B<KEY=VALUE>
+
+Posible B<KEY>s are:
+
+=over 4
+
+=item B<msitranslate=BOOLEAN>
+
+XXX
+
+=item B<power_mgmt=BOOLEAN>
+
+XXX
+
+=back
+
+=back
+
+=back
+
+=head2 Paravirtualised (PV) Guest Specific Options
+
+The following options apply only to Paravirtual guests.
+
+=over 4
+
+=item B<kernel="PATHNAME">
+
+Load the specified file as the kernel image.  Either B<kernel> or
+B<bootloader> must be specified for PV guests.
+
+=item B<ramdisk="PATHNAME">
+
+Load the specified file as the ramdisk.
+
+=item B<bootloader="PROGRAM">
+
+Run C<PROGRAM> to find the kernel image and ramdisk to use.  Normally
+C<PROGRAM> would be C<pygrub>, which is an emulation of
+grub/grub2/syslinux.
+
+=item B<bootloader_args=STRING>
+
+Append B<STRING> (split into words at whitespace) to the arguments to
+the B<bootloader> program.  XXX this should be a list of strings.
+
+=item B<root="STRING">
+
+Append B<root="STRING"> to the kernel command line (Note: it is guest
+specific what meaning this has).
+
+=item B<extra="STRING">
+
+Append B<STRING> to the kernel command line. Note: it is guest
+specific what meaning this has).
+
+=item B<e820_host=BOOLEAN>
+
+Selects whether to expose the host e820 (memory map) to the guest via
+the virtual e820. When this option is false the guest psuedo-physical
+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.
+
+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 Operaring System dependant 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 configued and false otherwise. If you do not
+configure any passthrough devices at domain creation time but expect
+to hotplug devices later then you should set this option. Conversely
+if your particular guest kernel does not require this behaviour then
+it is safe to allow this to be enabled but you may wish to disable it
+anyway.
+
+=back
+
+=head2 Fully-virtualised (HVM) Guest Specific Options
+
+The following options apply only to HVM guests.
+
+=head3 Boot Device
+
+=over 4
+
+=item B<boot=[c|d|n]>
+
+Selects the emulated virtual device to boot from. Options are hard
+disk (B<c>), cd-rom (B<d>) or network/PXE (B<n>). Multiple options can be
+given and will be attempted in the order they are given. e.g. to boot
+from cd-rom but fallback to the hard disk you can give B<dc>. The
+default is B<cd>.
+
+=back
+
+=head3 Paging
+
+The following options control the mechanisms used to virtualise guest
+memory.  The defaults are selected to give the best results for the
+common case and so you should normally leave these options
+unspecified.
+
+=over 4
+
+=item B<hap=BOOLEAN>
+
+Turns "hardware assisted paging" (the use of the hardware nested page
+table feature) on or off.  This feature is called EPT (Extended Page
+Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid
+Virtualisation Indexing) by AMD.  Affects HVM guests only.  If turned
+off, Xen will run the guest in "shadow page table" mode where the
+guest's page table updates and/or TLB flushes etc. will be emulated.
+Use of HAP is the default when available.
+
+=item B<oos=BOOLEAN>
+
+Turns "out of sync pagetables" on or off.  When running in shadow page
+table mode, the guest's page table updates may be deferred as
+specified in the Intel/AMD architecture manuals.  However this may
+expose unexpected bugs in the guest, or find bugs in Xen, so it is
+possible to disable this feature.  Use of out of sync page tables,
+when Xen thinks it appropriate, is the default.
+
+=item B<shadow_memory=MBYTES>
+
+Number of megabytes to set aside for shadowing guest pagetable pages
+(effectively acting as a cache of translated pages) or to use for HAP
+state. By default this is 1MB per guest vcpu plus 8KB per MB of guest
+RAM. You should not normally need to adjust this value. However if you
+are not using hardware assisted paging (i.e. you are using shadow
+mode) and your guest workload consists of a a very large number of
+similar processes then increasing this value may improve performance.
+
+=back
+
+=head3 Processor and Platform Features
+
+The following options allow various processor and platform level
+features to be hidden or exposed from the guest's point of view. This
+can be useful when running older guest Operating Systems which may
+misbehave when faced with more modern features. In general you should
+accept the defaults for these options wherever possible.
+
+=over 4
+
+=item B<pae=BOOLEAN>
+
+Hide or expose the IA32 Physical Address Extensions. These extensions
+make it possible for a 32 bit guest Operating System to access more
+than 4GB of RAM. Enabling PAE also enabled other features such as
+NX. PAE is required if you wish to run a 64-bit guest Operating
+System. In general you should leave this enabled and allow the guest
+Operating System to choose whether or not to use PAE. (X86 only)
+
+=item B<acpi=BOOLEAN>
+
+Expose ACPI (Advanced Configuration and Power Interface) tables from
+the virtual firmware to the guest Operating System. ACPI is required
+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<apic=BOOLEAN>
+
+Include information regarding APIC (Advanced Programmable Interrupt
+Controller) in the firmware/BIOS tables on a single processor
+guest. This causes the MP (multiprocessor) and PIR (PCI Interrupt
+Routing) tables to be exported by the virtual firmware. This option
+has no effect on a guest with multiple virtual CPUS as they must
+always include these tables. This option is enabled by default and you
+should usually omit it but it may be necessary to disable these
+firmware tables when using certain older guest Operating
+Systems. These tables have been superceded by newer constructs within
+the ACPI tables. (X86 only)
+
+=item B<nx=BOOLEAN>
+
+Hides or exposes the No-eXecute capability. This allows a guest
+Operating system to map pages such that they cannot be executed which
+can enhance security. This options requires that PAE also be
+enabled. (X86 only)
+
+=item B<hpet=BOOLEAN>
+
+Enables or disables HPET (High Precision Event Timer). This option is
+enabled by default and you should usually omit it. It may be necessary
+to disable the HPET in order to improve compatibility with guest
+Operating Systems (X86 only)
+
+=item B<nestedhvm=BOOLEAN>
+
+Enable or disables guest access to hardware virtualisation features,
+e.g. it allows a guest Operating System to also function as a
+hypervisor. This option is disabled by default. You may want this
+option if you want to run another hypervisor (including another copy
+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).
+
+=back 
+
+=head3 Guest Virtual Time Controls
+
+=over 4
+
+=item B<tsc_mode="MODE">
+
+Specifies how the TSC (Time Stamp Counter) should be provided to the
+guest.  XXX ???
+
+=back
+
+=head3 Support for Paravirtualisation of HVM Guests
+
+The following options allow Paravirtualised features (such as devices)
+to be exposed to the guest Operating System in an HVM guest.
+Utilising these features requires specific guest support but when
+available they will result in improved performance.
+
+=over 4
+
+=item B<xen_platform_pci=BOOLEAN>
+
+Enable or disable the Xen platform PCI device.  The presence of this
+virtual device enables a guest Operating System (subject to the
+availability of suitable drivers) to make use of paravirtualisation
+features such as disk and network devices etc. Enabling these drivers
+improves performance and is strongly recommended when available. PV
+drivers are available for various Operating Systems including HVM
+Linux L<http://wiki.xen.org/wiki/XenLinuxPVonHVMdrivers> and Microsoft
+Windows L<http://wiki.xen.org/wiki/XenWindowsGplPv>.
+
+=item B<viridian=BOOLEAN>
+
+Turns on or off the exposure of MicroSoft Hyper-V (AKA viridian)
+compatible enlightenments to the guest.  These can improve performance
+of Microsoft Windows guests (XXX which versions of Windows benefit?)
+
+=back
+
+=head3 Emulated VGA Graphics Device
+
+The following options control the features of the emulated graphics
+device.  Many of these options behave similarly to the equivalent key
+in the B<VFB_SPEC_STRING> for configuring virtual frame buffer devices
+(see above).
+
+=over 4
+
+=item B<videoram=MBYTES>
+
+Sets the amount of RAM which the emulated video card will contain,
+which in turn limits the resolutions and bit depths which will be
+available. This option is only available when using the B<stdvga>
+option (see below). The default is 8MB which is sufficient for
+e.g. 1600x1200 at 32bpp. When not using the B<stdvga> option the
+amount of video ram is fixed at 4MB which is sufficient for 1024x768
+at 32 bpp.
+
+=item B<stdvga=BOOLEAN>
+
+Select a standard VGA card with VBE (VESA BIOS Extensions) as the
+emulated graphics device. The default is false which means to emulate
+a Cirrus Logic GD5446 VGA card. If your guest supports VBE 2.0 or
+later (e.g. Windows XP onwards) then you should enable this.
+
+=item B<vnc=BOOLEAN>
+
+Allow access to the display via the VNC protocol.  This enables the
+other VNC-related settings.  The default is to enable this.
+
+=item B<vnclisten="ADDRESS[:DISPLAYNUM]">
+
+Specifies the IP address, and optionally VNC display number, to use.
+
+=item B<vncdisplay=DISPLAYNUM>
+
+Specifies the VNC display number to use. The actual TCP port number
+will be DISPLAYNUM+5900.
+
+=item B<vncunused=BOOLEAN>
+
+Requests that the VNC display setup search for a free TCP port to use.
+The actual display used can be accessed with C<xl vncviewer>.
+
+=item B<vncpasswd="PASSWORD">
+
+Specifies the password for the VNC server.
+
+=item B<keymap="LANG">
+
+Configure the keymap to use for the keyboard associated with this
+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
+L<qemu(1)> manpage. The default is B<en-us>.
+
+=item B<sdl=BOOLEAN>
+
+Specifies that the display should be presented via an X window (using
+Simple DirectMedia Layer). The default is not to enable this mode.
+
+=item B<opengl=BOOLEAN>
+
+Enable OpenGL acceleration of the SDL display. Only effects machines
+using B<device_model_version="qemu-xen-traditonal"> and only if the
+device-model was compiled with OpenGL support. Disabled by default.
+
+=item B<nographic=BOOLEAN>
+
+Enable or disable the virtual graphics device.  The default is to
+provide a VGA graphics device but this option can be used to disable
+it.
+
+=back
+
+=head3 Spice Graphics Support
+
+The following options control the features of SPICE.
+
+=over 4
+
+=item B<spice=BOOLEAN>
+
+Allow access to the display via the SPICE protocol.  This enables the
+other SPICE-related settings.
+
+=item B<spicehost="ADDRESS">
+
+Specify the interface address to listen on if given, otherwise any
+interface.
+
+=item B<spiceport=NUMBER>
+
+Specify the port to listen on by the SPICE server if the SPICE is
+enabled.
+
+=item B<spicetls_port=NUMBER>
+
+Specify the secure port to listen on by the SPICE server if the SPICE
+is enabled. At least one of the spiceport or spicetls_port must be
+given if SPICE is enabled.  NB. the options depending on spicetls_port
+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.
+
+=item B<spicepasswd="PASSWORD">
+
+Specify the ticket password which is used by a client for connection.
+
+=item B<spiceagent_mouse=BOOLEAN>
+
+Whether SPICE agent is used for client mouse mode. The default is true
+(turn on)
+
+=back
+
+=head3 Miscellaneous Emulated Hardware
+
+=over 4
+
+=item B<serial=DEVICE>
+
+Redirect the virtual serial port to B<DEVICE>. Please see the
+B<-serial> option in the L<qemu(1)> manpage for details of the valid
+B<DEVICE> options. Default is B<vc> when in graphical mode and
+B<stdio> if B<nographics=1> is used.
+
+=item B<soundhw=DEVICE>
+
+Select the virtual sound card to expose to the guest. The valid
+devices are defined by the device model configuration, please see the
+L<qemu(1)> manpage for details. The default is not to export any sound
+device.
+
+=item B<usb=BOOLEAN>
+
+Enables or disables a USB bus in the guest.
+
+=item B<usbdevice=DEVICE>
+
+Adds B<DEVICE> to the USB bus. The USB bus must also be enabled using
+B<usb=1>. The most common use for this option is B<usbdevice=tablet>
+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>.
+
+=back
+
+=head2 Device-Model Options
+
+The following options control the selection of the device-model.  This
+is the component which provides emulation of the virtual devices to an
+HVM guest.  For a PV guest a device-model is sometimes used to provide
+backends for certain PV devices (most usually a virtual framebuffer
+device).
+
+=over 4
+
+=item B<device_model_version="DEVICE-MODEL">
+
+Selects which variant of the device-model should be used for this
+guest. Valid values are:
+
+=over 4
+
+=item B<qemu-xen-traditional>
+
+Use the device-model based upon the historical Xen fork of Qemu.  This
+device-model is currently the default.
+
+=item B<qemu-xen>
+
+use the device-model merged into the upstream Qemu project.  This
+device-model will become the default in a future version of Xen.
+
+=back
+
+It is recommended to accept the default value for new guests.  If
+you have existing guests then, depeending on the nature of the guest
+Operating System, you may wish to force them to use the device
+model which they were installed with.
+
+=item B<device_model_override="PATH">
+
+Override the path to the binary to be used as the device-model. The
+binary provided here MUST be consistent with the
+`device_model_version` which you have specified. You should not
+normally need to specify this option.
+
+=item B<device_model_stubdomain_override=BOOLEAN>
+
+Override the use of stubdomain based device-model.  Normally this will
+be automatically selected based upon the other features and options
+you have selected.
+
+=item B<device_model_args=[ "ARG", "ARG", ...]>
+
+Pass additional arbitrary options on the devide-model command
+line. Each element in the list is passed as an option to the
+device-model.
+
+=item B<device_model_args_pv=[ "ARG", "ARG", ...]>
+
+Pass additional arbitrary options on the devide-model command line for
+a PV device model only. Each element in the list is passed as an
+option to the device-model.
+
+=item B<device_model_args_hvm=[ "ARG", "ARG", ...]>
+
+Pass additional arbitrary options on the devide-model command line for
+an HVM device model only. Each element in the list is passed as an
+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_passthrough=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=XXX>
+
+XXX
+
+=back
+
+=head2 Keymaps
+
+The keymaps available are defined by the device-model which you are
+using. Commonly this includes:
+
+        ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
+        da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
+        de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr
+
+The default is B<en-us>.
+
+See L<qemu(1)> for more information.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<xl(1)>
+
+=item F<xl-disk-configuration>
+
+=item F<xl-network-configuration>
+
+=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
+greatfully received on the [email protected] mailing
+list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
+information on how to submit a patch to Xen.
+

diff -r f3fc909a083d -r c88ff1ac2417 docs/man/xl.pod.1
@@ -54,7 +54,7 @@ previously, most commands take I<domain-
 
 =item B<create> [I<OPTIONS>] I<configfile>
 
-The create subcommand requires a config file: see L<xldomain.cfg> for
+The create subcommand requires a config file: see L<xl.cfg(5)> for
 full details of that file format and possible options.
 
 I<configfile> can either be an absolute path to a file, or a relative

@@ -232,7 +232,7 @@ FIXME: Why would you ever see this state
 
 The domain has crashed, which is always a violent ending.  Usually
 this state can only occur if the domain has been configured not to
-restart on crash.  See L<xldomain.cfg> for more info.
+restart on crash.  See L<xl.cfg(5)> for more info.
 
 =item B<d - dying>
 

@@ -319,8 +319,8 @@ executed the reboot action, which may be
 domain actually reboots.
 
 The behavior of what happens to a domain when it reboots is set by the
-B<on_reboot> parameter of the xldomain.cfg file when the domain was
-created.
+B<on_reboot> parameter of the domain configuration file when the
+domain was created.
 
 =item B<restore> [I<OPTIONS>] [I<ConfigFile>] I<CheckpointFile>
 

@@ -372,8 +372,8 @@ services must be shutdown in the domain.
 immediately after signally the domain unless that B<-w> flag is used.
 
 The behavior of what happens to a domain when it reboots is set by the
-B<on_shutdown> parameter of the xldomain.cfg file when the domain was
-created.
+B<on_shutdown> parameter of the domain configuration file when the
+domain was created.
 
 B<OPTIONS>
 

@@ -699,7 +699,7 @@ The domain id of the guest domain that t
 =item I<disc-spec-component>
 
 A disc specification in the same format used for the B<disk> variable in
-the domain config file. See L<xldomain.cfg>.
+the domain config file. See F<xl-disk-configuration>.
 
 =back
 

@@ -733,9 +733,9 @@ How the device should be presented to th
 
 =item I<be-dev>
 
-the device in the backend domain (usually domain 0) to be exported; it can be a
-path to a file (file://path/to/file.iso). See B<disk> in L<xldomain.cfg> for the
-details.
+the device in the backend domain (usually domain 0) to be exported; it
+can be a path to a file (file://path/to/file.iso). See B<disk> in
+L<xl.cfg(5)> for the details.
 
 =back
 

@@ -754,7 +754,7 @@ I<VirtualDevice> is the cdrom device in 
 
 Creates a new network device in the domain specified by I<domain-id>.
 I<network-device> describes the device to attach, using the same format as the
-B<vif> string in the domain config file. See L<xldomain.cfg> for the
+B<vif> string in the domain config file. See L<xl.cfg(5)> for the
 description.
 
 =item B<network-detach> I<domain-id> I<devid|mac>

@@ -795,7 +795,7 @@ List pass-through pci devices for a doma
 
 =head1 SEE ALSO
 
-B<xldomain.cfg>(5), B<xlcpupool.cfg>(5), B<xentop>(1)
+L<xl.cfg(5)>, L<xlcpupool.cfg(5)>, B<xentop(1)>
 
 =head1 AUTHOR
 

diff -r f3fc909a083d -r c88ff1ac2417 tools/examples/xlexample.hvm
@@ -3,7 +3,7 @@
 # =====================================================================
 #
 # This is a fairly minimal example of what is required for an
-# HVM guest. For a more complete guide see <XXX Document TBD>
+# HVM guest. For a more complete guide see xl.cfg(5)
 
 # This configures an HVM rather than PV guest
 builder = "hvm"

diff -r f3fc909a083d -r c88ff1ac2417 tools/examples/xlexample.pvlinux
@@ -3,7 +3,7 @@
 # =====================================================================
 #
 # This is a fairly minimal example of what is required for a
-# Paravirtualised Linux guest. For a more complete guide see <XXX Document TBD>
+# Paravirtualised Linux guest. For a more complete guide see xl.cfg(5)
 
 # Guest name
 name = "example.pvlinux"

diff -r 22264859117b -r f1464f6fba41 docs/Makefile
@@ -132,37 +132,30 @@ html/%.html: %.markdown
 	@$(INSTALL_DIR) $(@D)
 	@set -e ; if which $(MARKDOWN) 1>/dev/null 2>/dev/null; then \
 	echo "Running markdown to generate $*.html ... "; \
-	$(MARKDOWN) $< > [email protected] ; \
-	$(call move-if-changed,[email protected],$@) ; else \
+	$(MARKDOWN) $< > $@ ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
 html/man/%.1.html: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2HTML) --infile=$< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 
 html/man/%.5.html: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2HTML) --infile=$< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
-	cp $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	cp $< $@
 
 txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
-	cp $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	cp $< $@
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2TEXT) $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2TEXT) $< $@
 
 txt/man/%.5.txt: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2TEXT) $< [email protected]
-	$(call move-if-changed,[email protected],$@)
+	$(POD2TEXT) $< $@

diff -r 6911d1235f82 -r c4571d33f582 docs/man/xl.cfg.pod.5
@@ -491,11 +491,45 @@ compatibility mode on more modern Window
 
 =item B<tsc_mode="MODE">
 
+
 Specifies how the TSC (Time Stamp Counter) should be provided to the
-guest.  XXX ???
+guest (X86 only). Specifying this option as a number is
+deprecated. Options are:
+
+=over 4
+
+=item B<"default">
+
+Guest rdtsc/p executed natively when monotonicity can be guaranteed
+and emulated otherwise (with frequency scaled if necessary).
+
+=item B<"always_emulate">
+
+Guest rdtsc/p always emulated at 1GHz (kernel and user). Guest rdtsc/p
+always emulated and the virtual TSC will appear to increment (kernel
+and user) at a fixed 1GHz rate, regardless of the PCPU HZ rate or
+power state; Although there is an overhead associated with emulation
+this will NOT affect underlying CPU performance.
+
+=item B<"native">
+
+Guest rdtsc always executed natively (no monotonicity/frequency
+guarantees); guest rdtscp emulated at native frequency if unsupported
+by h/w, else executed natively.
+
+=item B<"native_paravirt">
+
+Same as B<native>, except xen manages TSC_AUX register so guest can
+determine when a restore/migration has occurred and assumes guest
+obtains/uses pvclock-like mechanism to adjust for monotonicity and
+frequency changes.
 
 =back
 
+=back
+
+Please see F<docs/misc/tscmode.txt> for more information on this option.
+
 =head3 Support for Paravirtualisation of HVM Guests
 
 The following options allow Paravirtualised features (such as devices)

diff -r 6911d1235f82 -r c4571d33f582 tools/libxl/libxl_types.idl
@@ -85,6 +85,13 @@ libxl_button = Enumeration("button", [
     (2, "SLEEP"),
     ])
 
+libxl_tsc_mode = Enumeration("tsc_mode", [
+    (0, "default"),
+    (1, "always_emulate"),
+    (2, "native"),
+    (3, "native_paravirt"),
+    ])
+
 #
 # Complex libxl types
 #

@@ -154,7 +161,7 @@ libxl_domain_create_info = Struct("domai
 libxl_domain_build_info = Struct("domain_build_info",[
     ("max_vcpus",       integer),
     ("cur_vcpus",       integer),
-    ("tsc_mode",        integer),
+    ("tsc_mode",        libxl_tsc_mode),
     ("max_memkb",       uint32),
     ("target_memkb",    uint32),
     ("video_memkb",     uint32),

diff -r c4571d33f582 -r 617f5d6e9e69 docs/misc/sedf_scheduler_mini-HOWTO.txt
@@ -8,37 +8,37 @@ Overview:
   uses realtime-algorithms to ensure time guarantees.
 
 Usage:
-   -add "sched=sedf" on Xen's boot command-line
-   -create domains as usual
-   -use "xm sched-sedf <dom-id> <period> <slice> <latency-hint> <extra> <weight>"
-    Where:
-      -period/slice are the normal EDF scheduling parameters in nanosecs
-      -latency-hint is the scaled period in case the domain is doing heavy I/O
+   -add "sched=sedf" on Xen's boot command-line
+   -create domains as usual
+   -use "xm sched-sedf <dom-id> <period> <slice> <latency-hint> <extra> <weight>"
+    Where:
+      -period/slice are the normal EDF scheduling parameters in nanosecs
+      -latency-hint is the scaled period in case the domain is doing heavy I/O
          (unused by the currently compiled version)
-      -extra is a flag (0/1), which controls whether the domain can run in
+      -extra is a flag (0/1), which controls whether the domain can run in
        extra-time
-      -weight is mutually exclusive with period/slice and specifies another
+      -weight is mutually exclusive with period/slice and specifies another
        way of setting a domains cpu slice
 
 Examples:
- normal EDF (20ms/5ms):
-  xm sched-sedf <dom-id> 20000000 5000000 0 0 0
+ normal EDF (20ms/5ms):
+  xm sched-sedf <dom-id> 20000000 5000000 0 0 0
   
- best-effort domains (i.e. non-realtime):
-  xm sched-sedf <dom-id> 20000000 0 0 1 0
- 
+ best-effort domains (i.e. non-realtime):
+  xm sched-sedf <dom-id> 20000000 0 0 1 0
+ 
  normal EDF (20ms/5ms) + share of extra-time:
-  xm sched-sedf <dom-id> 20000000 5000000 0 1 0
+  xm sched-sedf <dom-id> 20000000 5000000 0 1 0
   
- 4 domains with weights 2:3:4:2
-  xm sched-sedf <d1> 0 0 0 0 2
-  xm sched-sedf <d2> 0 0 0 0 3
-  xm sched-sedf <d3> 0 0 0 0 4
-  xm sched-sedf <d4> 0 0 0 0 2
+ 4 domains with weights 2:3:4:2
+  xm sched-sedf <d1> 0 0 0 0 2
+  xm sched-sedf <d2> 0 0 0 0 3
+  xm sched-sedf <d3> 0 0 0 0 4
+  xm sched-sedf <d4> 0 0 0 0 2
   
- 1 fully-specified (10ms/3ms) domain, 3 other domains share
- available rest in 2:7:3 ratio:
-  xm sched-sedf <d1> 10000000 3000000 0 0 0
-  xm sched-sedf <d2> 0 0 0 0 2
-  xm sched-sedf <d3> 0 0 0 0 7
-  xm sched-sedf <d4> 0 0 0 0 3
+ 1 fully-specified (10ms/3ms) domain, 3 other domains share
+ available rest in 2:7:3 ratio:
+  xm sched-sedf <d1> 10000000 3000000 0 0 0
+  xm sched-sedf <d2> 0 0 0 0 2
+  xm sched-sedf <d3> 0 0 0 0 7
+  xm sched-sedf <d4> 0 0 0 0 3

diff -r 617f5d6e9e69 -r 55ce23cb7b2a docs/misc/VMX_changes.txt
@@ -1,90 +0,0 @@
-Changes to Xen in support of Intel(R) Vanderpool Technology
--------------------------------------------------------------
-
-Our VT extensions to the Xen hypervisor provide full platform
-virtualization, including CPU(s), memory, and I/O infrastructure. The
-generic code in Xen handles and schedules those virtual machines as it
-does for the existing para-virtualized domains.
-
-Full virtualization required by the OS guests requires full device
-virtualization as well. The device models in BOCHS
-(http://bochs.sourceforge.net/) were decoupled from the CPU
-virtualization, and are used to virtualize the legacy devices (such as
-keyboard, mouse, VGA, IDE) in the PC platform. At this point, the
-device models run in user mode on domain 0, not in the Xen hypervisor.
-
-We would like to thank Ian Pratt and Keir Fraser for reviewing our
-design and code intensively, and for providing numerous useful
-suggestions to improve the architecture and code. 
-
-We have a list of Intel team members who take credit for making this
-release happen: Yunhong Jiang, Nitin Kamble, Chengyuan Li, Xin Li,
-Xiaofeng Ling, Benjamin Liu, Asit Mallick, Jun Nakajima, Sunil Saxena,
-Arun Sharma, Edwin Zhai, Jeff Zheng, and Louis Zhuang. We'll continue
-to add more features to complete full virtualization in Xen using VT.
-
-The notes document the changes to the Xen hypervisor in order to add
-VT support. The changes to other areas, such as Control Panel will be
-added as we deliver the code.
-
-Summary of changes for the first release
-----------------------------------------
-December 15, 2004
-
-    * VT specific event handling and domain management were added. 
-
-    * Shadow mode was extended to support full 32-bit guests
-    
-    * Domain switching code was extended to support VT domain
-    
-    * I/O request handling was added to communicate with the device model
-
-    * Domain builder was extended to provide the environment when the
-      guest enters the protected mode, including E820 memory and VGA
-      info, typically obtained by BIOS calls.
-
-New code:
----------
-    VT (Vanderpool Technology) is based on the new VMX (Virtual
-    Machine Extensions) architecture. The current release of the
-    software supports 32-bit only.
-
-    * arch/x86/vmx.[ch] and arch/x86/vmx_*.[ch]: created to handle
-      VMX-specific events in order to provide virtual machine.
-
-    * arch/x86/x86_32/entry.S: new code path was added to have the
-      first-level handler from VM exits. The first-level handler calls
-      the second-level handler in arch/x86/vmx.c.
-
-    * arch/x86/setup.c: new function start_vmx() to init_intel() to
-      enable VMX mode.
-
-    * include/asm-x86/config.h: #ifdef CONFIG_VMX was added.
-
-    * arch/x86/domain.c: new code patch was added to create a VMX
-      domain given the flag from the control panel.
-
-    * include/public/io/ioreq.h: A new data structure was added to
-      define the I/O requests between the Xen hypervisor and the
-      device models.
-
-Changes to the existing code:
------------------------------
-
-    * arch/x86/shadow.[ch]: new mode SHM_full_32 was added to support
-      full virtualization. The current Xen code assumes that the guest
-      page directory and tables have _machine_ (or host) physical page
-      frame numbers, and the new code allows to support _guest_
-      physical page frame numbers
-
-    * include/asm-x86/processor.h: struct arch_vmx_struct arch_vmx has
-      been added to the thread_struct data structure. The arch_vmx has
-      the additional VMX-related CPU context.
-
-    * arch/x86/io_apic.c: reverse mapping between vector and irq has
-      been added. We will revisit this code when considering MSI
-      support.
-
---- Jun
-
-

485 lines not on this page · raw message

diff -r 617f5d6e9e69 -r 55ce23cb7b2a docs/misc/cpuid-config-for-guest.txt
@@ -1,23 +0,0 @@
-CPUID emulation for guest
--------------------------
-
-When HVM guest tries to execute CPUID, or PV guest tries to execute XEN_CPUID,
-the xen hypervior traps and emultes them.
-
-For HVM guest and PV DomU guest, xen's CPUID emulation can be adjusted using
-the guest configation file if necessary (e.g., to supply better support for
-guest live migration). The CPUID syntax in guest configration file is
-described in detail in the examples like /etc/xen/xmexample.hvm,
-/etc/xen/xmexample.hvm-stubdom.
-
-However, a user (or an administrator) must be aware that the CPUID in guest
-configuration file can NOT be configured casually. The default CPUID
-configuration should be safe, but illegal configuration can cause unexpected
-behaviors of guest -- even can crash guest.
-
-For example, we should not expose the MONITOR CPUID feature flag (ECX bit 3;
-CPUID executed EAX = 1) to HVM guest, otherwise, on guest's attempt of
-executing MWAIT, the VMExit handler in Xen would inject #UD (Invalid Opcode
-Exception) into the HVM guest, and guest kernel would panic.
-
-/* We can add more unsafe CPUID configuration here in future. */

438 lines not on this page · raw message

196 lines not on this page · raw message

diff -r 55ce23cb7b2a -r c1f8406da507 docs/misc/qemu-upstream_howto_use_it.markdown
@@ -1,11 +1,11 @@
-Help to use QEMU (upstream version) with Xen
-============================================
+Using Upstream QEMU with Xen
+============================
 
 Note
 ----
 
 All these steps will become unnecessary after the patches to integrate
-SeaBIOS/QEMU build will be applied.
+SeaBIOS/QEMU into the Xen build system have been applied.
 
 
 How to build it

@@ -15,14 +15,15 @@ How to build it
 
 The new device-model needs a different BIOS, SeaBIOS. Clone the repository from:
 
-  - git://git.qemu.org/seabios.git
-  - http://git.qemu.org/git/seabios.git
+  - [git://git.qemu.org/seabios.git]()
+  - [http://git.qemu.org/git/seabios.git]()
 
-Put the `.config` file in the appendix at the root of seabios.git and build SeaBIOS.
+Put the `.config` file in the appendix at the root of `seabios.git`
+and build SeaBIOS by typing `make`.
 
-In xen-unstable source tree, add the file `.config` with
+In the xen-unstable source tree, add the file `.config` with
 `SEABIOS_DIR = /path/to/seabios.git`.
-To build hvmloader with SeaBIOS, you propably need to `make -C tools/firmware
+To build hvmloader with SeaBIOS, you probably need to `make -C tools/firmware
 clean` first and then `make tools`, to use the new SEABIOS_DIR parameter.
 
 

@@ -30,10 +31,10 @@ clean` first and then `make tools`, to u
 
 Get QEMU upstream source from:
 
-  - git://xenbits.xensource.com/qemu-upstream-unstable.git
-  - http://xenbits.xensource.com/git-http/qemu-upstream-unstable.git
+  - [git://xenbits.xensource.com/qemu-upstream-unstable.git]()
+  - [http://xenbits.xensource.com/git-http/qemu-upstream-unstable.git]()
 
-To configure build QEMU upstream with Xen
+To configure QEMU upstream with support for Xen:
 
     ./configure --enable-xen --target-list=i386-softmmu --extra-cflags="-I$path_to_xen_source/tools/include -I$path_to_xen_source/tools/libxc -I$path_to_xen_source/tools/xenstore" --extra-ldflags="-L$path_to_xen_source/tools/libxc -L$path_to_xen_source/tools/xenstore"
 

@@ -43,15 +44,15 @@ You can also use other several options s
 How to use QEMU upstream
 ------------------------
 
-Only xl support QEMU upstream.
+Only `xl` supports QEMU upstream.
 
 To actually use it, add or change this in your VM configuration file:
 
     device_model_version = 'qemu-xen'
     device_model_override = '/path/to/qemu/i386-softmmu/qemu'
 
-NB: On qemu-upstream repository, the default binary name has been renamed to
-`qemu-system-i386`.
+NB: In the `qemu-upstream` repository, the default binary name has been
+renamed to `qemu-system-i386`.
 
 
 Appendix

diff -r c1f8406da507 -r 8f2404eef8fa docs/INDEX
@@ -0,0 +1,5 @@
+misc/hvm-emulated-unplug	Xen HVM emulated device unplug protocol
+
+# These are not all that useful anymore, hide them from the index
+interface/index			NO-INDEX
+user/index			NO-INDEX

diff -r c1f8406da507 -r 8f2404eef8fa docs/Makefile
@@ -45,7 +45,7 @@ ps: $(DOC_PS)
 pdf: $(DOC_PDF)
 
 .PHONY: html
-html: $(DOC_HTML)
+html: $(DOC_HTML) html/index.html
 
 .PHONY: txt
 txt: $(DOC_TXT)

@@ -128,6 +128,9 @@ html/%/index.html: src/%.tex
 	$< 1>/dev/null 2>/dev/null ; else \
 	echo "latex2html not installed; skipping $*."; fi
 
+html/index.html: $(DOC_HTML) ./gen-html-index INDEX
+	./gen-html-index -i INDEX html $(DOC_HTML)
+
 html/%.html: %.markdown
 	@$(INSTALL_DIR) $(@D)
 	@set -e ; if which $(MARKDOWN) 1>/dev/null 2>/dev/null; then \

129 lines not on this page · raw message

diff -r 8f2404eef8fa -r 7d77e0269af7 docs/INDEX
@@ -1,5 +1,5 @@
 misc/hvm-emulated-unplug	Xen HVM emulated device unplug protocol
 
 # These are not all that useful anymore, hide them from the index
-interface/index			NO-INDEX
-user/index			NO-INDEX
+reference/interface/index	NO-INDEX
+reference/user/index		NO-INDEX

diff -r 8f2404eef8fa -r 7d77e0269af7 docs/Makefile
@@ -14,7 +14,7 @@ DOC_TEX		:= src/user.tex src/interface.t
 DOC_MARKDOWN	:= $(wildcard misc/*.markdown)
 DOC_PS		:= $(patsubst src/%.tex,ps/%.ps,$(DOC_TEX))
 DOC_PDF		:= $(patsubst src/%.tex,pdf/%.pdf,$(DOC_TEX))
-DOC_HTML	:= $(patsubst src/%.tex,html/%/index.html,$(DOC_TEX)) \
+DOC_HTML	:= $(patsubst src/%.tex,html/reference/%/index.html,$(DOC_TEX)) \
 		   $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN)) \
 		   $(patsubst man/%.pod.1,html/man/%.1.html,$(DOC_MAN1SRC)) \
 		   $(patsubst man/%.pod.5,html/man/%.5.html,$(DOC_MAN5SRC))

@@ -119,14 +119,14 @@ ps/%.ps: %.dvi
 %.eps: %.fig
 	$(FIG2DEV) -L eps $< $@
 
-html/%/index.html: src/%.tex
+html/reference/%/index.html: src/%.tex
 	@$(INSTALL_DIR) $(@D)
 	@set -e ; if which $(LATEX2HTML) 1>/dev/null 2>/dev/null; then \
-        echo "Running latex2html to generate $*/index.html ... "; \
+        echo "Running latex2html to generate reference/$*/index.html ... "; \
 	$(LATEX2HTML) -split 0 -show_section_numbers -toc_depth 3 -nonavigation \
 	-numbered_footnotes -local_icons -noinfo -math -dir $(@D) \
 	$< 1>/dev/null 2>/dev/null ; else \
-	echo "latex2html not installed; skipping $*."; fi
+	echo "latex2html not installed; skipping reference/$*."; fi
 
 html/index.html: $(DOC_HTML) ./gen-html-index INDEX
 	./gen-html-index -i INDEX html $(DOC_HTML)

diff -r 29d91e4d1f4f -r bd514e08c509 docs/man/xl.cfg.pod.5
@@ -321,10 +321,11 @@ Run C<PROGRAM> to find the kernel image 
 C<PROGRAM> would be C<pygrub>, which is an emulation of
 grub/grub2/syslinux.
 
-=item B<bootloader_args=STRING>
+=item B<bootloader_args=[ "ARG", "ARG", ...]>
 
-Append B<STRING> (split into words at whitespace) to the arguments to
-the B<bootloader> program.  XXX this should be a list of strings.
+Append B<ARGs to the arguments to the B<bootloader>
+program. Alternatively if the argument is a simple string then it will
+be split into words at whitespace (this second option is deprecated).
 
 =item B<root="STRING">
 

diff -r 29d91e4d1f4f -r bd514e08c509 tools/libxl/libxl_types.idl
@@ -185,7 +185,7 @@ libxl_domain_build_info = Struct("domain
                  ("pv", Struct(None, [("kernel", libxl_file_reference),
                                       ("slack_memkb", uint32),
                                       ("bootloader", string),
-                                      ("bootloader_args", string),
+                                      ("bootloader_args", libxl_string_list),
                                       ("cmdline", string),
                                       ("ramdisk", libxl_file_reference),
                                       ("features", string, True),

diff -r bd514e08c509 -r 83fc69637135 docs/INDEX
@@ -1,5 +1,7 @@
 misc/hvm-emulated-unplug	Xen HVM emulated device unplug protocol
 
+misc/console.txt		Xen PV Console notes
+
 # These are not all that useful anymore, hide them from the index
 reference/interface/index	NO-INDEX
 reference/user/index		NO-INDEX

diff -r bd514e08c509 -r 83fc69637135 docs/Makefile
@@ -17,7 +17,8 @@ DOC_PDF		:= $(patsubst src/%.tex,pdf/%.p
 DOC_HTML	:= $(patsubst src/%.tex,html/reference/%/index.html,$(DOC_TEX)) \
 		   $(patsubst %.markdown,html/%.html,$(DOC_MARKDOWN)) \
 		   $(patsubst man/%.pod.1,html/man/%.1.html,$(DOC_MAN1SRC)) \
-		   $(patsubst man/%.pod.5,html/man/%.5.html,$(DOC_MAN5SRC))
+		   $(patsubst man/%.pod.5,html/man/%.5.html,$(DOC_MAN5SRC)) \
+		   $(patsubst %.txt,html/%.txt,$(wildcard misc/*.txt))
 DOC_TXT         := $(patsubst %.txt,txt/%.txt,$(wildcard misc/*.txt)) \
 		   $(patsubst %.markdown,txt/%.txt,$(DOC_MARKDOWN)) \
 		   $(patsubst man/%.pod.1,txt/man/%.1.txt,$(DOC_MAN1SRC)) \

@@ -138,6 +139,10 @@ html/%.html: %.markdown
 	$(MARKDOWN) $< > $@ ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
+html/%.txt: %.txt
+	@$(INSTALL_DIR) $(@D)
+	cp $< $@
+
 html/man/%.1.html: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
 	$(POD2HTML) --infile=$< --outfile=$@