thr3ads.net - Xen devel - [Xen-devel] [PATCH 0 of 7] xl domain config file documentation & other bits [Nov 2011]

If this information is useful, please help other people find it:
Share via:

Ian Campbell

2011-Nov-07 15:13 UTC

[Xen-devel] [PATCH 0 of 7] xl domain config file documentation & other bits

The following contains a document describing the xl configuration file
format and the keys therein.

There is also a few incidental bits and bobs relating to documentation.

IanJ, the branch you sent me with the basis for this doc had various
other cleanups in it. I have pulled out the one which makes the "name"
parameter mandatory but have left the rest.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 1 of 7] docs: report when we don''t build docs due to a missing tool

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678727 0
# Node ID 7a126dbf62d76d45a10ea55be9c354b1bd4f4bf1
# Parent  c0702424afc5f7b972c26c6110f6489305844635
docs: report when we don''t build docs due to a missing tool

It''s useful if you are wondering why there are no docs..

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r c0702424afc5 -r 7a126dbf62d7 docs/Makefile
--- a/docs/Makefile	Mon Nov 07 10:29:14 2011 +0100
+++ b/docs/Makefile	Mon Nov 07 15:12:07 2011 +0000
@@ -58,7 +58,8 @@ python-dev-docs:
 .PHONY: man-pages
 man-pages:
 	@if which $(POD2MAN) 1>/dev/null 2>/dev/null; then \
-	$(MAKE) $(DOC_MAN1) $(DOC_MAN5); fi
+	$(MAKE) $(DOC_MAN1) $(DOC_MAN5); else              \
+	echo "pod2man not installed; skipping man-pages."; fi
 
 man1/%.1: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
@@ -120,14 +121,16 @@ html/%/index.html: src/%.tex
         echo "Running latex2html to generate $*/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 ;fi
+	$< 1>/dev/null 2>/dev/null ; else \
+	echo "latex2html not installed; skipping $*."; fi
 
 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) $< > $@.tmp ; \
-	$(call move-if-changed,$@.tmp,$@) ; fi
+	$(call move-if-changed,$@.tmp,$@) ; else \
+	echo "markdown not installed; skipping $*.html."; fi
 
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 2 of 7] README: add markdown to dependency list

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678728 0
# Node ID 705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb
# Parent  7a126dbf62d76d45a10ea55be9c354b1bd4f4bf1
README: add markdown to dependency list

although this tool is strictly speaking optional we are providing various user
docs in this format so increase the changes that they will install it.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 7a126dbf62d7 -r 705b2e659ff8 README
--- a/README	Mon Nov 07 15:12:07 2011 +0000
+++ b/README	Mon Nov 07 15:12:08 2011 +0000
@@ -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

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678758 0
# Node ID 291f6cb0d03e56e4edbe53c640c96dff85d9bf08
# Parent  705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb
docs: add a document describing the xl cfg file syntax

Based on an initial version by Ian Jackson.

I believe that all keys are now present in the document although there are are
various omissions in the actual documentation of them. Hopefully however this
covers the majority of the most interesting keys.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 705b2e659ff8 -r 291f6cb0d03e docs/Makefile
--- a/docs/Makefile	Mon Nov 07 15:12:08 2011 +0000
+++ b/docs/Makefile	Mon Nov 07 15:12:38 2011 +0000
@@ -11,7 +11,7 @@ DOC_MAN1SRC	:= $(wildcard man/*.pod.1)
 DOC_MAN1	:= $(patsubst man/%.pod.1,man1/%.1,$(DOC_MAN1SRC))
 DOC_MAN5	:= $(patsubst man/%.pod.5,man5/%.5,$(DOC_MAN5SRC))
 DOC_TEX		:= src/user.tex src/interface.tex
-DOC_MARKDOWN	:= $(wildcard misc/*.markdown)
+DOC_MARKDOWN	:= $(wildcard misc/*.markdown) $(wildcard user/*.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)) \
diff -r 705b2e659ff8 -r 291f6cb0d03e docs/user/xl-domain-config.markdown
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/user/xl-domain-config.markdown	Mon Nov 07 15:12:38 2011 +0000
@@ -0,0 +1,554 @@
+ # xl Domain Configuration
+
+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.
+
+## Work In Progress
+
+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 [xen-devel][] mailing list. Please see
+[SubmittingXenPatches][] wiki page for information on how to submit a
+patch to Xen.
+
+[xen-devel]: mailto:xen-devel@lists.xensource.com
+[SubmittingXenPatches]: http://wiki.xen.org/xenwiki/SubmittingXenPatches
+
+----------------------------------------
+
+## Syntax
+
+A domain config file consists of a series of `KEY=VALUE` pairs.
+
+Some `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 `VALUE` is one of:
+
+ * `"STRING"`: A string, surrounded by either single or double
quotes.
+ * `NUMBER`: A number, in either decimal, octal (using a `0 prefix`)
+   or hexadecimal (using an `0x` prefix`).
+ * `BOOLEAN`: A `NUMBER` interpreted as `False` (`0`) or `True` (any
+   other value).
+ * `[ VALUE, VALUE, ... ]`: A list of `VALUES` of the above
+   types. Lists are homogeneous and are not nested.
+
+The semantics of each `KEY` defines which form of `VALUE` is required.
+
+----------------------------------------
+
+## Mandatory Configuration Items
+
+The following key is mandatory for any guest type:
+
+ * `name="NAME"`: Specifies the name of the domain.  Names of domains
+   existing on a single host must be unique.
+
+## Selecting Guest Type
+
+ * `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.
+
+## Global Options
+
+The following options apply to guests of any type.
+
+ * `uuid="UUID"`: Specifies the UUID of the domain.  If not
specified,
+   a fresh unique UUID will be generated.
+
+ * `pool="CPUPOOLNAME"`: Put the guest''s vcpus into the
named cpu
+   pool.
+
+ * `vcpus=N`: Start the guest with N vcpus initially online.
+
+ * `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.
+
+ * `memory=MBYTES`: Start the guest with MBYTES megabytes of RAM.
+
+ * `on_poweroff=ACTION`: Specifies what should be done with the domain
+   if it shuts itself down.  The options are:
+
+     * `destroy`: destroy the domain;
+     
+     * `restart`: destroy the domain and immediately create a new
+        domain with the same configuration;
+        
+     * `rename-restart`: rename the domain which terminated, and then
+       immediately create a new domain with the same configuration as
+       the original;
+
+     * `preserve`: keep the domain.  It can be examined, and later
+       destroyed with `xl destroy`.
+
+     * `coredump-destroy`: write a "coredump" of the domain to
+       `/var/xen/dump/NAME` and then destroy the domain.
+
+     * `coredump-restart`: write a "coredump" of the domain to
+       `/var/xen/dump/NAME` and then restart the domain.
+
+   The default for `on_poweroff` is `destroy`.
+
+ * `on_reboot=ACTION`: Action to take if the domain shuts down with a
+   reason code requesting a reboot.  Default is `restart`.
+
+ * `on_watchdog=ACTION`: Action to take if the domain shuts down due
+   to a Xen watchdog timeout.  Default is `destroy`.
+
+ * `on_crash=ACTION`: Action to take if the domain crashes.  Default
+   is `destroy`.
+ 
+ * `seclabel=LABEL`: Assign an XSM security label to this domain.
+
+## Devices
+
+The following options define the paravirtual, emulated and physical
+devices which the guest will contain.
+
+ * `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 `docs/misc/xl-disk-configuration.txt`.
+
+ * `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 
+   `docs/misc/xl-network-configuration.markdown`.
+
+ * `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 "Emulated VGA Graphics Device" below for how
+   to configure the emulated device.
+
+   Each `VFB_SPEC_STRING` is a comma-separated list of `KEY=VALUE`
+   settings, from the following list:
+   
+     * `vnc=BOOLEAN`: Allow access to the display via the VNC
+       protocol.  This enables the other VNC-related settings.
+       The default is to enable this.
+
+     * `vnclisten="ADDRESS[:DISPLAYNUM]"`: Specifies the IP address,
+       and optionally VNC display number, to use.
+
+     * `vncdisplay=DISPLAYNUM`: Specifies the VNC display number to
+       use.  The actual TCP port number will be DISPLAYNUM+5900.
+
+     * `vncunused=BOOLEAN`: Requests that the VNC display setup search
+       for a free TCP port to use.  The actual display used can be
+       accessed with `xl vncviewer`.
+
+     * `vncpasswd="PASSWORD"`: Specifies the password for the VNC
+       server.
+
+     * `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
+
+     * `opengl=BOOLEAN`: Enable OpenGL acceleration of the SDL
+       display. Only effects machines using
+       `device_model_version="qemu-xen-traditonal"` and only if the
+       device-model was compiled with OpenGL support. Disabled by default.
+
+     * `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 "Keymaps" below of consult the `qemu(1)`
+       manpage. The default is `en-us`.
+
+     * `display=XXX`: XXX written to xenstore backend for vfb but does not
+       appear to be used anywhere?
+
+     * `authority=XXX`: XXX written to xenstore backend for vfb but does not
+       appear to be used anywhere?
+
+ * `pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ... ]`:
Specifies the
+   host PCI devices to passthrough to this guest. Each `PCI_SPEC_STRING`
+   has the form `[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...` where:
+
+   `DDDD:BB:DD.F` identifies the PCI device from the host perspective
+   in domain (`DDDD`), Bus (`BB`), Device (`DD`) and Function (`F`)
+   syntax. This is the same scheme as used in the output of `lspci`
+   for the device in question. Note: By default `lspci` will omit the
+   domain (`DDDD`) if it is zero and it is optional here also. You may
+   specify the function (''F'') as ''*'' to
indicate all functions.
+
+   `@VSLOT` specifies the virtual device where the guest will see this
+   device. This is equivalent to the `DD` which the guest sees. In a
+   guest `DDDD` and `BB` are 0000:00. XXX how does this really work?
+
+   Possible `KEY`s are:
+
+      * `msitranslate=BOOLEAN`: XXX
+      * `power_mgmt=BOOLEAN`: XXX
+
+## Paravirtualised (PV) Guest Specific Options
+
+The following options apply only to Paravirtual guests.
+
+ * `kernel="PATHNAME"`: Load the specified file as the kernel image
(for
+   PV guests only).  Either `kernel` or `bootloader` must be specified
+   for PV guests.
+
+ * `ramdisk="PATHNAME"`: Load the specified file as the ramdisk (for
PV
+   guests only).
+
+ * `bootloader="PROGRAM"`: Run PROGRAM to find the kernel image and
+   ramdisk to use (for PV guests only).  Normally PROGRAM would be
+   `pygrub`, which is an emulation of grub/grub2/syslinux.
+
+ * `bootloader_args=STRING`: Append STRING (split into words at
+   whitespace) to the arguments to the `bootloader` program.  XXX this
+   should be a list of strings.
+
+ * `root="STRING"`: Append `root="STRING"` to the kernel
command line
+   (Note: it is guest specific what meaning this has).
+
+ * `extra="STRING"`: Append "STRING" to the kernel command
line.
+    (Note: it is guest specific what meaning this has).
+
+ * `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.
+
+## Fully-virtualised (HVM) Guest Specific Options
+
+The following options apply only to HVM guests.
+
+### Boot Device
+
+ * `boot=[c|d|n]`: Selects the emulated virtual device to boot
+   from. Options are hard disk (`c`), cd-rom (`d`) or network/PXE
+   (`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 `dc`. The default is `cd`.
+
+### 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.
+
+ * `hap=BOOLEAN`: Turns "hardware assisted paging" (the use of the
+   hardware'' nested page table feature) on or off.  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.
+
+ * `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.
+
+ * `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 large number of processes which do not
+   share address space then increasing this value may improve
+   performance.
+
+### 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.
+
+ * `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)
+
+ * `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.
+
+ * `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)
+
+ * `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)
+
+ * `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)
+
+ * `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).
+
+### 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.
+
+ * `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][XenLinuxPVonHVMdrivers] and [Microsoft
+   Windows][XenWindowsGplPv].
+
+   [XenLinuxPVonHVMdrivers]: http://wiki.xen.org/xenwiki/XenLinuxPVonHVMdrivers
+   [XenWindowsGplPv]: http://wiki.xen.org/xenwiki/XenWindowsGplPv
+
+ * `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?)
+
+### 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).
+
+ * `device_model_version="DEVICE-MODEL"`: Selects which variant of
the
+   device-model should be used for this guest. Valid values are:
+
+     * `qemu-xen-traditional`: Use the device-model based upon the
+       historical Xen fork of Qemu.  This device-model is currently
+       the default.
+
+     * `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.
+
+   It is recommended to accept the default value for new guests.  If
+   you have existing guests then, dpeending on the nature of the guest
+   Operating System, you may wish to force them to use the device
+   model which they were installed with.
+
+ * `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.
+
+ * `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.
+
+ * `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.
+
+ * `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.
+
+ * `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.
+
+### 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 `VFB_SPEC_STRING` for configuring virtual frame buffer devices
+(see above).
+
+ * `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 `stdvga` option (see below). The default is 8MB which is
+   sufficient for e.g. 1600x1200 at 32bpp. When not using the `stdvga`
+   option the amount of video ram is fixed at 4MB which is sufficient
+   for 1024x768 at 32 bpp.
+
+ * `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.
+
+ * `vnc=BOOLEAN`: Allow access to the display via the VNC protocol.
+    This enables the other VNC-related settings.  The default is to
+    enable this.
+
+ * `vnclisten="ADDRESS[:DISPLAYNUM]": Specifies the IP address, and
+   optionally VNC display number, to use.
+
+ * `vncdisplay=DISPLAYNUM`: Specifies the VNC display number to use.
+   The actual TCP port number will be DISPLAYNUM+5900.
+
+ * `vncunused=BOOLEAN`: Requests that the VNC display setup search for
+   a free TCP port to use.  The actual display used can be accessed
+   with `xl vncviewer`.
+
+ * `vncpasswd="PASSWORD"`: Specifies the password for the VNC server.
+
+ * `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
+   "Keymaps" below of consult the `qemu(1)` manpage. The default is
+   `en-us`.
+
+ * `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.
+
+ * `opengl=BOOLEAN`: Enable OpenGL acceleration of the SDL
+   display. Only effects machines using
+   `device_model_version="qemu-xen-traditonal"` and only if the
+   device-model was compiled with OpenGL support. Disabled by default.
+
+ * `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.
+
+### Spice Graphics Support
+
+ * `spice=BOOLEAN`: XXX
+
+ * `spiceport=XXX`: XXX
+
+ * `spicetls_port=XXX`: XXX
+
+ * `spicehost=XXX`: XXX
+
+ * `spicedisable_ticketing=XXX`: XXX
+
+ * `spiceagent_mouse=XXX`: XXX
+
+### Miscellaneous Emulated Hardware
+
+ * `serial=DEVICE`: Redirect the virtual serial port to
+   `DEVICE`. Please see the `-serial` option in the `qemu(1)` manpage
+   for details of the valid `DEVICE` options. Default is `vc` when in
+   graphical mode and `stdio` if `nographics=1` is used.
+
+ * `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 `qemu(1)` manpage for details. The
+   default is not to export any sound device.
+
+ * `usb=BOOLEAN`: Enables or disables a USB bus in the guest.
+
+ * `usbdevice=DEVICE`: Adds `DEVICE` to the USB bus. The USB bus must
+   also be enabled using `usb=1`. The most common use for this option
+   is `usbdevice=table` 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.
+
+### Unclassified HVM Specific Options
+
+These HVM specific options have not yet been documented or
+classified. They almost certainly belong in a more appropriate
+section.
+
+ * `vpt_align=BOOLEAN`: Align the Virtual Platform Timer ??? XXX
+   Reduces interrupts?
+
+ * `timer_mode=NUMBER`: Set mode for Virtual Timers XXX ??? should be
+   an enum of particular values. See HVM_PARAM_TIMER_MODE in
+   xen/include/public/hvm/params.h
+
+## Unclassified General Options
+
+These have not yet been fully documented or classified. They almost
+certainly belong in a more appropriate section.
+
+ * `gfx_passthrough=BOOLEAN`: Enable graphics device PCI passthrough.
+   XXX which device is passed through ?
+
+ * `nomigrate=BOOLEAN`: Disable migration of this domain.  This
+   enables certain other features which are incompatible with
+   migration (currently certain TSC modes XXX ?).
+
+ * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter) should
+   be provided to the guest.  XXX ???
+
+ * `pci_msitranslate=BOOLEAN`: XXX
+
+ * `pci_power_mgmt=BOOLEAN`: XXX
+
+ * `cpuid=XXX`: XXX
+
+# 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 "en-us".
+
+See `qemu(1)` for more information.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 4 of 7] docs: fix references from xl man page to xldomain.cfg manpage

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678761 0
# Node ID 25c3e859855f71cf25a0d607736821d4858d880a
# Parent  291f6cb0d03e56e4edbe53c640c96dff85d9bf08
docs: fix references from xl man page to xldomain.cfg manpage.

They should reference the xl-domain-config document. pod2html (which I
will call shortly) doesn''t like these and reports: "cannot resolve
L<xldomain.cfg> in paragraph" and similar.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 291f6cb0d03e -r 25c3e859855f docs/man/xl.pod.1
--- a/docs/man/xl.pod.1	Mon Nov 07 15:12:38 2011 +0000
+++ b/docs/man/xl.pod.1	Mon Nov 07 15:12:41 2011 +0000
@@ -54,8 +54,9 @@ 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
-full details of that file format and possible options.
+The create subcommand requires a config file: see
+F<xl-domain-config> for full details of that file format and
+possible options.
 
 I<configfile> can either be an absolute path to a file, or a relative
 path to a file located in /etc/xen.
@@ -232,7 +233,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 F<xl-domain-config> for more info.
 
 =item B<d - dying>
 
@@ -319,8 +320,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 +373,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 +700,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 +734,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
+F<xl-domain-config> for the details.
 
 =back
 
@@ -754,7 +755,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 F<xl-domain-config>
for the
 description.
 
 =item B<network-detach> I<domain-id> I<devid|mac>
@@ -795,7 +796,7 @@ List pass-through pci devices for a doma
 
 =head1 SEE ALSO
 
-B<xldomain.cfg>(5), B<xlcpupool.cfg>(5), B<xentop>(1)
+F<xl-domain-config>, B<xlcpupool.cfg>(5), B<xentop>(1)
 
 =head1 AUTHOR
 
diff -r 291f6cb0d03e -r 25c3e859855f docs/man/xm.pod.1
--- a/docs/man/xm.pod.1	Mon Nov 07 15:12:38 2011 +0000
+++ b/docs/man/xm.pod.1	Mon Nov 07 15:12:41 2011 +0000
@@ -71,7 +71,7 @@ Use the key combination Ctrl+] to detach
 
 The create subcommand requires a config file and can optionally take a
 series of I<vars> that add to or override variables defined
-in the config file.  See L<xmdomain.cfg> for full details of that file
+in the config file.  See F<xmdomain.cfg> for full details of that file
 format, and possible options used in either the configfile or for
I<vars>.
 
 I<configfile> can either be an absolute path to a file, or a relative
@@ -301,7 +301,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<xmdomain.cfg> for more info.
+restart on crash.  See F<xmdomain.cfg> for more info.
 
 =item B<d - dying>
 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 5 of 7] docs: install html and txt versions of manpages

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678761 0
# Node ID 2f1fbfd8880858dba3fe18c811e3926293b6030b
# Parent  25c3e859855f71cf25a0d607736821d4858d880a
docs: install html and txt versions of manpages

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 25c3e859855f -r 2f1fbfd88808 docs/Docs.mk
--- a/docs/Docs.mk	Mon Nov 07 15:12:41 2011 +0000
+++ b/docs/Docs.mk	Mon Nov 07 15:12:41 2011 +0000
@@ -5,6 +5,8 @@ FIG2DEV		:= fig2dev
 LATEX2HTML	:= latex2html
 DOXYGEN		:= doxygen
 POD2MAN		:= pod2man
+POD2HTML	:= pod2html
+POD2TEXT	:= pod2text
 DOT		:= dot
 NEATO		:= neato
 MARKDOWN	:= markdown
diff -r 25c3e859855f -r 2f1fbfd88808 docs/Makefile
--- a/docs/Makefile	Mon Nov 07 15:12:41 2011 +0000
+++ b/docs/Makefile	Mon Nov 07 15:12:41 2011 +0000
@@ -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,$@.tmp,$@) ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
+html/man/%.1.html: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2HTML) --infile=$< --outfile=$@.tmp
+	$(call move-if-changed,$@.tmp,$@)
+
+html/man/%.5.html: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2HTML) --infile=$< --outfile=$@.tmp
+	$(call move-if-changed,$@.tmp,$@)
+
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
 	cp $< $@.tmp
@@ -141,3 +155,14 @@ txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
 	cp $< $@.tmp
 	$(call move-if-changed,$@.tmp,$@)
+
+txt/man/%.1.txt: man/%.pod.1 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2TEXT) $< $@.tmp
+	$(call move-if-changed,$@.tmp,$@)
+
+txt/man/%.5.txt: man/%.pod.5 Makefile
+	$(INSTALL_DIR) $(@D)
+	$(POD2TEXT) $< $@.tmp
+	$(call move-if-changed,$@.tmp,$@)
+

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 6 of 7] xl: the name field in a guest config file is mandatory

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678761 0
# Node ID 83c6d49df549f663291dbf032de70d6bab149feb
# Parent  2f1fbfd8880858dba3fe18c811e3926293b6030b
xl: the name field in a guest config file is mandatory

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 2f1fbfd88808 -r 83c6d49df549 tools/libxl/xl_cmdimpl.c
--- a/tools/libxl/xl_cmdimpl.c	Mon Nov 07 15:12:41 2011 +0000
+++ b/tools/libxl/xl_cmdimpl.c	Mon Nov 07 15:12:41 2011 +0000
@@ -575,8 +575,10 @@ static void parse_config_data(const char
     if (!xlu_cfg_get_long (config, "hap", &l))
         c_info->hap = l;
 
-    if (xlu_cfg_replace_string (config, "name",
&c_info->name))
-        c_info->name = strdup("test");
+    if (xlu_cfg_replace_string (config, "name",
&c_info->name)) {
+        fprintf(stderr, "Domain name must be specified.");
+        exit(1);
+    }
 
     if (!xlu_cfg_get_string (config, "uuid", &buf) ) {
         if ( libxl_uuid_from_string(&c_info->uuid, buf) ) {

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 15:13 UTC

head link

[Xen-devel] [PATCH 7 of 7] docs: generate docs direct into final filename

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320678761 0
# Node ID e97a5f1943e0a3641f9415e15bdeb991cf1c3bdd
# Parent  83c6d49df549f663291dbf032de70d6bab149feb
docs: generate docs direct into final filename

Nothing depends on the final document so there is not much point in generating
to a tempfile and move-if-changed.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 83c6d49df549 -r e97a5f1943e0 docs/Makefile
--- a/docs/Makefile	Mon Nov 07 15:12:41 2011 +0000
+++ b/docs/Makefile	Mon Nov 07 15:12:41 2011 +0000
@@ -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) $< > $@.tmp ; \
-	$(call move-if-changed,$@.tmp,$@) ; else \
+	$(MARKDOWN) $< > $@ ; else \
 	echo "markdown not installed; skipping $*.html."; fi
 
 html/man/%.1.html: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2HTML) --infile=$< --outfile=$@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 
 html/man/%.5.html: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2HTML) --infile=$< --outfile=$@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2HTML) --infile=$< --outfile=$@
 
 txt/%.txt: %.txt
 	$(INSTALL_DIR) $(@D)
-	cp $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	cp $< $@
 
 txt/%.txt: %.markdown
 	$(INSTALL_DIR) $(@D)
-	cp $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	cp $< $@
 
 txt/man/%.1.txt: man/%.pod.1 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2TEXT) $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2TEXT) $< $@
 
 txt/man/%.5.txt: man/%.pod.5 Makefile
 	$(INSTALL_DIR) $(@D)
-	$(POD2TEXT) $< $@.tmp
-	$(call move-if-changed,$@.tmp,$@)
+	$(POD2TEXT) $< $@
 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 16:06 UTC

head link

[Xen-devel] [PATCH] docs: xlexample.hvm is missing "builder = ''hvm''"

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320681787 0
# Node ID e4a5b7b7f9ac739bb350080524279580086e0ad9
# Parent  e97a5f1943e0a3641f9415e15bdeb991cf1c3bdd
docs: xlexample.hvm is missing "builder = ''hvm''"

This is rather critical...

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r e97a5f1943e0 -r e4a5b7b7f9ac tools/examples/xlexample.hvm
--- a/tools/examples/xlexample.hvm	Mon Nov 07 15:12:41 2011 +0000
+++ b/tools/examples/xlexample.hvm	Mon Nov 07 16:03:07 2011 +0000
@@ -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"
 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 16:06 UTC

head link

[Xen-devel] [PATCH] docs: xlexample.*: reference xl-domain-config document

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320681846 0
# Node ID 30c6d81d3509a35365ac4bd68bdfdc035f768ff3
# Parent  e4a5b7b7f9ac739bb350080524279580086e0ad9
docs: xlexample.*: reference xl-domain-config document

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r e4a5b7b7f9ac -r 30c6d81d3509 tools/examples/xlexample.hvm
--- a/tools/examples/xlexample.hvm	Mon Nov 07 16:03:07 2011 +0000
+++ b/tools/examples/xlexample.hvm	Mon Nov 07 16:04:06 2011 +0000
@@ -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-domain-config>
 
 # This configures an HVM rather than PV guest
 builder = "hvm"
diff -r e4a5b7b7f9ac -r 30c6d81d3509 tools/examples/xlexample.pvlinux
--- a/tools/examples/xlexample.pvlinux	Mon Nov 07 16:03:07 2011 +0000
+++ b/tools/examples/xlexample.pvlinux	Mon Nov 07 16:04:06 2011 +0000
@@ -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-domain-config>
 
 # Guest name
 name = "example.pvlinux"

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-07 16:07 UTC

head link

Re: [Xen-devel] [PATCH 0 of 7] xl domain config file documentation & other bits

On Mon, 2011-11-07 at 15:13 +0000, Ian Campbell wrote:> The following contains a document describing the xl configuration file
> format and the keys therein.
I just sent 2 additional patches:

[PATCH 8 of 7]  docs: xlexample.hvm is missing "builder =
''hvm''"
[PATCH 9 of 7]  docs: xlexample.*: reference xl-domain-config document

Ian.


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-09 15:00 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Mon, 2011-11-07 at 15:13 +0000, Ian Campbell wrote:> 
> +### Spice Graphics Support
> +
> + * `spice=BOOLEAN`: XXX
> +
> + * `spiceport=XXX`: XXX
> +
> + * `spicetls_port=XXX`: XXX
> +
> + * `spicehost=XXX`: XXX
> +
> + * `spicedisable_ticketing=XXX`: XXX
> +
> + * `spiceagent_mouse=XXX`: XXX 
Hi Zhou,

It seems that you added most of these commands to xl. Can I trouble you
to write a few words about what they do?

Thanks,

Ian.


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

ZhouPeng

2011-Nov-10 05:18 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Wed, Nov 9, 2011 at 11:00 PM, Ian Campbell <Ian.Campbell@citrix.com>
wrote:> It seems that you added most of these commands to xl. Can I trouble you
> to write a few words about what they do?Hi Ian,
This is the doc in line below.
Sorry not sent in a diff patch. I checked but It seems your doc patch has
not been committed into the unstable.

Signed-off-by: Zhou Peng <zhoupeng@nfs.iscas.ac.cn>

### Spice Graphics Support

The following options control the features of SPICE.

 * `spice=BOOLEAN`: Allow access to the display via the SPICE protocol.
    This enables the other SPICE-related settings.

 * `spicehost="ADDRESS"`: Specify the interface address to listen on
if
    given, otherwise any interface.

 * `spiceport=NUMBER`: Specify the port to listen on by the SPICE server
    if the SPICE is enabled.

 * `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.

 * `spicedisable_ticketing=BOOLEAN`: Enable client connection
    without password. The default is false. If it''s false (set to 0),
    spicepasswd must be set.

 * `spicepasswd="PASSWORD"`: Specify the ticket password which is used
by
    a client for connection.

 * `spiceagent_mouse=BOOLEAN`: Whether SPICE agent is used
    for client mouse mode. The default is true (turn on)

-- 
Zhou Peng

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 08:04 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Thu, 2011-11-10 at 05:18 +0000, ZhouPeng wrote:> On Wed, Nov 9, 2011 at 11:00 PM, Ian Campbell
<Ian.Campbell@citrix.com> wrote:
> > It seems that you added most of these commands to xl. Can I trouble
you
> > to write a few words about what they do?
> Hi Ian,
> This is the doc in line below.
> Sorry not sent in a diff patch. I checked but It seems your doc patch has
> not been committed into the unstable.
> 
> Signed-off-by: Zhou Peng <zhoupeng@nfs.iscas.ac.cn>
Thanks Zhou, I''ll add this to the end of my series and repost it.

Ian.
> 
> ### Spice Graphics Support
> 
> The following options control the features of SPICE.
> 
>  * `spice=BOOLEAN`: Allow access to the display via the SPICE protocol.
>     This enables the other SPICE-related settings.
> 
>  * `spicehost="ADDRESS"`: Specify the interface address to listen
on if
>     given, otherwise any interface.
> 
>  * `spiceport=NUMBER`: Specify the port to listen on by the SPICE server
>     if the SPICE is enabled.
> 
>  * `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.
> 
>  * `spicedisable_ticketing=BOOLEAN`: Enable client connection
>     without password. The default is false. If it''s false (set to
0),
>     spicepasswd must be set.
> 
>  * `spicepasswd="PASSWORD"`: Specify the ticket password which is
used by
>     a client for connection.
> 
>  * `spiceagent_mouse=BOOLEAN`: Whether SPICE agent is used
>     for client mouse mode. The default is true (turn on)
> 


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 08:06 UTC

head link

[Xen-devel] [PATCH] docs: add spice options to xl domain cfg document

# HG changeset patch
# User Ian Campbell <ian.campbell@citrix.com>
# Date 1320912366 0
# Node ID ceebf46a339d6c5e1bb2f91abe8a7ed0cc0178bf
# Parent  30c6d81d3509a35365ac4bd68bdfdc035f768ff3
docs: add spice options to xl domain cfg document

Signed-off-by: Zhou Peng <zhoupeng@nfs.iscas.ac.cn>
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

diff -r 30c6d81d3509 -r ceebf46a339d docs/user/xl-domain-config.markdown
--- a/docs/user/xl-domain-config.markdown	Mon Nov 07 16:04:06 2011 +0000
+++ b/docs/user/xl-domain-config.markdown	Thu Nov 10 08:06:06 2011 +0000
@@ -471,17 +471,31 @@ in the `VFB_SPEC_STRING` for configuring
 
 ### Spice Graphics Support
 
- * `spice=BOOLEAN`: XXX
+The following options control the features of SPICE.
 
- * `spiceport=XXX`: XXX
+ * `spice=BOOLEAN`: Allow access to the display via the SPICE protocol.
+    This enables the other SPICE-related settings.
 
- * `spicetls_port=XXX`: XXX
+ * `spicehost="ADDRESS"`: Specify the interface address to listen on
if
+    given, otherwise any interface.
 
- * `spicehost=XXX`: XXX
+ * `spiceport=NUMBER`: Specify the port to listen on by the SPICE server
+    if the SPICE is enabled.
 
- * `spicedisable_ticketing=XXX`: XXX
+ * `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.
 
- * `spiceagent_mouse=XXX`: XXX
+ * `spicedisable_ticketing=BOOLEAN`: Enable client connection
+    without password. The default is false. If it''s false (set to 0),
+    spicepasswd must be set.
+
+ * `spicepasswd="PASSWORD"`: Specify the ticket password which is
used by
+    a client for connection.
+
+ * `spiceagent_mouse=BOOLEAN`: Whether SPICE agent is used
+    for client mouse mode. The default is true (turn on)
 
 ### Miscellaneous Emulated Hardware
 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 08:10 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Tim, George:

Is this broadly accurate? In particular the bit about why one would use
the shadow_memory option and the suggestion that it also controls the
space used by the HAP overhead.

Cheers,
Ian.

On Mon, 2011-11-07 at 15:13 +0000, Ian Campbell wrote:> 
> +### 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.
> +
> + * `hap=BOOLEAN`: Turns "hardware assisted paging" (the use of
the
> +   hardware'' nested page table feature) on or off.  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.
> +
> + * `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.
> +
> + * `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 large number of processes which do
> not
> +   share address space then increasing this value may improve
> +   performance. 

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Tim Deegan

2011-Nov-10 09:54 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

At 08:10 +0000 on 10 Nov (1320912604), Ian Campbell
wrote:> Tim, George:
> 
> Is this broadly accurate? In particular the bit about why one would use
> the shadow_memory option and the suggestion that it also controls the
> space used by the HAP overhead.
> 
> Cheers,
> Ian.
> 
> On Mon, 2011-11-07 at 15:13 +0000, Ian Campbell wrote:
> > 
> > +### 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.
> > +
> > + * `hap=BOOLEAN`: Turns "hardware assisted paging" (the use
of the
> > +   hardware'' nested page table feature) on or off.  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.
Yep.  Might be worth mentioning that HAP is called EPT and NPT (or RVI)
by the hardware vendors.
> > + * `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.
Yep. 
> > + * `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 large number of processes which do
> > not
> > +   share address space then increasing this value may improve
> > +   performance. 
Actually in the bad case the processes _do_ share address space
(otherwise the guest would be thrashing for RAM before it rnus out of
shadow memory).  Maybe ''a very large number of similar
processes''?

Cheers,

Tim.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 09:58 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

On Thu, 2011-11-10 at 09:54 +0000, Tim Deegan wrote:> At 08:10 +0000 on 10 Nov (1320912604), Ian Campbell wrote:
> > Tim, George:
> > 
> > Is this broadly accurate? In particular the bit about why one would
use
> > the shadow_memory option and the suggestion that it also controls the
> > space used by the HAP overhead.
> > 
> > Cheers,
> > Ian.
> > 
> > On Mon, 2011-11-07 at 15:13 +0000, Ian Campbell wrote:
> > > 
> > > +### 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.
> > > +
> > > + * `hap=BOOLEAN`: Turns "hardware assisted paging"
(the use of the
> > > +   hardware'' nested page table feature) on or off. 
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.
> 
> Yep.  Might be worth mentioning that HAP is called EPT and NPT (or RVI)
> by the hardware vendors.
Good idea. Since I had to look them up:
EPT -- Extended Page Tables (Intel)
NPT -- Nested Page Tables (AMD)
RVI -- Rapid Virtualisation Indexing (vmware''s name, I think?)
> 
> > > + * `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.
> 
> Yep. 
> 
> > > + * `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 large number of processes which
do
> > > not
> > > +   share address space then increasing this value may improve
> > > +   performance. 
> 
> Actually in the bad case the processes _do_ share address space
> (otherwise the guest would be thrashing for RAM before it rnus out of
> shadow memory).  Maybe ''a very large number of similar
processes''?
Sounds fine, thanks!
> 
> Cheers,
> 
> Tim.


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Tim Deegan

2011-Nov-10 10:11 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

At 09:58 +0000 on 10 Nov (1320919091), Ian Campbell
wrote:> > Yep.  Might be worth mentioning that HAP is called EPT and NPT (or
RVI)
> > by the hardware vendors.
> 
> Good idea. Since I had to look them up:
> EPT -- Extended Page Tables (Intel)
> NPT -- Nested Page Tables (AMD)
> RVI -- Rapid Virtualisation Indexing (vmware''s name, I think?)
RVI is AMD''s marketing name for NPT, I think, but it never made it into
the technical manuals.  

VMware doesn''t really have a generic name for HAP; they call it
''hardware MMU'' in some docs but EPT/RVI in their UI. 
Microsoft calls it
SLAT (?!) for Second-Level Address Translation.

Tim.

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 10:13 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

On Thu, 2011-11-10 at 10:11 +0000, Tim Deegan wrote:> At 09:58 +0000 on 10 Nov (1320919091), Ian Campbell wrote:
> > > Yep.  Might be worth mentioning that HAP is called EPT and NPT
(or RVI)
> > > by the hardware vendors.
> > 
> > Good idea. Since I had to look them up:
> > EPT -- Extended Page Tables (Intel)
> > NPT -- Nested Page Tables (AMD)
> > RVI -- Rapid Virtualisation Indexing (vmware''s name, I
think?)
> 
> RVI is AMD''s marketing name for NPT, I think, but it never made it
into
> the technical manuals.  
Thanks, Google spat out some vmware docs as the first hit. I''ll include
both names.
> VMware doesn''t really have a generic name for HAP; they call it
> ''hardware MMU'' in some docs but EPT/RVI in their UI. 
Microsoft calls it
> SLAT (?!) for Second-Level Address Translation.
Nice.

Ian.



_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Stefano Stabellini

2011-Nov-10 11:37 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Mon, 7 Nov 2011, Ian Campbell wrote:> # HG changeset patch
> # User Ian Campbell <ian.campbell@citrix.com>
> # Date 1320678758 0
> # Node ID 291f6cb0d03e56e4edbe53c640c96dff85d9bf08
> # Parent  705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb
> docs: add a document describing the xl cfg file syntax
> 
> Based on an initial version by Ian Jackson.
> 
> I believe that all keys are now present in the document although there are
are
> various omissions in the actual documentation of them. Hopefully however
this
> covers the majority of the most interesting keys.
I think it would be very useful as a manpage.
If we really want to keep it in markdown rather than pod, we could still
find a way to convert it into a manpage (using ronn, pandoc, etc.).

> Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
> 
> diff -r 705b2e659ff8 -r 291f6cb0d03e docs/Makefile
> --- a/docs/Makefile     Mon Nov 07 15:12:08 2011 +0000
> +++ b/docs/Makefile     Mon Nov 07 15:12:38 2011 +0000
> @@ -11,7 +11,7 @@ DOC_MAN1SRC   := $(wildcard man/*.pod.1)
>  DOC_MAN1       := $(patsubst man/%.pod.1,man1/%.1,$(DOC_MAN1SRC))
>  DOC_MAN5       := $(patsubst man/%.pod.5,man5/%.5,$(DOC_MAN5SRC))
>  DOC_TEX                := src/user.tex src/interface.tex
> -DOC_MARKDOWN   := $(wildcard misc/*.markdown)
> +DOC_MARKDOWN   := $(wildcard misc/*.markdown) $(wildcard user/*.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)) \
> diff -r 705b2e659ff8 -r 291f6cb0d03e docs/user/xl-domain-config.markdown
> --- /dev/null   Thu Jan 01 00:00:00 1970 +0000
> +++ b/docs/user/xl-domain-config.markdown       Mon Nov 07 15:12:38 2011
+0000
> @@ -0,0 +1,554 @@
> + # xl Domain Configuration
> +
> +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.
> +
> +## Work In Progress
> +
> +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 [xen-devel][] mailing list. Please see
> +[SubmittingXenPatches][] wiki page for information on how to submit a
> +patch to Xen.
> +
> +[xen-devel]: mailto:xen-devel@lists.xensource.com
> +[SubmittingXenPatches]: http://wiki.xen.org/xenwiki/SubmittingXenPatches
> +
> +----------------------------------------
> +
> +## Syntax
> +
> +A domain config file consists of a series of `KEY=VALUE` pairs.
> +
> +Some `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 `VALUE` is one of:
> +
> + * `"STRING"`: A string, surrounded by either single or double
quotes.
> + * `NUMBER`: A number, in either decimal, octal (using a `0 prefix`)
> +   or hexadecimal (using an `0x` prefix`).
> + * `BOOLEAN`: A `NUMBER` interpreted as `False` (`0`) or `True` (any
> +   other value).
> + * `[ VALUE, VALUE, ... ]`: A list of `VALUES` of the above
> +   types. Lists are homogeneous and are not nested.
> +
> +The semantics of each `KEY` defines which form of `VALUE` is required.
> +
> +----------------------------------------
> +
> +## Mandatory Configuration Items
> +
> +The following key is mandatory for any guest type:
> +
> + * `name="NAME"`: Specifies the name of the domain.  Names of
domains
> +   existing on a single host must be unique.
> +
> +## Selecting Guest Type
> +
> + * `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.
I think builder=[hvm|pv] would make it clearer what the options are. I
know that the idea is that a pv guest doesn''t need this key pair but I
think that as it is can be confusing.

[...]
> +
> +## Devices
> +
> +The following options define the paravirtual, emulated and physical
> +devices which the guest will contain.
> +
> + * `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 `docs/misc/xl-disk-configuration.txt`.
> +
> + * `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
> +   `docs/misc/xl-network-configuration.markdown`.
> +
> + * `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 "Emulated VGA Graphics Device" below for
how
> +   to configure the emulated device.
and it is only relevant for PV guests.

[...]
> + * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter) should
> +   be provided to the guest.  XXX ???
see docs/misc/tscmode.txt


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-10 11:42 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Thu, 2011-11-10 at 11:37 +0000, Stefano Stabellini
wrote:> On Mon, 7 Nov 2011, Ian Campbell wrote:
> > # HG changeset patch
> > # User Ian Campbell <ian.campbell@citrix.com>
> > # Date 1320678758 0
> > # Node ID 291f6cb0d03e56e4edbe53c640c96dff85d9bf08
> > # Parent  705b2e659ff885379fb8b1c4aefbecfb3b8cc1eb
> > docs: add a document describing the xl cfg file syntax
> > 
> > Based on an initial version by Ian Jackson.
> > 
> > I believe that all keys are now present in the document although there
are are
> > various omissions in the actual documentation of them. Hopefully
however this
> > covers the majority of the most interesting keys.
> 
> I think it would be very useful as a manpage.
> If we really want to keep it in markdown rather than pod, we could still
> find a way to convert it into a manpage (using ronn, pandoc, etc.).
If there is a good markdown->man converter I''m all for using it.

> > +## Selecting Guest Type
> > +
> > + * `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.
> 
> I think builder=[hvm|pv] would make it clearer what the options are. I
> know that the idea is that a pv guest doesn''t need this key pair
but I
> think that as it is can be confusing.
I remember thinking that too, I wonder why I didn''t actually make the
change. I will do so now.
> 
> [...]
> 
> > +
> > +## Devices
> > +
> > +The following options define the paravirtual, emulated and physical
> > +devices which the guest will contain.
> > +
> > + * `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 `docs/misc/xl-disk-configuration.txt`.
> > +
> > + * `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
> > +   `docs/misc/xl-network-configuration.markdown`.
> > +
> > + * `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 "Emulated VGA Graphics Device"
below for how
> > +   to configure the emulated device.
> 
> and it is only relevant for PV guests.
Really, I thought that it was possible for a PVHVM to have a PV FB too?
Perhaps only in theory?
> 
> [...]
> 
> > + * `tsc_mode=VALUE`: Specifies how the TSC (Time Stamp Counter)
should
> > +   be provided to the guest.  XXX ???
> 
> see docs/misc/tscmode.txt
I just posted a patch to update this section. I hadn''t noticed this doc
so the snarky comment in that patch now seems a little unwarranted...

Ian.
> 


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Stefano Stabellini

2011-Nov-10 11:46 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Thu, 10 Nov 2011, Ian Campbell wrote:> > I think it would be very useful as a manpage.
> > If we really want to keep it in markdown rather than pod, we could
still
> > find a way to convert it into a manpage (using ronn, pandoc, etc.).
> 
> If there is a good markdown->man converter I''m all for using
it.
well, I am not sure if any of them are good, but a badly formatted
manpage is still better than no manpage at all

> > > +
> > > +## Devices
> > > +
> > > +The following options define the paravirtual, emulated and
physical
> > > +devices which the guest will contain.
> > > +
> > > + * `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 `docs/misc/xl-disk-configuration.txt`.
> > > +
> > > + * `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
> > > +   `docs/misc/xl-network-configuration.markdown`.
> > > +
> > > + * `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 "Emulated VGA Graphics Device"
below for how
> > > +   to configure the emulated device.
> > 
> > and it is only relevant for PV guests.
> 
> Really, I thought that it was possible for a PVHVM to have a PV FB too?
> Perhaps only in theory?
Only in theory, there is no support for it at the moment and I don''t
think there will be anytime soon.


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Stefano Stabellini

2011-Nov-10 12:23 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Thu, 10 Nov 2011, Stefano Stabellini wrote:> On Thu, 10 Nov 2011, Ian Campbell wrote:
> > > I think it would be very useful as a manpage.
> > > If we really want to keep it in markdown rather than pod, we
could still
> > > find a way to convert it into a manpage (using ronn, pandoc,
etc.).
> > 
> > If there is a good markdown->man converter I''m all for
using it.
> 
> well, I am not sure if any of them are good, but a badly formatted
> manpage is still better than no manpage at all
I take it back: manpages generated by pandoc are unreadble but ronn
seems to work pretty well

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ian Campbell

2011-Nov-11 13:06 UTC

head link

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

On Thu, 2011-11-10 at 12:23 +0000, Stefano Stabellini
wrote:> On Thu, 10 Nov 2011, Stefano Stabellini wrote:
> > On Thu, 10 Nov 2011, Ian Campbell wrote:
> > > > I think it would be very useful as a manpage.
> > > > If we really want to keep it in markdown rather than pod, we
could still
> > > > find a way to convert it into a manpage (using ronn, pandoc,
etc.).
> > > 
> > > If there is a good markdown->man converter I''m all
for using it.
> > 
> > well, I am not sure if any of them are good, but a badly formatted
> > manpage is still better than no manpage at all
> 
> I take it back: manpages generated by pandoc are unreadble but ronn
> seems to work pretty well
Not widely available though :-(

I can reformat as pod but I''d like to hear from IanJ first since this
is
based on his first draft which was in markdown.

Ian.


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Xen devel - Nov 2011 - [PATCH 0 of 7] xl domain config file documentation & other bits

[Xen-devel] [PATCH 0 of 7] xl domain config file documentation & other bits

[Xen-devel] [PATCH 1 of 7] docs: report when we don''t build docs due to a missing tool

[Xen-devel] [PATCH 2 of 7] README: add markdown to dependency list

[Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

[Xen-devel] [PATCH 4 of 7] docs: fix references from xl man page to xldomain.cfg manpage

[Xen-devel] [PATCH 5 of 7] docs: install html and txt versions of manpages

[Xen-devel] [PATCH 6 of 7] xl: the name field in a guest config file is mandatory

[Xen-devel] [PATCH 7 of 7] docs: generate docs direct into final filename

[Xen-devel] [PATCH] docs: xlexample.hvm is missing "builder = ''hvm''"

[Xen-devel] [PATCH] docs: xlexample.*: reference xl-domain-config document

Re: [Xen-devel] [PATCH 0 of 7] xl domain config file documentation & other bits

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

[Xen-devel] [PATCH] docs: add spice options to xl domain cfg document

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax\

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax

Re: [Xen-devel] [PATCH 3 of 7] docs: add a document describing the xl cfg file syntax