dist/*
docs/tmp.*
docs/html/
-docs/man/xl.cfg.pod.5
-docs/man/xl.pod.1
+docs/man/xl.cfg.5.pod
+docs/man/xl.1.pod
docs/man1/
docs/man5/
docs/man7/
DATE := $(shell date +%Y-%m-%d)
DOC_ARCHES := arm x86_32 x86_64
+MAN_SECTIONS := 1 5 7 8
# Documentation sources to build
-MAN1SRC-y := $(sort $(wildcard man/*.pod.1 man/*.markdown.1))
-MAN5SRC-y := $(sort $(wildcard man/*.pod.5 man/*.markdown.5))
-MAN7SRC-y := $(sort $(wildcard man/*.pod.7 man/*.markdown.7))
-MAN8SRC-y := $(sort $(wildcard man/*.pod.8 man/*.markdown.8))
+MAN-SRC-y := $(sort $(basename $(wildcard man/*.pod man/*.pandoc)))
MARKDOWNSRC-y := $(sort $(shell find misc -name '*.markdown' -print))
PANDOCSRC-y := $(sort $(shell find designs/ features/ misc/ process/ specs/ -name '*.pandoc' -print))
# Documentation targets
-DOC_MAN1 := $(patsubst man/%.pod.1,man1/%.1,$(MAN1SRC-y)) \
- $(patsubst man/%.markdown.1,man1/%.1,$(MAN1SRC-y))
-DOC_MAN5 := $(patsubst man/%.pod.5,man5/%.5,$(MAN5SRC-y)) \
- $(patsubst man/%.markdown.5,man5/%.5,$(MAN5SRC-y))
-DOC_MAN7 := $(patsubst man/%.pod.7,man7/%.7,$(MAN7SRC-y)) \
- $(patsubst man/%.markdown.7,man7/%.7,$(MAN7SRC-y))
-DOC_MAN8 := $(patsubst man/%.pod.8,man8/%.8,$(MAN8SRC-y)) \
- $(patsubst man/%.markdown.8,man8/%.8,$(MAN8SRC-y))
+$(foreach i,$(MAN_SECTIONS), \
+ $(eval DOC_MAN$(i) := $(patsubst man/%.$(i),man$(i)/%.$(i), \
+ $(filter %.$(i),$(MAN-SRC-y)))))
+
DOC_HTML := html/SUPPORT.html \
$(patsubst %.markdown,html/%.html,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,html/%.html,$(PANDOCSRC-y)) \
- $(patsubst man/%.markdown.1,html/man/%.1.html,$(MAN1SRC-y)) \
- $(patsubst man/%.markdown.5,html/man/%.5.html,$(MAN5SRC-y)) \
- $(patsubst man/%.markdown.7,html/man/%.7.html,$(MAN7SRC-y)) \
- $(patsubst man/%.markdown.8,html/man/%.8.html,$(MAN8SRC-y)) \
- $(patsubst man/%.pod.1,html/man/%.1.html,$(MAN1SRC-y)) \
- $(patsubst man/%.pod.5,html/man/%.5.html,$(MAN5SRC-y)) \
- $(patsubst man/%.pod.7,html/man/%.7.html,$(MAN7SRC-y)) \
- $(patsubst man/%.pod.8,html/man/%.8.html,$(MAN8SRC-y)) \
+ $(patsubst %,html/%.html,$(MAN-SRC-y)) \
$(patsubst %.txt,html/%.txt,$(TXTSRC-y)) \
$(patsubst %,html/hypercall/%/index.html,$(DOC_ARCHES))
DOC_TXT := $(patsubst %.txt,txt/%.txt,$(TXTSRC-y)) \
$(patsubst %.markdown,txt/%.txt,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,txt/%.txt,$(PANDOCSRC-y)) \
- $(patsubst man/%.markdown.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
- $(patsubst man/%.markdown.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
- $(patsubst man/%.markdown.7,txt/man/%.7.txt,$(MAN7SRC-y)) \
- $(patsubst man/%.markdown.8,txt/man/%.8.txt,$(MAN8SRC-y)) \
- $(patsubst man/%.pod.1,txt/man/%.1.txt,$(MAN1SRC-y)) \
- $(patsubst man/%.pod.5,txt/man/%.5.txt,$(MAN5SRC-y)) \
- $(patsubst man/%.pod.7,txt/man/%.7.txt,$(MAN7SRC-y)) \
- $(patsubst man/%.pod.8,txt/man/%.8.txt,$(MAN8SRC-y))
+ $(patsubst %,txt/%.txt,$(MAN-SRC-y))
DOC_PDF := $(patsubst %.markdown,pdf/%.pdf,$(MARKDOWNSRC-y)) \
$(patsubst %.pandoc,pdf/%.pdf,$(PANDOCSRC-y))
define GENERATE_MANPAGE_RULES
# Real manpages
-man$(1)/%.$(1): man/%.pod.$(1) Makefile
+man$(1)/%.$(1): man/%.$(1).pod Makefile
ifneq ($(POD2MAN),)
@$(INSTALL_DIR) $$(@D)
$(POD2MAN) --release=$(VERSION) --name=$$* -s $(1) -c "Xen" $$< $$@
@echo "pod2man not installed; skipping $$@"
endif
-man$(1)/%.$(1): man/%.markdown.$(1) Makefile
+man$(1)/%.$(1): man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone -V title=$$* -V section=$(1) \
endif
# HTML manpages
-html/man/%.$(1).html: man/%.pod.$(1) Makefile
+html/man/%.$(1).html: man/%.$(1).pod Makefile
ifneq ($(POD2HTML),)
@$(INSTALL_DIR) $$(@D)
$(POD2HTML) --infile=$$< --outfile=$$@
@echo "pod2html not installed; skipping $$@"
endif
-html/man/%.$(1).html: man/%.markdown.$(1) Makefile
+html/man/%.$(1).html: man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone $$< -t html --toc --output $$@
endif
# Text manpages
-txt/man/%.$(1).txt: man/%.pod.$(1) Makefile
+txt/man/%.$(1).txt: man/%.$(1).pod Makefile
ifneq ($(POD2TEXT),)
@$(INSTALL_DIR) $$(@D)
$(POD2TEXT) $$< $$@
@echo "pod2text not installed; skipping $$@"
endif
-txt/man/%.$(1).txt: man/%.markdown.$(1) Makefile
+txt/man/%.$(1).txt: man/%.$(1).pandoc Makefile
ifneq ($(PANDOC),)
@$(INSTALL_DIR) $$(@D)
$(PANDOC) --standalone $$< -t plain --output $$@
# Uninstall
.PHONY: uninstall-man$(1)-pages
uninstall-man$(1)-pages:
- rm -f $(addprefix $(DESTDIR)$(mandir)/man$(1)/, $(filter-out %.pod.$(1) %.markdown.$(1), $(notdir $(DOC_MAN$(1)))))
+ rm -f $(addprefix $(DESTDIR)$(mandir)/,$(DOC_MAN$(1)))
# Link buld/install/clean to toplevel rules
man-pages: man$(1)-pages
endef
# Generate manpage rules for each section
-$(foreach i,1 5 7 8,$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
+$(foreach i,$(MAN_SECTIONS),$(eval $(call GENERATE_MANPAGE_RULES,$(i))))
.PHONY: install-html
install-html: html txt figs
-ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.pod.5 man/xl.pod.1"
+ac_config_files="$ac_config_files ../config/Docs.mk man/xl.cfg.5.pod man/xl.1.pod"
ac_aux_dir=
for ac_dir in ../ "$srcdir"/../; do
do
case $ac_config_target in
"../config/Docs.mk") CONFIG_FILES="$CONFIG_FILES ../config/Docs.mk" ;;
- "man/xl.cfg.pod.5") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.pod.5" ;;
- "man/xl.pod.1") CONFIG_FILES="$CONFIG_FILES man/xl.pod.1" ;;
+ "man/xl.cfg.5.pod") CONFIG_FILES="$CONFIG_FILES man/xl.cfg.5.pod" ;;
+ "man/xl.1.pod") CONFIG_FILES="$CONFIG_FILES man/xl.1.pod" ;;
*) as_fn_error $? "invalid argument: \`$ac_config_target'" "$LINENO" 5;;
esac
AC_CONFIG_SRCDIR([misc/xen-command-line.markdown])
AC_CONFIG_FILES([
../config/Docs.mk
-man/xl.cfg.pod.5
-man/xl.pod.1
+man/xl.cfg.5.pod
+man/xl.1.pod
])
AC_CONFIG_AUX_DIR([../])
--- /dev/null
+=head1 NAME
+
+xen-pci-device-reservations - Xen PCI device ID registry
+
+=head1 Description
+
+PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to
+advertise certain virtual hardware to guest virtual machines. The primary
+use of this is with device ID 0x0001 to advertise 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.
+
+Some Xen vendors wish to provide alternative and/or additional guest drivers
+that can bind to virtual devices[1]. This may be done using the Xen PCI
+vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file
+records reservations made within the device ID range in order to avoid
+multiple Xen vendors using conflicting IDs.
+
+=head1 Guidelines
+
+=over 4
+
+=item 1. A vendor may request a range of device IDs by submitting a patch to
+ this file.
+
+=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the
+ possibility of clashes with community IDs assigned from the bottom up.
+
+=item 3. The vendor is responsible for allocations within the range and should
+ try to record specific device IDs in PCI ID databases such as
+ http://pciids.sourceforge.net and http//www.pcidatabase.com
+
+=back
+
+=head1 Reservations
+
+ range | vendor/product
+ --------------+--------------------------------------------------------------
+ 0x0001 | (Xen Platform PCI device)
+ 0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1)
+ 0xc000-0xc0ff | Citrix XenServer
+ 0xc100-0xc1ff | Citrix XenClient
+ 0xc200-0xc2ff | XCP-ng Project (https://xcp-ng.org)
+
+=head1 Notes
+
+=over 4
+
+=item 1.
+
+Upstream QEMU provides a parameterized device called xen-pvdevice that
+can be used to host guest drivers. Execute:
+
+ qemu-system-i386 -device xen-pvdevice,help
+
+for a list of all parameters. The following parameters are relevant to
+driver binding:
+
+=over 4
+
+=item vendor-id (default 0x5853)
+
+The PCI vendor ID and subsystem vendor ID of the device.
+
+=item device-id (must be specified)
+
+The PCI device ID and subsystem device ID of the device.
+
+=item revision (default 0x01)
+
+The PCI revision of the device
+
+=back
+
+Also the size parameter (default 0x400000) can be used to specify the
+size of the single MMIO BAR that the device exposes. This area may be
+used by drivers for mapping grant tables, etc.
+
+Note that the presence of the Xen Platform PCI device is generally a
+pre-requisite for an additional xen-pvdevice as it is the platform
+device that provides that IO ports necessary for unplugging emulated
+devices. See hvm-emulated-unplug.markdown for details of the IO ports
+and unplug protocol.
+
+libxl provides support for creation of a single additional xen-pvdevice.
+See the vendor_device parameter in xl.cfg(5).
+
+=back
+++ /dev/null
-=head1 NAME
-
-xen-pci-device-reservations - Xen PCI device ID registry
-
-=head1 Description
-
-PCI vendor ID 0x5853 has been reserved for use by Xen systems in order to
-advertise certain virtual hardware to guest virtual machines. The primary
-use of this is with device ID 0x0001 to advertise 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.
-
-Some Xen vendors wish to provide alternative and/or additional guest drivers
-that can bind to virtual devices[1]. This may be done using the Xen PCI
-vendor ID of 0x5853 and Xen-vendor/device specific PCI device IDs. This file
-records reservations made within the device ID range in order to avoid
-multiple Xen vendors using conflicting IDs.
-
-=head1 Guidelines
-
-=over 4
-
-=item 1. A vendor may request a range of device IDs by submitting a patch to
- this file.
-
-=item 2. Vendor allocations should be in the range 0xc000-0xfffe to reduce the
- possibility of clashes with community IDs assigned from the bottom up.
-
-=item 3. The vendor is responsible for allocations within the range and should
- try to record specific device IDs in PCI ID databases such as
- http://pciids.sourceforge.net and http//www.pcidatabase.com
-
-=back
-
-=head1 Reservations
-
- range | vendor/product
- --------------+--------------------------------------------------------------
- 0x0001 | (Xen Platform PCI device)
- 0x0002 | Citrix XenServer (grandfathered allocation for XenServer 6.1)
- 0xc000-0xc0ff | Citrix XenServer
- 0xc100-0xc1ff | Citrix XenClient
- 0xc200-0xc2ff | XCP-ng Project (https://xcp-ng.org)
-
-=head1 Notes
-
-=over 4
-
-=item 1.
-
-Upstream QEMU provides a parameterized device called xen-pvdevice that
-can be used to host guest drivers. Execute:
-
- qemu-system-i386 -device xen-pvdevice,help
-
-for a list of all parameters. The following parameters are relevant to
-driver binding:
-
-=over 4
-
-=item vendor-id (default 0x5853)
-
-The PCI vendor ID and subsystem vendor ID of the device.
-
-=item device-id (must be specified)
-
-The PCI device ID and subsystem device ID of the device.
-
-=item revision (default 0x01)
-
-The PCI revision of the device
-
-=back
-
-Also the size parameter (default 0x400000) can be used to specify the
-size of the single MMIO BAR that the device exposes. This area may be
-used by drivers for mapping grant tables, etc.
-
-Note that the presence of the Xen Platform PCI device is generally a
-pre-requisite for an additional xen-pvdevice as it is the platform
-device that provides that IO ports necessary for unplugging emulated
-devices. See hvm-emulated-unplug.markdown for details of the IO ports
-and unplug protocol.
-
-libxl provides support for creation of a single additional xen-pvdevice.
-See the vendor_device parameter in xl.cfg(5).
-
-=back
--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+xen-pv-channel - Xen PV Channels
+
+=head1 DESCRIPTION
+
+A channel is a low-bandwidth private byte stream similar to a serial
+link. Typical uses of channels are
+
+=over
+
+=item 1.
+
+to provide initial configuration information to a VM on boot
+(example use: CloudStack's cloud-early-config service)
+
+
+=item 2.
+
+to signal/query an in-guest agent
+(example use: oVirt's guest agent)
+
+
+=back
+
+Channels are similar to virtio-serial devices and emulated serial links.
+Channels are intended to be used in the implementation of libvirt s
+when running on Xen.
+
+Note: if an application requires a high-bandwidth link then it should use
+vchan instead.
+
+
+=head2 How to use channels: an example
+
+Consider a cloud deployment where VMs are cloned from pre-made templates,
+and customised on first boot by an in-guest agent which sets the IP address,
+hostname, ssh keys etc. To install the system the cloud administrator would
+first:
+
+=over
+
+=item 1.
+
+Install a guest as normal (no channel configuration necessary)
+
+
+=item 2.
+
+Install the in-guest agent specific to the cloud software. This will
+prepare the guest to communicate over the channel, and also prepare
+the guest to be cloned safely (sometimes known as "sysprepping")
+
+
+=item 3.
+
+Shutdown the guest
+
+
+=item 4.
+
+Register the guest as a template with the cloud orchestration software
+
+
+=item 5.
+
+Install the cloud orchestration agent in dom0
+
+
+=back
+
+At runtime, when a cloud tenant requests that a VM is created from the template,
+the sequence of events would be: (assuming a Linux domU)
+
+=over
+
+=item 1.
+
+A VM is "cloned" from the template
+
+
+=item 2.
+
+A unique Unix domain socket path in dom0 is allocated
+(e.g. /my/cloud/software/talk/to/domain/)
+
+
+=item 3.
+
+Domain configuration is created for the VM, listing the channel
+name expected by the in-guest agent. In xl syntax this would be:
+
+channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ]
+
+=item 4.
+
+The VM is started
+
+
+=item 5.
+
+In dom0 the cloud orchestration agent connects to the Unix domain
+socket, writes a handshake message and waits for a reply
+
+
+=item 6.
+
+Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console
+driver will generate a hotplug event
+
+
+=item 7.
+
+A udev rule is activated by the hotplug event.
+
+The udev rule would look something like:
+
+SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup"
+
+where the "xen-console-setup" script would read the channel name and
+make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1
+pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]".
+In other words, "/devices/console-2" maps to /dev/hvc2.
+
+
+=item 8.
+
+The in-guest agent uses inotify to see the creation of the /dev/xen-channel
+symlink and opens the device.
+
+
+=item 9.
+
+The in-guest agent completes the handshake with the dom0 agent
+
+
+=item 10.
+
+The dom0 agent transmits the unique VM configuration: hostname, IP
+address, ssh keys etc etc
+
+
+=item 11.
+
+The in-guest agent receives the configuration and applies it.
+
+
+=back
+
+Using channels avoids having to use a temporary disk device or network
+connection.
+
+
+=head2 Design recommendations and pitfalls
+
+It's necessary to install channel-specific software (an "agent") into the guest
+before you can use a channel. By default a channel will appear as a device
+which could be mistaken for a serial port or regular console. It is known
+that some software will proactively seek out serial ports and issue AT commands
+at them; make sure such software is disabled!
+
+Since channels are identified by names, application authors must ensure their
+channel names are unique to avoid clashes. We recommend that channel names
+include parts unique to the application such as a domain names. To assist
+prevent clashes we recommend authors add their names to our global channel
+registry at the end of this document.
+
+
+=head2 Limitations
+
+Hotplug and unplug of channels is not currently implemented.
+
+
+=head2 Channel name registry
+
+It is important that channel names are globally unique. To help ensure
+that no-one's name clashes with yours, please add yours to this list.
+
+ Key:
+ N: Name
+ C: Contact
+ D: Short description of use, possibly including a URL to your software or API
+
+ N: org.xenproject.guest.clipboard.0.1
+ C: David Scott <dave.scott@citrix.com>
+ D: Share clipboard data via an in-guest agent. See:
+ http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
+++ /dev/null
-=encoding utf8
-
-=head1 NAME
-
-xen-pv-channel - Xen PV Channels
-
-=head1 DESCRIPTION
-
-A channel is a low-bandwidth private byte stream similar to a serial
-link. Typical uses of channels are
-
-=over
-
-=item 1.
-
-to provide initial configuration information to a VM on boot
-(example use: CloudStack's cloud-early-config service)
-
-
-=item 2.
-
-to signal/query an in-guest agent
-(example use: oVirt's guest agent)
-
-
-=back
-
-Channels are similar to virtio-serial devices and emulated serial links.
-Channels are intended to be used in the implementation of libvirt s
-when running on Xen.
-
-Note: if an application requires a high-bandwidth link then it should use
-vchan instead.
-
-
-=head2 How to use channels: an example
-
-Consider a cloud deployment where VMs are cloned from pre-made templates,
-and customised on first boot by an in-guest agent which sets the IP address,
-hostname, ssh keys etc. To install the system the cloud administrator would
-first:
-
-=over
-
-=item 1.
-
-Install a guest as normal (no channel configuration necessary)
-
-
-=item 2.
-
-Install the in-guest agent specific to the cloud software. This will
-prepare the guest to communicate over the channel, and also prepare
-the guest to be cloned safely (sometimes known as "sysprepping")
-
-
-=item 3.
-
-Shutdown the guest
-
-
-=item 4.
-
-Register the guest as a template with the cloud orchestration software
-
-
-=item 5.
-
-Install the cloud orchestration agent in dom0
-
-
-=back
-
-At runtime, when a cloud tenant requests that a VM is created from the template,
-the sequence of events would be: (assuming a Linux domU)
-
-=over
-
-=item 1.
-
-A VM is "cloned" from the template
-
-
-=item 2.
-
-A unique Unix domain socket path in dom0 is allocated
-(e.g. /my/cloud/software/talk/to/domain/)
-
-
-=item 3.
-
-Domain configuration is created for the VM, listing the channel
-name expected by the in-guest agent. In xl syntax this would be:
-
-channel = [ "connection=socket, name=org.my.cloud.software.agent.version1, path = /my/cloud/software/talk/to/domain/" ]
-
-=item 4.
-
-The VM is started
-
-
-=item 5.
-
-In dom0 the cloud orchestration agent connects to the Unix domain
-socket, writes a handshake message and waits for a reply
-
-
-=item 6.
-
-Assuming the guest kernel has CONFIG_HVC_XEN_FRONTEND set then the console
-driver will generate a hotplug event
-
-
-=item 7.
-
-A udev rule is activated by the hotplug event.
-
-The udev rule would look something like:
-
-SUBSYSTEM=="xen", DEVPATH=="/devices/console-[0-9]", RUN+="xen-console-setup"
-
-where the "xen-console-setup" script would read the channel name and
-make a symlink in /dev/xen-channel/org.my.cloud.software.agent.version1
-pointing to /dev/hvcN. N is the same number as the number in "/devices/console-[0-9]".
-In other words, "/devices/console-2" maps to /dev/hvc2.
-
-
-=item 8.
-
-The in-guest agent uses inotify to see the creation of the /dev/xen-channel
-symlink and opens the device.
-
-
-=item 9.
-
-The in-guest agent completes the handshake with the dom0 agent
-
-
-=item 10.
-
-The dom0 agent transmits the unique VM configuration: hostname, IP
-address, ssh keys etc etc
-
-
-=item 11.
-
-The in-guest agent receives the configuration and applies it.
-
-
-=back
-
-Using channels avoids having to use a temporary disk device or network
-connection.
-
-
-=head2 Design recommendations and pitfalls
-
-It's necessary to install channel-specific software (an "agent") into the guest
-before you can use a channel. By default a channel will appear as a device
-which could be mistaken for a serial port or regular console. It is known
-that some software will proactively seek out serial ports and issue AT commands
-at them; make sure such software is disabled!
-
-Since channels are identified by names, application authors must ensure their
-channel names are unique to avoid clashes. We recommend that channel names
-include parts unique to the application such as a domain names. To assist
-prevent clashes we recommend authors add their names to our global channel
-registry at the end of this document.
-
-
-=head2 Limitations
-
-Hotplug and unplug of channels is not currently implemented.
-
-
-=head2 Channel name registry
-
-It is important that channel names are globally unique. To help ensure
-that no-one's name clashes with yours, please add yours to this list.
-
- Key:
- N: Name
- C: Contact
- D: Short description of use, possibly including a URL to your software or API
-
- N: org.xenproject.guest.clipboard.0.1
- C: David Scott <dave.scott@citrix.com>
- D: Share clipboard data via an in-guest agent. See:
- http://wiki.xenproject.org/wiki/Clipboard_sharing_protocol
--- /dev/null
+=head1 NAME
+
+xen-tscmode - Xen TSC (time stamp counter) and timekeeping discussion
+
+=head1 OVERVIEW
+
+As of Xen 4.0, a new config option called tsc_mode may be specified
+for each domain. The default for tsc_mode handles the vast majority
+of hardware and software environments. This document is targeted
+for Xen users and administrators that may need to select a non-default
+tsc_mode.
+
+Proper selection of tsc_mode depends on an understanding not only of
+the guest operating system (OS), but also of the application set that will
+ever run on this guest OS. This is because tsc_mode applies
+equally to both the OS and ALL apps that are running on this
+domain, now or in the future.
+
+Key questions to be answered for the OS and/or each application are:
+
+=over 4
+
+=item *
+
+Does the OS/app use the rdtsc instruction at all?
+(We will explain below how to determine this.)
+
+=item *
+
+At what frequency is the rdtsc instruction executed by either the OS
+or any running apps? If the sum exceeds about 10,000 rdtsc instructions
+per second per processor, we call this a "high-TSC-frequency"
+OS/app/environment. (This is relatively rare, and developers of OS's
+and apps that are high-TSC-frequency are usually aware of it.)
+
+=item *
+
+If the OS/app does use rdtsc, will it behave incorrectly if "time goes
+backwards" or if the frequency of the TSC suddenly changes? If so,
+we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient".
+
+=back
+
+This last is the US$64,000 question as it may be very difficult
+(or, for legacy apps, even impossible) to predict all possible
+failure cases. As a result, unless proven otherwise, any app
+that uses rdtsc must be assumed to be TSC-sensitive and, as we
+will see, this is the default starting in Xen 4.0.
+
+Xen's new tsc_mode parameter determines the circumstances under which
+the family of rdtsc instructions are executed "natively" vs emulated.
+Roughly speaking, native means rdtsc is fast but TSC-sensitive apps
+may, under unpredictable circumstances, run incorrectly; emulated means
+there is some performance degradation (unobservable in most cases),
+but TSC-sensitive apps will always run correctly. Prior to Xen 4.0,
+all rdtsc instructions were native: "fast but potentially incorrect."
+Starting at Xen 4.0, the default is that all rdtsc instructions are
+"correct but potentially slow". The tsc_mode parameter in 4.0 provides
+an intelligent default but allows system administrator's to adjust
+how rdtsc instructions are executed differently for different domains.
+
+The non-default choices for tsc_mode are:
+
+=over 4
+
+=item * B<tsc_mode=1> (always emulate).
+
+All rdtsc instructions are emulated; this is the best choice when
+TSC-sensitive apps are running and it is necessary to understand
+worst-case performance degradation for a specific hardware environment.
+
+=item * B<tsc_mode=2> (never emulate).
+
+This is the same as prior to Xen 4.0 and is the best choice if it
+is certain that all apps running in this VM are TSC-resilient and
+highest performance is required.
+
+=item * B<tsc_mode=3> (PVRDTSCP).
+
+This mode has been removed.
+
+=back
+
+If tsc_mode is left unspecified (or set to B<tsc_mode=0>), a hybrid
+algorithm is utilized to ensure correctness while providing the
+best performance possible given:
+
+=over 4
+
+=item *
+
+the requirement of correctness,
+
+=item *
+
+the underlying hardware, and
+
+=item *
+
+whether or not the VM has been saved/restored/migrated
+
+=back
+
+To understand this in more detail, the rest of this document must
+be read.
+
+=head1 DETERMINING RDTSC FREQUENCY
+
+To determine the frequency of rdtsc instructions that are emulated,
+an "xl" command can be used by a privileged user of domain0. The
+command:
+
+ # xl debug-key s; xl dmesg | tail
+
+provides information about TSC usage in each domain where TSC
+emulation is currently enabled.
+
+=head1 TSC HISTORY
+
+To understand tsc_mode completely, some background on TSC is required:
+
+The x86 "timestamp counter", or TSC, is a 64-bit register on each
+processor that increases monotonically. Historically, TSC incremented
+every processor cycle, but on recent processors, it increases
+at a constant rate even if the processor changes frequency (for example,
+to reduce processor power usage). TSC is known by x86 programmers
+as the fastest, highest-precision measurement of the passage of time
+so it is often used as a foundation for performance monitoring.
+And since it is guaranteed to be monotonically increasing and, at
+64 bits, is guaranteed to not wraparound within 10 years, it is
+sometimes used as a random number or a unique sequence identifier,
+such as to stamp transactions so they can be replayed in a specific
+order.
+
+On most older SMP and early multi-core machines, TSC was not synchronized
+between processors. Thus if an application were to read the TSC on
+one processor, then was moved by the OS to another processor, then read
+TSC again, it might appear that "time went backwards". This loss of
+monotonicity resulted in many obscure application bugs when TSC-sensitive
+apps were ported from a uniprocessor to an SMP environment; as a result,
+many applications -- especially in the Windows world -- removed their
+dependency on TSC and replaced their timestamp needs with OS-specific
+functions, losing both performance and precision. On some more recent
+generations of multi-core machines, especially multi-socket multi-core
+machines, the TSC was synchronized but if one processor were to enter
+certain low-power states, its TSC would stop, destroying the synchrony
+and again causing obscure bugs. This reinforced decisions to avoid use
+of TSC altogether. On the most recent generations of multi-core
+machines, however, synchronization is provided across all processors
+in all power states, even on multi-socket machines, and provide a
+flag that indicates that TSC is synchronized and "invariant". Thus
+TSC is once again useful for applications, and even newer operating
+systems are using and depending upon TSC for critical timekeeping
+tasks when running on these recent machines.
+
+We will refer to hardware that ensures TSC is both synchronized and
+invariant as "TSC-safe" and any hardware on which TSC is not (or
+may not remain) synchronized as "TSC-unsafe".
+
+As a result of TSC's sordid history, two classes of applications use
+TSC: old applications designed for single processors, and the most recent
+enterprise applications which require high-frequency high-precision
+timestamping.
+
+We will refer to apps that might break if running on a TSC-unsafe
+machine as "TSC-sensitive"; apps that don't use TSC, or do use
+TSC but use it in a way that monotonicity and frequency invariance
+are unimportant as "TSC-resilient".
+
+The emergence of virtualization once again complicates the usage of
+TSC. When features such as save/restore or live migration are employed,
+a guest OS and all its currently running applications may be invisibly
+transported to an entirely different physical machine. While TSC
+may be "safe" on one machine, it is essentially impossible to precisely
+synchronize TSC across a data center or even a pool of machines. As
+a result, when run in a virtualized environment, rare and obscure
+"time going backwards" problems might once again occur for those
+TSC-sensitive applications. Worse, if a guest OS moves from, for
+example, a 3GHz
+machine to a 1.5GHz machine, attempts by an OS/app to measure time
+intervals with TSC may without notice be incorrect by a factor of two.
+
+The rdtsc (read timestamp counter) instruction is used to read the
+TSC register. The rdtscp instruction is a variant of rdtsc on recent
+processors. We refer to these together as the rdtsc family of instructions,
+or just "rdtsc". Instructions in the rdtsc family are non-privileged, but
+privileged software may set a cpuid bit to cause all rdtsc family
+instructions to trap. This trap can be detected by Xen, which can
+then transparently "emulate" the results of the rdtsc instruction and
+return control to the code following the rdtsc instruction.
+
+To provide a "safe" TSC, i.e. to ensure both TSC monotonicity and a
+fixed rate, Xen provides rdtsc emulation whenever necessary or when
+explicitly specified by a per-VM configuration option. TSC emulation is
+relatively slow -- roughly 15-20 times slower than the rdtsc instruction
+when executed natively. However, except when an OS or application uses
+the rdtsc instruction at a high frequency (e.g. more than about 10,000 times
+per second per processor), this performance degradation is not noticeable
+(i.e. <0.3%). And, TSC emulation is nearly always faster than
+OS-provided alternatives (e.g. Linux's gettimeofday). For environments
+where it is certain that all apps are TSC-resilient (e.g.
+"TSC-safeness" is not necessary) and highest performance is a
+requirement, TSC emulation may be entirely disabled (tsc_mode==2).
+
+The default mode (tsc_mode==0) checks TSC-safeness of the underlying
+hardware on which the virtual machine is launched. If it is
+TSC-safe, rdtsc will execute at hardware speed; if it is not, rdtsc
+will be emulated. Once a virtual machine is save/restored or migrated,
+however, there are two possibilities: TSC remains native IF the source
+physical machine and target physical machine have the same TSC frequency
+(or, for HVM/PVH guests, if TSC scaling support is available); else TSC
+is emulated. Note that, though emulated, the "apparent" TSC frequency
+will be the TSC frequency of the initial physical machine, even after
+migration.
+
+Finally, tsc_mode==1 always enables TSC emulation, regardless of
+the underlying physical hardware. The "apparent" TSC frequency will
+be the TSC frequency of the initial physical machine, even after migration.
+This mode is useful to measure any performance degradation that
+might be encountered by a tsc_mode==0 domain after migration occurs,
+or a tsc_mode==3 domain when it is running on TSC-unsafe hardware.
+
+Note that while Xen ensures that an emulated TSC is "safe" across migration,
+it does not ensure that it continues to tick at the same rate during
+the actual migration. As an oversimplified example, if TSC is ticking
+once per second in a guest, and the guest is saved when the TSC is 1000,
+then restored 30 seconds later, TSC is only guaranteed to be greater
+than or equal to 1001, not precisely 1030. This has some OS implications
+as will be seen in the next section.
+
+=head1 TSC INVARIANT BIT and NO_MIGRATE
+
+Related to TSC emulation, the "TSC Invariant" bit is architecturally defined
+in a cpuid bit on the most recent x86 processors. If set, TSC invariance
+ensures that the TSC is "safe", that is it will increment at a constant rate
+regardless of power events, will be synchronized across all processors, and
+was properly initialized to zero on all processors at boot-time
+by system hardware/BIOS. As long as system software never writes to TSC,
+TSC will be safe and continuously incremented at a fixed rate and thus
+can be used as a system "clocksource".
+
+This bit is used by some OS's, and specifically by Linux starting with
+version 2.6.30(?), to select TSC as a system clocksource. Once selected,
+TSC remains the Linux system clocksource unless manually overridden. In
+a virtualized environment, since it is not possible to synchronize TSC
+across all the machines in a pool or data center, a migration may "break"
+TSC as a usable clocksource; while time will not go backwards, it may
+not track wallclock time well enough to avoid certain time-sensitive
+consequences. As a result, Xen can only expose the TSC Invariant bit
+to a guest OS if it is certain that the domain will never migrate.
+As of Xen 4.0, the "no_migrate=1" VM configuration option may be specified
+to disable migration. If no_migrate is selected and the VM is running
+on a physical machine with "TSC Invariant", Linux 2.6.30+ will safely
+use TSC as the system clocksource. But, attempts to migrate or, once
+saved, restore this domain will fail.
+
+There is another cpuid-related complication: The x86 cpuid instruction is
+non-privileged. HVM domains are configured to always trap this instruction
+to Xen, where Xen can "filter" the result. In a PV OS, all cpuid instructions
+have been replaced by a paravirtualized equivalent of the cpuid instruction
+("pvcpuid") and also trap to Xen. But apps in a PV guest that use a
+cpuid instruction execute it directly, without a trap to Xen. As a result,
+an app may directly examine the physical TSC Invariant cpuid bit and make
+decisions based on that bit.
+
+=head1 HARDWARE TSC SCALING
+
+Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read
+by guest rdtsc/p increasing in a different frequency than the host
+TSC frequency.
+
+If a HVM container in default TSC mode (tsc_mode=0) is created on a host
+that provides constant TSC, its guest TSC frequency will be the same as
+the host. If it is later migrated to another host that provides constant
+TSC and supports Intel VMX TSC scaling/AMD SVM TSC ratio, its guest TSC
+frequency will be the same before and after migration.
+
+For above HVM container in default TSC mode (tsc_mode=0), if above
+hosts support rdtscp, both guest rdtsc and rdtscp instructions will be
+executed natively before and after migration.
+
+=head1 AUTHORS
+
+Dan Magenheimer <dan.magenheimer@oracle.com>
+++ /dev/null
-=head1 NAME
-
-xen-tscmode - Xen TSC (time stamp counter) and timekeeping discussion
-
-=head1 OVERVIEW
-
-As of Xen 4.0, a new config option called tsc_mode may be specified
-for each domain. The default for tsc_mode handles the vast majority
-of hardware and software environments. This document is targeted
-for Xen users and administrators that may need to select a non-default
-tsc_mode.
-
-Proper selection of tsc_mode depends on an understanding not only of
-the guest operating system (OS), but also of the application set that will
-ever run on this guest OS. This is because tsc_mode applies
-equally to both the OS and ALL apps that are running on this
-domain, now or in the future.
-
-Key questions to be answered for the OS and/or each application are:
-
-=over 4
-
-=item *
-
-Does the OS/app use the rdtsc instruction at all?
-(We will explain below how to determine this.)
-
-=item *
-
-At what frequency is the rdtsc instruction executed by either the OS
-or any running apps? If the sum exceeds about 10,000 rdtsc instructions
-per second per processor, we call this a "high-TSC-frequency"
-OS/app/environment. (This is relatively rare, and developers of OS's
-and apps that are high-TSC-frequency are usually aware of it.)
-
-=item *
-
-If the OS/app does use rdtsc, will it behave incorrectly if "time goes
-backwards" or if the frequency of the TSC suddenly changes? If so,
-we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient".
-
-=back
-
-This last is the US$64,000 question as it may be very difficult
-(or, for legacy apps, even impossible) to predict all possible
-failure cases. As a result, unless proven otherwise, any app
-that uses rdtsc must be assumed to be TSC-sensitive and, as we
-will see, this is the default starting in Xen 4.0.
-
-Xen's new tsc_mode parameter determines the circumstances under which
-the family of rdtsc instructions are executed "natively" vs emulated.
-Roughly speaking, native means rdtsc is fast but TSC-sensitive apps
-may, under unpredictable circumstances, run incorrectly; emulated means
-there is some performance degradation (unobservable in most cases),
-but TSC-sensitive apps will always run correctly. Prior to Xen 4.0,
-all rdtsc instructions were native: "fast but potentially incorrect."
-Starting at Xen 4.0, the default is that all rdtsc instructions are
-"correct but potentially slow". The tsc_mode parameter in 4.0 provides
-an intelligent default but allows system administrator's to adjust
-how rdtsc instructions are executed differently for different domains.
-
-The non-default choices for tsc_mode are:
-
-=over 4
-
-=item * B<tsc_mode=1> (always emulate).
-
-All rdtsc instructions are emulated; this is the best choice when
-TSC-sensitive apps are running and it is necessary to understand
-worst-case performance degradation for a specific hardware environment.
-
-=item * B<tsc_mode=2> (never emulate).
-
-This is the same as prior to Xen 4.0 and is the best choice if it
-is certain that all apps running in this VM are TSC-resilient and
-highest performance is required.
-
-=item * B<tsc_mode=3> (PVRDTSCP).
-
-This mode has been removed.
-
-=back
-
-If tsc_mode is left unspecified (or set to B<tsc_mode=0>), a hybrid
-algorithm is utilized to ensure correctness while providing the
-best performance possible given:
-
-=over 4
-
-=item *
-
-the requirement of correctness,
-
-=item *
-
-the underlying hardware, and
-
-=item *
-
-whether or not the VM has been saved/restored/migrated
-
-=back
-
-To understand this in more detail, the rest of this document must
-be read.
-
-=head1 DETERMINING RDTSC FREQUENCY
-
-To determine the frequency of rdtsc instructions that are emulated,
-an "xl" command can be used by a privileged user of domain0. The
-command:
-
- # xl debug-key s; xl dmesg | tail
-
-provides information about TSC usage in each domain where TSC
-emulation is currently enabled.
-
-=head1 TSC HISTORY
-
-To understand tsc_mode completely, some background on TSC is required:
-
-The x86 "timestamp counter", or TSC, is a 64-bit register on each
-processor that increases monotonically. Historically, TSC incremented
-every processor cycle, but on recent processors, it increases
-at a constant rate even if the processor changes frequency (for example,
-to reduce processor power usage). TSC is known by x86 programmers
-as the fastest, highest-precision measurement of the passage of time
-so it is often used as a foundation for performance monitoring.
-And since it is guaranteed to be monotonically increasing and, at
-64 bits, is guaranteed to not wraparound within 10 years, it is
-sometimes used as a random number or a unique sequence identifier,
-such as to stamp transactions so they can be replayed in a specific
-order.
-
-On most older SMP and early multi-core machines, TSC was not synchronized
-between processors. Thus if an application were to read the TSC on
-one processor, then was moved by the OS to another processor, then read
-TSC again, it might appear that "time went backwards". This loss of
-monotonicity resulted in many obscure application bugs when TSC-sensitive
-apps were ported from a uniprocessor to an SMP environment; as a result,
-many applications -- especially in the Windows world -- removed their
-dependency on TSC and replaced their timestamp needs with OS-specific
-functions, losing both performance and precision. On some more recent
-generations of multi-core machines, especially multi-socket multi-core
-machines, the TSC was synchronized but if one processor were to enter
-certain low-power states, its TSC would stop, destroying the synchrony
-and again causing obscure bugs. This reinforced decisions to avoid use
-of TSC altogether. On the most recent generations of multi-core
-machines, however, synchronization is provided across all processors
-in all power states, even on multi-socket machines, and provide a
-flag that indicates that TSC is synchronized and "invariant". Thus
-TSC is once again useful for applications, and even newer operating
-systems are using and depending upon TSC for critical timekeeping
-tasks when running on these recent machines.
-
-We will refer to hardware that ensures TSC is both synchronized and
-invariant as "TSC-safe" and any hardware on which TSC is not (or
-may not remain) synchronized as "TSC-unsafe".
-
-As a result of TSC's sordid history, two classes of applications use
-TSC: old applications designed for single processors, and the most recent
-enterprise applications which require high-frequency high-precision
-timestamping.
-
-We will refer to apps that might break if running on a TSC-unsafe
-machine as "TSC-sensitive"; apps that don't use TSC, or do use
-TSC but use it in a way that monotonicity and frequency invariance
-are unimportant as "TSC-resilient".
-
-The emergence of virtualization once again complicates the usage of
-TSC. When features such as save/restore or live migration are employed,
-a guest OS and all its currently running applications may be invisibly
-transported to an entirely different physical machine. While TSC
-may be "safe" on one machine, it is essentially impossible to precisely
-synchronize TSC across a data center or even a pool of machines. As
-a result, when run in a virtualized environment, rare and obscure
-"time going backwards" problems might once again occur for those
-TSC-sensitive applications. Worse, if a guest OS moves from, for
-example, a 3GHz
-machine to a 1.5GHz machine, attempts by an OS/app to measure time
-intervals with TSC may without notice be incorrect by a factor of two.
-
-The rdtsc (read timestamp counter) instruction is used to read the
-TSC register. The rdtscp instruction is a variant of rdtsc on recent
-processors. We refer to these together as the rdtsc family of instructions,
-or just "rdtsc". Instructions in the rdtsc family are non-privileged, but
-privileged software may set a cpuid bit to cause all rdtsc family
-instructions to trap. This trap can be detected by Xen, which can
-then transparently "emulate" the results of the rdtsc instruction and
-return control to the code following the rdtsc instruction.
-
-To provide a "safe" TSC, i.e. to ensure both TSC monotonicity and a
-fixed rate, Xen provides rdtsc emulation whenever necessary or when
-explicitly specified by a per-VM configuration option. TSC emulation is
-relatively slow -- roughly 15-20 times slower than the rdtsc instruction
-when executed natively. However, except when an OS or application uses
-the rdtsc instruction at a high frequency (e.g. more than about 10,000 times
-per second per processor), this performance degradation is not noticeable
-(i.e. <0.3%). And, TSC emulation is nearly always faster than
-OS-provided alternatives (e.g. Linux's gettimeofday). For environments
-where it is certain that all apps are TSC-resilient (e.g.
-"TSC-safeness" is not necessary) and highest performance is a
-requirement, TSC emulation may be entirely disabled (tsc_mode==2).
-
-The default mode (tsc_mode==0) checks TSC-safeness of the underlying
-hardware on which the virtual machine is launched. If it is
-TSC-safe, rdtsc will execute at hardware speed; if it is not, rdtsc
-will be emulated. Once a virtual machine is save/restored or migrated,
-however, there are two possibilities: TSC remains native IF the source
-physical machine and target physical machine have the same TSC frequency
-(or, for HVM/PVH guests, if TSC scaling support is available); else TSC
-is emulated. Note that, though emulated, the "apparent" TSC frequency
-will be the TSC frequency of the initial physical machine, even after
-migration.
-
-Finally, tsc_mode==1 always enables TSC emulation, regardless of
-the underlying physical hardware. The "apparent" TSC frequency will
-be the TSC frequency of the initial physical machine, even after migration.
-This mode is useful to measure any performance degradation that
-might be encountered by a tsc_mode==0 domain after migration occurs,
-or a tsc_mode==3 domain when it is running on TSC-unsafe hardware.
-
-Note that while Xen ensures that an emulated TSC is "safe" across migration,
-it does not ensure that it continues to tick at the same rate during
-the actual migration. As an oversimplified example, if TSC is ticking
-once per second in a guest, and the guest is saved when the TSC is 1000,
-then restored 30 seconds later, TSC is only guaranteed to be greater
-than or equal to 1001, not precisely 1030. This has some OS implications
-as will be seen in the next section.
-
-=head1 TSC INVARIANT BIT and NO_MIGRATE
-
-Related to TSC emulation, the "TSC Invariant" bit is architecturally defined
-in a cpuid bit on the most recent x86 processors. If set, TSC invariance
-ensures that the TSC is "safe", that is it will increment at a constant rate
-regardless of power events, will be synchronized across all processors, and
-was properly initialized to zero on all processors at boot-time
-by system hardware/BIOS. As long as system software never writes to TSC,
-TSC will be safe and continuously incremented at a fixed rate and thus
-can be used as a system "clocksource".
-
-This bit is used by some OS's, and specifically by Linux starting with
-version 2.6.30(?), to select TSC as a system clocksource. Once selected,
-TSC remains the Linux system clocksource unless manually overridden. In
-a virtualized environment, since it is not possible to synchronize TSC
-across all the machines in a pool or data center, a migration may "break"
-TSC as a usable clocksource; while time will not go backwards, it may
-not track wallclock time well enough to avoid certain time-sensitive
-consequences. As a result, Xen can only expose the TSC Invariant bit
-to a guest OS if it is certain that the domain will never migrate.
-As of Xen 4.0, the "no_migrate=1" VM configuration option may be specified
-to disable migration. If no_migrate is selected and the VM is running
-on a physical machine with "TSC Invariant", Linux 2.6.30+ will safely
-use TSC as the system clocksource. But, attempts to migrate or, once
-saved, restore this domain will fail.
-
-There is another cpuid-related complication: The x86 cpuid instruction is
-non-privileged. HVM domains are configured to always trap this instruction
-to Xen, where Xen can "filter" the result. In a PV OS, all cpuid instructions
-have been replaced by a paravirtualized equivalent of the cpuid instruction
-("pvcpuid") and also trap to Xen. But apps in a PV guest that use a
-cpuid instruction execute it directly, without a trap to Xen. As a result,
-an app may directly examine the physical TSC Invariant cpuid bit and make
-decisions based on that bit.
-
-=head1 HARDWARE TSC SCALING
-
-Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read
-by guest rdtsc/p increasing in a different frequency than the host
-TSC frequency.
-
-If a HVM container in default TSC mode (tsc_mode=0) is created on a host
-that provides constant TSC, its guest TSC frequency will be the same as
-the host. If it is later migrated to another host that provides constant
-TSC and supports Intel VMX TSC scaling/AMD SVM TSC ratio, its guest TSC
-frequency will be the same before and after migration.
-
-For above HVM container in default TSC mode (tsc_mode=0), if above
-hosts support rdtscp, both guest rdtsc and rdtscp instructions will be
-executed natively before and after migration.
-
-=head1 AUTHORS
-
-Dan Magenheimer <dan.magenheimer@oracle.com>
--- /dev/null
+Xen guest interface
+-------------------
+
+A Xen guest can be provided with block devices. These are always
+provided as Xen VBDs; for HVM guests they may also be provided as
+emulated IDE, AHCI or SCSI disks.
+
+The abstract interface involves specifying, for each block device:
+
+ * Nominal disk type: Xen virtual disk (aka xvd*, the default); SCSI
+ (sd*); IDE or AHCI (hd*).
+
+ For HVM guests, each whole-disk hd* and and sd* device is made
+ available _both_ via emulated IDE resp. SCSI controller, _and_ as a
+ Xen VBD. The HVM guest is entitled to assume that the IDE or SCSI
+ disks available via the emulated IDE controller target the same
+ underlying devices as the corresponding Xen VBD (ie, multipath).
+ In hd* case with hdtype=ahci, disk will be AHCI via emulated
+ ich9 disk controller.
+
+ For PV guests every device is made available to the guest only as a
+ Xen VBD. For these domains the type is advisory, for use by the
+ guest's device naming scheme.
+
+ The Xen interface does not specify what name a device should have
+ in the guest (nor what major/minor device number it should have in
+ the guest, if the guest has such a concept).
+
+ * Disk number, which is a nonnegative integer,
+ conventionally starting at 0 for the first disk.
+
+ * Partition number, which is a nonnegative integer where by
+ convention partition 0 indicates the "whole disk".
+
+ Normally for any disk _either_ partition 0 should be supplied in
+ which case the guest is expected to treat it as they would a native
+ whole disk (for example by putting or expecting a partition table
+ or disk label on it);
+
+ _Or_ only non-0 partitions should be supplied in which case the
+ guest should expect storage management to be done by the host and
+ treat each vbd as it would a partition or slice or LVM volume (for
+ example by putting or expecting a filesystem on it).
+
+ Non-whole disk devices cannot be passed through to HVM guests via
+ the emulated IDE or SCSI controllers.
+
+
+Configuration file syntax
+-------------------------
+
+The config file syntaxes are, for example
+
+ d0 d0p0 xvda Xen virtual disk 0 partition 0 (whole disk)
+ d1p2 xvdb2 Xen virtual disk 1 partition 2
+ d536p37 xvdtq37 Xen virtual disk 536 partition 37
+ sdb3 SCSI disk 1 partition 3
+ hdc2 IDE disk 2 partition 2
+
+The d*p* syntax is not supported by xm/xend.
+
+To cope with guests which predate this specification we preserve the
+existing facility to specify the xenstore numerical value directly by
+putting a single number (hex, decimal or octal) in the domain config
+file instead of the disk identifier; this number is written directly
+to xenstore (after conversion to the canonical decimal format).
+
+
+Concrete encoding in the VBD interface (in xenstore)
+----------------------------------------------------
+
+The information above is encoded in the concrete interface as an
+integer (in a canonical decimal format in xenstore), whose value
+encodes the information above as follows:
+
+ 1 << 28 | disk << 8 | partition xvd, disks or partitions 16 onwards
+ 202 << 8 | disk << 4 | partition xvd, disks and partitions up to 15
+ 8 << 8 | disk << 4 | partition sd, disks and partitions up to 15
+ 3 << 8 | disk << 6 | partition hd, disks 0..1, partitions 0..63
+ 22 << 8 | (disk-2) << 6 | partition hd, disks 2..3, partitions 0..63
+ 2 << 28 onwards reserved for future use
+ other values less than 1 << 28 deprecated / reserved
+
+The 1<<28 format handles disks up to (1<<20)-1 and partitions up to
+255. It will be used only where the 202<<8 format does not have
+enough bits.
+
+Guests MAY support any subset of the formats above except that if they
+support 1<<28 they MUST also support 202<<8. PV-on-HVM drivers MUST
+support at least one of 3<<8 or 8<<8; 3<<8 is recommended.
+
+Some software has used or understood Linux-specific encodings for SCSI
+disks beyond disk 15 partition 15, and IDE disks beyond disk 3
+partition 63. These vbds, and the corresponding encoded integers, are
+deprecated.
+
+Guests SHOULD ignore numbers that they do not understand or
+recognise. They SHOULD check supplied numbers for validity.
+
+
+Notes on Linux as a guest
+-------------------------
+
+Very old Linux guests (PV and PV-on-HVM) are able to "steal" the
+device numbers and names normally used by the IDE and SCSI
+controllers, so that writing "hda1" in the config file results in
+/dev/hda1 in the guest. These systems interpret the xenstore integer
+as
+ major << 8 | minor
+where major and minor are the Linux-specific device numbers. Some old
+configurations may depend on deprecated high-numbered SCSI and IDE
+disks. This does not work in recent versions of Linux.
+
+So for Linux PV guests, users are recommended to supply xvd* devices
+only. Modern PV drivers will map these to identically-named devices
+in the guest.
+
+For Linux HVM guests using PV-on-HVM drivers, users are recommended to
+supply as few hd* devices as possible, and for the rest of the disks,
+to use pure xvd* devices starting at xvde. Modern PV-on-HVM drivers
+will map provided hd* devices to the corresponding /dev/xvd* (for
+example, hda is presented also as /dev/xvda).
+
+Some Linux HVM guests with broken PV-on-HVM drivers do not cope
+properly if both hda and hdc are supplied, nor with both hda and xvda,
+because they directly map the bottom 8 bits of the xenstore integer
+directly to the Linux guest's device number and throw away the rest;
+they can crash due to minor number clashes. With these guests, the
+workaround is not to supply problematic combinations of devices.
+
+
+Other frontend and backend options
+----------------------------------
+
+See xen/include/public/io/blkif.h for the full list of options.
+++ /dev/null
-Xen guest interface
--------------------
-
-A Xen guest can be provided with block devices. These are always
-provided as Xen VBDs; for HVM guests they may also be provided as
-emulated IDE, AHCI or SCSI disks.
-
-The abstract interface involves specifying, for each block device:
-
- * Nominal disk type: Xen virtual disk (aka xvd*, the default); SCSI
- (sd*); IDE or AHCI (hd*).
-
- For HVM guests, each whole-disk hd* and and sd* device is made
- available _both_ via emulated IDE resp. SCSI controller, _and_ as a
- Xen VBD. The HVM guest is entitled to assume that the IDE or SCSI
- disks available via the emulated IDE controller target the same
- underlying devices as the corresponding Xen VBD (ie, multipath).
- In hd* case with hdtype=ahci, disk will be AHCI via emulated
- ich9 disk controller.
-
- For PV guests every device is made available to the guest only as a
- Xen VBD. For these domains the type is advisory, for use by the
- guest's device naming scheme.
-
- The Xen interface does not specify what name a device should have
- in the guest (nor what major/minor device number it should have in
- the guest, if the guest has such a concept).
-
- * Disk number, which is a nonnegative integer,
- conventionally starting at 0 for the first disk.
-
- * Partition number, which is a nonnegative integer where by
- convention partition 0 indicates the "whole disk".
-
- Normally for any disk _either_ partition 0 should be supplied in
- which case the guest is expected to treat it as they would a native
- whole disk (for example by putting or expecting a partition table
- or disk label on it);
-
- _Or_ only non-0 partitions should be supplied in which case the
- guest should expect storage management to be done by the host and
- treat each vbd as it would a partition or slice or LVM volume (for
- example by putting or expecting a filesystem on it).
-
- Non-whole disk devices cannot be passed through to HVM guests via
- the emulated IDE or SCSI controllers.
-
-
-Configuration file syntax
--------------------------
-
-The config file syntaxes are, for example
-
- d0 d0p0 xvda Xen virtual disk 0 partition 0 (whole disk)
- d1p2 xvdb2 Xen virtual disk 1 partition 2
- d536p37 xvdtq37 Xen virtual disk 536 partition 37
- sdb3 SCSI disk 1 partition 3
- hdc2 IDE disk 2 partition 2
-
-The d*p* syntax is not supported by xm/xend.
-
-To cope with guests which predate this specification we preserve the
-existing facility to specify the xenstore numerical value directly by
-putting a single number (hex, decimal or octal) in the domain config
-file instead of the disk identifier; this number is written directly
-to xenstore (after conversion to the canonical decimal format).
-
-
-Concrete encoding in the VBD interface (in xenstore)
-----------------------------------------------------
-
-The information above is encoded in the concrete interface as an
-integer (in a canonical decimal format in xenstore), whose value
-encodes the information above as follows:
-
- 1 << 28 | disk << 8 | partition xvd, disks or partitions 16 onwards
- 202 << 8 | disk << 4 | partition xvd, disks and partitions up to 15
- 8 << 8 | disk << 4 | partition sd, disks and partitions up to 15
- 3 << 8 | disk << 6 | partition hd, disks 0..1, partitions 0..63
- 22 << 8 | (disk-2) << 6 | partition hd, disks 2..3, partitions 0..63
- 2 << 28 onwards reserved for future use
- other values less than 1 << 28 deprecated / reserved
-
-The 1<<28 format handles disks up to (1<<20)-1 and partitions up to
-255. It will be used only where the 202<<8 format does not have
-enough bits.
-
-Guests MAY support any subset of the formats above except that if they
-support 1<<28 they MUST also support 202<<8. PV-on-HVM drivers MUST
-support at least one of 3<<8 or 8<<8; 3<<8 is recommended.
-
-Some software has used or understood Linux-specific encodings for SCSI
-disks beyond disk 15 partition 15, and IDE disks beyond disk 3
-partition 63. These vbds, and the corresponding encoded integers, are
-deprecated.
-
-Guests SHOULD ignore numbers that they do not understand or
-recognise. They SHOULD check supplied numbers for validity.
-
-
-Notes on Linux as a guest
--------------------------
-
-Very old Linux guests (PV and PV-on-HVM) are able to "steal" the
-device numbers and names normally used by the IDE and SCSI
-controllers, so that writing "hda1" in the config file results in
-/dev/hda1 in the guest. These systems interpret the xenstore integer
-as
- major << 8 | minor
-where major and minor are the Linux-specific device numbers. Some old
-configurations may depend on deprecated high-numbered SCSI and IDE
-disks. This does not work in recent versions of Linux.
-
-So for Linux PV guests, users are recommended to supply xvd* devices
-only. Modern PV drivers will map these to identically-named devices
-in the guest.
-
-For Linux HVM guests using PV-on-HVM drivers, users are recommended to
-supply as few hd* devices as possible, and for the rest of the disks,
-to use pure xvd* devices starting at xvde. Modern PV-on-HVM drivers
-will map provided hd* devices to the corresponding /dev/xvd* (for
-example, hda is presented also as /dev/xvda).
-
-Some Linux HVM guests with broken PV-on-HVM drivers do not cope
-properly if both hda and hdc are supplied, nor with both hda and xvda,
-because they directly map the bottom 8 bits of the xenstore integer
-directly to the Linux guest's device number and throw away the rest;
-they can crash due to minor number clashes. With these guests, the
-workaround is not to supply problematic combinations of devices.
-
-
-Other frontend and backend options
-----------------------------------
-
-See xen/include/public/io/blkif.h for the full list of options.
--- /dev/null
+=head1 NAME
+
+xen-vtpm - Xen virtual Trusted Platform Module (vTPM) subsystem
+
+=head1 RUBRIC
+
+Copyright (c) 2010-2012 United States Government, as represented by
+the Secretary of Defense. All rights reserved.
+November 12 2012
+Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
+
+This document describes the virtual Trusted Platform Module (vTPM) subsystem
+for Xen. The reader is assumed to have familiarity with building and installing
+Xen, Linux, and a basic understanding of the TPM and vTPM concepts.
+
+=head1 INTRODUCTION
+
+The goal of this work is to provide a TPM functionality to a virtual guest
+operating system (a DomU). This allows programs to interact with a TPM in a
+virtual system the same way they interact with a TPM on the physical system.
+Each guest gets its own unique, emulated, software TPM. However, each of the
+vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, which
+seals the secrets to the Physical TPM. If the process of creating each of these
+domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the
+chain of trust rooted in the hardware TPM to virtual machines in Xen. Each
+major component of vTPM is implemented as a separate domain, providing secure
+separation guaranteed by the hypervisor. The vTPM domains are implemented in
+mini-os to reduce memory and processor overhead.
+
+This mini-os vTPM subsystem was built on top of the previous vTPM work done by
+IBM and Intel corporation.
+
+=head1 DESIGN OVERVIEW
+
+The architecture of vTPM is described below:
+
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM |
+ +------------------+
+
+=over 4
+
+=item Linux DomU
+
+The Linux based guest that wants to use a vTPM. There many be
+more than one of these.
+
+=item xen-tpmfront.ko
+
+Linux kernel virtual TPM frontend driver. This driver
+provides vTPM access to a para-virtualized Linux based DomU.
+
+=item mini-os/tpmback
+
+Mini-os TPM backend driver. The Linux frontend driver
+connects to this backend driver to facilitate
+communications between the Linux DomU and its vTPM. This
+driver is also used by vtpmmgr-stubdom to communicate with
+vtpm-stubdom.
+
+=item vtpm-stubdom
+
+A mini-os stub domain that implements a vTPM. There is a
+one to one mapping between running vtpm-stubdom instances and
+logical vtpms on the system. The vTPM Platform Configuration
+Registers (PCRs) are all initialized to zero.
+
+=item mini-os/tpmfront
+
+Mini-os TPM frontend driver. The vTPM mini-os domain
+vtpm-stubdom uses this driver to communicate with
+vtpmmgr-stubdom. This driver could also be used separately to
+implement a mini-os domain that wishes to use a vTPM of
+its own.
+
+=item vtpmmgr-stubdom
+
+A mini-os domain that implements the vTPM manager.
+There is only one vTPM manager and it should be running during
+the entire lifetime of the machine. This domain regulates
+access to the physical TPM on the system and secures the
+persistent state of each vTPM.
+
+=item mini-os/tpm_tis
+
+Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+driver. This driver used by vtpmmgr-stubdom to talk directly to
+the hardware TPM. Communication is facilitated by mapping
+hardware memory pages into vtpmmgr-stubdom.
+
+=item Hardware TPM
+
+The physical TPM that is soldered onto the motherboard.
+
+=back
+
+=head1 INSTALLATION
+
+=head2 Prerequisites:
+
+You must have an x86 machine with a TPM on the motherboard. The only extra
+software requirement for compiling vTPM is cmake. You must use libxl to manage
+domains with vTPMs; 'xm' is deprecated and does not support vTPMs.
+
+=head2 Compiling the Xen tree:
+
+Compile and install the Xen tree as usual; be sure that the vTPM domains are
+enabled when you run configure.
+
+=head2 Compiling the LINUX dom0 kernel:
+
+Because the TPM manager uses direct access to the physical TPM, it may interfere
+with access to the TPM by dom0. The simplest solution for this is to prevent
+dom0 from accessing the physical TPM by compiling the kernel without a driver or
+blacklisting the module. If dom0 needs a TPM but does not need to use it during
+the boot process (i.e. it is not using IMA), a virtual TPM can be attached to
+dom0 after the system is booted.
+
+Access to the physical TPM may be required in order to manage the NVRAM or to
+perform other advanced operations where the vTPM is insufficient. In order to
+prevent interference, the TPM Manager and dom0 should use different values for
+the TPM's locality; since Linux always uses locality 0, using locality 2 for the
+TPM Manager is recommended. If both Linux and the TPM Manager attempt to access
+the TPM at the same time, the TPM device will return a busy status; some
+applications will consider this a fatal error instead of retrying the command at
+a later time. If a vTPM gets an error when loading its key, it will currently
+generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM).
+
+
+=head2 Compiling the LINUX domU kernel:
+
+The domU kernel used by domains with vtpms must include the xen-tpmfront.ko
+driver. It can be built directly into the kernel or as a module; however, some
+features such as IMA require the TPM to be built in to the kernel.
+
+ CONFIG_TCG_TPM=y
+ CONFIG_TCG_XEN=y
+
+=head1 VTPM MANAGER SETUP
+
+=head2 Manager disk image setup:
+
+The vTPM Manager requires a disk image to store its encrypted data. The image
+does not require a filesystem and can live anywhere on the host disk. The image
+is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
+but can support more than 20,000 vTPMs.
+
+=head2 Manager config file:
+
+The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
+virtual machine and requires a config file. The manager requires a disk image
+for storage and permission to access the hardware memory pages for the TPM. The
+disk must be presented as "hda", and the TPM memory pages are passed using the
+iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per
+locality) that start at physical address 0xfed40000. By default, the TPM manager
+uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on
+the domain's command line. For full functionality in deep quotes, using
+locality 2 is required to manipulate PCR 20-22.
+
+=head2 Starting and stopping the manager:
+
+The vTPM manager should be started at boot; you may wish to create an init
+script to do this. If a domain builder is used, the TPM Manager should be
+started by the domain builder to minimize the trusted computing base for the
+vTPM manager's secrets.
+
+Once initialization is complete you should see the following:
+
+ INFO[VTPM]: Waiting for commands from vTPM's:
+
+The TPM Manager does not respond to shutdown requests; use the destroy command
+to shut it down.
+
+=head1 VTPM AND LINUX PVM SETUP
+
+=head2 vTPM disk image setup:
+
+The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM,
+etc). The image does not require a filesystem. The image does not need to be
+large; 2 Mb should be sufficient.
+
+=head2 vTPM config file:
+
+The vTPM domain requires a configuration file like any other domain. The vTPM
+requires a disk image for storage and a TPM frontend driver to communicate with
+the manager. You are required to generate a uuid for this vtpm, which is
+specified on the C<vtpm=> line that describes its connection to the vTPM Manager.
+The uuidgen application may be used to generate a uuid, or one from the output
+of the C<manage-vtpmmgr.pl vtpm-add> command may be used to create a vTPM
+belonging to a specific group.
+
+If you wish to clear the vTPM data you can either recreate the disk image or
+change the uuid.
+
+=head2 Linux Guest config file:
+
+The Linux guest config file needs to be modified to include the Linux tpmfront
+driver. Add the following line:
+
+ vtpm=["backend=domu-vtpm"]
+
+Currently only Linux guests are supported (PV or HVM with PV drivers).
+
+While attaching a vTPM after a guest is booted (using xl vtpm-attach) is
+supported, the attached vTPM will not have a record of the boot of the attached
+guest. Furthermore, if the vTPM has been freshly created, a malicious guest
+could then extend any values into PCRs, potentially forging its boot
+configuration. Attaching a vTPM to a running domain should only be used for
+trusted domains or when measurements have already been sent to the vTPM from
+another source.
+
+=head2 Using the vTPM in the guest:
+
+If xen-tpmfront was compiled as a module, it must be loaded it in the guest.
+
+ # modprobe xen-tpmfront
+
+After the Linux domain boots and the xen-tpmfront driver is loaded, you should
+see the following on the vtpm console:
+
+ Info: VTPM attached to Frontend X/Y
+
+You can quickly test the vTPM by using the sysfs interface:
+
+ # cat /sys/devices/vtpm-0/pubek
+ # cat /sys/devices/vtpm-0/pcrs
+
+If you have trousers and tpm_tools installed on the guest, the tpm_version
+command should return the following:
+
+The version command should return the following:
+
+ TPM 1.2 Version Info:
+ Chip Version: 1.2.0.7
+ Spec Level: 2
+ Errata Revision: 1
+ TPM Vendor ID: ETHZ
+ TPM Version: 01010000
+ Manufacturer Info: 4554485a
+
+You should also see the command being sent to the vtpm console as well as the
+vtpm saving its state. You should see the vtpm key being encrypted and stored on
+the vtpmmgr console.
+
+You may wish to write a script to start your vtpm and guest together and to
+destroy the vtpm when the guest shuts down.
+
+=head1 INTEGRATION WITH PV-GRUB
+
+The vTPM currently starts up with all PCRs set to their default values (all
+zeros for the lower 16). This means that any decisions about the
+trustworthiness of the created domain must be made based on the environment that
+created the vTPM and the domU; for example, a system that only constructs images
+using a trusted configuration and guest kernel be able to provide guarantees
+about the guests and any measurements done that kernel (such as the IMA TCB
+log). Guests wishing to use a custom kernel in such a secure environment are
+often started using the pv-grub bootloader as the kernel, which then can load
+the untrusted kernel without needing to parse an untrusted filesystem and kernel
+in dom0. If the pv-grub stub domain succeeds in connecting to a vTPM, it will
+extend the hash of the kernel that it boots into PCR #4, and will extend the
+command line and initrd into PCR #5 before booting so that a domU booted in this
+way can attest to its early boot state.
+
+=head1 MORE INFORMATION
+
+See <xen-vtpmmgr(7)> for more details about how the manager domain works, how to use
+it, and its command line parameters.
+
+=head1 VTPM DOMAIN OPERATION
+
+The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to
+use. It is a small wrapper around the Berlios TPM emulator version 0.7.4.
+Commands are passed from the linux guest via the mini-os TPM backend driver.
+vTPM data is encrypted and stored via a disk image provided to the virtual
+machine. The key used to encrypt the data along with a hash of the vTPM's data
+is sent to the vTPM manager for secure storage and later retrieval. The vTPM
+domain communicates with the manager using a mini-os tpm front/back device pair.
+
+=head1 VTPM DOMAIN COMMAND LINE ARGUMENTS
+
+Command line arguments are passed to the domain via the 'extra' parameter in the
+VM config file. Each parameter is separated by white space. For example:
+
+ extra="foo=bar baz"
+
+=head2 List of Arguments:
+
+=over 4
+
+=item B<loglevel>=<LOG>
+
+Controls the amount of logging printed to the console.
+The possible values for <LOG> are:
+
+=over 4
+
+=item * error
+
+=item * info (default)
+
+=item * debug
+
+=back
+
+=item B<clear>
+
+Start the Berlios emulator in "clear" mode. (default)
+
+=item B<save>
+
+Start the Berlios emulator in "save" mode.
+
+=item B<deactivated>
+
+Start the Berlios emulator in "deactivated" mode.
+See the Berlios TPM emulator documentation for details
+about the startup mode. For all normal use, always use clear
+which is the default. You should not need to specify any of these.
+
+=item B<maintcmds>=<1|0>
+
+Enable to disable the TPM maintenance commands.
+These commands are used by tpm manufacturers and thus
+open a security hole. They are disabled by default.
+
+=item B<hwinitpcr>=<PCRSPEC>
+
+Initialize the virtual Platform Configuration Registers
+(PCRs) with PCR values from the hardware TPM. Each pcr specified by
+<PCRSPEC> will be initialized with the value of that same PCR in TPM
+once at startup. By default all PCRs are zero initialized.
+Possible values of <PCRSPEC> are:
+
+=over
+
+=item * all: copy all pcrs
+
+=item * none: copy no pcrs (default)
+
+=item * <N>: copy pcr n
+
+=item * <X-Y>: copy pcrs x to y (inclusive)
+
+=back
+
+These can also be combined by comma separation, for example:
+C<hwinitpcrs=5,12-16> will copy pcrs 5, 12, 13, 14, 15, and 16.
+
+=back
+
+=head1 REFERENCES
+
+Berlios TPM Emulator: L<http://tpm-emulator.berlios.de/>
+++ /dev/null
-=head1 NAME
-
-xen-vtpm - Xen virtual Trusted Platform Module (vTPM) subsystem
-
-=head1 RUBRIC
-
-Copyright (c) 2010-2012 United States Government, as represented by
-the Secretary of Defense. All rights reserved.
-November 12 2012
-Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
-
-This document describes the virtual Trusted Platform Module (vTPM) subsystem
-for Xen. The reader is assumed to have familiarity with building and installing
-Xen, Linux, and a basic understanding of the TPM and vTPM concepts.
-
-=head1 INTRODUCTION
-
-The goal of this work is to provide a TPM functionality to a virtual guest
-operating system (a DomU). This allows programs to interact with a TPM in a
-virtual system the same way they interact with a TPM on the physical system.
-Each guest gets its own unique, emulated, software TPM. However, each of the
-vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, which
-seals the secrets to the Physical TPM. If the process of creating each of these
-domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends the
-chain of trust rooted in the hardware TPM to virtual machines in Xen. Each
-major component of vTPM is implemented as a separate domain, providing secure
-separation guaranteed by the hypervisor. The vTPM domains are implemented in
-mini-os to reduce memory and processor overhead.
-
-This mini-os vTPM subsystem was built on top of the previous vTPM work done by
-IBM and Intel corporation.
-
-=head1 DESIGN OVERVIEW
-
-The architecture of vTPM is described below:
-
- +------------------+
- | Linux DomU | ...
- | | ^ |
- | v | |
- | xen-tpmfront |
- +------------------+
- | ^
- v |
- +------------------+
- | mini-os/tpmback |
- | | ^ |
- | v | |
- | vtpm-stubdom | ...
- | | ^ |
- | v | |
- | mini-os/tpmfront |
- +------------------+
- | ^
- v |
- +------------------+
- | mini-os/tpmback |
- | | ^ |
- | v | |
- | vtpmmgr-stubdom |
- | | ^ |
- | v | |
- | mini-os/tpm_tis |
- +------------------+
- | ^
- v |
- +------------------+
- | Hardware TPM |
- +------------------+
-
-=over 4
-
-=item Linux DomU
-
-The Linux based guest that wants to use a vTPM. There many be
-more than one of these.
-
-=item xen-tpmfront.ko
-
-Linux kernel virtual TPM frontend driver. This driver
-provides vTPM access to a para-virtualized Linux based DomU.
-
-=item mini-os/tpmback
-
-Mini-os TPM backend driver. The Linux frontend driver
-connects to this backend driver to facilitate
-communications between the Linux DomU and its vTPM. This
-driver is also used by vtpmmgr-stubdom to communicate with
-vtpm-stubdom.
-
-=item vtpm-stubdom
-
-A mini-os stub domain that implements a vTPM. There is a
-one to one mapping between running vtpm-stubdom instances and
-logical vtpms on the system. The vTPM Platform Configuration
-Registers (PCRs) are all initialized to zero.
-
-=item mini-os/tpmfront
-
-Mini-os TPM frontend driver. The vTPM mini-os domain
-vtpm-stubdom uses this driver to communicate with
-vtpmmgr-stubdom. This driver could also be used separately to
-implement a mini-os domain that wishes to use a vTPM of
-its own.
-
-=item vtpmmgr-stubdom
-
-A mini-os domain that implements the vTPM manager.
-There is only one vTPM manager and it should be running during
-the entire lifetime of the machine. This domain regulates
-access to the physical TPM on the system and secures the
-persistent state of each vTPM.
-
-=item mini-os/tpm_tis
-
-Mini-os TPM version 1.2 TPM Interface Specification (TIS)
-driver. This driver used by vtpmmgr-stubdom to talk directly to
-the hardware TPM. Communication is facilitated by mapping
-hardware memory pages into vtpmmgr-stubdom.
-
-=item Hardware TPM
-
-The physical TPM that is soldered onto the motherboard.
-
-=back
-
-=head1 INSTALLATION
-
-=head2 Prerequisites:
-
-You must have an x86 machine with a TPM on the motherboard. The only extra
-software requirement for compiling vTPM is cmake. You must use libxl to manage
-domains with vTPMs; 'xm' is deprecated and does not support vTPMs.
-
-=head2 Compiling the Xen tree:
-
-Compile and install the Xen tree as usual; be sure that the vTPM domains are
-enabled when you run configure.
-
-=head2 Compiling the LINUX dom0 kernel:
-
-Because the TPM manager uses direct access to the physical TPM, it may interfere
-with access to the TPM by dom0. The simplest solution for this is to prevent
-dom0 from accessing the physical TPM by compiling the kernel without a driver or
-blacklisting the module. If dom0 needs a TPM but does not need to use it during
-the boot process (i.e. it is not using IMA), a virtual TPM can be attached to
-dom0 after the system is booted.
-
-Access to the physical TPM may be required in order to manage the NVRAM or to
-perform other advanced operations where the vTPM is insufficient. In order to
-prevent interference, the TPM Manager and dom0 should use different values for
-the TPM's locality; since Linux always uses locality 0, using locality 2 for the
-TPM Manager is recommended. If both Linux and the TPM Manager attempt to access
-the TPM at the same time, the TPM device will return a busy status; some
-applications will consider this a fatal error instead of retrying the command at
-a later time. If a vTPM gets an error when loading its key, it will currently
-generate a fresh vTPM image (with a new EK, SRK, and blank NVRAM).
-
-
-=head2 Compiling the LINUX domU kernel:
-
-The domU kernel used by domains with vtpms must include the xen-tpmfront.ko
-driver. It can be built directly into the kernel or as a module; however, some
-features such as IMA require the TPM to be built in to the kernel.
-
- CONFIG_TCG_TPM=y
- CONFIG_TCG_XEN=y
-
-=head1 VTPM MANAGER SETUP
-
-=head2 Manager disk image setup:
-
-The vTPM Manager requires a disk image to store its encrypted data. The image
-does not require a filesystem and can live anywhere on the host disk. The image
-is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
-but can support more than 20,000 vTPMs.
-
-=head2 Manager config file:
-
-The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
-virtual machine and requires a config file. The manager requires a disk image
-for storage and permission to access the hardware memory pages for the TPM. The
-disk must be presented as "hda", and the TPM memory pages are passed using the
-iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per
-locality) that start at physical address 0xfed40000. By default, the TPM manager
-uses locality 0 (so only the page at 0xfed40 is needed); this can be changed on
-the domain's command line. For full functionality in deep quotes, using
-locality 2 is required to manipulate PCR 20-22.
-
-=head2 Starting and stopping the manager:
-
-The vTPM manager should be started at boot; you may wish to create an init
-script to do this. If a domain builder is used, the TPM Manager should be
-started by the domain builder to minimize the trusted computing base for the
-vTPM manager's secrets.
-
-Once initialization is complete you should see the following:
-
- INFO[VTPM]: Waiting for commands from vTPM's:
-
-The TPM Manager does not respond to shutdown requests; use the destroy command
-to shut it down.
-
-=head1 VTPM AND LINUX PVM SETUP
-
-=head2 vTPM disk image setup:
-
-The vTPM requires a disk image to store its persistent data (RSA keys, NVRAM,
-etc). The image does not require a filesystem. The image does not need to be
-large; 2 Mb should be sufficient.
-
-=head2 vTPM config file:
-
-The vTPM domain requires a configuration file like any other domain. The vTPM
-requires a disk image for storage and a TPM frontend driver to communicate with
-the manager. You are required to generate a uuid for this vtpm, which is
-specified on the C<vtpm=> line that describes its connection to the vTPM Manager.
-The uuidgen application may be used to generate a uuid, or one from the output
-of the C<manage-vtpmmgr.pl vtpm-add> command may be used to create a vTPM
-belonging to a specific group.
-
-If you wish to clear the vTPM data you can either recreate the disk image or
-change the uuid.
-
-=head2 Linux Guest config file:
-
-The Linux guest config file needs to be modified to include the Linux tpmfront
-driver. Add the following line:
-
- vtpm=["backend=domu-vtpm"]
-
-Currently only Linux guests are supported (PV or HVM with PV drivers).
-
-While attaching a vTPM after a guest is booted (using xl vtpm-attach) is
-supported, the attached vTPM will not have a record of the boot of the attached
-guest. Furthermore, if the vTPM has been freshly created, a malicious guest
-could then extend any values into PCRs, potentially forging its boot
-configuration. Attaching a vTPM to a running domain should only be used for
-trusted domains or when measurements have already been sent to the vTPM from
-another source.
-
-=head2 Using the vTPM in the guest:
-
-If xen-tpmfront was compiled as a module, it must be loaded it in the guest.
-
- # modprobe xen-tpmfront
-
-After the Linux domain boots and the xen-tpmfront driver is loaded, you should
-see the following on the vtpm console:
-
- Info: VTPM attached to Frontend X/Y
-
-You can quickly test the vTPM by using the sysfs interface:
-
- # cat /sys/devices/vtpm-0/pubek
- # cat /sys/devices/vtpm-0/pcrs
-
-If you have trousers and tpm_tools installed on the guest, the tpm_version
-command should return the following:
-
-The version command should return the following:
-
- TPM 1.2 Version Info:
- Chip Version: 1.2.0.7
- Spec Level: 2
- Errata Revision: 1
- TPM Vendor ID: ETHZ
- TPM Version: 01010000
- Manufacturer Info: 4554485a
-
-You should also see the command being sent to the vtpm console as well as the
-vtpm saving its state. You should see the vtpm key being encrypted and stored on
-the vtpmmgr console.
-
-You may wish to write a script to start your vtpm and guest together and to
-destroy the vtpm when the guest shuts down.
-
-=head1 INTEGRATION WITH PV-GRUB
-
-The vTPM currently starts up with all PCRs set to their default values (all
-zeros for the lower 16). This means that any decisions about the
-trustworthiness of the created domain must be made based on the environment that
-created the vTPM and the domU; for example, a system that only constructs images
-using a trusted configuration and guest kernel be able to provide guarantees
-about the guests and any measurements done that kernel (such as the IMA TCB
-log). Guests wishing to use a custom kernel in such a secure environment are
-often started using the pv-grub bootloader as the kernel, which then can load
-the untrusted kernel without needing to parse an untrusted filesystem and kernel
-in dom0. If the pv-grub stub domain succeeds in connecting to a vTPM, it will
-extend the hash of the kernel that it boots into PCR #4, and will extend the
-command line and initrd into PCR #5 before booting so that a domU booted in this
-way can attest to its early boot state.
-
-=head1 MORE INFORMATION
-
-See <xen-vtpmmgr(7)> for more details about how the manager domain works, how to use
-it, and its command line parameters.
-
-=head1 VTPM DOMAIN OPERATION
-
-The vtpm-stubdom is a mini-OS domain that emulates a TPM for the guest OS to
-use. It is a small wrapper around the Berlios TPM emulator version 0.7.4.
-Commands are passed from the linux guest via the mini-os TPM backend driver.
-vTPM data is encrypted and stored via a disk image provided to the virtual
-machine. The key used to encrypt the data along with a hash of the vTPM's data
-is sent to the vTPM manager for secure storage and later retrieval. The vTPM
-domain communicates with the manager using a mini-os tpm front/back device pair.
-
-=head1 VTPM DOMAIN COMMAND LINE ARGUMENTS
-
-Command line arguments are passed to the domain via the 'extra' parameter in the
-VM config file. Each parameter is separated by white space. For example:
-
- extra="foo=bar baz"
-
-=head2 List of Arguments:
-
-=over 4
-
-=item B<loglevel>=<LOG>
-
-Controls the amount of logging printed to the console.
-The possible values for <LOG> are:
-
-=over 4
-
-=item * error
-
-=item * info (default)
-
-=item * debug
-
-=back
-
-=item B<clear>
-
-Start the Berlios emulator in "clear" mode. (default)
-
-=item B<save>
-
-Start the Berlios emulator in "save" mode.
-
-=item B<deactivated>
-
-Start the Berlios emulator in "deactivated" mode.
-See the Berlios TPM emulator documentation for details
-about the startup mode. For all normal use, always use clear
-which is the default. You should not need to specify any of these.
-
-=item B<maintcmds>=<1|0>
-
-Enable to disable the TPM maintenance commands.
-These commands are used by tpm manufacturers and thus
-open a security hole. They are disabled by default.
-
-=item B<hwinitpcr>=<PCRSPEC>
-
-Initialize the virtual Platform Configuration Registers
-(PCRs) with PCR values from the hardware TPM. Each pcr specified by
-<PCRSPEC> will be initialized with the value of that same PCR in TPM
-once at startup. By default all PCRs are zero initialized.
-Possible values of <PCRSPEC> are:
-
-=over
-
-=item * all: copy all pcrs
-
-=item * none: copy no pcrs (default)
-
-=item * <N>: copy pcr n
-
-=item * <X-Y>: copy pcrs x to y (inclusive)
-
-=back
-
-These can also be combined by comma separation, for example:
-C<hwinitpcrs=5,12-16> will copy pcrs 5, 12, 13, 14, 15, and 16.
-
-=back
-
-=head1 REFERENCES
-
-Berlios TPM Emulator: L<http://tpm-emulator.berlios.de/>
--- /dev/null
+=head1 NAME
+
+xen-vtpmgr - Xen virtual TPM stubdomain
+
+=head1 Authors
+
+=over 4
+
+=item Daniel De Graaf <dgdegra@tycho.nsa.gov>
+
+=item Quan Xu <quan.xu@intel.com>
+
+=back
+
+This document describes the operation and command line interface of
+vtpmmgr-stubdom. See L<xen-vtpm(7)> for details on the vTPM subsystem as a
+whole.
+
+=head1 Overview
+
+The TPM Manager has three primary functions:
+
+=over 4
+
+=item 1. Securely store the encryption keys for vTPMs
+
+=item 2. Provide a single controlled path of access to the physical TPM
+
+=item 3. Provide evidence (via TPM Quotes) of the current configuration
+
+=back
+
+When combined with a platform that provides a trusted method for creating
+domains, the TPM Manager provides assurance that the private keys in a vTPM are
+only available in specific trusted configurations.
+
+The manager accepts commands from the vtpm-stubdom domains via the mini-os TPM
+backend driver. The vTPM manager communicates directly with hardware TPM using
+the mini-os tpm_tis driver.
+
+=head1 Boot Configurations and TPM Groups
+
+The TPM Manager's data is secured by using the physical TPM's seal operation,
+which allows data to be bound to specific PCRs. These PCRs are populated in the
+physical TPM during the boot process, either by the firmware/BIOS or by a
+dynamic launch environment such as TBOOT. In order to provide assurance of the
+system's security, the PCRs used to seal the TPM manager's data must contain
+measurements for domains used to bootstrap the TPM Manager and vTPMs.
+
+Because these measurements are based on hashes, they will change any time that
+any component of the system is upgraded. Since it is not possible to construct a
+list of all possible future good measurements, the job of approving
+configurations is delegated to a third party, referred to here as the system
+approval agent (SAA). The SAA is identified by its public (RSA) signature key,
+which is used to sign lists of valid configurations. A single TPM manager can
+support multiple SAAs via the use of vTPM groups. Each group is associated with
+a single SAA; this allows the creation of a multi-tenant environment where
+tenants may not all choose to trust the same SAA.
+
+Each vTPM is bound to a vTPM group at the time of its creation. Each vTPM group
+has its own AIK in the physical TPM for quotes of the hardware TPM state; when
+used with a conforming Privacy CA, this allows each group on the system to form
+the basis of a distinct identity.
+
+=head1 Initial Provisioning
+
+When the TPM Manager first boots up, it will create a stub vTPM group along with
+entries for any vTPMs that communicate with it. This stub group must be
+provisioned with an SAA and a boot configuration in order to survive a reboot.
+
+When a vTPM is connected to the TPM Manager using a UUID that is not recognized,
+a slot will be created in group 0 for it. In the future, this auto-creation may
+be restricted to specific UUIDs (such as the all-zero UUID) to enforce the use
+of the TPM manager as the generator of the UUID. The first vTPM to be connected
+is given administrative privileges for the TPM Manager, and should be attached
+to dom0 or a control domain in order to send provisioning commands.
+
+Provisioning a vTPM group for the system requires the public key of the SAA and
+privacy CA data used to certify the AIK (see the TPM spec for details). Once the
+group is created, a signed list of boot measurements can be installed. The
+initial group controls the ability to boot the system as a whole, and cannot be
+deleted once provisioned.
+
+=head1 Command Line Arguments
+
+Command line arguments are passed to the domain via the 'extra' parameter in the
+VM config file. Each parameter is separated by white space. For example:
+
+ extra="foo=bar baz"
+
+Valid arguments:
+
+=over 4
+
+=item owner_auth=<AUTHSPEC>
+
+=item srk_auth=<AUTHSPEC>
+
+Set the owner and SRK authdata for the TPM. If not specified, the
+default is 160 zero bits (the well-known auth value). Valid values of
+<AUTHSPEC> are:
+
+=over 4
+
+=item well-known
+
+Use the well known auth (default)
+
+=item hash:<HASH>
+
+Use the given 40-character ASCII hex string
+
+=item text:<STR>
+
+Use sha1 hash of <STR>.
+
+=back
+
+=item tpmdriver=<DRIVER>
+
+Choose the driver used for communication with the hardware TPM. Values
+other than tpm_tis should only be used for testing.
+
+The possible values of <DRIVER> are:
+
+=over 4
+
+=item tpm_tis
+
+Direct communication with a hardware TPM 1.2. The
+domain must have access to TPM IO memory. (default)
+
+=item tpmfront
+
+Use the Xen tpmfront interface to talk to another
+domain which provides access to the TPM.
+
+=back
+
+=back
+
+The following options only apply to the tpm_tis driver:
+
+=over 4
+
+=item tpmiomem=<ADDR>
+
+The base address of the hardware memory pages of the TPM.
+The default is 0xfed40000, as defined by the TCG's PC Client spec.
+
+=item tpmirq=<IRQ>
+
+The irq of the hardware TPM if using interrupts. A value of
+"probe" can be set to probe for the irq. A value of 0 disables
+interrupts and uses polling (default 0).
+
+=item tpmlocality=<LOC>
+
+Attempt to use locality <LOC> of the hardware TPM.
+For full functionality of the TPM Manager, this should be set to "2".
+
+=back
+
+=head1 Platform Security Assumptions
+
+While the TPM Manager has the ability to check the hash of the vTPM requesting a
+key, there is currently no trusted method to inform the TPM Manager of the hash
+of each new domain. Because of this, the TPM Manager trusts the UUID key in
+Xenstore to identify a vTPM in a trusted manner. The XSM policy may be used to
+strengthen this assumption if the creation of vTPM-labeled domains is more
+constrained (for example, only permitted to a domain builder service): the only
+grants mapped by the TPM Manager should belong to vTPM domains, so restricting
+the ability to map other domain's granted pages will prevent other domains from
+directly requesting keys from the TPM Manager. The TPM Manager uses the hash of
+the XSM label of the attached vTPM as the kernel hash, so vTPMs with distinct
+labels may be further partitioned using vTPM groups.
+
+A domain with direct access to the hardware TPM will be able to decrypt the TPM
+Manager's disk image if the haredware TPM's PCR values are in a permitted
+configuration. To protect the TPM Manager's data, the list of permitted
+configurations should be chosen to include PCRs that measure the hypervisor,
+domain 0, the TPM Manager, and other critical configuration such as the XSM
+policy. If the TPM Manager is configured to use locality 2 as recommended, it
+is safe to permit the hardware domain to access locality 0 (the default in
+Linux), although concurrent use of the TPM should be avoided as it can result in
+unexpected busy errors from the TPM driver. The ability to access locality 2 of
+the TPM should be enforced using IO memory labeling in the XSM policy; the
+physical address 0xFED42xxx is always locality 2 for TPMs using the TIS driver.
+
+=head1 Appendix: unsecured migration process for vtpmmgr domain upgrade
+
+There is no direct upgrade supported from previous versions of the vtpmmgr
+domain due to changes in the on-disk format and the method used to seal data.
+If a vTPM domain supports migration, this feature should be used to migrate the
+vTPM's data; however, the vTPM packaged with Xen does not yet support migration.
+
+If adding migration support to the vTPM is not desired, a simpler migration
+domain usable only for local migration can be constructed. The migration process
+would look like the following:
+
+=over 4
+
+=item 1. Start the old vtpmmgr
+
+=item 2. Start the vTPM migration domain
+
+=item 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
+
+=item 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
+
+=item 5. Start the new vtpmmgr, possibly shutting down the old one first
+
+=item 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
+
+=item 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
+
+=back
+
+This requires the migration domain to be added to the list of valid vTPM kernel
+hashes. In the current version of the vtpmmgr domain, this is the hash of the
+XSM label, not the kernel.
+
+=head1 Appendix B: vtpmmgr on TPM 2.0
+
+=head2 Manager disk image setup:
+
+The vTPM Manager requires a disk image to store its encrypted data. The image
+does not require a filesystem and can live anywhere on the host disk. The image
+is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
+but can support more than 20,000 vTPMs.
+
+ dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
+
+=head2 Manager config file:
+
+The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
+virtual machine and requires a config file. The manager requires a disk image
+for storage and permission to access the hardware memory pages for the TPM. The
+disk must be presented as "hda", and the TPM memory pages are passed using the
+iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per
+locality) that start at physical address 0xfed40000. By default, the TPM manager
+uses locality 0 (so only the page at 0xfed40 is needed).
+
+Add:
+
+ extra="tpm2=1"
+
+extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
+1.x. for example:
+
+ kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
+ memory=128
+ disk=["file:/home/vtpm2/vmgr,hda,w"]
+ name="vtpmmgr"
+ iomem=["fed40,5"]
+ extra="tpm2=1"
+
+
+=head2 Key Hierarchy
+
+ +------------------+
+ | vTPM's secrets | ...
+ +------------------+
+ | ^
+ | |(Bind / Unbind)
+- - - - - -v |- - - - - - - - TPM 2.0
+ +------------------+
+ | SK +
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | SRK |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | TPM 2.0 Storage |
+ | Primary Seed |
+ +------------------+
+
+Now the secrets for the vTPMs are only being bound to the presence of thephysical
+TPM 2.0. Since using PCRs to seal the data can be an important security feature
+that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with
+TPM2_Seal/TPM2_Unseal to provide as much security as it did for TPM 1.2 in later
+series of patch.
+
+=head2 Design Overview
+
+The architecture of vTPM subsystem on TPM 2.0 is described below:
+
+ +------------------+
+ | Linux DomU | ...
+ | | ^ |
+ | v | |
+ | xen-tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpm-stubdom | ...
+ | | ^ |
+ | v | |
+ | mini-os/tpmfront |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | mini-os/tpmback |
+ | | ^ |
+ | v | |
+ | vtpmmgr-stubdom |
+ | | ^ |
+ | v | |
+ | mini-os/tpm2_tis |
+ +------------------+
+ | ^
+ v |
+ +------------------+
+ | Hardware TPM 2.0 |
+ +------------------+
+
+=over 4
+
+=item Linux DomU
+
+The Linux based guest that wants to use a vTPM. There many be
+more than one of these.
+
+=item xen-tpmfront.ko
+
+Linux kernel virtual TPM frontend driver. This driver
+provides vTPM access to a para-virtualized Linux based DomU.
+
+=item mini-os/tpmback
+
+Mini-os TPM backend driver. The Linux frontend driver
+connects to this backend driver to facilitate
+communications between the Linux DomU and its vTPM. This
+driver is also used by vtpmmgr-stubdom to communicate with
+vtpm-stubdom.
+
+=item vtpm-stubdom
+
+A mini-os stub domain that implements a vTPM. There is a
+one to one mapping between running vtpm-stubdom instances and
+logical vtpms on the system. The vTPM Platform Configuration
+Registers (PCRs) are all initialized to zero.
+
+=item mini-os/tpmfront
+
+Mini-os TPM frontend driver. The vTPM mini-os domain
+vtpm-stubdom uses this driver to communicate with
+vtpmmgr-stubdom. This driver could also be used separately to
+implement a mini-os domain that wishes to use a vTPM of
+its own.
+
+=item vtpmmgr-stubdom
+
+A mini-os domain that implements the vTPM manager.
+There is only one vTPM manager and it should be running during
+the entire lifetime of the machine. This domain regulates
+access to the physical TPM on the system and secures the
+persistent state of each vTPM.
+
+=item mini-os/tpm2_tis
+
+Mini-os TPM version 2.0 TPM Interface Specification (TIS)
+driver. This driver used by vtpmmgr-stubdom to talk directly
+to the hardware TPM 2.0. Communication is facilitated by mapping
+hardware memory pages into vtpmmgr-stubdom.
+
+=item Hardware TPM 2.0
+
+The physical TPM 2.0 that is soldered onto the motherboard.
+
+=back
+
+Noted:
+ functionality for a virtual guest operating system (a DomU) is still TPM 1.2.
+++ /dev/null
-=head1 NAME
-
-xen-vtpmgr - Xen virtual TPM stubdomain
-
-=head1 Authors
-
-=over 4
-
-=item Daniel De Graaf <dgdegra@tycho.nsa.gov>
-
-=item Quan Xu <quan.xu@intel.com>
-
-=back
-
-This document describes the operation and command line interface of
-vtpmmgr-stubdom. See L<xen-vtpm(7)> for details on the vTPM subsystem as a
-whole.
-
-=head1 Overview
-
-The TPM Manager has three primary functions:
-
-=over 4
-
-=item 1. Securely store the encryption keys for vTPMs
-
-=item 2. Provide a single controlled path of access to the physical TPM
-
-=item 3. Provide evidence (via TPM Quotes) of the current configuration
-
-=back
-
-When combined with a platform that provides a trusted method for creating
-domains, the TPM Manager provides assurance that the private keys in a vTPM are
-only available in specific trusted configurations.
-
-The manager accepts commands from the vtpm-stubdom domains via the mini-os TPM
-backend driver. The vTPM manager communicates directly with hardware TPM using
-the mini-os tpm_tis driver.
-
-=head1 Boot Configurations and TPM Groups
-
-The TPM Manager's data is secured by using the physical TPM's seal operation,
-which allows data to be bound to specific PCRs. These PCRs are populated in the
-physical TPM during the boot process, either by the firmware/BIOS or by a
-dynamic launch environment such as TBOOT. In order to provide assurance of the
-system's security, the PCRs used to seal the TPM manager's data must contain
-measurements for domains used to bootstrap the TPM Manager and vTPMs.
-
-Because these measurements are based on hashes, they will change any time that
-any component of the system is upgraded. Since it is not possible to construct a
-list of all possible future good measurements, the job of approving
-configurations is delegated to a third party, referred to here as the system
-approval agent (SAA). The SAA is identified by its public (RSA) signature key,
-which is used to sign lists of valid configurations. A single TPM manager can
-support multiple SAAs via the use of vTPM groups. Each group is associated with
-a single SAA; this allows the creation of a multi-tenant environment where
-tenants may not all choose to trust the same SAA.
-
-Each vTPM is bound to a vTPM group at the time of its creation. Each vTPM group
-has its own AIK in the physical TPM for quotes of the hardware TPM state; when
-used with a conforming Privacy CA, this allows each group on the system to form
-the basis of a distinct identity.
-
-=head1 Initial Provisioning
-
-When the TPM Manager first boots up, it will create a stub vTPM group along with
-entries for any vTPMs that communicate with it. This stub group must be
-provisioned with an SAA and a boot configuration in order to survive a reboot.
-
-When a vTPM is connected to the TPM Manager using a UUID that is not recognized,
-a slot will be created in group 0 for it. In the future, this auto-creation may
-be restricted to specific UUIDs (such as the all-zero UUID) to enforce the use
-of the TPM manager as the generator of the UUID. The first vTPM to be connected
-is given administrative privileges for the TPM Manager, and should be attached
-to dom0 or a control domain in order to send provisioning commands.
-
-Provisioning a vTPM group for the system requires the public key of the SAA and
-privacy CA data used to certify the AIK (see the TPM spec for details). Once the
-group is created, a signed list of boot measurements can be installed. The
-initial group controls the ability to boot the system as a whole, and cannot be
-deleted once provisioned.
-
-=head1 Command Line Arguments
-
-Command line arguments are passed to the domain via the 'extra' parameter in the
-VM config file. Each parameter is separated by white space. For example:
-
- extra="foo=bar baz"
-
-Valid arguments:
-
-=over 4
-
-=item owner_auth=<AUTHSPEC>
-
-=item srk_auth=<AUTHSPEC>
-
-Set the owner and SRK authdata for the TPM. If not specified, the
-default is 160 zero bits (the well-known auth value). Valid values of
-<AUTHSPEC> are:
-
-=over 4
-
-=item well-known
-
-Use the well known auth (default)
-
-=item hash:<HASH>
-
-Use the given 40-character ASCII hex string
-
-=item text:<STR>
-
-Use sha1 hash of <STR>.
-
-=back
-
-=item tpmdriver=<DRIVER>
-
-Choose the driver used for communication with the hardware TPM. Values
-other than tpm_tis should only be used for testing.
-
-The possible values of <DRIVER> are:
-
-=over 4
-
-=item tpm_tis
-
-Direct communication with a hardware TPM 1.2. The
-domain must have access to TPM IO memory. (default)
-
-=item tpmfront
-
-Use the Xen tpmfront interface to talk to another
-domain which provides access to the TPM.
-
-=back
-
-=back
-
-The following options only apply to the tpm_tis driver:
-
-=over 4
-
-=item tpmiomem=<ADDR>
-
-The base address of the hardware memory pages of the TPM.
-The default is 0xfed40000, as defined by the TCG's PC Client spec.
-
-=item tpmirq=<IRQ>
-
-The irq of the hardware TPM if using interrupts. A value of
-"probe" can be set to probe for the irq. A value of 0 disables
-interrupts and uses polling (default 0).
-
-=item tpmlocality=<LOC>
-
-Attempt to use locality <LOC> of the hardware TPM.
-For full functionality of the TPM Manager, this should be set to "2".
-
-=back
-
-=head1 Platform Security Assumptions
-
-While the TPM Manager has the ability to check the hash of the vTPM requesting a
-key, there is currently no trusted method to inform the TPM Manager of the hash
-of each new domain. Because of this, the TPM Manager trusts the UUID key in
-Xenstore to identify a vTPM in a trusted manner. The XSM policy may be used to
-strengthen this assumption if the creation of vTPM-labeled domains is more
-constrained (for example, only permitted to a domain builder service): the only
-grants mapped by the TPM Manager should belong to vTPM domains, so restricting
-the ability to map other domain's granted pages will prevent other domains from
-directly requesting keys from the TPM Manager. The TPM Manager uses the hash of
-the XSM label of the attached vTPM as the kernel hash, so vTPMs with distinct
-labels may be further partitioned using vTPM groups.
-
-A domain with direct access to the hardware TPM will be able to decrypt the TPM
-Manager's disk image if the haredware TPM's PCR values are in a permitted
-configuration. To protect the TPM Manager's data, the list of permitted
-configurations should be chosen to include PCRs that measure the hypervisor,
-domain 0, the TPM Manager, and other critical configuration such as the XSM
-policy. If the TPM Manager is configured to use locality 2 as recommended, it
-is safe to permit the hardware domain to access locality 0 (the default in
-Linux), although concurrent use of the TPM should be avoided as it can result in
-unexpected busy errors from the TPM driver. The ability to access locality 2 of
-the TPM should be enforced using IO memory labeling in the XSM policy; the
-physical address 0xFED42xxx is always locality 2 for TPMs using the TIS driver.
-
-=head1 Appendix: unsecured migration process for vtpmmgr domain upgrade
-
-There is no direct upgrade supported from previous versions of the vtpmmgr
-domain due to changes in the on-disk format and the method used to seal data.
-If a vTPM domain supports migration, this feature should be used to migrate the
-vTPM's data; however, the vTPM packaged with Xen does not yet support migration.
-
-If adding migration support to the vTPM is not desired, a simpler migration
-domain usable only for local migration can be constructed. The migration process
-would look like the following:
-
-=over 4
-
-=item 1. Start the old vtpmmgr
-
-=item 2. Start the vTPM migration domain
-
-=item 3. Attach the vTPM migration domain's vtpm/0 device to the old vtpmmgr
-
-=item 4. Migration domain executes vtpmmgr_LoadHashKey on vtpm/0
-
-=item 5. Start the new vtpmmgr, possibly shutting down the old one first
-
-=item 6. Attach the vTPM migration domain's vtpm/1 device to the new vtpmmgr
-
-=item 7. Migration domain executes vtpmmgr_SaveHashKey on vtpm/1
-
-=back
-
-This requires the migration domain to be added to the list of valid vTPM kernel
-hashes. In the current version of the vtpmmgr domain, this is the hash of the
-XSM label, not the kernel.
-
-=head1 Appendix B: vtpmmgr on TPM 2.0
-
-=head2 Manager disk image setup:
-
-The vTPM Manager requires a disk image to store its encrypted data. The image
-does not require a filesystem and can live anywhere on the host disk. The image
-is not large; the Xen 4.5 vtpmmgr is limited to using the first 2MB of the image
-but can support more than 20,000 vTPMs.
-
- dd if=/dev/zero of=/home/vtpm2/vmgr bs=16M count=1
-
-=head2 Manager config file:
-
-The vTPM Manager domain (vtpmmgr-stubdom) must be started like any other Xen
-virtual machine and requires a config file. The manager requires a disk image
-for storage and permission to access the hardware memory pages for the TPM. The
-disk must be presented as "hda", and the TPM memory pages are passed using the
-iomem configuration parameter. The TPM TIS uses 5 pages of IO memory (one per
-locality) that start at physical address 0xfed40000. By default, the TPM manager
-uses locality 0 (so only the page at 0xfed40 is needed).
-
-Add:
-
- extra="tpm2=1"
-
-extra option to launch vtpmmgr-stubdom domain on TPM 2.0, and ignore it on TPM
-1.x. for example:
-
- kernel="/usr/lib/xen/boot/vtpmmgr-stubdom.gz"
- memory=128
- disk=["file:/home/vtpm2/vmgr,hda,w"]
- name="vtpmmgr"
- iomem=["fed40,5"]
- extra="tpm2=1"
-
-
-=head2 Key Hierarchy
-
- +------------------+
- | vTPM's secrets | ...
- +------------------+
- | ^
- | |(Bind / Unbind)
-- - - - - -v |- - - - - - - - TPM 2.0
- +------------------+
- | SK +
- +------------------+
- | ^
- v |
- +------------------+
- | SRK |
- +------------------+
- | ^
- v |
- +------------------+
- | TPM 2.0 Storage |
- | Primary Seed |
- +------------------+
-
-Now the secrets for the vTPMs are only being bound to the presence of thephysical
-TPM 2.0. Since using PCRs to seal the data can be an important security feature
-that users of the vtpmmgr rely on. I will replace TPM2_Bind/TPM2_Unbind with
-TPM2_Seal/TPM2_Unseal to provide as much security as it did for TPM 1.2 in later
-series of patch.
-
-=head2 Design Overview
-
-The architecture of vTPM subsystem on TPM 2.0 is described below:
-
- +------------------+
- | Linux DomU | ...
- | | ^ |
- | v | |
- | xen-tpmfront |
- +------------------+
- | ^
- v |
- +------------------+
- | mini-os/tpmback |
- | | ^ |
- | v | |
- | vtpm-stubdom | ...
- | | ^ |
- | v | |
- | mini-os/tpmfront |
- +------------------+
- | ^
- v |
- +------------------+
- | mini-os/tpmback |
- | | ^ |
- | v | |
- | vtpmmgr-stubdom |
- | | ^ |
- | v | |
- | mini-os/tpm2_tis |
- +------------------+
- | ^
- v |
- +------------------+
- | Hardware TPM 2.0 |
- +------------------+
-
-=over 4
-
-=item Linux DomU
-
-The Linux based guest that wants to use a vTPM. There many be
-more than one of these.
-
-=item xen-tpmfront.ko
-
-Linux kernel virtual TPM frontend driver. This driver
-provides vTPM access to a para-virtualized Linux based DomU.
-
-=item mini-os/tpmback
-
-Mini-os TPM backend driver. The Linux frontend driver
-connects to this backend driver to facilitate
-communications between the Linux DomU and its vTPM. This
-driver is also used by vtpmmgr-stubdom to communicate with
-vtpm-stubdom.
-
-=item vtpm-stubdom
-
-A mini-os stub domain that implements a vTPM. There is a
-one to one mapping between running vtpm-stubdom instances and
-logical vtpms on the system. The vTPM Platform Configuration
-Registers (PCRs) are all initialized to zero.
-
-=item mini-os/tpmfront
-
-Mini-os TPM frontend driver. The vTPM mini-os domain
-vtpm-stubdom uses this driver to communicate with
-vtpmmgr-stubdom. This driver could also be used separately to
-implement a mini-os domain that wishes to use a vTPM of
-its own.
-
-=item vtpmmgr-stubdom
-
-A mini-os domain that implements the vTPM manager.
-There is only one vTPM manager and it should be running during
-the entire lifetime of the machine. This domain regulates
-access to the physical TPM on the system and secures the
-persistent state of each vTPM.
-
-=item mini-os/tpm2_tis
-
-Mini-os TPM version 2.0 TPM Interface Specification (TIS)
-driver. This driver used by vtpmmgr-stubdom to talk directly
-to the hardware TPM 2.0. Communication is facilitated by mapping
-hardware memory pages into vtpmmgr-stubdom.
-
-=item Hardware TPM 2.0
-
-The physical TPM 2.0 that is soldered onto the motherboard.
-
-=back
-
-Noted:
- functionality for a virtual guest operating system (a DomU) is still TPM 1.2.
--- /dev/null
+=head1 NAME
+
+xenstore-chmod - set the permissions of a Xenstore key
+
+=head1 SYNOPSIS
+
+B<xenstore-chmod> [I<OPTION>]... [I<KEY>] [I<PERM>]...
+
+=head1 DESCRIPTION
+
+Sets the permissions of the Xenstore I<KEY>.
+
+I<PERM> has the format I<LD>, where I<L> is a letter for the type of
+permission and I<D> is the corresponding domain ID.
+
+The types of permission are:
+
+=over
+
+=item B<r>
+
+read
+
+=item B<w>
+
+write
+
+=item B<b>
+
+read and write (both)
+
+=item B<n>
+
+no access
+
+=back
+
+The first permission entry is the domain owning the key (the owner)
+I<and> the permissions for any domain not explicitly listed in
+subsequent entries. The key owner always has full access (read,
+write, and set permissions).
+
+=over
+
+=item B<-r>
+
+Apply the permissions to the key and all its I<children>.
+
+=item B<-s>
+
+Connect to the Xenstore daemon using a local socket only.
+
+=item B<-u>
+
+Apply the permissions to the key and all its I<parents>.
+
+=back
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
+++ /dev/null
-=head1 NAME
-
-xenstore-chmod - set the permissions of a Xenstore key
-
-=head1 SYNOPSIS
-
-B<xenstore-chmod> [I<OPTION>]... [I<KEY>] [I<PERM>]...
-
-=head1 DESCRIPTION
-
-Sets the permissions of the Xenstore I<KEY>.
-
-I<PERM> has the format I<LD>, where I<L> is a letter for the type of
-permission and I<D> is the corresponding domain ID.
-
-The types of permission are:
-
-=over
-
-=item B<r>
-
-read
-
-=item B<w>
-
-write
-
-=item B<b>
-
-read and write (both)
-
-=item B<n>
-
-no access
-
-=back
-
-The first permission entry is the domain owning the key (the owner)
-I<and> the permissions for any domain not explicitly listed in
-subsequent entries. The key owner always has full access (read,
-write, and set permissions).
-
-=over
-
-=item B<-r>
-
-Apply the permissions to the key and all its I<children>.
-
-=item B<-s>
-
-Connect to the Xenstore daemon using a local socket only.
-
-=item B<-u>
-
-Apply the permissions to the key and all its I<parents>.
-
-=back
-
-=head1 BUGS
-
-Send bugs to xen-devel@lists.xen.org, see
-http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xenstore-ls - list Xenstore keys and values
+
+=head1 SYNOPSIS
+
+B<xenstore-ls> [I<OPTION>]... [I<PATH>]...
+
+=head1 DESCRIPTION
+
+List keys, values and permissions of one or more Xenstore I<PATH>s,
+using a nested, tree-like view.
+
+=over
+
+=item B<-f>
+
+Show the full path for all keys.
+
+=item B<-p>
+
+Show permissions of all the listed keys as comma separated list. The
+format of each permission is I<LD>, where I<L> is a letter for the
+type of permission and I<D> is the corresponding domain ID.
+
+The types of permission are:
+
+=over
+
+=item B<r>
+
+read
+
+=item B<w>
+
+write
+
+=item B<b>
+
+read and write (both)
+
+=item B<n>
+
+no access
+
+=back
+
+The first permission entry is the domain owning the key (the owner)
+I<and> the permissions for any domain not explicitly listed in
+subsequent entries. The key owner always has full access (read,
+write, and set permissions).
+
+=item B<-s>
+
+Connect to the Xenstore daemon using a local socket only.
+
+=back
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
+++ /dev/null
-=head1 NAME
-
-xenstore-ls - list Xenstore keys and values
-
-=head1 SYNOPSIS
-
-B<xenstore-ls> [I<OPTION>]... [I<PATH>]...
-
-=head1 DESCRIPTION
-
-List keys, values and permissions of one or more Xenstore I<PATH>s,
-using a nested, tree-like view.
-
-=over
-
-=item B<-f>
-
-Show the full path for all keys.
-
-=item B<-p>
-
-Show permissions of all the listed keys as comma separated list. The
-format of each permission is I<LD>, where I<L> is a letter for the
-type of permission and I<D> is the corresponding domain ID.
-
-The types of permission are:
-
-=over
-
-=item B<r>
-
-read
-
-=item B<w>
-
-write
-
-=item B<b>
-
-read and write (both)
-
-=item B<n>
-
-no access
-
-=back
-
-The first permission entry is the domain owning the key (the owner)
-I<and> the permissions for any domain not explicitly listed in
-subsequent entries. The key owner always has full access (read,
-write, and set permissions).
-
-=item B<-s>
-
-Connect to the Xenstore daemon using a local socket only.
-
-=back
-
-=head1 BUGS
-
-Send bugs to xen-devel@lists.xen.org, see
-http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xenstore-read - read Xenstore values
+
+=head1 SYNOPSIS
+
+B<xenstore-read> [I<OPTION>]... [I<PATH>]...
+
+=head1 DESCRIPTION
+
+Read values of one or more Xenstore I<PATH>s.
+
+=over
+
+=item B<-p>
+
+Prefix value with key name.
+
+=item B<-s>
+
+Connect to the Xenstore daemon using a local socket only.
+
+=item B<-R>
+
+Read raw value, skip escaping non-printable characters (\x..).
+
+=back
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
+++ /dev/null
-=head1 NAME
-
-xenstore-read - read Xenstore values
-
-=head1 SYNOPSIS
-
-B<xenstore-read> [I<OPTION>]... [I<PATH>]...
-
-=head1 DESCRIPTION
-
-Read values of one or more Xenstore I<PATH>s.
-
-=over
-
-=item B<-p>
-
-Prefix value with key name.
-
-=item B<-s>
-
-Connect to the Xenstore daemon using a local socket only.
-
-=item B<-R>
-
-Read raw value, skip escaping non-printable characters (\x..).
-
-=back
-
-=head1 BUGS
-
-Send bugs to xen-devel@lists.xen.org, see
-http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xenstore-write - write Xenstore values
+
+=head1 SYNOPSIS
+
+B<xenstore-read> [I<OPTION>]... I<PATH> I<VALUE>...
+
+=head1 DESCRIPTION
+
+Write I<VALUE>s to Xenstore I<PATH>s. Multiple pairs I<PATH> I<VALUE> can be
+provided to write them at once - in one Xenstore transaction.
+
+=over
+
+=item B<-s>
+
+Connect to the Xenstore daemon using a local socket only.
+
+=item B<-R>
+
+Write raw value, skip parsing escaped characters (\x..).
+
+=back
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
+++ /dev/null
-=head1 NAME
-
-xenstore-write - write Xenstore values
-
-=head1 SYNOPSIS
-
-B<xenstore-read> [I<OPTION>]... I<PATH> I<VALUE>...
-
-=head1 DESCRIPTION
-
-Write I<VALUE>s to Xenstore I<PATH>s. Multiple pairs I<PATH> I<VALUE> can be
-provided to write them at once - in one Xenstore transaction.
-
-=over
-
-=item B<-s>
-
-Connect to the Xenstore daemon using a local socket only.
-
-=item B<-R>
-
-Write raw value, skip parsing escaped characters (\x..).
-
-=back
-
-=head1 BUGS
-
-Send bugs to xen-devel@lists.xen.org, see
-http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xenstore - interact with Xenstore
+
+=head1 SYNOPSIS
+
+B<xenstore> I<CMD> ...
+
+=head1 DESCRIPTION
+
+A set of utilities for interacting with Xenstore.
+
+=over
+
+=item B<xenstore-chmod>(1)
+
+Sets the permissions of keys.
+
+=item B<xenstore-exists>(1)
+
+Test for the existence of a key.
+
+=item B<xenstore-list>(1)
+
+List keys.
+
+=item B<xenstore-ls>(1)
+
+List keys, values and permissions.
+
+=item B<xenstore-read>(1)
+
+Read the value of a key.
+
+=item B<xenstore-rm>(1)
+
+Remove keys.
+
+=item B<xenstore-watch>(1)
+
+Watch for changes to keys or values.
+
+=item B<xenstore-write>(1)
+
+Add or modify keys and values.
+
+=back
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
+++ /dev/null
-=head1 NAME
-
-xenstore - interact with Xenstore
-
-=head1 SYNOPSIS
-
-B<xenstore> I<CMD> ...
-
-=head1 DESCRIPTION
-
-A set of utilities for interacting with Xenstore.
-
-=over
-
-=item B<xenstore-chmod>(1)
-
-Sets the permissions of keys.
-
-=item B<xenstore-exists>(1)
-
-Test for the existence of a key.
-
-=item B<xenstore-list>(1)
-
-List keys.
-
-=item B<xenstore-ls>(1)
-
-List keys, values and permissions.
-
-=item B<xenstore-read>(1)
-
-Read the value of a key.
-
-=item B<xenstore-rm>(1)
-
-Remove keys.
-
-=item B<xenstore-watch>(1)
-
-Watch for changes to keys or values.
-
-=item B<xenstore-write>(1)
-
-Add or modify keys and values.
-
-=back
-
-=head1 BUGS
-
-Send bugs to xen-devel@lists.xen.org, see
-http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xentop - displays real-time information about a Xen system and domains
+
+=head1 SYNOPSIS
+
+B<xentop> [B<-h>] [B<-V>] [B<-d>SECONDS] [B<-n>] [B<-r>] [B<-v>] [B<-f>]
+[B<-b>] [B<-i>ITERATIONS]
+
+=head1 DESCRIPTION
+
+B<xentop> displays information about the Xen system and domains, in a
+continually-updating manner. Command-line options and interactive commands
+can change the detail and format of the information displayed by B<xentop>.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>, B<--help>
+
+display help and exit
+
+=item B<-V>, B<--version>
+
+output version information and exit
+
+=item B<-d>, B<--delay>=I<SECONDS>
+
+seconds between updates (default 3)
+
+=item B<-n>, B<--networks>
+
+output network information
+
+=item B<-x>, B<--vbds>
+
+output vbd block device data
+
+=item B<-r>, B<--repeat-header>
+
+repeat table header before each domain
+
+=item B<-v>, B<--vcpus>
+
+output VCPU data
+
+=item B<-f>, B<--full-name>
+
+output the full domain name (not truncated)
+
+=item B<-b>, B<--batch>
+
+output data in batch mode (to stdout)
+
+=item B<-i>, B<--iterations>=I<ITERATIONS>
+
+maximum number of iterations xentop should produce before ending
+
+=back
+
+=head1 INTERACTIVE COMMANDS
+
+All interactive commands are case-insensitive.
+
+=over 4
+
+=item B<D>
+
+set delay between updates
+
+=item B<N>
+
+toggle display of network information
+
+=item B<Q>, B<Esc>
+
+quit
+
+=item B<R>
+
+toggle table header before each domain
+
+=item B<S>
+
+cycle sort order
+
+=item B<V>
+
+toggle display of VCPU information
+
+=item B<Arrows>
+
+scroll domain display
+
+=back
+
+=head1 AUTHORS
+
+Written by Judy Fischbach, David Hendricks, and Josh Triplett
+
+=head1 REPORTING BUGS
+
+Report bugs to <xen-devel@lists.xen.org>.
+
+=head1 COPYRIGHT
+
+Copyright 2005 International Business Machines Corp
+
+This is free software; see the source for copying conditions. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+++ /dev/null
-=head1 NAME
-
-xentop - displays real-time information about a Xen system and domains
-
-=head1 SYNOPSIS
-
-B<xentop> [B<-h>] [B<-V>] [B<-d>SECONDS] [B<-n>] [B<-r>] [B<-v>] [B<-f>]
-[B<-b>] [B<-i>ITERATIONS]
-
-=head1 DESCRIPTION
-
-B<xentop> displays information about the Xen system and domains, in a
-continually-updating manner. Command-line options and interactive commands
-can change the detail and format of the information displayed by B<xentop>.
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-h>, B<--help>
-
-display help and exit
-
-=item B<-V>, B<--version>
-
-output version information and exit
-
-=item B<-d>, B<--delay>=I<SECONDS>
-
-seconds between updates (default 3)
-
-=item B<-n>, B<--networks>
-
-output network information
-
-=item B<-x>, B<--vbds>
-
-output vbd block device data
-
-=item B<-r>, B<--repeat-header>
-
-repeat table header before each domain
-
-=item B<-v>, B<--vcpus>
-
-output VCPU data
-
-=item B<-f>, B<--full-name>
-
-output the full domain name (not truncated)
-
-=item B<-b>, B<--batch>
-
-output data in batch mode (to stdout)
-
-=item B<-i>, B<--iterations>=I<ITERATIONS>
-
-maximum number of iterations xentop should produce before ending
-
-=back
-
-=head1 INTERACTIVE COMMANDS
-
-All interactive commands are case-insensitive.
-
-=over 4
-
-=item B<D>
-
-set delay between updates
-
-=item B<N>
-
-toggle display of network information
-
-=item B<Q>, B<Esc>
-
-quit
-
-=item B<R>
-
-toggle table header before each domain
-
-=item B<S>
-
-cycle sort order
-
-=item B<V>
-
-toggle display of VCPU information
-
-=item B<Arrows>
-
-scroll domain display
-
-=back
-
-=head1 AUTHORS
-
-Written by Judy Fischbach, David Hendricks, and Josh Triplett
-
-=head1 REPORTING BUGS
-
-Report bugs to <xen-devel@lists.xen.org>.
-
-=head1 COPYRIGHT
-
-Copyright 2005 International Business Machines Corp
-
-This is free software; see the source for copying conditions. There is NO
-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
--- /dev/null
+=head1 NAME
+
+xentrace - capture Xen trace buffer data
+
+=head1 SYNOPSIS
+
+B<xentrace> [ I<OPTIONS> ] [ I<FILE> ]
+
+=head1 DESCRIPTION
+
+B<xentrace> is used to capture trace buffer data from Xen. The data is
+output in the following binary format (host endian):
+
+ CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32)
+
+Where CPU is the processor number, TSC is the record's timestamp
+(the value of the CPU cycle counter), EVENT is the event ID and
+D1...D5 are the trace data.
+
+Data is dumped onto the standard output (which must not be a TTY) or a
+I<FILE> specified on the command line.
+
+The output should be parsed using the tool xentrace_format, which can
+produce human-readable output in ASCII format.
+
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-t> I<l>, B<--log-thresh>=I<l>
+
+set the threshold number, I<l>, of new records required to trigger a write of
+all new records to the output
+
+=item B<-s> I<p>, B<--poll-sleep>=I<p>
+
+set the time, I<p>, (in milliseconds) to sleep between polling the buffers
+for new data.
+
+=item B<-c> [I<c>|I<CPU-LIST>|I<all>], B<--cpu-mask>=[I<c>|I<CPU-LIST>|I<all>]
+
+This can be: a hex value (of the form 0xNNNN...), or a set of cpu
+ranges as described below, or the string I<all>. Hex values are limited
+to 32 bits. If not specified, the cpu-mask as set during bootup will be
+constructed. If using the I<CPU-LIST> it expects decimal numbers, which
+may be specified as follows:
+
+ "0-3"
+ Trace only on CPUs 0 through 3
+
+ "0,2,5-7"
+ Trace only on CPUs 0, 2, and 5 through 7
+
+ "-3"
+ Trace only on CPUs 0 through 3
+
+ "-3,7"
+ Trace only on CPUs 0 through 3 and 7
+
+ "3-"
+ Trace only on CPUs 3 up to maximum numbers of CPUs the host has
+
+If using I<all> it will use all of the CPUs the host has.
+
+=item B<-e> I<mask>, B<--evt-mask>=I<mask>
+
+set event capture mask. If not specified the TRC_ALL will be used.
+
+=item B<-?>, B<--help>
+
+Give this help list
+
+=item B<--usage>
+
+Give a short usage message
+
+=item B<-V>, B<--version>
+
+Print program version
+
+=back
+
+=head2 Event Classes (Masks)
+
+The following event classes (masks) can be used to filter the events being
+gathered by xentrace:
+
+ ID Description
+
+ 0x0001f000 TRC_GEN
+ 0x0002f000 TRC_SCHED
+ 0x0004f000 TRC_DOM0OP
+ 0x0008f000 TRC_HVM
+ 0x0010f000 TRC_MEM
+ 0xfffff000 TRC_ALL
+
+
+=head2 Event Subclasses (More Masks)
+
+The following event subclasses (masks) can also be used to filter the events being
+gathered by xentrace:
+
+ ID Description
+
+ 0x00081000 TRC_HVM_ENTRYEXIT
+ 0x00082000 TRC_HVM_HANDLER
+
+
+=head2 Events
+
+B<xentrace> collects the following events from the trace buffer:
+
+ ID Description
+
+ 0x0001f001 TRC_LOST_RECORDS
+ 0x0002f001 TRC_SCHED_DOM_ADD
+ 0x0002f002 TRC_SCHED_DOM_REM
+ 0x0002f003 TRC_SCHED_SLEEP
+ 0x0002f004 TRC_SCHED_WAKE
+ 0x0002f005 TRC_SCHED_YIELD
+ 0x0002f006 TRC_SCHED_BLOCK
+ 0x0002f007 TRC_SCHED_SHUTDOWN
+ 0x0002f008 TRC_SCHED_CTL
+ 0x0002f009 TRC_SCHED_ADJDOM
+ 0x0002f010 TRC_SCHED_SWITCH
+ 0x0002f011 TRC_SCHED_S_TIMER_FN
+ 0x0002f012 TRC_SCHED_T_TIMER_FN
+ 0x0002f013 TRC_SCHED_DOM_TIMER_FN
+ 0x0002f014 TRC_SCHED_SWITCH_INFPREV
+ 0x0002f015 TRC_SCHED_SWITCH_INFNEXT
+
+ 0x00081001 TRC_HVM_VMENTRY
+ 0x00081002 TRC_HVM_VMEXIT
+ 0x00082001 TRC_HVM_PF_XEN
+ 0x00082002 TRC_HVM_PF_INJECT
+ 0x00082003 TRC_HVM_INJ_EXC
+ 0x00082004 TRC_HVM_INJ_VIRQ
+ 0x00082005 TRC_HVM_REINJ_VIRQ
+ 0x00082006 TRC_HVM_IO_READ
+ 0x00082007 TRC_HVM_IO_WRITE
+ 0x00082008 TRC_HVM_CR_READ
+ 0x00082009 TRC_HVM_CR_WRITE
+ 0x0008200A TRC_HVM_DR_READ
+ 0x0008200B TRC_HVM_DR_WRITE
+ 0x0008200C TRC_HVM_MSR_READ
+ 0x0008200D TRC_HVM_MSR_WRITE
+ 0x0008200E TRC_HVM_CPUID
+ 0x0008200F TRC_HVM_INTR
+ 0x00082010 TRC_HVM_NMI
+ 0x00082011 TRC_HVM_SMI
+ 0x00082012 TRC_HVM_VMMCALL
+ 0x00082013 TRC_HVM_HLT
+ 0x00082014 TRC_HVM_INVLPG
+
+ 0x0010f001 TRC_MEM_PAGE_GRANT_MAP
+ 0x0010f002 TRC_MEM_PAGE_GRANT_UNMAP
+ 0x0010f003 TRC_MEM_PAGE_GRANT_TRANSFER
+
+=head1 AUTHOR
+
+Mark A. Williamson <mark.a.williamson@intel.com>
+
+=head1 SEE ALSO
+
+xentrace_format(1)
+++ /dev/null
-=head1 NAME
-
-xentrace - capture Xen trace buffer data
-
-=head1 SYNOPSIS
-
-B<xentrace> [ I<OPTIONS> ] [ I<FILE> ]
-
-=head1 DESCRIPTION
-
-B<xentrace> is used to capture trace buffer data from Xen. The data is
-output in the following binary format (host endian):
-
- CPU(uint) TSC(u64) EVENT(u32) D1 D2 D3 D4 D5 (all u32)
-
-Where CPU is the processor number, TSC is the record's timestamp
-(the value of the CPU cycle counter), EVENT is the event ID and
-D1...D5 are the trace data.
-
-Data is dumped onto the standard output (which must not be a TTY) or a
-I<FILE> specified on the command line.
-
-The output should be parsed using the tool xentrace_format, which can
-produce human-readable output in ASCII format.
-
-
-=head1 OPTIONS
-
-=over 4
-
-=item B<-t> I<l>, B<--log-thresh>=I<l>
-
-set the threshold number, I<l>, of new records required to trigger a write of
-all new records to the output
-
-=item B<-s> I<p>, B<--poll-sleep>=I<p>
-
-set the time, I<p>, (in milliseconds) to sleep between polling the buffers
-for new data.
-
-=item B<-c> [I<c>|I<CPU-LIST>|I<all>], B<--cpu-mask>=[I<c>|I<CPU-LIST>|I<all>]
-
-This can be: a hex value (of the form 0xNNNN...), or a set of cpu
-ranges as described below, or the string I<all>. Hex values are limited
-to 32 bits. If not specified, the cpu-mask as set during bootup will be
-constructed. If using the I<CPU-LIST> it expects decimal numbers, which
-may be specified as follows:
-
- "0-3"
- Trace only on CPUs 0 through 3
-
- "0,2,5-7"
- Trace only on CPUs 0, 2, and 5 through 7
-
- "-3"
- Trace only on CPUs 0 through 3
-
- "-3,7"
- Trace only on CPUs 0 through 3 and 7
-
- "3-"
- Trace only on CPUs 3 up to maximum numbers of CPUs the host has
-
-If using I<all> it will use all of the CPUs the host has.
-
-=item B<-e> I<mask>, B<--evt-mask>=I<mask>
-
-set event capture mask. If not specified the TRC_ALL will be used.
-
-=item B<-?>, B<--help>
-
-Give this help list
-
-=item B<--usage>
-
-Give a short usage message
-
-=item B<-V>, B<--version>
-
-Print program version
-
-=back
-
-=head2 Event Classes (Masks)
-
-The following event classes (masks) can be used to filter the events being
-gathered by xentrace:
-
- ID Description
-
- 0x0001f000 TRC_GEN
- 0x0002f000 TRC_SCHED
- 0x0004f000 TRC_DOM0OP
- 0x0008f000 TRC_HVM
- 0x0010f000 TRC_MEM
- 0xfffff000 TRC_ALL
-
-
-=head2 Event Subclasses (More Masks)
-
-The following event subclasses (masks) can also be used to filter the events being
-gathered by xentrace:
-
- ID Description
-
- 0x00081000 TRC_HVM_ENTRYEXIT
- 0x00082000 TRC_HVM_HANDLER
-
-
-=head2 Events
-
-B<xentrace> collects the following events from the trace buffer:
-
- ID Description
-
- 0x0001f001 TRC_LOST_RECORDS
- 0x0002f001 TRC_SCHED_DOM_ADD
- 0x0002f002 TRC_SCHED_DOM_REM
- 0x0002f003 TRC_SCHED_SLEEP
- 0x0002f004 TRC_SCHED_WAKE
- 0x0002f005 TRC_SCHED_YIELD
- 0x0002f006 TRC_SCHED_BLOCK
- 0x0002f007 TRC_SCHED_SHUTDOWN
- 0x0002f008 TRC_SCHED_CTL
- 0x0002f009 TRC_SCHED_ADJDOM
- 0x0002f010 TRC_SCHED_SWITCH
- 0x0002f011 TRC_SCHED_S_TIMER_FN
- 0x0002f012 TRC_SCHED_T_TIMER_FN
- 0x0002f013 TRC_SCHED_DOM_TIMER_FN
- 0x0002f014 TRC_SCHED_SWITCH_INFPREV
- 0x0002f015 TRC_SCHED_SWITCH_INFNEXT
-
- 0x00081001 TRC_HVM_VMENTRY
- 0x00081002 TRC_HVM_VMEXIT
- 0x00082001 TRC_HVM_PF_XEN
- 0x00082002 TRC_HVM_PF_INJECT
- 0x00082003 TRC_HVM_INJ_EXC
- 0x00082004 TRC_HVM_INJ_VIRQ
- 0x00082005 TRC_HVM_REINJ_VIRQ
- 0x00082006 TRC_HVM_IO_READ
- 0x00082007 TRC_HVM_IO_WRITE
- 0x00082008 TRC_HVM_CR_READ
- 0x00082009 TRC_HVM_CR_WRITE
- 0x0008200A TRC_HVM_DR_READ
- 0x0008200B TRC_HVM_DR_WRITE
- 0x0008200C TRC_HVM_MSR_READ
- 0x0008200D TRC_HVM_MSR_WRITE
- 0x0008200E TRC_HVM_CPUID
- 0x0008200F TRC_HVM_INTR
- 0x00082010 TRC_HVM_NMI
- 0x00082011 TRC_HVM_SMI
- 0x00082012 TRC_HVM_VMMCALL
- 0x00082013 TRC_HVM_HLT
- 0x00082014 TRC_HVM_INVLPG
-
- 0x0010f001 TRC_MEM_PAGE_GRANT_MAP
- 0x0010f002 TRC_MEM_PAGE_GRANT_UNMAP
- 0x0010f003 TRC_MEM_PAGE_GRANT_TRANSFER
-
-=head1 AUTHOR
-
-Mark A. Williamson <mark.a.williamson@intel.com>
-
-=head1 SEE ALSO
-
-xentrace_format(1)
--- /dev/null
+=head1 NAME
+
+xentrace_format - pretty-print Xen trace data
+
+=head1 SYNOPSIS
+
+B<xentrace_format> [ I<DEFS-FILE> ]
+
+=head1 DESCRIPTION
+
+B<xentrace_format> parses trace data in B<xentrace> binary format from
+standard input and reformats it according to the rules in a file of
+definitions (I<DEFS-FILE>), printing to standard output.
+
+The rules in I<DEFS-FILE> should have the format shown below:
+
+I<event_id> I<whitespace> I<format>
+
+Each rule should start on a new line.
+
+The format string may include format specifiers, such as:
+%(cpu)d, %(tsc)d, %(event)d, %(1)d, %(2)d, %(3)d, %(4)d, %(5)d
+
+[ the `d' format specifier output in decimal, alternatively `x'
+ will output in hexadecimal and `o' will output in octal ]
+
+These correspond to the CPU number, event ID, timestamp counter and
+the 5 data fields from the trace record. There should be one such
+rule for each type of event to be pretty-printed (events which do not
+have formatting rules are ignored).
+
+A sample format file for Xen's predefined trace events is available
+in the file tools/xentrace/formats in the Xen source tree.
+
+Depending on your system and the rate at which trace data is produced,
+this script may not be able to keep up with the output of
+B<xentrace> if it is piped directly. In these circumstances you
+should have B<xentrace> output to a file for processing off-line.
+
+=head1 AUTHOR
+
+Mark A. Williamson <mark.a.williamson@intel.com>
+
+=head1 SEE ALSO
+
+xentrace(8)
+++ /dev/null
-=head1 NAME
-
-xentrace_format - pretty-print Xen trace data
-
-=head1 SYNOPSIS
-
-B<xentrace_format> [ I<DEFS-FILE> ]
-
-=head1 DESCRIPTION
-
-B<xentrace_format> parses trace data in B<xentrace> binary format from
-standard input and reformats it according to the rules in a file of
-definitions (I<DEFS-FILE>), printing to standard output.
-
-The rules in I<DEFS-FILE> should have the format shown below:
-
-I<event_id> I<whitespace> I<format>
-
-Each rule should start on a new line.
-
-The format string may include format specifiers, such as:
-%(cpu)d, %(tsc)d, %(event)d, %(1)d, %(2)d, %(3)d, %(4)d, %(5)d
-
-[ the `d' format specifier output in decimal, alternatively `x'
- will output in hexadecimal and `o' will output in octal ]
-
-These correspond to the CPU number, event ID, timestamp counter and
-the 5 data fields from the trace record. There should be one such
-rule for each type of event to be pretty-printed (events which do not
-have formatting rules are ignored).
-
-A sample format file for Xen's predefined trace events is available
-in the file tools/xentrace/formats in the Xen source tree.
-
-Depending on your system and the rate at which trace data is produced,
-this script may not be able to keep up with the output of
-B<xentrace> if it is piped directly. In these circumstances you
-should have B<xentrace> output to a file for processing off-line.
-
-=head1 AUTHOR
-
-Mark A. Williamson <mark.a.williamson@intel.com>
-
-=head1 SEE ALSO
-
-xentrace(8)
--- /dev/null
+=head1 NAME
+
+xl-disk-configuration - XL Disk Configuration Syntax
+
+=head1 SYNTAX
+
+This document specifies the xl config file format disk configuration
+option. It has the following form:
+
+ disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
+
+where each C<DISKSPEC> is in this form:
+
+ [<key>=<value>|<flag>,]*,
+ [<target>, [<format>, [<vdev>, [<access>]]]],
+ [<key>=<value>|<flag>,]*
+ [target=<target>]
+
+For example, these strings are equivalent:
+
+ /dev/vg/guest-volume,,hda
+ /dev/vg/guest-volume,raw,hda,rw
+ format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
+ raw:/dev/vg/guest-volume,hda,w (deprecated, see below)
+
+As are these:
+
+ /root/image.iso,,hdc,cdrom
+ /root/image.iso,,hdc,,cdrom
+ /root/image.iso,raw,hdc,devtype=cdrom
+ format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
+ raw:/root/image.iso,hdc:cdrom,ro (deprecated, see below)
+
+These might be specified in the domain config file like this:
+
+ disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
+
+
+More formally, the string is a series of comma-separated keyword/value
+pairs, flags and positional parameters. Parameters which are not bare
+keywords and which do not contain "=" symbols are assigned to the
+so-far-unspecified positional parameters, in the order below. The
+positional parameters may also be specified explicitly by name.
+
+Each parameter may be specified at most once, either as a positional
+parameter or a named parameter. Default values apply if the parameter
+is not specified, or if it is specified with an empty value (whether
+positionally or explicitly).
+
+Whitespace may appear before each parameter and will be ignored.
+
+=head1 Positional Parameters
+
+=over 4
+
+=item B<target>
+
+=over 4
+
+=item Description
+
+Block device or image file path. When this is used as a path, F</dev>
+will be prepended if the path doesn't start with a '/'.
+
+=item Supported values
+
+N/A
+
+=item Deprecated values
+
+N/A
+
+=item Default value
+
+None. While a path is provided in most cases there is an exception:
+for a cdrom device, lack of this attribute would imply an empty cdrom
+drive.
+
+=item Special syntax
+
+When this parameter is specified by name, ie with the C<target=>
+syntax in the configuration file, it consumes the whole rest of the
+C<DISKSPEC> including trailing whitespaces. Therefore in that case
+it must come last. This is permissible even if an empty value for
+the target was already specified as a positional parameter. This
+is the only way to specify a target string containing metacharacters
+such as commas and (in some cases) colons, which would otherwise be
+misinterpreted.
+
+Future parameter and flag names will start with an ascii letter and
+contain only ascii alphanumerics, hyphens and underscores, and will
+not be legal as vdevs. Targets which might match that syntax
+should not be specified as positional parameters.
+
+=back
+
+=item B<format>
+
+=over 4
+
+=item Description
+
+Specifies the format of image file.
+
+=item Supported values
+
+raw, qcow, qcow2, vhd, qed
+
+=item Deprecated values
+
+None
+
+=item Default value
+
+raw
+
+=back
+
+=item B<vdev>
+
+=over 4
+
+=item Description
+
+Virtual device as seen by the guest (also referred to as guest drive
+designation in some specifications). L<xen-vbd-interface(7)>
+
+=item Supported values
+
+hd[x], xvd[x], sd[x] etc. Please refer to the above specification for
+further details.
+
+=item Deprecated values
+
+None
+
+=item Default Value
+
+None, this parameter is mandatory.
+
+=back
+
+=item B<access>
+
+=over 4
+
+=item Description
+
+Specified access control information. Whether or not the block device is
+provided to the guest in read-only or read-write mode depends on this
+attribute.
+
+=item Supported values
+
+C<ro>, C<r> (specifies read-only)
+
+C<rw>, C<w> (specifies read/write)
+
+=item Deprecated values
+
+None
+
+=item Default value
+
+C<rw> unless devtype=cdrom, in which case C<r>
+
+=back
+
+=back
+
+=head1 Other Parameters And Flags
+
+=over 4
+
+=item B<devtype>=I<DEVTYPE>
+
+=over 4
+
+=item Description
+
+Qualifies virtual device type.
+
+=item Supported values
+
+cdrom
+
+=item Deprecated values
+
+None
+
+=item Mandatory
+
+No
+
+=back
+
+=item B<cdrom>
+
+Convenience alias for "devtype=cdrom".
+
+
+=item B<backend>=I<DOMAIN-NAME>
+
+=over 4
+
+=item Description
+
+Designates a backend domain for the device
+
+=item Supported values
+
+Valid domain names
+
+=item Mandatory
+
+No
+
+=back
+
+Specifies the backend domain which this device should attach to. This
+defaults to domain 0. Specifying another domain requires setting up a
+driver domain which is outside the scope of this document.
+
+
+=item B<backendtype>=I<TYPE>
+
+=over 4
+
+=item Description
+
+Specifies the backend implementation to use
+
+=item Supported values
+
+phy, tap, qdisk
+
+=item Mandatory
+
+No
+
+=item Default value
+
+Automatically determine which backend to use.
+
+=back
+
+This does not affect the guest's view of the device. It controls
+which software implementation of the Xen backend driver is used.
+
+Not all backend drivers support all combinations of other options.
+For example, "phy" does not support formats other than "raw".
+Normally this option should not be specified, in which case libxl will
+automatically determine the most suitable backend.
+
+
+=item B<script>=I<SCRIPT>
+
+Specifies that B<target> is not a normal host path, but rather
+information to be interpreted by the executable program I<SCRIPT>,
+(looked for in F</etc/xen/scripts>, if it doesn't contain a slash).
+
+These scripts are normally called "block-I<SCRIPT>".
+
+
+=item B<direct-io-safe>
+
+=over 4
+
+=item Description
+
+Disables non-O_DIRECT workaround
+
+=item Supported values
+
+absent, present
+
+=item Mandatory
+
+No
+
+=item Default value
+
+absent (workaround may be enabled)
+
+=back
+
+There is a memory lifetime bug in some driver domain (dom0) kernels
+which can cause crashes when using O_DIRECT. The bug occurs due to a
+mismatch between the backend-visible lifetime of pages used for the
+Xen PV network protocol and that expected by the backend kernel's
+networking subsystem. This can cause crashes when using certain
+backends with certain underlying storage.
+
+See:
+ L<http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html>
+
+For this reason, (this version of) the Xen libxl toolstack disables
+O_DIRECT when using the qemu-based Xen PV backend (C<qdisk>).
+
+However, this workaround has performance and scaling implications, and
+it is only necessary if the underlying device is a network filesystem.
+If the underlying device is not, then it is good to disable it; that
+is what this option is for.
+
+This option simply requests that the workaround be disabled. (However,
+not all backends versions which use the workaround understand this
+option, so this is on a best effort basis.)
+
+It's important to note that if you are storing the VM disk on a
+network filesystem or a network block device (NFS or ISCSI) it might
+not be safe to use this option. Otherwise specifying it is safe and
+can give better performances.
+
+If in the future the bug is fixed properly this option will then be
+silently ignored.
+
+
+=item B<discard> / B<no-discard>
+
+=over 4
+
+=item Description
+
+Request that backend advertise discard support to frontend
+
+=item Supported values
+
+discard, no-discard
+
+=item Mandatory
+
+No
+
+=item Default value
+
+discard
+
+=back
+
+An advisory setting for the backend driver, specifying whether to
+advertise discard support (TRIM, UNMAP) to the frontend. The real
+benefit of this option is to be able to force it off rather than on. It
+can be used to disable "hole punching" for file based backends which
+were intentionally created non-sparse to avoid fragmentation of the
+file.
+
+=back
+
+
+=head1 COLO Parameters
+
+=over 4
+
+=item B<colo>
+
+Enable COLO HA for disk. For better understanding block replication on
+QEMU, please refer to: L<http://wiki.qemu.org/Features/BlockReplication>
+Note that the COLO configuration settings should be considered unstable.
+They may change incompatibly in future versions of Xen.
+
+
+=item B<colo-host>
+
+=over 4
+
+=item Description
+
+Secondary host's address
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<colo-port>
+
+=over 4
+
+=item Description
+
+Secondary port. We will run a nbd server on secondary host,
+and the nbd server will listen this port.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<colo-export>
+
+=over 4
+
+=item Description
+
+We will run a nbd server on secondary host, exportname is
+the nbd server's disk export name.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<active-disk>
+
+=over 4
+
+=item Description
+
+This is used by secondary. Secondary guest's write will be buffered in this
+disk.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=item B<hidden-disk>
+
+=over 4
+
+=item Description
+
+This is used by secondary. It buffers the original content that is modified
+by the primary VM.
+
+=item Mandatory
+
+Yes when COLO enabled
+
+=back
+
+=back
+
+
+=head1 Deprecated Parameters, Prefixes And Syntaxes
+
+Deprecated forms are acceptable and are intended work compatibly with
+xend and xl from xen 4.1. In future they may print a warning.
+Support for deprecated parameters and syntaxes are likely to be
+dropped in future versions of xl.
+
+There is support for a deprecated old syntax for C<DISKSPEC>:
+
+ [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
+
+This syntax also supports deprecated prefixes, described below. These
+are found prepended to the format parameter - eg C<tap:aio:qcow:>.
+
+=over 4
+
+=item B<format>
+
+=over 4
+
+=item Description
+
+Specifies the format (deprecated)
+
+=item Supported values
+
+raw: qcow2: vhd:
+
+=back
+
+In xend and old versions of libxl it was necessary to specify the
+format with a prefix. For compatibility, these three prefixes are
+recognised as specifying the corresponding format. They are
+equivalent to C<format=FORMAT> or the specification of B<format>
+(without a colon) as a positional parameter.
+
+
+=item B<script>
+
+=over 4
+
+=item Description
+
+Specifies the script (deprecated)
+
+=item Supported values
+
+iscsi: nbd: enbd: drbd:
+
+=back
+
+In xend and old versions of libxl it was necessary to specify the
+"script" (see above) with a prefix. For compatibility, these four
+prefixes are recognised as specifying the corresponding script. They
+are equivalent to C<script=block-SCRIPT>.
+
+
+=item B<deprecated-prefix>
+
+=over 4
+
+=item Description
+
+Deprecated prefix, ignored
+
+=item Supported values
+
+tapdisk: tap2: aio: ioemu: file: phy:
+
+=back
+
+Various prefixes were required by xend and older versions of libxl to
+make the block devices work. In some cases these options would
+override the backend type, but in other cases they would be ignored in
+favour of "making it work"; in yet other cases it would be necessary
+to specify several of these, for example:
+
+ tap:aio:/some/path...
+
+All of these prefixes are now stripped and ignored.
+
+=back
+
+=head2 Missing format and empty target
+
+The following syntax is also supported:
+
+ ,<vdev>:<devtype>,<access> (deprecated)
+
+This is solely for compatibility with xend's syntax for empty cdroms,
+which is (for example) C<,hdc:cdrom,r>.
+++ /dev/null
-=head1 NAME
-
-xl-disk-configuration - XL Disk Configuration Syntax
-
-=head1 SYNTAX
-
-This document specifies the xl config file format disk configuration
-option. It has the following form:
-
- disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
-
-where each C<DISKSPEC> is in this form:
-
- [<key>=<value>|<flag>,]*,
- [<target>, [<format>, [<vdev>, [<access>]]]],
- [<key>=<value>|<flag>,]*
- [target=<target>]
-
-For example, these strings are equivalent:
-
- /dev/vg/guest-volume,,hda
- /dev/vg/guest-volume,raw,hda,rw
- format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
- raw:/dev/vg/guest-volume,hda,w (deprecated, see below)
-
-As are these:
-
- /root/image.iso,,hdc,cdrom
- /root/image.iso,,hdc,,cdrom
- /root/image.iso,raw,hdc,devtype=cdrom
- format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
- raw:/root/image.iso,hdc:cdrom,ro (deprecated, see below)
-
-These might be specified in the domain config file like this:
-
- disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
-
-
-More formally, the string is a series of comma-separated keyword/value
-pairs, flags and positional parameters. Parameters which are not bare
-keywords and which do not contain "=" symbols are assigned to the
-so-far-unspecified positional parameters, in the order below. The
-positional parameters may also be specified explicitly by name.
-
-Each parameter may be specified at most once, either as a positional
-parameter or a named parameter. Default values apply if the parameter
-is not specified, or if it is specified with an empty value (whether
-positionally or explicitly).
-
-Whitespace may appear before each parameter and will be ignored.
-
-=head1 Positional Parameters
-
-=over 4
-
-=item B<target>
-
-=over 4
-
-=item Description
-
-Block device or image file path. When this is used as a path, F</dev>
-will be prepended if the path doesn't start with a '/'.
-
-=item Supported values
-
-N/A
-
-=item Deprecated values
-
-N/A
-
-=item Default value
-
-None. While a path is provided in most cases there is an exception:
-for a cdrom device, lack of this attribute would imply an empty cdrom
-drive.
-
-=item Special syntax
-
-When this parameter is specified by name, ie with the C<target=>
-syntax in the configuration file, it consumes the whole rest of the
-C<DISKSPEC> including trailing whitespaces. Therefore in that case
-it must come last. This is permissible even if an empty value for
-the target was already specified as a positional parameter. This
-is the only way to specify a target string containing metacharacters
-such as commas and (in some cases) colons, which would otherwise be
-misinterpreted.
-
-Future parameter and flag names will start with an ascii letter and
-contain only ascii alphanumerics, hyphens and underscores, and will
-not be legal as vdevs. Targets which might match that syntax
-should not be specified as positional parameters.
-
-=back
-
-=item B<format>
-
-=over 4
-
-=item Description
-
-Specifies the format of image file.
-
-=item Supported values
-
-raw, qcow, qcow2, vhd, qed
-
-=item Deprecated values
-
-None
-
-=item Default value
-
-raw
-
-=back
-
-=item B<vdev>
-
-=over 4
-
-=item Description
-
-Virtual device as seen by the guest (also referred to as guest drive
-designation in some specifications). L<xen-vbd-interface(7)>
-
-=item Supported values
-
-hd[x], xvd[x], sd[x] etc. Please refer to the above specification for
-further details.
-
-=item Deprecated values
-
-None
-
-=item Default Value
-
-None, this parameter is mandatory.
-
-=back
-
-=item B<access>
-
-=over 4
-
-=item Description
-
-Specified access control information. Whether or not the block device is
-provided to the guest in read-only or read-write mode depends on this
-attribute.
-
-=item Supported values
-
-C<ro>, C<r> (specifies read-only)
-
-C<rw>, C<w> (specifies read/write)
-
-=item Deprecated values
-
-None
-
-=item Default value
-
-C<rw> unless devtype=cdrom, in which case C<r>
-
-=back
-
-=back
-
-=head1 Other Parameters And Flags
-
-=over 4
-
-=item B<devtype>=I<DEVTYPE>
-
-=over 4
-
-=item Description
-
-Qualifies virtual device type.
-
-=item Supported values
-
-cdrom
-
-=item Deprecated values
-
-None
-
-=item Mandatory
-
-No
-
-=back
-
-=item B<cdrom>
-
-Convenience alias for "devtype=cdrom".
-
-
-=item B<backend>=I<DOMAIN-NAME>
-
-=over 4
-
-=item Description
-
-Designates a backend domain for the device
-
-=item Supported values
-
-Valid domain names
-
-=item Mandatory
-
-No
-
-=back
-
-Specifies the backend domain which this device should attach to. This
-defaults to domain 0. Specifying another domain requires setting up a
-driver domain which is outside the scope of this document.
-
-
-=item B<backendtype>=I<TYPE>
-
-=over 4
-
-=item Description
-
-Specifies the backend implementation to use
-
-=item Supported values
-
-phy, tap, qdisk
-
-=item Mandatory
-
-No
-
-=item Default value
-
-Automatically determine which backend to use.
-
-=back
-
-This does not affect the guest's view of the device. It controls
-which software implementation of the Xen backend driver is used.
-
-Not all backend drivers support all combinations of other options.
-For example, "phy" does not support formats other than "raw".
-Normally this option should not be specified, in which case libxl will
-automatically determine the most suitable backend.
-
-
-=item B<script>=I<SCRIPT>
-
-Specifies that B<target> is not a normal host path, but rather
-information to be interpreted by the executable program I<SCRIPT>,
-(looked for in F</etc/xen/scripts>, if it doesn't contain a slash).
-
-These scripts are normally called "block-I<SCRIPT>".
-
-
-=item B<direct-io-safe>
-
-=over 4
-
-=item Description
-
-Disables non-O_DIRECT workaround
-
-=item Supported values
-
-absent, present
-
-=item Mandatory
-
-No
-
-=item Default value
-
-absent (workaround may be enabled)
-
-=back
-
-There is a memory lifetime bug in some driver domain (dom0) kernels
-which can cause crashes when using O_DIRECT. The bug occurs due to a
-mismatch between the backend-visible lifetime of pages used for the
-Xen PV network protocol and that expected by the backend kernel's
-networking subsystem. This can cause crashes when using certain
-backends with certain underlying storage.
-
-See:
- L<http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html>
-
-For this reason, (this version of) the Xen libxl toolstack disables
-O_DIRECT when using the qemu-based Xen PV backend (C<qdisk>).
-
-However, this workaround has performance and scaling implications, and
-it is only necessary if the underlying device is a network filesystem.
-If the underlying device is not, then it is good to disable it; that
-is what this option is for.
-
-This option simply requests that the workaround be disabled. (However,
-not all backends versions which use the workaround understand this
-option, so this is on a best effort basis.)
-
-It's important to note that if you are storing the VM disk on a
-network filesystem or a network block device (NFS or ISCSI) it might
-not be safe to use this option. Otherwise specifying it is safe and
-can give better performances.
-
-If in the future the bug is fixed properly this option will then be
-silently ignored.
-
-
-=item B<discard> / B<no-discard>
-
-=over 4
-
-=item Description
-
-Request that backend advertise discard support to frontend
-
-=item Supported values
-
-discard, no-discard
-
-=item Mandatory
-
-No
-
-=item Default value
-
-discard
-
-=back
-
-An advisory setting for the backend driver, specifying whether to
-advertise discard support (TRIM, UNMAP) to the frontend. The real
-benefit of this option is to be able to force it off rather than on. It
-can be used to disable "hole punching" for file based backends which
-were intentionally created non-sparse to avoid fragmentation of the
-file.
-
-=back
-
-
-=head1 COLO Parameters
-
-=over 4
-
-=item B<colo>
-
-Enable COLO HA for disk. For better understanding block replication on
-QEMU, please refer to: L<http://wiki.qemu.org/Features/BlockReplication>
-Note that the COLO configuration settings should be considered unstable.
-They may change incompatibly in future versions of Xen.
-
-
-=item B<colo-host>
-
-=over 4
-
-=item Description
-
-Secondary host's address
-
-=item Mandatory
-
-Yes when COLO enabled
-
-=back
-
-=item B<colo-port>
-
-=over 4
-
-=item Description
-
-Secondary port. We will run a nbd server on secondary host,
-and the nbd server will listen this port.
-
-=item Mandatory
-
-Yes when COLO enabled
-
-=back
-
-=item B<colo-export>
-
-=over 4
-
-=item Description
-
-We will run a nbd server on secondary host, exportname is
-the nbd server's disk export name.
-
-=item Mandatory
-
-Yes when COLO enabled
-
-=back
-
-=item B<active-disk>
-
-=over 4
-
-=item Description
-
-This is used by secondary. Secondary guest's write will be buffered in this
-disk.
-
-=item Mandatory
-
-Yes when COLO enabled
-
-=back
-
-=item B<hidden-disk>
-
-=over 4
-
-=item Description
-
-This is used by secondary. It buffers the original content that is modified
-by the primary VM.
-
-=item Mandatory
-
-Yes when COLO enabled
-
-=back
-
-=back
-
-
-=head1 Deprecated Parameters, Prefixes And Syntaxes
-
-Deprecated forms are acceptable and are intended work compatibly with
-xend and xl from xen 4.1. In future they may print a warning.
-Support for deprecated parameters and syntaxes are likely to be
-dropped in future versions of xl.
-
-There is support for a deprecated old syntax for C<DISKSPEC>:
-
- [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
-
-This syntax also supports deprecated prefixes, described below. These
-are found prepended to the format parameter - eg C<tap:aio:qcow:>.
-
-=over 4
-
-=item B<format>
-
-=over 4
-
-=item Description
-
-Specifies the format (deprecated)
-
-=item Supported values
-
-raw: qcow2: vhd:
-
-=back
-
-In xend and old versions of libxl it was necessary to specify the
-format with a prefix. For compatibility, these three prefixes are
-recognised as specifying the corresponding format. They are
-equivalent to C<format=FORMAT> or the specification of B<format>
-(without a colon) as a positional parameter.
-
-
-=item B<script>
-
-=over 4
-
-=item Description
-
-Specifies the script (deprecated)
-
-=item Supported values
-
-iscsi: nbd: enbd: drbd:
-
-=back
-
-In xend and old versions of libxl it was necessary to specify the
-"script" (see above) with a prefix. For compatibility, these four
-prefixes are recognised as specifying the corresponding script. They
-are equivalent to C<script=block-SCRIPT>.
-
-
-=item B<deprecated-prefix>
-
-=over 4
-
-=item Description
-
-Deprecated prefix, ignored
-
-=item Supported values
-
-tapdisk: tap2: aio: ioemu: file: phy:
-
-=back
-
-Various prefixes were required by xend and older versions of libxl to
-make the block devices work. In some cases these options would
-override the backend type, but in other cases they would be ignored in
-favour of "making it work"; in yet other cases it would be necessary
-to specify several of these, for example:
-
- tap:aio:/some/path...
-
-All of these prefixes are now stripped and ignored.
-
-=back
-
-=head2 Missing format and empty target
-
-The following syntax is also supported:
-
- ,<vdev>:<devtype>,<access> (deprecated)
-
-This is solely for compatibility with xend's syntax for empty cdroms,
-which is (for example) C<,hdc:cdrom,r>.
--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+xl-network-configuration - XL Network Configuration Syntax
+
+
+=head1 SYNTAX
+
+This document specifies the xl config file format vif configuration
+option. It has the following form:
+
+ vif = [ '<vifspec>', '<vifspec>', ... ]
+
+where each vifspec is in this form:
+
+ [<key>=<value>|<flag>,]
+
+For example:
+
+ 'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
+ 'mac=00:16:3E:74:34:32'
+ '' # The empty string
+
+These might be specified in the domain config file like this:
+
+ vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]
+
+More formally, the string is a series of comma-separated keyword/value
+pairs. All keywords are optional.
+
+Each device has a C<DEVID> which is its index within the vif list, starting from 0.
+
+
+=head1 Keywords
+
+
+=head2 mac
+
+If specified then this option specifies the MAC address inside the
+guest of this VIF device. The value is a 48-bit number represented as
+six groups of two hexadecimal digits, separated by colons (:).
+
+The default if this keyword is not specified is to be automatically
+generate a MAC address inside the space assigned to Xen's
+L<Organizationally Unique Identifier|http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier> (00:16:3e).
+
+If you are choosing a MAC address then it is strongly recommend to
+follow one of the following strategies:
+
+=over
+
+=item *
+
+Generate a random sequence of 6 byte, set the locally administered
+bit (bit 2 of the first byte) and clear the multicast bit (bit 1
+of the first byte). In other words the first byte should have the
+bit pattern xxxxxx10 (where x is a randomly generated bit) and the
+remaining 5 bytes are randomly generated See
+[http://en.wikipedia.org/wiki/MAC_address] for more details the
+structure of a MAC address.
+
+
+=item *
+
+Allocate an address from within the space defined by your
+organization's OUI (if you have one) following your organization's
+procedures for doing so.
+
+
+=item *
+
+Allocate an address from within the space defined by Xen's OUI
+(00:16:3e). Taking care not to clash with other users of the
+physical network segment where this VIF will reside.
+
+
+=back
+
+If you have an OUI for your own use then that is the preferred
+strategy. Otherwise in general you should prefer to generate a random
+MAC and set the locally administered bit since this allows for more
+bits of randomness than using the Xen OUI.
+
+
+=head2 bridge
+
+Specifies the name of the network bridge which this VIF should be
+added to. The default is C<xenbr0>. The bridge must be configured using
+your distribution's network configuration tools. See the L<wiki|http://wiki.xen.org/wiki/HostConfiguration/Networking>
+for guidance and examples.
+
+
+=head2 gatewaydev
+
+Specifies the name of the network interface which has an IP and which
+is in the network the VIF should communicate with. This is used in the host
+by the vif-route hotplug script. See L<wiki|http://wiki.xen.org/wiki/Vif-route> for guidance and
+examples.
+
+NOTE: netdev is a deprecated alias of this option.
+
+
+=head2 type
+
+This keyword is valid for HVM guests only.
+
+Specifies the type of device to valid values are:
+
+=over
+
+=item *
+
+C<ioemu> (default) -- this device will be provided as an emulate
+device to the guest and also as a paravirtualised device which the
+guest may choose to use instead if it has suitable drivers
+available.
+
+
+=item *
+
+C<vif> -- this device will be provided as a paravirtualised device
+only.
+
+
+=back
+
+
+=head2 model
+
+This keyword is valid for HVM guest devices with C<type=ioemu> only.
+
+Specifies the type device to emulated for this guest. Valid values
+are:
+
+=over
+
+=item *
+
+C<rtl8139> (default) -- Realtek RTL8139
+
+
+=item *
+
+C<e1000> -- Intel E1000
+
+
+=item *
+
+in principle any device supported by your device model
+
+
+=back
+
+
+=head2 vifname
+
+Specifies the backend device name for the virtual device.
+
+If the domain is an HVM domain then the associated emulated (tap)
+device will have a "-emu" suffice added.
+
+The default name for the virtual device is C<vifDOMID.DEVID> where
+C<DOMID> is the guest domain ID and C<DEVID> is the device
+number. Likewise the default tap name is C<vifDOMID.DEVID-emu>.
+
+
+=head2 script
+
+Specifies the hotplug script to run to configure this device (e.g. to
+add it to the relevant bridge). Defaults to
+C<XEN_SCRIPT_DIR/vif-bridge> but can be set to any script. Some example
+scripts are installed in C<XEN_SCRIPT_DIR>.
+
+
+=head2 ip
+
+Specifies the IP address for the device, the default is not to
+specify an IP address.
+
+What, if any, effect this has depends on the hotplug script which is
+configured. A typically behaviour (exhibited by the example hotplug
+scripts) if set might be to configure firewall rules to allow only the
+specified IP address to be used by the guest (blocking all others).
+
+
+=head2 backend
+
+Specifies the backend domain which this device should attach to. This
+defaults to domain 0. Specifying another domain requires setting up a
+driver domain which is outside the scope of this document.
+
+
+=head2 rate
+
+Specifies the rate at which the outgoing traffic will be limited to.
+The default if this keyword is not specified is unlimited.
+
+The rate may be specified as "/s" or optionally "/s@".
+
+=over
+
+=item *
+
+C<RATE> is in bytes and can accept suffixes:
+
+=over
+
+=item *
+
+GB, MB, KB, B for bytes.
+
+
+=item *
+
+Gb, Mb, Kb, b for bits.
+
+
+=back
+
+
+
+=item *
+
+C<INTERVAL> is in microseconds and can accept suffixes: ms, us, s.
+It determines the frequency at which the vif transmission credit
+is replenished. The default is 50ms.
+
+
+=back
+
+Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
+available credit will be equivalent of the traffic you would have done
+at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
+replenished every 20,000 us.
+
+For example:
+
+ 'rate=10Mb/s' -- meaning up to 10 megabits every second
+ 'rate=250KB/s' -- meaning up to 250 kilobytes every second
+ 'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
+
+NOTE: The actual underlying limits of rate limiting are dependent
+on the underlying netback implementation.
+
+
+=head2 devid
+
+Specifies the devid manually instead of letting xl choose the lowest index available.
+
+NOTE: This should not be set unless you have a reason to.
+++ /dev/null
-=encoding utf8
-
-=head1 NAME
-
-xl-network-configuration - XL Network Configuration Syntax
-
-
-=head1 SYNTAX
-
-This document specifies the xl config file format vif configuration
-option. It has the following form:
-
- vif = [ '<vifspec>', '<vifspec>', ... ]
-
-where each vifspec is in this form:
-
- [<key>=<value>|<flag>,]
-
-For example:
-
- 'mac=00:16:3E:74:3d:76,model=rtl8139,bridge=xenbr0'
- 'mac=00:16:3E:74:34:32'
- '' # The empty string
-
-These might be specified in the domain config file like this:
-
- vif = [ 'mac=00:16:3E:74:34:32', 'mac=00:16:3e:5f:48:e4,bridge=xenbr1' ]
-
-More formally, the string is a series of comma-separated keyword/value
-pairs. All keywords are optional.
-
-Each device has a C<DEVID> which is its index within the vif list, starting from 0.
-
-
-=head1 Keywords
-
-
-=head2 mac
-
-If specified then this option specifies the MAC address inside the
-guest of this VIF device. The value is a 48-bit number represented as
-six groups of two hexadecimal digits, separated by colons (:).
-
-The default if this keyword is not specified is to be automatically
-generate a MAC address inside the space assigned to Xen's
-L<Organizationally Unique Identifier|http://en.wikipedia.org/wiki/Organizationally_Unique_Identifier> (00:16:3e).
-
-If you are choosing a MAC address then it is strongly recommend to
-follow one of the following strategies:
-
-=over
-
-=item *
-
-Generate a random sequence of 6 byte, set the locally administered
-bit (bit 2 of the first byte) and clear the multicast bit (bit 1
-of the first byte). In other words the first byte should have the
-bit pattern xxxxxx10 (where x is a randomly generated bit) and the
-remaining 5 bytes are randomly generated See
-[http://en.wikipedia.org/wiki/MAC_address] for more details the
-structure of a MAC address.
-
-
-=item *
-
-Allocate an address from within the space defined by your
-organization's OUI (if you have one) following your organization's
-procedures for doing so.
-
-
-=item *
-
-Allocate an address from within the space defined by Xen's OUI
-(00:16:3e). Taking care not to clash with other users of the
-physical network segment where this VIF will reside.
-
-
-=back
-
-If you have an OUI for your own use then that is the preferred
-strategy. Otherwise in general you should prefer to generate a random
-MAC and set the locally administered bit since this allows for more
-bits of randomness than using the Xen OUI.
-
-
-=head2 bridge
-
-Specifies the name of the network bridge which this VIF should be
-added to. The default is C<xenbr0>. The bridge must be configured using
-your distribution's network configuration tools. See the L<wiki|http://wiki.xen.org/wiki/HostConfiguration/Networking>
-for guidance and examples.
-
-
-=head2 gatewaydev
-
-Specifies the name of the network interface which has an IP and which
-is in the network the VIF should communicate with. This is used in the host
-by the vif-route hotplug script. See L<wiki|http://wiki.xen.org/wiki/Vif-route> for guidance and
-examples.
-
-NOTE: netdev is a deprecated alias of this option.
-
-
-=head2 type
-
-This keyword is valid for HVM guests only.
-
-Specifies the type of device to valid values are:
-
-=over
-
-=item *
-
-C<ioemu> (default) -- this device will be provided as an emulate
-device to the guest and also as a paravirtualised device which the
-guest may choose to use instead if it has suitable drivers
-available.
-
-
-=item *
-
-C<vif> -- this device will be provided as a paravirtualised device
-only.
-
-
-=back
-
-
-=head2 model
-
-This keyword is valid for HVM guest devices with C<type=ioemu> only.
-
-Specifies the type device to emulated for this guest. Valid values
-are:
-
-=over
-
-=item *
-
-C<rtl8139> (default) -- Realtek RTL8139
-
-
-=item *
-
-C<e1000> -- Intel E1000
-
-
-=item *
-
-in principle any device supported by your device model
-
-
-=back
-
-
-=head2 vifname
-
-Specifies the backend device name for the virtual device.
-
-If the domain is an HVM domain then the associated emulated (tap)
-device will have a "-emu" suffice added.
-
-The default name for the virtual device is C<vifDOMID.DEVID> where
-C<DOMID> is the guest domain ID and C<DEVID> is the device
-number. Likewise the default tap name is C<vifDOMID.DEVID-emu>.
-
-
-=head2 script
-
-Specifies the hotplug script to run to configure this device (e.g. to
-add it to the relevant bridge). Defaults to
-C<XEN_SCRIPT_DIR/vif-bridge> but can be set to any script. Some example
-scripts are installed in C<XEN_SCRIPT_DIR>.
-
-
-=head2 ip
-
-Specifies the IP address for the device, the default is not to
-specify an IP address.
-
-What, if any, effect this has depends on the hotplug script which is
-configured. A typically behaviour (exhibited by the example hotplug
-scripts) if set might be to configure firewall rules to allow only the
-specified IP address to be used by the guest (blocking all others).
-
-
-=head2 backend
-
-Specifies the backend domain which this device should attach to. This
-defaults to domain 0. Specifying another domain requires setting up a
-driver domain which is outside the scope of this document.
-
-
-=head2 rate
-
-Specifies the rate at which the outgoing traffic will be limited to.
-The default if this keyword is not specified is unlimited.
-
-The rate may be specified as "/s" or optionally "/s@".
-
-=over
-
-=item *
-
-C<RATE> is in bytes and can accept suffixes:
-
-=over
-
-=item *
-
-GB, MB, KB, B for bytes.
-
-
-=item *
-
-Gb, Mb, Kb, b for bits.
-
-
-=back
-
-
-
-=item *
-
-C<INTERVAL> is in microseconds and can accept suffixes: ms, us, s.
-It determines the frequency at which the vif transmission credit
-is replenished. The default is 50ms.
-
-
-=back
-
-Vif rate limiting is credit-based. It means that for "1MB/s@20ms", the
-available credit will be equivalent of the traffic you would have done
-at "1MB/s" during 20ms. This will results in a credit of 20,000 bytes
-replenished every 20,000 us.
-
-For example:
-
- 'rate=10Mb/s' -- meaning up to 10 megabits every second
- 'rate=250KB/s' -- meaning up to 250 kilobytes every second
- 'rate=1MB/s@20ms' -- meaning 20,000 bytes in every 20 millisecond period
-
-NOTE: The actual underlying limits of rate limiting are dependent
-on the underlying netback implementation.
-
-
-=head2 devid
-
-Specifies the devid manually instead of letting xl choose the lowest index available.
-
-NOTE: This should not be set unless you have a reason to.
--- /dev/null
+=encoding utf8
+
+=head1 NAME
+
+xl-numa-placement - Guest Automatic NUMA Placement in libxl and xl
+
+=head1 DESCRIPTION
+
+=head2 Rationale
+
+NUMA (which stands for Non-Uniform Memory Access) means that the memory
+accessing times of a program running on a CPU depends on the relative
+distance between that CPU and that memory. In fact, most of the NUMA
+systems are built in such a way that each processor has its local memory,
+on which it can operate very fast. On the other hand, getting and storing
+data from and on remote memory (that is, memory local to some other processor)
+is quite more complex and slow. On these machines, a NUMA node is usually
+defined as a set of processor cores (typically a physical CPU package) and
+the memory directly attached to the set of cores.
+
+NUMA awareness becomes very important as soon as many domains start
+running memory-intensive workloads on a shared host. In fact, the cost
+of accessing non node-local memory locations is very high, and the
+performance degradation is likely to be noticeable.
+
+For more information, have a look at the L<Xen NUMA Introduction|http://wiki.xen.org/wiki/Xen_NUMA_Introduction>
+page on the Wiki.
+
+
+=head2 Xen and NUMA machines: the concept of I<node-affinity>
+
+The Xen hypervisor deals with NUMA machines throughout the concept of
+I<node-affinity>. The node-affinity of a domain is the set of NUMA nodes
+of the host where the memory for the domain is being allocated (mostly,
+at domain creation time). This is, at least in principle, different and
+unrelated with the vCPU (hard and soft, see below) scheduling affinity,
+which instead is the set of pCPUs where the vCPU is allowed (or prefers)
+to run.
+
+Of course, despite the fact that they belong to and affect different
+subsystems, the domain node-affinity and the vCPUs affinity are not
+completely independent.
+In fact, if the domain node-affinity is not explicitly specified by the
+user, via the proper libxl calls or xl config item, it will be computed
+basing on the vCPUs' scheduling affinity.
+
+Notice that, even if the node affinity of a domain may change on-line,
+it is very important to "place" the domain correctly when it is fist
+created, as the most of its memory is allocated at that time and can
+not (for now) be moved easily.
+
+
+=head2 Placing via pinning and cpupools
+
+The simplest way of placing a domain on a NUMA node is setting the hard
+scheduling affinity of the domain's vCPUs to the pCPUs of the node. This
+also goes under the name of vCPU pinning, and can be done through the
+"cpus=" option in the config file (more about this below). Another option
+is to pool together the pCPUs spanning the node and put the domain in
+such a I<cpupool> with the "pool=" config option (as documented in our
+L<Wiki|http://wiki.xen.org/wiki/Cpupools_Howto>).
+
+In both the above cases, the domain will not be able to execute outside
+the specified set of pCPUs for any reasons, even if all those pCPUs are
+busy doing something else while there are others, idle, pCPUs.
+
+So, when doing this, local memory accesses are 100% guaranteed, but that
+may come at he cost of some load imbalances.
+
+
+=head2 NUMA aware scheduling
+
+If using the credit1 scheduler, and starting from Xen 4.3, the scheduler
+itself always tries to run the domain's vCPUs on one of the nodes in
+its node-affinity. Only if that turns out to be impossible, it will just
+pick any free pCPU. Locality of access is less guaranteed than in the
+pinning case, but that comes along with better chances to exploit all
+the host resources (e.g., the pCPUs).
+
+Starting from Xen 4.5, credit1 supports two forms of affinity: hard and
+soft, both on a per-vCPU basis. This means each vCPU can have its own
+soft affinity, stating where such vCPU prefers to execute on. This is
+less strict than what it (also starting from 4.5) is called hard affinity,
+as the vCPU can potentially run everywhere, it just prefers some pCPUs
+rather than others.
+In Xen 4.5, therefore, NUMA-aware scheduling is achieved by matching the
+soft affinity of the vCPUs of a domain with its node-affinity.
+
+In fact, as it was for 4.3, if all the pCPUs in a vCPU's soft affinity
+are busy, it is possible for the domain to run outside from there. The
+idea is that slower execution (due to remote memory accesses) is still
+better than no execution at all (as it would happen with pinning). For
+this reason, NUMA aware scheduling has the potential of bringing
+substantial performances benefits, although this will depend on the
+workload.
+
+Notice that, for each vCPU, the following three scenarios are possbile:
+
+=over
+
+=item *
+
+a vCPU I<is pinned> to some pCPUs and I<does not have> any soft affinity
+In this case, the vCPU is always scheduled on one of the pCPUs to which
+it is pinned, without any specific peference among them.
+
+
+=item *
+
+a vCPU I<has> its own soft affinity and I<is not> pinned to any particular
+pCPU. In this case, the vCPU can run on every pCPU. Nevertheless, the
+scheduler will try to have it running on one of the pCPUs in its soft
+affinity;
+
+
+=item *
+
+a vCPU I<has> its own vCPU soft affinity and I<is also> pinned to some
+pCPUs. In this case, the vCPU is always scheduled on one of the pCPUs
+onto which it is pinned, with, among them, a preference for the ones
+that also forms its soft affinity. In case pinning and soft affinity
+form two disjoint sets of pCPUs, pinning "wins", and the soft affinity
+is just ignored.
+
+
+=back
+
+
+=head2 Guest placement in xl
+
+If using xl for creating and managing guests, it is very easy to ask for
+both manual or automatic placement of them across the host's NUMA nodes.
+
+Note that xm/xend does a very similar thing, the only differences being
+the details of the heuristics adopted for automatic placement (see below),
+and the lack of support (in both xm/xend and the Xen versions where that
+was the default toolstack) for NUMA aware scheduling.
+
+
+=head2 Placing the guest manually
+
+Thanks to the "cpus=" option, it is possible to specify where a domain
+should be created and scheduled on, directly in its config file. This
+affects NUMA placement and memory accesses as, in this case, the
+hypervisor constructs the node-affinity of a VM basing right on its
+vCPU pinning when it is created.
+
+This is very simple and effective, but requires the user/system
+administrator to explicitly specify the pinning for each and every domain,
+or Xen won't be able to guarantee the locality for their memory accesses.
+
+That, of course, also mean the vCPUs of the domain will only be able to
+execute on those same pCPUs.
+
+It is is also possible to have a "cpus_soft=" option in the xl config file,
+to specify the soft affinity for all the vCPUs of the domain. This affects
+the NUMA placement in the following way:
+
+=over
+
+=item *
+
+if only "cpus_soft=" is present, the VM's node-affinity will be equal
+to the nodes to which the pCPUs in the soft affinity mask belong;
+
+
+=item *
+
+if both "cpus_soft=" and "cpus=" are present, the VM's node-affinity
+will be equal to the nodes to which the pCPUs present both in hard and
+soft affinity belong.
+
+
+=back
+
+
+=head2 Placing the guest automatically
+
+If neither "cpus=" nor "cpus_soft=" are present in the config file, libxl
+tries to figure out on its own on which node(s) the domain could fit best.
+If it finds one (some), the domain's node affinity get set to there,
+and both memory allocations and NUMA aware scheduling (for the credit
+scheduler and starting from Xen 4.3) will comply with it. Starting from
+Xen 4.5, this also means that the mask resulting from this "fitting"
+procedure will become the soft affinity of all the vCPUs of the domain.
+
+It is worthwhile noting that optimally fitting a set of VMs on the NUMA
+nodes of an host is an incarnation of the Bin Packing Problem. In fact,
+the various VMs with different memory sizes are the items to be packed,
+and the host nodes are the bins. As such problem is known to be NP-hard,
+we will be using some heuristics.
+
+The first thing to do is find the nodes or the sets of nodes (from now
+on referred to as 'candidates') that have enough free memory and enough
+physical CPUs for accommodating the new domain. The idea is to find a
+spot for the domain with at least as much free memory as it has configured
+to have, and as much pCPUs as it has vCPUs. After that, the actual
+decision on which candidate to pick happens accordingly to the following
+heuristics:
+
+=over
+
+=item *
+
+candidates involving fewer nodes are considered better. In case
+two (or more) candidates span the same number of nodes,
+
+
+=item *
+
+candidates with a smaller number of vCPUs runnable on them (due
+to previous placement and/or plain vCPU pinning) are considered
+better. In case the same number of vCPUs can run on two (or more)
+candidates,
+
+
+=item *
+
+the candidate with with the greatest amount of free memory is
+considered to be the best one.
+
+
+=back
+
+Giving preference to candidates with fewer nodes ensures better
+performance for the guest, as it avoid spreading its memory among
+different nodes. Favoring candidates with fewer vCPUs already runnable
+there ensures a good balance of the overall host load. Finally, if more
+candidates fulfil these criteria, prioritizing the nodes that have the
+largest amounts of free memory helps keeping the memory fragmentation
+small, and maximizes the probability of being able to put more domains
+there.
+
+
+=head2 Guest placement in libxl
+
+xl achieves automatic NUMA placement because that is what libxl does
+by default. No API is provided (yet) for modifying the behaviour of
+the placement algorithm. However, if your program is calling libxl,
+it is possible to set the C<numa_placement> build info key to C<false>
+(it is C<true> by default) with something like the below, to prevent
+any placement from happening:
+
+ libxl_defbool_set(&domain_build_info->numa_placement, false);
+
+Also, if C<numa_placement> is set to C<true>, the domain's vCPUs must
+not be pinned (i.e., C<<< domain_build_info->cpumap >>> must have all its
+bits set, as it is by default), or domain creation will fail with
+C<ERROR_INVAL>.
+
+Starting from Xen 4.3, in case automatic placement happens (and is
+successful), it will affect the domain's node-affinity and I<not> its
+vCPU pinning. Namely, the domain's vCPUs will not be pinned to any
+pCPU on the host, but the memory from the domain will come from the
+selected node(s) and the NUMA aware scheduling (if the credit scheduler
+is in use) will try to keep the domain's vCPUs there as much as possible.
+
+Besides than that, looking and/or tweaking the placement algorithm
+search "Automatic NUMA placement" in libxl_internal.h.
+
+Note this may change in future versions of Xen/libxl.
+
+
+=head2 Xen < 4.5
+
+The concept of vCPU soft affinity has been introduced for the first time
+in Xen 4.5. In 4.3, it is the domain's node-affinity that drives the
+NUMA-aware scheduler. The main difference is soft affinity is per-vCPU,
+and so each vCPU can have its own mask of pCPUs, while node-affinity is
+per-domain, that is the equivalent of having all the vCPUs with the same
+soft affinity.
+
+
+=head2 Xen < 4.3
+
+As NUMA aware scheduling is a new feature of Xen 4.3, things are a little
+bit different for earlier version of Xen. If no "cpus=" option is specified
+and Xen 4.2 is in use, the automatic placement algorithm still runs, but
+the results is used to I<pin> the vCPUs of the domain to the output node(s).
+This is consistent with what was happening with xm/xend.
+
+On a version of Xen earlier than 4.2, there is not automatic placement at
+all in xl or libxl, and hence no node-affinity, vCPU affinity or pinning
+being introduced/modified.
+
+
+=head2 Limitations
+
+Analyzing various possible placement solutions is what makes the
+algorithm flexible and quite effective. However, that also means
+it won't scale well to systems with arbitrary number of nodes.
+For this reason, automatic placement is disabled (with a warning)
+if it is requested on a host with more than 16 NUMA nodes.
+++ /dev/null
-=encoding utf8
-
-=head1 NAME
-
-xl-numa-placement - Guest Automatic NUMA Placement in libxl and xl
-
-=head1 DESCRIPTION
-
-=head2 Rationale
-
-NUMA (which stands for Non-Uniform Memory Access) means that the memory
-accessing times of a program running on a CPU depends on the relative
-distance between that CPU and that memory. In fact, most of the NUMA
-systems are built in such a way that each processor has its local memory,
-on which it can operate very fast. On the other hand, getting and storing
-data from and on remote memory (that is, memory local to some other processor)
-is quite more complex and slow. On these machines, a NUMA node is usually
-defined as a set of processor cores (typically a physical CPU package) and
-the memory directly attached to the set of cores.
-
-NUMA awareness becomes very important as soon as many domains start
-running memory-intensive workloads on a shared host. In fact, the cost
-of accessing non node-local memory locations is very high, and the
-performance degradation is likely to be noticeable.
-
-For more information, have a look at the L<Xen NUMA Introduction|http://wiki.xen.org/wiki/Xen_NUMA_Introduction>
-page on the Wiki.
-
-
-=head2 Xen and NUMA machines: the concept of I<node-affinity>
-
-The Xen hypervisor deals with NUMA machines throughout the concept of
-I<node-affinity>. The node-affinity of a domain is the set of NUMA nodes
-of the host where the memory for the domain is being allocated (mostly,
-at domain creation time). This is, at least in principle, different and
-unrelated with the vCPU (hard and soft, see below) scheduling affinity,
-which instead is the set of pCPUs where the vCPU is allowed (or prefers)
-to run.
-
-Of course, despite the fact that they belong to and affect different
-subsystems, the domain node-affinity and the vCPUs affinity are not
-completely independent.
-In fact, if the domain node-affinity is not explicitly specified by the
-user, via the proper libxl calls or xl config item, it will be computed
-basing on the vCPUs' scheduling affinity.
-
-Notice that, even if the node affinity of a domain may change on-line,
-it is very important to "place" the domain correctly when it is fist
-created, as the most of its memory is allocated at that time and can
-not (for now) be moved easily.
-
-
-=head2 Placing via pinning and cpupools
-
-The simplest way of placing a domain on a NUMA node is setting the hard
-scheduling affinity of the domain's vCPUs to the pCPUs of the node. This
-also goes under the name of vCPU pinning, and can be done through the
-"cpus=" option in the config file (more about this below). Another option
-is to pool together the pCPUs spanning the node and put the domain in
-such a I<cpupool> with the "pool=" config option (as documented in our
-L<Wiki|http://wiki.xen.org/wiki/Cpupools_Howto>).
-
-In both the above cases, the domain will not be able to execute outside
-the specified set of pCPUs for any reasons, even if all those pCPUs are
-busy doing something else while there are others, idle, pCPUs.
-
-So, when doing this, local memory accesses are 100% guaranteed, but that
-may come at he cost of some load imbalances.
-
-
-=head2 NUMA aware scheduling
-
-If using the credit1 scheduler, and starting from Xen 4.3, the scheduler
-itself always tries to run the domain's vCPUs on one of the nodes in
-its node-affinity. Only if that turns out to be impossible, it will just
-pick any free pCPU. Locality of access is less guaranteed than in the
-pinning case, but that comes along with better chances to exploit all
-the host resources (e.g., the pCPUs).
-
-Starting from Xen 4.5, credit1 supports two forms of affinity: hard and
-soft, both on a per-vCPU basis. This means each vCPU can have its own
-soft affinity, stating where such vCPU prefers to execute on. This is
-less strict than what it (also starting from 4.5) is called hard affinity,
-as the vCPU can potentially run everywhere, it just prefers some pCPUs
-rather than others.
-In Xen 4.5, therefore, NUMA-aware scheduling is achieved by matching the
-soft affinity of the vCPUs of a domain with its node-affinity.
-
-In fact, as it was for 4.3, if all the pCPUs in a vCPU's soft affinity
-are busy, it is possible for the domain to run outside from there. The
-idea is that slower execution (due to remote memory accesses) is still
-better than no execution at all (as it would happen with pinning). For
-this reason, NUMA aware scheduling has the potential of bringing
-substantial performances benefits, although this will depend on the
-workload.
-
-Notice that, for each vCPU, the following three scenarios are possbile:
-
-=over
-
-=item *
-
-a vCPU I<is pinned> to some pCPUs and I<does not have> any soft affinity
-In this case, the vCPU is always scheduled on one of the pCPUs to which
-it is pinned, without any specific peference among them.
-
-
-=item *
-
-a vCPU I<has> its own soft affinity and I<is not> pinned to any particular
-pCPU. In this case, the vCPU can run on every pCPU. Nevertheless, the
-scheduler will try to have it running on one of the pCPUs in its soft
-affinity;
-
-
-=item *
-
-a vCPU I<has> its own vCPU soft affinity and I<is also> pinned to some
-pCPUs. In this case, the vCPU is always scheduled on one of the pCPUs
-onto which it is pinned, with, among them, a preference for the ones
-that also forms its soft affinity. In case pinning and soft affinity
-form two disjoint sets of pCPUs, pinning "wins", and the soft affinity
-is just ignored.
-
-
-=back
-
-
-=head2 Guest placement in xl
-
-If using xl for creating and managing guests, it is very easy to ask for
-both manual or automatic placement of them across the host's NUMA nodes.
-
-Note that xm/xend does a very similar thing, the only differences being
-the details of the heuristics adopted for automatic placement (see below),
-and the lack of support (in both xm/xend and the Xen versions where that
-was the default toolstack) for NUMA aware scheduling.
-
-
-=head2 Placing the guest manually
-
-Thanks to the "cpus=" option, it is possible to specify where a domain
-should be created and scheduled on, directly in its config file. This
-affects NUMA placement and memory accesses as, in this case, the
-hypervisor constructs the node-affinity of a VM basing right on its
-vCPU pinning when it is created.
-
-This is very simple and effective, but requires the user/system
-administrator to explicitly specify the pinning for each and every domain,
-or Xen won't be able to guarantee the locality for their memory accesses.
-
-That, of course, also mean the vCPUs of the domain will only be able to
-execute on those same pCPUs.
-
-It is is also possible to have a "cpus_soft=" option in the xl config file,
-to specify the soft affinity for all the vCPUs of the domain. This affects
-the NUMA placement in the following way:
-
-=over
-
-=item *
-
-if only "cpus_soft=" is present, the VM's node-affinity will be equal
-to the nodes to which the pCPUs in the soft affinity mask belong;
-
-
-=item *
-
-if both "cpus_soft=" and "cpus=" are present, the VM's node-affinity
-will be equal to the nodes to which the pCPUs present both in hard and
-soft affinity belong.
-
-
-=back
-
-
-=head2 Placing the guest automatically
-
-If neither "cpus=" nor "cpus_soft=" are present in the config file, libxl
-tries to figure out on its own on which node(s) the domain could fit best.
-If it finds one (some), the domain's node affinity get set to there,
-and both memory allocations and NUMA aware scheduling (for the credit
-scheduler and starting from Xen 4.3) will comply with it. Starting from
-Xen 4.5, this also means that the mask resulting from this "fitting"
-procedure will become the soft affinity of all the vCPUs of the domain.
-
-It is worthwhile noting that optimally fitting a set of VMs on the NUMA
-nodes of an host is an incarnation of the Bin Packing Problem. In fact,
-the various VMs with different memory sizes are the items to be packed,
-and the host nodes are the bins. As such problem is known to be NP-hard,
-we will be using some heuristics.
-
-The first thing to do is find the nodes or the sets of nodes (from now
-on referred to as 'candidates') that have enough free memory and enough
-physical CPUs for accommodating the new domain. The idea is to find a
-spot for the domain with at least as much free memory as it has configured
-to have, and as much pCPUs as it has vCPUs. After that, the actual
-decision on which candidate to pick happens accordingly to the following
-heuristics:
-
-=over
-
-=item *
-
-candidates involving fewer nodes are considered better. In case
-two (or more) candidates span the same number of nodes,
-
-
-=item *
-
-candidates with a smaller number of vCPUs runnable on them (due
-to previous placement and/or plain vCPU pinning) are considered
-better. In case the same number of vCPUs can run on two (or more)
-candidates,
-
-
-=item *
-
-the candidate with with the greatest amount of free memory is
-considered to be the best one.
-
-
-=back
-
-Giving preference to candidates with fewer nodes ensures better
-performance for the guest, as it avoid spreading its memory among
-different nodes. Favoring candidates with fewer vCPUs already runnable
-there ensures a good balance of the overall host load. Finally, if more
-candidates fulfil these criteria, prioritizing the nodes that have the
-largest amounts of free memory helps keeping the memory fragmentation
-small, and maximizes the probability of being able to put more domains
-there.
-
-
-=head2 Guest placement in libxl
-
-xl achieves automatic NUMA placement because that is what libxl does
-by default. No API is provided (yet) for modifying the behaviour of
-the placement algorithm. However, if your program is calling libxl,
-it is possible to set the C<numa_placement> build info key to C<false>
-(it is C<true> by default) with something like the below, to prevent
-any placement from happening:
-
- libxl_defbool_set(&domain_build_info->numa_placement, false);
-
-Also, if C<numa_placement> is set to C<true>, the domain's vCPUs must
-not be pinned (i.e., C<<< domain_build_info->cpumap >>> must have all its
-bits set, as it is by default), or domain creation will fail with
-C<ERROR_INVAL>.
-
-Starting from Xen 4.3, in case automatic placement happens (and is
-successful), it will affect the domain's node-affinity and I<not> its
-vCPU pinning. Namely, the domain's vCPUs will not be pinned to any
-pCPU on the host, but the memory from the domain will come from the
-selected node(s) and the NUMA aware scheduling (if the credit scheduler
-is in use) will try to keep the domain's vCPUs there as much as possible.
-
-Besides than that, looking and/or tweaking the placement algorithm
-search "Automatic NUMA placement" in libxl_internal.h.
-
-Note this may change in future versions of Xen/libxl.
-
-
-=head2 Xen < 4.5
-
-The concept of vCPU soft affinity has been introduced for the first time
-in Xen 4.5. In 4.3, it is the domain's node-affinity that drives the
-NUMA-aware scheduler. The main difference is soft affinity is per-vCPU,
-and so each vCPU can have its own mask of pCPUs, while node-affinity is
-per-domain, that is the equivalent of having all the vCPUs with the same
-soft affinity.
-
-
-=head2 Xen < 4.3
-
-As NUMA aware scheduling is a new feature of Xen 4.3, things are a little
-bit different for earlier version of Xen. If no "cpus=" option is specified
-and Xen 4.2 is in use, the automatic placement algorithm still runs, but
-the results is used to I<pin> the vCPUs of the domain to the output node(s).
-This is consistent with what was happening with xm/xend.
-
-On a version of Xen earlier than 4.2, there is not automatic placement at
-all in xl or libxl, and hence no node-affinity, vCPU affinity or pinning
-being introduced/modified.
-
-
-=head2 Limitations
-
-Analyzing various possible placement solutions is what makes the
-algorithm flexible and quite effective. However, that also means
-it won't scale well to systems with arbitrary number of nodes.
-For this reason, automatic placement is disabled (with a warning)
-if it is requested on a host with more than 16 NUMA nodes.
--- /dev/null
+=head1 NAME
+
+xl - Xen management tool, based on LibXenlight
+
+=head1 SYNOPSIS
+
+B<xl> I<subcommand> [I<args>]
+
+=head1 DESCRIPTION
+
+The B<xl> program is the new tool for managing Xen guest
+domains. The program can be used to create, pause, and shutdown
+domains. It can also be used to list current domains, enable or pin
+VCPUs, and attach or detach virtual block devices.
+
+The basic structure of every B<xl> command is almost always:
+
+=over 2
+
+B<xl> I<subcommand> [I<OPTIONS>] I<domain-id>
+
+=back
+
+Where I<subcommand> is one of the subcommands listed below, I<domain-id>
+is the numeric domain id, or the domain name (which will be internally
+translated to domain id), and I<OPTIONS> are subcommand specific
+options. There are a few exceptions to this rule in the cases where
+the subcommand in question acts on all domains, the entire machine,
+or directly on the Xen hypervisor. Those exceptions will be clear for
+each of those subcommands.
+
+=head1 NOTES
+
+=over 4
+
+=item start the script B</etc/init.d/xencommons> at boot time
+
+Most B<xl> operations rely upon B<xenstored> and B<xenconsoled>: make
+sure you start the script B</etc/init.d/xencommons> at boot time to
+initialize all the daemons needed by B<xl>.
+
+=item setup a B<xenbr0> bridge in dom0
+
+In the most common network configuration, you need to setup a bridge in dom0
+named B<xenbr0> in order to have a working network in the guest domains.
+Please refer to the documentation of your Linux distribution to know how to
+setup the bridge.
+
+=item B<autoballoon>
+
+If you specify the amount of memory dom0 has, passing B<dom0_mem> to
+Xen, it is highly recommended to disable B<autoballoon>. Edit
+B</etc/xen/xl.conf> and set it to 0.
+
+=item run xl as B<root>
+
+Most B<xl> commands require root privileges to run due to the
+communications channels used to talk to the hypervisor. Running as
+non root will return an error.
+
+=back
+
+=head1 GLOBAL OPTIONS
+
+Some global options are always available:
+
+=over 4
+
+=item B<-v>
+
+Verbose.
+
+=item B<-N>
+
+Dry run: do not actually execute the command.
+
+=item B<-f>
+
+Force execution: xl will refuse to run some commands if it detects that xend is
+also running, this option will force the execution of those commands, even
+though it is unsafe.
+
+=item B<-t>
+
+Always use carriage-return-based overwriting for displaying progress
+messages without scrolling the screen. Without -t, this is done only
+if stderr is a tty.
+
+=back
+
+=head1 DOMAIN SUBCOMMANDS
+
+The following subcommands manipulate domains directly. As stated
+previously, most commands take I<domain-id> as the first parameter.
+
+=over 4
+
+=item B<button-press> I<domain-id> I<button>
+
+I<This command is deprecated. Please use C<xl trigger> instead.>
+
+Indicate an ACPI button press to the domain, where I<button> can be 'power' or
+'sleep'. This command is only available for HVM domains.
+
+=item B<create> [I<configfile>] [I<OPTIONS>]
+
+The create subcommand takes a config file as its first argument: see
+L<xl.cfg(5)> for full details of the file format and possible options.
+If I<configfile> is missing B<xl> creates the domain assuming the default
+values for every option.
+
+I<configfile> has to be an absolute path to a file.
+
+Create will return B<as soon> as the domain is started. This B<does
+not> mean the guest OS in the domain has actually booted, or is
+available for input.
+
+If the I<-F> option is specified, create will start the domain and not
+return until its death.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-q>, B<--quiet>
+
+No console output.
+
+=item B<-f=FILE>, B<--defconfig=FILE>
+
+Use the given configuration file.
+
+=item B<-p>
+
+Leave the domain paused after it is created.
+
+=item B<-F>
+
+Run in foreground until death of the domain.
+
+=item B<-V>, B<--vncviewer>
+
+Attach to domain's VNC server, forking a vncviewer process.
+
+=item B<-A>, B<--vncviewer-autopass>
+
+Pass the VNC password to vncviewer via stdin.
+
+=item B<-c>
+
+Attach console to the domain as soon as it has started. This is
+useful for determining issues with crashing domains and just as a
+general convenience since you often want to watch the
+domain boot.
+
+=item B<key=value>
+
+It is possible to pass I<key=value> pairs on the command line to provide
+options as if they were written in the configuration file; these override
+whatever is in the I<configfile>.
+
+NB: Many config options require characters such as quotes or brackets
+which are interpreted by the shell (and often discarded) before being
+passed to xl, resulting in xl being unable to parse the value
+correctly. A simple work-around is to put all extra options within a
+single set of quotes, separated by semicolons. (See below for an example.)
+
+=back
+
+B<EXAMPLES>
+
+=over 4
+
+=item I<with config file>
+
+ xl create DebianLenny
+
+This creates a domain with the file /etc/xen/DebianLenny, and returns as
+soon as it is run.
+
+=item I<with extra parameters>
+
+ xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
+
+This creates a domain with the file hvm.cfg, but additionally pins it to
+cpus 0-3, and passes through two PCI devices.
+
+=back
+
+=item B<config-update> I<domain-id> [I<configfile>] [I<OPTIONS>]
+
+Update the saved configuration for a running domain. This has no
+immediate effect but will be applied when the guest is next
+restarted. This command is useful to ensure that runtime modifications
+made to the guest will be preserved when the guest is restarted.
+
+Since Xen 4.5 xl has improved capabilities to handle dynamic domain
+configuration changes and will preserve any changes made at runtime
+when necessary. Therefore it should not normally be necessary to use
+this command any more.
+
+I<configfile> has to be an absolute path to a file.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-f=FILE>, B<--defconfig=FILE>
+
+Use the given configuration file.
+
+=item B<key=value>
+
+It is possible to pass I<key=value> pairs on the command line to
+provide options as if they were written in the configuration file;
+these override whatever is in the I<configfile>. Please see the note
+under I<create> on handling special characters when passing
+I<key=value> pairs on the command line.
+
+=back
+
+=item B<console> [I<OPTIONS>] I<domain-id>
+
+Attach to the console of a domain specified by I<domain-id>. If you've set up
+your domains to have a traditional login console this will look much like a
+normal text login screen.
+
+Use the key combination Ctrl+] to detach from the domain console.
+
+B<OPTIONS>
+
+=over 4
+
+=item I<-t [pv|serial]>
+
+Connect to a PV console or connect to an emulated serial console.
+PV consoles are the only consoles available for PV domains while HVM
+domains can have both. If this option is not specified it defaults to
+emulated serial for HVM guests and PV console for PV guests.
+
+=item I<-n NUM>
+
+Connect to console number I<NUM>. Console numbers start from 0.
+
+=back
+
+=item B<destroy> [I<OPTIONS>] I<domain-id>
+
+Immediately terminate the domain specified by I<domain-id>. This doesn't give
+the domain OS any chance to react, and is the equivalent of ripping the power
+cord out on a physical machine. In most cases you will want to use the
+B<shutdown> command instead.
+
+B<OPTIONS>
+
+=over 4
+
+=item I<-f>
+
+Allow domain 0 to be destroyed. Because a domain cannot destroy itself, this
+is only possible when using a disaggregated toolstack, and is most useful when
+using a hardware domain separated from domain 0.
+
+=back
+
+=item B<domid> I<domain-name>
+
+Converts a domain name to a domain id.
+
+=item B<domname> I<domain-id>
+
+Converts a domain id to a domain name.
+
+=item B<rename> I<domain-id> I<new-name>
+
+Change the domain name of a domain specified by I<domain-id> to I<new-name>.
+
+=item B<dump-core> I<domain-id> [I<filename>]
+
+Dumps the virtual machine's memory for the specified domain to the
+I<filename> specified, without pausing the domain. The dump file will
+be written to a distribution specific directory for dump files, for example:
+@XEN_DUMP_DIR@/dump.
+
+=item B<help> [I<--long>]
+
+Displays the short help message (i.e. common commands) by default.
+
+If the I<--long> option is specified, it displays the complete set of B<xl>
+subcommands, grouped by function.
+
+=item B<list> [I<OPTIONS>] [I<domain-id> ...]
+
+Displays information about one or more domains. If no domains are
+specified it displays information about all domains.
+
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-l>, B<--long>
+
+The output for B<xl list> is not the table view shown below, but
+instead presents the data as a JSON data structure.
+
+=item B<-Z>, B<--context>
+
+Also displays the security labels.
+
+=item B<-v>, B<--verbose>
+
+Also displays the domain UUIDs, the shutdown reason and security labels.
+
+=item B<-c>, B<--cpupool>
+
+Also displays the cpupool the domain belongs to.
+
+=item B<-n>, B<--numa>
+
+Also displays the domain NUMA node affinity.
+
+=back
+
+B<EXAMPLE>
+
+An example format for the list is as follows:
+
+ Name ID Mem VCPUs State Time(s)
+ Domain-0 0 750 4 r----- 11794.3
+ win 1 1019 1 r----- 0.3
+ linux 2 2048 2 r----- 5624.2
+
+Name is the name of the domain. ID the numeric domain id. Mem is the
+desired amount of memory to allocate to the domain (although it may
+not be the currently allocated amount). VCPUs is the number of
+virtual CPUs allocated to the domain. State is the run state (see
+below). Time is the total run time of the domain as accounted for by
+Xen.
+
+B<STATES>
+
+The State field lists 6 states for a Xen domain, and which ones the
+current domain is in.
+
+=over 4
+
+=item B<r - running>
+
+The domain is currently running on a CPU.
+
+=item B<b - blocked>
+
+The domain is blocked, and not running or runnable. This can be because the
+domain is waiting on IO (a traditional wait state) or has
+gone to sleep because there was nothing else for it to do.
+
+=item B<p - paused>
+
+The domain has been paused, usually occurring through the administrator
+running B<xl pause>. When in a paused state the domain will still
+consume allocated resources (like memory), but will not be eligible for
+scheduling by the Xen hypervisor.
+
+=item B<s - shutdown>
+
+The guest OS has shut down (SCHEDOP_shutdown has been called) but the
+domain is not dying yet.
+
+=item B<c - crashed>
+
+The domain has crashed, which is always a violent ending. Usually
+this state only occurs if the domain has been configured not to
+restart on a crash. See L<xl.cfg(5)> for more info.
+
+=item B<d - dying>
+
+The domain is in the process of dying, but hasn't completely shut down or
+crashed.
+
+=back
+
+B<NOTES>
+
+=over 4
+
+The Time column is deceptive. Virtual IO (network and block devices)
+used by the domains requires coordination by Domain0, which means that
+Domain0 is actually charged for much of the time that a DomainU is
+doing IO. Use of this time value to determine relative utilizations
+by domains is thus very unreliable, as a high IO workload may show as
+less utilized than a high CPU workload. Consider yourself warned.
+
+=back
+
+=item B<mem-max> I<domain-id> I<mem>
+
+Specify the maximum amount of memory the domain is able to use, appending 't'
+for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b'
+for bytes.
+
+The mem-max value may not correspond to the actual memory used in the
+domain, as it may balloon down its memory to give more back to the OS.
+
+The value given just sets the memory amount the domain is allowed to allocate
+in the hypervisor. It can't be set lower than the current reservation, but
+it is allowed to be higher than the configured maximum memory size of the
+domain (B<maxmem> parameter in the domain's configuration). Using B<xl mem-max>
+to set the maximum memory above the initial B<maxmem> value will not allow the
+additional memory to be used via B<xl mem-set>. The initial B<maxmem> value is
+still used as an upper limit for B<xl mem-set>.
+
+The domain will not receive any signal regarding the changed memory limit.
+
+=item B<mem-set> I<domain-id> I<mem>
+
+Set the domain's used memory using the balloon driver; append 't' for
+terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' for
+bytes.
+
+Because this operation requires cooperation from the domain operating
+system, there is no guarantee that it will succeed. This command will
+definitely not work unless the domain has the required paravirt
+driver.
+
+B<Warning:> There is no good way to know in advance how small of a
+mem-set will make a domain unstable and cause it to crash. Be very
+careful when using this command on running domains.
+
+=item B<migrate> [I<OPTIONS>] I<domain-id> I<host>
+
+Migrate a domain to another host machine. By default B<xl> relies on ssh as a
+transport mechanism between the two hosts.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-s> I<sshcommand>
+
+Use <sshcommand> instead of ssh. String will be passed to sh. If empty, run
+<host> instead of ssh <host> xl migrate-receive [-d -e].
+
+=item B<-e>
+
+On the new <host>, do not wait in the background for the death of the
+domain. See the corresponding option of the I<create> subcommand.
+
+=item B<-C> I<config>
+
+Send the specified <config> file instead of the file used on creation of the
+domain.
+
+=item B<--debug>
+
+Display huge (!) amount of debug information during the migration process.
+
+=item B<-p>
+
+Leave the domain on the receive side paused after migration.
+
+=back
+
+=item B<remus> [I<OPTIONS>] I<domain-id> I<host>
+
+Enable Remus HA or COLO HA for domain. By default B<xl> relies on ssh as a
+transport mechanism between the two hosts.
+
+B<NOTES>
+
+=over 4
+
+Remus support in xl is still in experimental (proof-of-concept) phase.
+Disk replication support is limited to DRBD disks.
+
+COLO support in xl is still in experimental (proof-of-concept)
+phase. All options are subject to change in the future.
+
+=back
+
+COLO disk configuration looks like:
+
+ disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']
+
+The supported options are:
+
+=over 4
+
+=item B<colo-host> : Secondary host's ip address.
+
+=item B<colo-port> : Secondary host's port, we will run a nbd server on the
+secondary host, and the nbd server will listen on this port.
+
+=item B<colo-export> : Nbd server's disk export name of the secondary host.
+
+=item B<active-disk> : Secondary's guest write will be buffered to this disk,
+and it's used by the secondary.
+
+=item B<hidden-disk> : Primary's modified contents will be buffered in this
+disk, and it's used by the secondary.
+
+=back
+
+COLO network configuration looks like:
+
+ vif = [ '...,forwarddev=xxx,...']
+
+The supported options are:
+
+=over 4
+
+=item B<forwarddev> : Forward devices for the primary and the secondary, they
+are directly connected.
+
+
+=back
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-i> I<MS>
+
+Checkpoint domain memory every MS milliseconds (default 200ms).
+
+=item B<-u>
+
+Disable memory checkpoint compression.
+
+=item B<-s> I<sshcommand>
+
+Use <sshcommand> instead of ssh. String will be passed to sh.
+If empty, run <host> instead of ssh <host> xl migrate-receive -r [-e].
+
+=item B<-e>
+
+On the new <host>, do not wait in the background for the death of the domain.
+See the corresponding option of the I<create> subcommand.
+
+=item B<-N> I<netbufscript>
+
+Use <netbufscript> to setup network buffering instead of the
+default script (/etc/xen/scripts/remus-netbuf-setup).
+
+=item B<-F>
+
+Run Remus in unsafe mode. Use this option with caution as failover may
+not work as intended.
+
+=item B<-b>
+
+Replicate memory checkpoints to /dev/null (blackhole).
+Generally useful for debugging. Requires enabling unsafe mode.
+
+=item B<-n>
+
+Disable network output buffering. Requires enabling unsafe mode.
+
+=item B<-d>
+
+Disable disk replication. Requires enabling unsafe mode.
+
+=item B<-c>
+
+Enable COLO HA. This conflicts with B<-i> and B<-b>, and memory
+checkpoint compression must be disabled.
+
+=item B<-p>
+
+Use userspace COLO Proxy. This option must be used in conjunction
+with B<-c>.
+
+=back
+
+=item B<pause> I<domain-id>
+
+Pause a domain. When in a paused state the domain will still consume
+allocated resources (such as memory), but will not be eligible for
+scheduling by the Xen hypervisor.
+
+=item B<reboot> [I<OPTIONS>] I<domain-id>
+
+Reboot a domain. This acts just as if the domain had the B<reboot>
+command run from the console. The command returns as soon as it has
+executed the reboot action, which may be significantly earlier than when the
+domain actually reboots.
+
+For HVM domains this requires PV drivers to be installed in your guest
+OS. If PV drivers are not present but you have configured the guest OS
+to behave appropriately you may be able to use the I<-F> option to
+trigger a reset button press.
+
+The behavior of what happens to a domain when it reboots is set by the
+B<on_reboot> parameter of the domain configuration file when the
+domain was created.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-F>
+
+If the guest does not support PV reboot control then fallback to
+sending an ACPI power event (equivalent to the I<reset> option to
+I<trigger>).
+
+You should ensure that the guest is configured to behave as expected
+in response to this event.
+
+=back
+
+=item B<restore> [I<OPTIONS>] [I<configfile>] I<checkpointfile>
+
+Build a domain from an B<xl save> state file. See B<save> for more info.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-p>
+
+Do not unpause the domain after restoring it.
+
+=item B<-e>
+
+Do not wait in the background for the death of the domain on the new host.
+See the corresponding option of the I<create> subcommand.
+
+=item B<-d>
+
+Enable debug messages.
+
+=item B<-V>, B<--vncviewer>
+
+Attach to the domain's VNC server, forking a vncviewer process.
+
+=item B<-A>, B<--vncviewer-autopass>
+
+Pass the VNC password to vncviewer via stdin.
+
+
+
+=back
+
+=item B<save> [I<OPTIONS>] I<domain-id> I<checkpointfile> [I<configfile>]
+
+Saves a running domain to a state file so that it can be restored
+later. Once saved, the domain will no longer be running on the
+system, unless the -c or -p options are used.
+B<xl restore> restores from this checkpoint file.
+Passing a config file argument allows the user to manually select the VM config
+file used to create the domain.
+
+=over 4
+
+=item B<-c>
+
+Leave the domain running after creating the snapshot.
+
+=item B<-p>
+
+Leave the domain paused after creating the snapshot.
+
+=back
+
+=item B<sharing> [I<domain-id>]
+
+Display the number of shared pages for a specified domain. If no domain is
+specified it displays information about all domains.
+
+=item B<shutdown> [I<OPTIONS>] I<-a|domain-id>
+
+Gracefully shuts down a domain. This coordinates with the domain OS
+to perform graceful shutdown, so there is no guarantee that it will
+succeed, and may take a variable length of time depending on what
+services must be shut down in the domain.
+
+For HVM domains this requires PV drivers to be installed in your guest
+OS. If PV drivers are not present but you have configured the guest OS
+to behave appropriately you may be able to use the I<-F> option to
+trigger a power button press.
+
+The command returns immediately after signaling the domain unless the
+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 domain configuration file when the
+domain was created.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-a>, B<--all>
+
+Shutdown all guest domains. Often used when doing a complete shutdown
+of a Xen system.
+
+=item B<-w>, B<--wait>
+
+Wait for the domain to complete shutdown before returning.
+
+=item B<-F>
+
+If the guest does not support PV shutdown control then fallback to
+sending an ACPI power event (equivalent to the I<power> option to
+I<trigger>).
+
+You should ensure that the guest is configured to behave as expected
+in response to this event.
+
+=back
+
+=item B<sysrq> I<domain-id> I<letter>
+
+Send a <Magic System Request> to the domain, each type of request is
+represented by a different letter.
+It can be used to send SysRq requests to Linux guests, see sysrq.txt in
+your Linux Kernel sources for more information.
+It requires PV drivers to be installed in your guest OS.
+
+=item B<trigger> I<domain-id> I<nmi|reset|init|power|sleep|s3resume> [I<VCPU>]
+
+Send a trigger to a domain, where the trigger can be: nmi, reset, init, power
+or sleep. Optionally a specific vcpu number can be passed as an argument.
+This command is only available for HVM domains.
+
+=item B<unpause> I<domain-id>
+
+Moves a domain out of the paused state. This will allow a previously
+paused domain to now be eligible for scheduling by the Xen hypervisor.
+
+=item B<vcpu-set> I<domain-id> I<vcpu-count>
+
+Enables the I<vcpu-count> virtual CPUs for the domain in question.
+Like mem-set, this command can only allocate up to the maximum virtual
+CPU count configured at boot for the domain.
+
+If the I<vcpu-count> is smaller than the current number of active
+VCPUs, the highest number VCPUs will be hotplug removed. This may be
+important for pinning purposes.
+
+Attempting to set the VCPUs to a number larger than the initially
+configured VCPU count is an error. Trying to set VCPUs to < 1 will be
+quietly ignored.
+
+Some guests may need to actually bring the newly added CPU online
+after B<vcpu-set>, go to B<SEE ALSO> section for information.
+
+=item B<vcpu-list> [I<domain-id>]
+
+Lists VCPU information for a specific domain. If no domain is
+specified, VCPU information for all domains will be provided.
+
+=item B<vcpu-pin> [I<-f|--force>] I<domain-id> I<vcpu> I<cpus hard> I<cpus soft>
+
+Set hard and soft affinity for a I<vcpu> of <domain-id>. Normally VCPUs
+can float between available CPUs whenever Xen deems a different run state
+is appropriate.
+
+Hard affinity can be used to restrict this, by ensuring certain VCPUs
+can only run on certain physical CPUs. Soft affinity specifies a I<preferred>
+set of CPUs. Soft affinity needs special support in the scheduler, which is
+only provided in credit1.
+
+The keyword B<all> can be used to apply the hard and soft affinity masks to
+all the VCPUs in the domain. The symbol '-' can be used to leave either
+hard or soft affinity alone.
+
+For example:
+
+ xl vcpu-pin 0 3 - 6-9
+
+will set soft affinity for vCPU 3 of domain 0 to pCPUs 6,7,8 and 9,
+leaving its hard affinity untouched. On the other hand:
+
+ xl vcpu-pin 0 3 3,4 6-9
+
+will set both hard and soft affinity, the former to pCPUs 3 and 4, the
+latter to pCPUs 6,7,8, and 9.
+
+Specifying I<-f> or I<--force> will remove a temporary pinning done by the
+operating system (normally this should be done by the operating system).
+In case a temporary pinning is active for a vcpu the affinity of this vcpu
+can't be changed without this option.
+
+=item B<vm-list>
+
+Prints information about guests. This list excludes information about
+service or auxiliary domains such as dom0 and stubdoms.
+
+B<EXAMPLE>
+
+An example format for the list is as follows:
+
+ UUID ID name
+ 59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5 2 win
+ 50bc8f75-81d0-4d53-b2e6-95cb44e2682e 3 linux
+
+=item B<vncviewer> [I<OPTIONS>] I<domain-id>
+
+Attach to the domain's VNC server, forking a vncviewer process.
+
+B<OPTIONS>
+
+=over 4
+
+=item I<--autopass>
+
+Pass the VNC password to vncviewer via stdin.
+
+=back
+
+=back
+
+=head1 XEN HOST SUBCOMMANDS
+
+=over 4
+
+=item B<debug-keys> I<keys>
+
+Send debug I<keys> to Xen. It is the same as pressing the Xen
+"conswitch" (Ctrl-A by default) three times and then pressing "keys".
+
+=item B<set-parameters> I<params>
+
+Set hypervisor parameters as specified in I<params>. This allows for some
+boot parameters of the hypervisor to be modified in the running systems.
+
+=item B<dmesg> [I<OPTIONS>]
+
+Reads the Xen message buffer, similar to dmesg on a Linux system. The
+buffer contains informational, warning, and error messages created
+during Xen's boot process. If you are having problems with Xen, this
+is one of the first places to look as part of problem determination.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-c>, B<--clear>
+
+Clears Xen's message buffer.
+
+=back
+
+=item B<info> [I<OPTIONS>]
+
+Print information about the Xen host in I<name : value> format. When
+reporting a Xen bug, please provide this information as part of the
+bug report. See I<http://wiki.xen.org/xenwiki/ReportingBugs> on how to
+report Xen bugs.
+
+Sample output looks as follows:
+
+ host : scarlett
+ release : 3.1.0-rc4+
+ version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011
+ machine : x86_64
+ nr_cpus : 4
+ nr_nodes : 1
+ cores_per_socket : 4
+ threads_per_core : 1
+ cpu_mhz : 2266
+ hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000
+ virt_caps : hvm hvm_directio
+ total_memory : 6141
+ free_memory : 4274
+ free_cpus : 0
+ outstanding_claims : 0
+ xen_major : 4
+ xen_minor : 2
+ xen_extra : -unstable
+ xen_caps : xen-3.0-x86_64 xen-3.0-x86_32p hvm-3.0-x86_32 hvm-3.0-x86_32p hvm-3.0-x86_64
+ xen_scheduler : credit
+ xen_pagesize : 4096
+ platform_params : virt_start=0xffff800000000000
+ xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241
+ xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1
+ cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8)
+ cc_compile_by : sstabellini
+ cc_compile_domain : uk.xensource.com
+ cc_compile_date : Tue Nov 8 12:03:05 UTC 2011
+ xend_config_format : 4
+
+
+B<FIELDS>
+
+Not all fields will be explained here, but some of the less obvious
+ones deserve explanation:
+
+=over 4
+
+=item B<hw_caps>
+
+A vector showing what hardware capabilities are supported by your
+processor. This is equivalent to, though more cryptic, the flags
+field in /proc/cpuinfo on a normal Linux machine: they both derive from
+the feature bits returned by the cpuid command on x86 platforms.
+
+=item B<free_memory>
+
+Available memory (in MB) not allocated to Xen, or any other domains, or
+claimed for domains.
+
+=item B<outstanding_claims>
+
+When a claim call is done (see L<xl.conf>) a reservation for a specific
+amount of pages is set and also a global value is incremented. This
+global value (outstanding_claims) is then reduced as the domain's memory
+is populated and eventually reaches zero. Most of the time the value will
+be zero, but if you are launching multiple guests, and B<claim_mode> is
+enabled, this value can increase/decrease. Note that the value also
+affects the B<free_memory> - as it will reflect the free memory
+in the hypervisor minus the outstanding pages claimed for guests.
+See xl I<info> B<claims> parameter for detailed listing.
+
+=item B<xen_caps>
+
+The Xen version and architecture. Architecture values can be one of:
+x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
+
+=item B<xen_changeset>
+
+The Xen mercurial changeset id. Very useful for determining exactly
+what version of code your Xen system was built from.
+
+=back
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-n>, B<--numa>
+
+List host NUMA topology information
+
+=back
+
+=item B<top>
+
+Executes the B<xentop(1)> command, which provides real time monitoring of
+domains. Xentop has a curses interface, and is reasonably self explanatory.
+
+=item B<uptime>
+
+Prints the current uptime of the domains running.
+
+=item B<claims>
+
+Prints information about outstanding claims by the guests. This provides
+the outstanding claims and currently populated memory count for the guests.
+These values added up reflect the global outstanding claim value, which
+is provided via the I<info> argument, B<outstanding_claims> value.
+The B<Mem> column has the cumulative value of outstanding claims and
+the total amount of memory that has been right now allocated to the guest.
+
+B<EXAMPLE>
+
+An example format for the list is as follows:
+
+ Name ID Mem VCPUs State Time(s) Claimed
+ Domain-0 0 2047 4 r----- 19.7 0
+ OL5 2 2048 1 --p--- 0.0 847
+ OL6 3 1024 4 r----- 5.9 0
+ Windows_XP 4 2047 1 --p--- 0.0 1989
+
+In which it can be seen that the OL5 guest still has 847MB of claimed
+memory (out of the total 2048MB where 1191MB has been allocated to
+the guest).
+
+=back
+
+=head1 SCHEDULER SUBCOMMANDS
+
+Xen ships with a number of domain schedulers, which can be set at boot
+time with the B<sched=> parameter on the Xen command line. By
+default B<credit> is used for scheduling.
+
+=over 4
+
+=item B<sched-credit> [I<OPTIONS>]
+
+Set or get credit (aka credit1) scheduler parameters. The credit scheduler is
+a proportional fair share CPU scheduler built from the ground up to be
+work conserving on SMP hosts.
+
+Each domain (including Domain0) is assigned a weight and a cap.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-d DOMAIN>, B<--domain=DOMAIN>
+
+Specify domain for which scheduler parameters are to be modified or retrieved.
+Mandatory for modifying scheduler parameters.
+
+=item B<-w WEIGHT>, B<--weight=WEIGHT>
+
+A domain with a weight of 512 will get twice as much CPU as a domain
+with a weight of 256 on a contended host. Legal weights range from 1
+to 65535 and the default is 256.
+
+=item B<-c CAP>, B<--cap=CAP>
+
+The cap optionally fixes the maximum amount of CPU a domain will be
+able to consume, even if the host system has idle CPU cycles. The cap
+is expressed in percentage of one physical CPU: 100 is 1 physical CPU,
+50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is
+no upper cap.
+
+NB: Many systems have features that will scale down the computing
+power of a cpu that is not 100% utilized. This can be in the
+operating system, but can also sometimes be below the operating system
+in the BIOS. If you set a cap such that individual cores are running
+at less than 100%, this may have an impact on the performance of your
+workload over and above the impact of the cap. For example, if your
+processor runs at 2GHz, and you cap a vm at 50%, the power management
+system may also reduce the clock speed to 1GHz; the effect will be
+that your VM gets 25% of the available power (50% of 1GHz) rather than
+50% (50% of 2GHz). If you are not getting the performance you expect,
+look at performance and cpufreq options in your operating system and
+your BIOS.
+
+=item B<-p CPUPOOL>, B<--cpupool=CPUPOOL>
+
+Restrict output to domains in the specified cpupool.
+
+=item B<-s>, B<--schedparam>
+
+Specify to list or set pool-wide scheduler parameters.
+
+=item B<-t TSLICE>, B<--tslice_ms=TSLICE>
+
+Timeslice tells the scheduler how long to allow VMs to run before
+pre-empting. The default is 30ms. Valid ranges are 1ms to 1000ms.
+The length of the timeslice (in ms) must be higher than the length of
+the ratelimit (see below).
+
+=item B<-r RLIMIT>, B<--ratelimit_us=RLIMIT>
+
+Ratelimit attempts to limit the number of schedules per second. It
+sets a minimum amount of time (in microseconds) a VM must run before
+we will allow a higher-priority VM to pre-empt it. The default value
+is 1000 microseconds (1ms). Valid range is 100 to 500000 (500ms).
+The ratelimit length must be lower than the timeslice length.
+
+=item B<-m DELAY>, B<--migration_delay_us=DELAY>
+
+Migration delay specifies for how long a vCPU, after it stopped running should
+be considered "cache-hot". Basically, if less than DELAY us passed since when
+the vCPU was executing on a CPU, it is likely that most of the vCPU's working
+set is still in the CPU's cache, and therefore the vCPU is not migrated.
+
+Default is 0. Maximum is 100 ms. This can be effective at preventing vCPUs
+to bounce among CPUs too quickly, but, at the same time, the scheduler stops
+being fully work-conserving.
+
+=back
+
+B<COMBINATION>
+
+The following is the effect of combining the above options:
+
+=over 4
+
+=item B<E<lt>nothingE<gt>> : List all domain params and sched params from all pools
+
+=item B<-d [domid]> : List domain params for domain [domid]
+
+=item B<-d [domid] [params]> : Set domain params for domain [domid]
+
+=item B<-p [pool]> : list all domains and sched params for [pool]
+
+=item B<-s> : List sched params for poolid 0
+
+=item B<-s [params]> : Set sched params for poolid 0
+
+=item B<-p [pool] -s> : List sched params for [pool]
+
+=item B<-p [pool] -s [params]> : Set sched params for [pool]
+
+=item B<-p [pool] -d>... : Illegal
+
+=back
+
+=item B<sched-credit2> [I<OPTIONS>]
+
+Set or get credit2 scheduler parameters. The credit2 scheduler is a
+proportional fair share CPU scheduler built from the ground up to be
+work conserving on SMP hosts.
+
+Each domain (including Domain0) is assigned a weight.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-d DOMAIN>, B<--domain=DOMAIN>
+
+Specify domain for which scheduler parameters are to be modified or retrieved.
+Mandatory for modifying scheduler parameters.
+
+=item B<-w WEIGHT>, B<--weight=WEIGHT>
+
+A domain with a weight of 512 will get twice as much CPU as a domain
+with a weight of 256 on a contended host. Legal weights range from 1
+to 65535 and the default is 256.
+
+=item B<-p CPUPOOL>, B<--cpupool=CPUPOOL>
+
+Restrict output to domains in the specified cpupool.
+
+=item B<-s>, B<--schedparam>
+
+Specify to list or set pool-wide scheduler parameters.
+
+=item B<-r RLIMIT>, B<--ratelimit_us=RLIMIT>
+
+Attempts to limit the rate of context switching. It is basically the same
+as B<--ratelimit_us> in B<sched-credit>
+
+=back
+
+=item B<sched-rtds> [I<OPTIONS>]
+
+Set or get rtds (Real Time Deferrable Server) scheduler parameters.
+This rt scheduler applies Preemptive Global Earliest Deadline First
+real-time scheduling algorithm to schedule VCPUs in the system.
+Each VCPU has a dedicated period, budget and extratime.
+While scheduled, a VCPU burns its budget.
+A VCPU has its budget replenished at the beginning of each period;
+Unused budget is discarded at the end of each period.
+A VCPU with extratime set gets extra time from the unreserved system resource.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-d DOMAIN>, B<--domain=DOMAIN>
+
+Specify domain for which scheduler parameters are to be modified or retrieved.
+Mandatory for modifying scheduler parameters.
+
+=item B<-v VCPUID/all>, B<--vcpuid=VCPUID/all>
+
+Specify vcpu for which scheduler parameters are to be modified or retrieved.
+
+=item B<-p PERIOD>, B<--period=PERIOD>
+
+Period of time, in microseconds, over which to replenish the budget.
+
+=item B<-b BUDGET>, B<--budget=BUDGET>
+
+Amount of time, in microseconds, that the VCPU will be allowed
+to run every period.
+
+=item B<-e Extratime>, B<--extratime=Extratime>
+
+Binary flag to decide if the VCPU will be allowed to get extra time from
+the unreserved system resource.
+
+=item B<-c CPUPOOL>, B<--cpupool=CPUPOOL>
+
+Restrict output to domains in the specified cpupool.
+
+=back
+
+B<EXAMPLE>
+
+=over 4
+
+1) Use B<-v all> to see the budget and period of all the VCPUs of
+all the domains:
+
+ xl sched-rtds -v all
+ Cpupool Pool-0: sched=RTDS
+ Name ID VCPU Period Budget Extratime
+ Domain-0 0 0 10000 4000 yes
+ vm1 2 0 300 150 yes
+ vm1 2 1 400 200 yes
+ vm1 2 2 10000 4000 yes
+ vm1 2 3 1000 500 yes
+ vm2 4 0 10000 4000 yes
+ vm2 4 1 10000 4000 yes
+
+Without any arguments, it will output the default scheduling
+parameters for each domain:
+
+ xl sched-rtds
+ Cpupool Pool-0: sched=RTDS
+ Name ID Period Budget Extratime
+ Domain-0 0 10000 4000 yes
+ vm1 2 10000 4000 yes
+ vm2 4 10000 4000 yes
+
+
+2) Use, for instance, B<-d vm1, -v all> to see the budget and
+period of all VCPUs of a specific domain (B<vm1>):
+
+ xl sched-rtds -d vm1 -v all
+ Name ID VCPU Period Budget Extratime
+ vm1 2 0 300 150 yes
+ vm1 2 1 400 200 yes
+ vm1 2 2 10000 4000 yes
+ vm1 2 3 1000 500 yes
+
+To see the parameters of a subset of the VCPUs of a domain, use:
+
+ xl sched-rtds -d vm1 -v 0 -v 3
+ Name ID VCPU Period Budget Extratime
+ vm1 2 0 300 150 yes
+ vm1 2 3 1000 500 yes
+
+If no B<-v> is specified, the default scheduling parameters for the
+domain are shown:
+
+ xl sched-rtds -d vm1
+ Name ID Period Budget Extratime
+ vm1 2 10000 4000 yes
+
+
+3) Users can set the budget and period of multiple VCPUs of a
+specific domain with only one command,
+e.g., "xl sched-rtds -d vm1 -v 0 -p 100 -b 50 -e 1 -v 3 -p 300 -b 150 -e 0".
+
+To change the parameters of all the VCPUs of a domain, use B<-v all>,
+e.g., "xl sched-rtds -d vm1 -v all -p 500 -b 250 -e 1".
+
+=back
+
+=back
+
+=head1 CPUPOOLS COMMANDS
+
+Xen can group the physical cpus of a server in cpu-pools. Each physical CPU is
+assigned at most to one cpu-pool. Domains are each restricted to a single
+cpu-pool. Scheduling does not cross cpu-pool boundaries, so each cpu-pool has
+its own scheduler.
+Physical cpus and domains can be moved from one cpu-pool to another only by an
+explicit command.
+Cpu-pools can be specified either by name or by id.
+
+=over 4
+
+=item B<cpupool-create> [I<OPTIONS>] [I<configfile>] [I<variable=value> ...]
+
+Create a cpu pool based an config from a I<configfile> or command-line
+parameters. Variable settings from the I<configfile> may be altered
+by specifying new or additional assignments on the command line.
+
+See the L<xlcpupool.cfg(5)> manpage for more information.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-f=FILE>, B<--defconfig=FILE>
+
+Use the given configuration file.
+
+=back
+
+=item B<cpupool-list> [I<OPTIONS>] [I<cpu-pool>]
+
+List CPU pools on the host.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-c>, B<--cpus>
+
+If this option is specified, B<xl> prints a list of CPUs used by I<cpu-pool>.
+
+=back
+
+=item B<cpupool-destroy> I<cpu-pool>
+
+Deactivates a cpu pool.
+This is possible only if no domain is active in the cpu-pool.
+
+=item B<cpupool-rename> I<cpu-pool> <newname>
+
+Renames a cpu-pool to I<newname>.
+
+=item B<cpupool-cpu-add> I<cpu-pool> I<cpus|node:nodes>
+
+Adds one or more CPUs or NUMA nodes to I<cpu-pool>. CPUs and NUMA
+nodes can be specified as single CPU/node IDs or as ranges.
+
+For example:
+
+ (a) xl cpupool-cpu-add mypool 4
+ (b) xl cpupool-cpu-add mypool 1,5,10-16,^13
+ (c) xl cpupool-cpu-add mypool node:0,nodes:2-3,^10-12,8
+
+means adding CPU 4 to mypool, in (a); adding CPUs 1,5,10,11,12,14,15
+and 16, in (b); and adding all the CPUs of NUMA nodes 0, 2 and 3,
+plus CPU 8, but keeping out CPUs 10,11,12, in (c).
+
+All the specified CPUs that can be added to the cpupool will be added
+to it. If some CPU can't (e.g., because they're already part of another
+cpupool), an error is reported about each one of them.
+
+=item B<cpupool-cpu-remove> I<cpus|node:nodes>
+
+Removes one or more CPUs or NUMA nodes from I<cpu-pool>. CPUs and NUMA
+nodes can be specified as single CPU/node IDs or as ranges, using the
+exact same syntax as in B<cpupool-cpu-add> above.
+
+=item B<cpupool-migrate> I<domain-id> I<cpu-pool>
+
+Moves a domain specified by domain-id or domain-name into a cpu-pool.
+Domain-0 can't be moved to another cpu-pool.
+
+=item B<cpupool-numa-split>
+
+Splits up the machine into one cpu-pool per numa node.
+
+=back
+
+=head1 VIRTUAL DEVICE COMMANDS
+
+Most virtual devices can be added and removed while guests are
+running, assuming that the necessary support exists in the guest OS. The
+effect to the guest OS is much the same as any hotplug event.
+
+=head2 BLOCK DEVICES
+
+=over 4
+
+=item B<block-attach> I<domain-id> I<disc-spec-component(s)> ...
+
+Create a new virtual block device and attach it to the specified domain.
+A disc specification is in the same format used for the B<disk> variable in
+the domain config file. See L<xl-disk-configuration(5)>. This will trigger a
+hotplug event for the guest.
+
+Note that only PV block devices are supported by block-attach.
+Requests to attach emulated devices (eg, vdev=hdc) will result in only
+the PV view being available to the guest.
+
+=item B<block-detach> I<domain-id> I<devid> [I<OPTIONS>]
+
+Detach a domain's virtual block device. I<devid> may be the symbolic
+name or the numeric device id given to the device by domain 0. You
+will need to run B<xl block-list> to determine that number.
+
+Detaching the device requires the cooperation of the domain. If the
+domain fails to release the device (perhaps because the domain is hung
+or is still using the device), the detach will fail.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<--force>
+
+If this parameter is specified the device will be forcefully detached, which
+may cause IO errors in the domain.
+
+=back
+
+
+
+=item B<block-list> I<domain-id>
+
+List virtual block devices for a domain.
+
+=item B<cd-insert> I<domain-id> I<virtualdevice> I<target>
+
+Insert a cdrom into a guest domain's existing virtual cd drive. The
+virtual drive must already exist but can be empty. How the device should be
+presented to the guest domain is specified by the I<virtualdevice> parameter;
+for example "hdc". Parameter I<target> is the target path in the backend domain
+(usually domain 0) to be exported; can be a block device or a file etc.
+See B<target> in L<xl-disk-configuration(5)>.
+
+Only works with HVM domains.
+
+
+=item B<cd-eject> I<domain-id> I<virtualdevice>
+
+Eject a cdrom from a guest domain's virtual cd drive, specified by
+I<virtualdevice>. Only works with HVM domains.
+
+=back
+
+=head2 NETWORK DEVICES
+
+=over 4
+
+=item B<network-attach> I<domain-id> I<network-device>
+
+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<xl.cfg(5)> and
+L<xl-network-configuration(5)>
+for more information.
+
+Note that only attaching PV network interfaces is supported.
+
+=item B<network-detach> I<domain-id> I<devid|mac>
+
+Removes the network device from the domain specified by I<domain-id>.
+I<devid> is the virtual interface device number within the domain
+(i.e. the 3 in vif22.3). Alternatively, the I<mac> address can be used to
+select the virtual interface to detach.
+
+=item B<network-list> I<domain-id>
+
+List virtual network interfaces for a domain.
+
+=back
+
+=head2 CHANNEL DEVICES
+
+=over 4
+
+=item B<channel-list> I<domain-id>
+
+List virtual channel interfaces for a domain.
+
+=back
+
+=head2 VIRTUAL TRUSTED PLATFORM MODULE (vTPM) DEVICES
+
+=over 4
+
+=item B<vtpm-attach> I<domain-id> I<vtpm-device>
+
+Creates a new vtpm (virtual Trusted Platform Module) device in the domain
+specified by I<domain-id>. I<vtpm-device> describes the device to attach,
+using the same format as the B<vtpm> string in the domain config file.
+See L<xl.cfg(5)> for more information.
+
+=item B<vtpm-detach> I<domain-id> I<devid|uuid>
+
+Removes the vtpm device from the domain specified by I<domain-id>.
+I<devid> is the numeric device id given to the virtual Trusted
+Platform Module device. You will need to run B<xl vtpm-list> to determine that
+number. Alternatively, the I<uuid> of the vtpm can be used to
+select the virtual device to detach.
+
+=item B<vtpm-list> I<domain-id>
+
+List virtual Trusted Platform Modules for a domain.
+
+=back
+
+=head2 VDISPL DEVICES
+
+=over 4
+
+=item B<vdispl-attach> I<domain-id> I<vdispl-device>
+
+Creates a new vdispl device in the domain specified by I<domain-id>.
+I<vdispl-device> describes the device to attach, using the same format as the
+B<vdispl> string in the domain config file. See L<xl.cfg> for
+more information.
+
+B<NOTES>
+
+=over 4
+
+As in I<vdispl-device> string semicolon is used then put quotes or escaping
+when using from the shell.
+
+B<EXAMPLE>
+
+=over 4
+
+xl vdispl-attach DomU connectors='id0:1920x1080;id1:800x600;id2:640x480'
+
+or
+
+xl vdispl-attach DomU connectors=id0:1920x1080\;id1:800x600\;id2:640x480
+
+=back
+
+=back
+
+=item B<vdispl-detach> I<domain-id> I<dev-id>
+
+Removes the vdispl device specified by I<dev-id> from the domain specified by I<domain-id>.
+
+=item B<vdispl-list> I<domain-id>
+
+List virtual displays for a domain.
+
+=back
+
+=head2 VSND DEVICES
+
+=over 4
+
+=item B<vsnd-attach> I<domain-id> I<vsnd-item> I<vsnd-item> ...
+
+Creates a new vsnd device in the domain specified by I<domain-id>.
+I<vsnd-item>'s describe the vsnd device to attach, using the same format as the
+B<VSND_ITEM_SPEC> string in the domain config file. See L<xl.cfg> for
+more information.
+
+B<EXAMPLE>
+
+=over 4
+
+xl vsnd-attach DomU 'CARD, short-name=Main, sample-formats=s16_le;s8;u32_be'
+'PCM, name=Main' 'STREAM, id=0, type=p' 'STREAM, id=1, type=c, channels-max=2'
+
+=back
+
+=item B<vsnd-detach> I<domain-id> I<dev-id>
+
+Removes the vsnd device specified by I<dev-id> from the domain specified by I<domain-id>.
+
+=item B<vsnd-list> I<domain-id>
+
+List vsnd devices for a domain.
+
+=back
+
+=head2 KEYBOARD DEVICES
+
+=over 4
+
+=item B<vkb-attach> I<domain-id> I<vkb-device>
+
+Creates a new keyboard device in the domain specified by I<domain-id>.
+I<vkb-device> describes the device to attach, using the same format as the
+B<VKB_SPEC_STRING> string in the domain config file. See L<xl.cfg(5)>
+for more informations.
+
+=item B<vkb-detach> I<domain-id> I<devid>
+
+Removes the keyboard device from the domain specified by I<domain-id>.
+I<devid> is the virtual interface device number within the domain
+
+=item B<vkb-list> I<domain-id>
+
+List virtual network interfaces for a domain.
+
+=back
+
+=head1 PCI PASS-THROUGH
+
+=over 4
+
+=item B<pci-assignable-list>
+
+List all the assignable PCI devices.
+These are devices in the system which are configured to be
+available for passthrough and are bound to a suitable PCI
+backend driver in domain 0 rather than a real driver.
+
+=item B<pci-assignable-add> I<BDF>
+
+Make the device at PCI Bus/Device/Function BDF assignable to guests.
+This will bind the device to the pciback driver. If it is already
+bound to a driver, it will first be unbound, and the original driver
+stored so that it can be re-bound to the same driver later if desired.
+If the device is already bound, it will return success.
+
+CAUTION: This will make the device unusable by Domain 0 until it is
+returned with pci-assignable-remove. Care should therefore be taken
+not to do this on a device critical to domain 0's operation, such as
+storage controllers, network interfaces, or GPUs that are currently
+being used.
+
+=item B<pci-assignable-remove> [I<-r>] I<BDF>
+
+Make the device at PCI Bus/Device/Function BDF not assignable to guests. This
+will at least unbind the device from pciback. If the -r option is specified,
+it will also attempt to re-bind the device to its original driver, making it
+usable by Domain 0 again. If the device is not bound to pciback, it will
+return success.
+
+=item B<pci-attach> I<domain-id> I<BDF>
+
+Hot-plug a new pass-through pci device to the specified domain.
+B<BDF> is the PCI Bus/Device/Function of the physical device to pass-through.
+
+=item B<pci-detach> [I<OPTIONS>] I<domain-id> I<BDF>
+
+Hot-unplug a previously assigned pci device from a domain. B<BDF> is the PCI
+Bus/Device/Function of the physical device to be removed from the guest domain.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-f>
+
+If this parameter is specified, B<xl> is going to forcefully remove the device
+even without guest domain's collaboration.
+
+=back
+
+=item B<pci-list> I<domain-id>
+
+List pass-through pci devices for a domain.
+
+=back
+
+=head1 USB PASS-THROUGH
+
+=over 4
+
+=item B<usbctrl-attach> I<domain-id> I<usbctrl-device>
+
+Create a new USB controller in the domain specified by I<domain-id>,
+I<usbctrl-device> describes the device to attach, using form
+C<KEY=VALUE KEY=VALUE ...> where B<KEY=VALUE> has the same
+meaning as the B<usbctrl> description in the domain config file.
+See L<xl.cfg(5)> for more information.
+
+=item B<usbctrl-detach> I<domain-id> I<devid>
+
+Destroy a USB controller from the specified domain.
+B<devid> is devid of the USB controller.
+
+=item B<usbdev-attach> I<domain-id> I<usbdev-device>
+
+Hot-plug a new pass-through USB device to the domain specified by
+I<domain-id>, I<usbdev-device> describes the device to attach, using
+form C<KEY=VALUE KEY=VALUE ...> where B<KEY=VALUE> has the same
+meaning as the B<usbdev> description in the domain config file.
+See L<xl.cfg(5)> for more information.
+
+=item B<usbdev-detach> I<domain-id> I<controller=devid> I<port=number>
+
+Hot-unplug a previously assigned USB device from a domain.
+B<controller=devid> and B<port=number> is USB controller:port in the guest
+domain the USB device is attached to.
+
+=item B<usb-list> I<domain-id>
+
+List pass-through usb devices for a domain.
+
+=back
+
+=head1 DEVICE-MODEL CONTROL
+
+=over 4
+
+=item B<qemu-monitor-command> I<domain-id> I<command>
+
+Issue a monitor command to the device model of the domain specified by
+I<domain-id>. I<command> can be any valid command qemu understands. This
+can be e.g. used to add non-standard devices or devices with non-standard
+parameters to a domain. The output of the command is printed to stdout.
+
+B<Warning:> This qemu monitor access is provided for convenience when
+debugging, troubleshooting, and experimenting. Its use is not
+supported by the Xen Project.
+
+Specifically, not all information displayed by the qemu monitor will
+necessarily be accurate or complete, because in a Xen system qemu
+does not have a complete view of the guest.
+
+Furthermore, modifying the guest's setup via the qemu monitor may
+conflict with the Xen toolstack's assumptions. Resulting problems
+may include, but are not limited to: guest crashes; toolstack error
+messages; inability to migrate the guest; and security
+vulnerabilities which are not covered by the Xen Project security
+response policy.
+
+B<EXAMPLE>
+
+Obtain information of USB devices connected as such via the device model
+(only!) to a domain:
+
+ xl qemu-monitor-command vm1 'info usb'
+ Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage
+
+=back
+
+=head1 TRANSCENDENT MEMORY (TMEM)
+
+=over 4
+
+=item B<tmem-list> I<[OPTIONS]> I<domain-id>
+
+List tmem pools.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-l>
+
+If this parameter is specified, also list tmem stats.
+
+=back
+
+=item B<tmem-freeze> I<domain-id>
+
+Freeze tmem pools.
+
+=item B<tmem-thaw> I<domain-id>
+
+Thaw tmem pools.
+
+=item B<tmem-set> I<domain-id> [I<OPTIONS>]
+
+Change tmem settings.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-w> I<WEIGHT>
+
+Weight (int)
+
+=item B<-p> I<COMPRESS>
+
+Compress (int)
+
+=back
+
+=item B<tmem-shared-auth> I<domain-id> [I<OPTIONS>]
+
+De/authenticate shared tmem pool.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-u> I<UUID>
+
+Specify uuid (abcdef01-2345-6789-1234-567890abcdef)
+
+=item B<-a> I<AUTH>
+
+0=auth,1=deauth
+
+=back
+
+=item B<tmem-freeable>
+
+Get information about how much freeable memory (MB) is in-use by tmem.
+
+=back
+
+=head1 FLASK
+
+B<FLASK> is a security framework that defines a mandatory access control policy
+providing fine-grained controls over Xen domains, allowing the policy writer
+to define what interactions between domains, devices, and the hypervisor are
+permitted. Some example of what you can do using XSM/FLASK:
+ - Prevent two domains from communicating via event channels or grants
+ - Control which domains can use device passthrough (and which devices)
+ - Restrict or audit operations performed by privileged domains
+ - Prevent a privileged domain from arbitrarily mapping pages from other
+ domains.
+
+You can find more details on how to use FLASK and an example security
+policy here: L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
+
+=over 4
+
+=item B<getenforce>
+
+Determine if the FLASK security module is loaded and enforcing its policy.
+
+=item B<setenforce> I<1|0|Enforcing|Permissive>
+
+Enable or disable enforcing of the FLASK access controls. The default is
+permissive, but this can be changed to enforcing by specifying "flask=enforcing"
+or "flask=late" on the hypervisor's command line.
+
+=item B<loadpolicy> I<policy-file>
+
+Load FLASK policy from the given policy file. The initial policy is provided to
+the hypervisor as a multiboot module; this command allows runtime updates to the
+policy. Loading new security policy will reset runtime changes to device labels.
+
+=back
+
+=head1 PLATFORM SHARED RESOURCE MONITORING/CONTROL
+
+Intel Haswell and later server platforms offer shared resource monitoring
+and control technologies. The availability of these technologies and the
+hardware capabilities can be shown with B<psr-hwinfo>.
+
+See L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html> for more
+information.
+
+=over 4
+
+=item B<psr-hwinfo> [I<OPTIONS>]
+
+Show Platform Shared Resource (PSR) hardware information.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-m>, B<--cmt>
+
+Show Cache Monitoring Technology (CMT) hardware information.
+
+=item B<-a>, B<--cat>
+
+Show Cache Allocation Technology (CAT) hardware information.
+
+=back
+
+=back
+
+=head2 CACHE MONITORING TECHNOLOGY
+
+Intel Haswell and later server platforms offer monitoring capability in each
+logical processor to measure specific platform shared resource metric, for
+example, L3 cache occupancy. In the Xen implementation, the monitoring
+granularity is domain level. To monitor a specific domain, just attach the
+domain id with the monitoring service. When the domain doesn't need to be
+monitored any more, detach the domain id from the monitoring service.
+
+Intel Broadwell and later server platforms also offer total/local memory
+bandwidth monitoring. Xen supports per-domain monitoring for these two
+additional monitoring types. Both memory bandwidth monitoring and L3 cache
+occupancy monitoring share the same set of underlying monitoring service. Once
+a domain is attached to the monitoring service, monitoring data can be shown
+for any of these monitoring types.
+
+There is no cache monitoring and memory bandwidth monitoring on L2 cache so
+far.
+
+=over 4
+
+=item B<psr-cmt-attach> I<domain-id>
+
+attach: Attach the platform shared resource monitoring service to a domain.
+
+=item B<psr-cmt-detach> I<domain-id>
+
+detach: Detach the platform shared resource monitoring service from a domain.
+
+=item B<psr-cmt-show> I<psr-monitor-type> [I<domain-id>]
+
+Show monitoring data for a certain domain or all domains. Current supported
+monitor types are:
+ - "cache-occupancy": showing the L3 cache occupancy(KB).
+ - "total-mem-bandwidth": showing the total memory bandwidth(KB/s).
+ - "local-mem-bandwidth": showing the local memory bandwidth(KB/s).
+
+=back
+
+=head2 CACHE ALLOCATION TECHNOLOGY
+
+Intel Broadwell and later server platforms offer capabilities to configure and
+make use of the Cache Allocation Technology (CAT) mechanisms, which enable more
+cache resources (i.e. L3/L2 cache) to be made available for high priority
+applications. In the Xen implementation, CAT is used to control cache allocation
+on VM basis. To enforce cache on a specific domain, just set capacity bitmasks
+(CBM) for the domain.
+
+Intel Broadwell and later server platforms also offer Code/Data Prioritization
+(CDP) for cache allocations, which support specifying code or data cache for
+applications. CDP is used on a per VM basis in the Xen implementation. To
+specify code or data CBM for the domain, CDP feature must be enabled and CBM
+type options need to be specified when setting CBM, and the type options (code
+and data) are mutually exclusive. There is no CDP support on L2 so far.
+
+=over 4
+
+=item B<psr-cat-set> [I<OPTIONS>] I<domain-id> I<cbm>
+
+Set cache capacity bitmasks(CBM) for a domain. For how to specify I<cbm>
+please refer to L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-s SOCKET>, B<--socket=SOCKET>
+
+Specify the socket to process, otherwise all sockets are processed.
+
+=item B<-l LEVEL>, B<--level=LEVEL>
+
+Specify the cache level to process, otherwise the last level cache (L3) is
+processed.
+
+=item B<-c>, B<--code>
+
+Set code CBM when CDP is enabled.
+
+=item B<-d>, B<--data>
+
+Set data CBM when CDP is enabled.
+
+=back
+
+=item B<psr-cat-show> [I<OPTIONS>] [I<domain-id>]
+
+Show CAT settings for a certain domain or all domains.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-l LEVEL>, B<--level=LEVEL>
+
+Specify the cache level to process, otherwise the last level cache (L3) is
+processed.
+
+=back
+
+=back
+
+=head2 Memory Bandwidth Allocation
+
+Intel Skylake and later server platforms offer capabilities to configure and
+make use of the Memory Bandwidth Allocation (MBA) mechanisms, which provides
+OS/VMMs the ability to slow misbehaving apps/VMs by using a credit-based
+throttling mechanism. In the Xen implementation, MBA is used to control memory
+bandwidth on VM basis. To enforce bandwidth on a specific domain, just set
+throttling value (THRTL) for the domain.
+
+=over 4
+
+=item B<psr-mba-set> [I<OPTIONS>] I<domain-id> I<thrtl>
+
+Set throttling value (THRTL) for a domain. For how to specify I<thrtl>
+please refer to L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
+
+B<OPTIONS>
+
+=over 4
+
+=item B<-s SOCKET>, B<--socket=SOCKET>
+
+Specify the socket to process, otherwise all sockets are processed.
+
+=back
+
+=item B<psr-mba-show> [I<domain-id>]
+
+Show MBA settings for a certain domain or all domains. For linear mode, it
+shows the decimal value. For non-linear mode, it shows hexadecimal value.
+
+=back
+
+=head1 IGNORED FOR COMPATIBILITY WITH XM
+
+xl is mostly command-line compatible with the old xm utility used with
+the old Python xend. For compatibility, the following options are
+ignored:
+
+=over 4
+
+=item B<xl migrate --live>
+
+=back
+
+=head1 TO BE DOCUMENTED
+
+We need better documentation for:
+
+=over 4
+
+=item B<tmem>
+
+Transcendent Memory.
+
+=back
+
+=head1 SEE ALSO
+
+The following man pages:
+
+L<xl.cfg>(5), L<xlcpupool.cfg>(5), L<xentop>(1), L<xl-disk-configuration(5)>
+L<xl-network-configuration(5)>
+
+And the following documents on the xen.org website:
+
+L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
+L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
+
+For systems that don't automatically bring the CPU online:
+
+L<http://wiki.xen.org/wiki/Paravirt_Linux_CPU_Hotplug>
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xl.cfg - xl domain configuration file syntax
+
+=head1 SYNOPSIS
+
+ /etc/xen/xldomain
+
+=head1 DESCRIPTION
+
+Creating a VM (a domain in Xen terminology, sometimes called a guest)
+with xl requires the provision of a domain configuration file. Typically,
+these live in F</etc/xen/DOMAIN.cfg>, where DOMAIN is the name of the
+domain.
+
+=head1 SYNTAX
+
+A domain configuration file consists of a series of options, specified by
+using C<KEY=VALUE> pairs.
+
+Some C<KEY>s are mandatory, some are general options which apply to
+any guest type, while others relate only to specific guest types
+(e.g. PV or HVM guests).
+
+A C<VALUE> can be one of:
+
+=over 4
+
+=item B<"STRING">
+
+A string, surrounded by either single or double quotes. But if the
+STRING is part of a SPEC_STRING, the quotes should be omitted.
+
+=item B<NUMBER>
+
+A number, in either decimal, octal (using a C<0> prefix) or
+hexadecimal (using a C<0x> prefix) format.
+
+=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<VALUE>s of the above types. Lists can be heterogeneous and
+nested.
+
+=back
+
+The semantics of each C<KEY> defines which type of C<VALUE> is required.
+
+Pairs may be separated either by a newline or a semicolon. Both
+of the following are valid:
+
+ name="h0"
+ type="hvm"
+
+ name="h0"; type="hvm"
+
+=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<type="pv">
+
+Specifies that this is to be a PV domain, suitable for hosting Xen-aware
+guest operating systems. This is the default on x86.
+
+=item B<type="pvh">
+
+Specifies that this is to be an PVH domain. That is a lightweight HVM-like
+guest without a device model and without many of the emulated devices
+available to HVM guests. Note that this mode requires a PVH aware kernel on
+x86. This is the default on Arm.
+
+=item B<type="hvm">
+
+Specifies that this is to be an HVM domain. That is, a fully virtualised
+computer with emulated BIOS, disk and network peripherals, etc.
+
+=back
+
+=head3 Deprecated guest type selection
+
+Note that the builder option is being deprecated in favor of the type
+option.
+
+=over 4
+
+=item B<builder="generic">
+
+Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest
+operating systems. 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.
+
+=back
+
+=head2 General Options
+
+The following options apply to guests of any type.
+
+=head3 CPU Allocation
+
+=over 4
+
+=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. When starting the guest, if
+B<vcpus=N> is less than B<maxvcpus=M> then the first B<N> vCPUs will be
+created online and the remainder will be created offline.
+
+=item B<cpus="CPULIST">
+
+List of host CPUs the guest is allowed to use. Default is no pinning at
+all (more on this below). A C<CPULIST> may be specified as follows:
+
+=over 4
+
+=item "all"
+
+To allow all the vCPUs of the guest to run on all the CPUs on the host.
+
+=item "0-3,5,^1"
+
+To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It is possible to
+combine this with "all", meaning "all,^7" results in all the vCPUs
+of the guest being allowed to run on all the CPUs of the host except CPU 7.
+
+=item "nodes:0-3,^node:2"
+
+To allow all the vCPUs of the guest to run on the CPUs from NUMA nodes
+0,1,3 of the host. So, if CPUs 0-3 belong to node 0, CPUs 4-7 belong
+to node 1, CPUs 8-11 to node 2 and CPUs 12-15 to node 3, the above would mean
+all the vCPUs of the guest would be allowed to run on CPUs 0-7,12-15.
+
+Combining this notation with the one above is possible. For instance,
+"1,node:1,^6", means all the vCPUs of the guest will run on CPU 1 and
+on all the CPUs of NUMA node 1, but not on CPU 6. Following the same
+example as above, that would be CPUs 1,4,5,7.
+
+Combining this with "all" is also possible, meaning "all,^node:1"
+results in all the vCPUs of the guest running on all the CPUs on the
+host, except for the CPUs belonging to the host NUMA node 1.
+
+=item ["2", "3-8,^5"]
+
+To ask for specific vCPU mapping. That means (in this example), vCPU 0
+of the guest will run on CPU 2 of the host and vCPU 1 of the guest will
+run on CPUs 3,4,6,7,8 of the host (excluding CPU 5).
+
+More complex notation can be also used, exactly as described above. So
+"all,^5-8", or just "all", or "node:0,node:2,^9-11,18-20" are all legal,
+for each element of the list.
+
+=back
+
+If this option is not specified, no vCPU to CPU pinning is established,
+and the vCPUs of the guest can run on all the CPUs of the host. If this
+option is specified, the intersection of the vCPU pinning mask, provided
+here, and the soft affinity mask, if provided via B<cpus_soft=>,
+is utilized to compute the domain node-affinity for driving memory
+allocations.
+
+=item B<cpus_soft="CPULIST">
+
+Exactly as B<cpus=>, but specifies soft affinity, rather than pinning
+(hard affinity). When using the credit scheduler, this means what CPUs
+the vCPUs of the domain prefer.
+
+A C<CPULIST> is specified exactly as for B<cpus=>, detailed earlier in the
+manual.
+
+If this option is not specified, the vCPUs of the guest will not have
+any preference regarding host CPUs. If this option is specified,
+the intersection of the soft affinity mask, provided here, and the vCPU
+pinning, if provided via B<cpus=>, is utilized to compute the
+domain node-affinity for driving memory allocations.
+
+If this option is not specified (and B<cpus=> is not specified either),
+libxl automatically tries to place the guest on the least possible
+number of nodes. A heuristic approach is used for choosing the best
+node (or set of nodes), with the goal of maximizing performance for
+the guest and, at the same time, achieving efficient utilization of
+host CPUs and memory. In that case, the soft affinity of all the vCPUs
+of the domain will be set to host CPUs belonging to NUMA nodes
+chosen during placement.
+
+For more details, see L<xl-numa-placement(7)>.
+
+=back
+
+=head3 CPU Scheduling
+
+=over 4
+
+=item B<cpu_weight=WEIGHT>
+
+A domain with a weight of 512 will get twice as much CPU as a domain
+with a weight of 256 on a contended host.
+Legal weights range from 1 to 65535 and the default is 256.
+Honoured by the credit and credit2 schedulers.
+
+=item B<cap=N>
+
+The cap optionally fixes the maximum amount of CPU a domain will be
+able to consume, even if the host system has idle CPU cycles.
+The cap is expressed as a percentage of one physical CPU:
+100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
+The default, 0, means there is no cap.
+Honoured by the credit and credit2 schedulers.
+
+B<NOTE>: Many systems have features that will scale down the computing
+power of a CPU that is not 100% utilized. This can be done in the
+operating system, but can also sometimes be done below the operating system,
+in the BIOS. If you set a cap such that individual cores are running
+at less than 100%, this may have an impact on the performance of your
+workload over and above the impact of the cap. For example, if your
+processor runs at 2GHz, and you cap a VM at 50%, the power management
+system may also reduce the clock speed to 1GHz; the effect will be
+that your VM gets 25% of the available power (50% of 1GHz) rather than
+50% (50% of 2GHz). If you are not getting the performance you expect,
+look at performance and CPU frequency options in your operating system and
+your BIOS.
+
+=back
+
+=head3 Memory Allocation
+
+=over 4
+
+=item B<memory=MBYTES>
+
+Start the guest with MBYTES megabytes of RAM.
+
+=item B<maxmem=MBYTES>
+
+Specifies the maximum amount of memory a guest can ever see.
+The value of B<maxmem=> must be equal to or greater than that of B<memory=>.
+
+In combination with B<memory=> it will start the guest "pre-ballooned",
+if the values of B<memory=> and B<maxmem=> differ.
+A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver
+it will crash.
+
+B<NOTE>: Because of the way ballooning works, the guest has to allocate
+memory to keep track of maxmem pages, regardless of how much memory it
+actually has available to it. A guest with maxmem=262144 and
+memory=8096 will report significantly less memory available for use
+than a system with maxmem=8096 memory=8096 due to the memory overhead
+of having to track the unused pages.
+
+=back
+
+=head3 Guest Virtual NUMA Configuration
+
+=over 4
+
+=item B<vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]>
+
+Specify virtual NUMA configuration with positional arguments. The
+nth B<VNODE_SPEC> in the list specifies the configuration of the nth
+virtual node.
+
+Note that virtual NUMA is not supported for PV guests yet, because
+there is an issue with the CPUID instruction handling that affects PV virtual
+NUMA. Furthermore, guests with virtual NUMA cannot be saved or migrated
+because the migration stream does not preserve node information.
+
+Each B<VNODE_SPEC> is a list, which has a form of
+"[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the quotes).
+
+For example, vnuma = [ ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ]
+means vnode 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the
+distance to itself is 10 and the distance to vnode 1 is 20.
+
+Each B<VNODE_CONFIG_OPTION> is a quoted C<KEY=VALUE> pair. Supported
+B<VNODE_CONFIG_OPTION>s are (they are all mandatory at the moment):
+
+=over 4
+
+=item B<pnode=NUMBER>
+
+Specifies which physical node this virtual node maps to.
+
+=item B<size=MBYTES>
+
+Specifies the size of this virtual node. The sum of memory sizes of all
+vnodes will become B<maxmem=>. If B<maxmem=> is specified separately,
+a check is performed to make sure the sum of all vnode memory matches
+B<maxmem=>.
+
+=item B<vcpus="CPUSTRING">
+
+Specifies which vCPUs belong to this node. B<"CPUSTRING"> is a string of numerical
+values separated by a comma. You can specify a range and/or a single CPU.
+An example would be "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5,
+and vCPU 8.
+
+=item B<vdistances=NUMBER, NUMBER, ... >
+
+Specifies the virtual distance from this node to all nodes (including
+itself) with positional arguments. For example, "vdistance=10,20"
+for vnode 0 means the distance from vnode 0 to vnode 0 is 10, from
+vnode 0 to vnode 1 is 20. The number of arguments supplied must match
+the total number of vnodes.
+
+Normally you can use the values from B<xl info -n> or B<numactl
+--hardware> to fill the vdistances list.
+
+=back
+
+=back
+
+=head3 Event Actions
+
+=over 4
+
+=item B<on_poweroff="ACTION">
+
+Specifies what should be done with the domain if it shuts itself down.
+The B<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 then immediately 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 B<xl destroy>.
+
+=item B<coredump-destroy>
+
+write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then
+destroy the domain.
+
+=item B<coredump-restart>
+
+write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then
+restart the domain.
+
+=item B<soft-reset>
+
+Reset all Xen specific interfaces for the Xen-aware HVM domain allowing
+it to reestablish these interfaces and continue executing the domain. PV
+and non-Xen-aware HVM guests are not supported.
+
+=back
+
+The default for B<on_poweroff> is B<destroy>.
+
+=item B<on_reboot="ACTION">
+
+Action to take if the domain shuts down with a reason code requesting
+a reboot. Default is B<restart>.
+
+=item B<on_watchdog="ACTION">
+
+Action to take if the domain shuts down due to a Xen watchdog timeout.
+Default is B<destroy>.
+
+=item B<on_crash="ACTION">
+
+Action to take if the domain crashes. Default is B<destroy>.
+
+=item B<on_soft_reset="ACTION">
+
+Action to take if the domain performs a 'soft reset' (e.g. does B<kexec>).
+Default is B<soft-reset>.
+
+=back
+
+=head3 Direct Kernel Boot
+
+Direct kernel boot allows booting guests with a kernel and an initrd
+stored on a filesystem available to the host physical machine, allowing
+command line arguments to be passed directly. PV guest direct kernel boot is
+supported. HVM guest direct kernel boot is supported with some limitations
+(it's supported when using B<qemu-xen> and the default BIOS 'seabios',
+but not supported in case of using B<stubdom-dm> and the old 'rombios'.)
+
+=over 4
+
+=item B<kernel="PATHNAME">
+
+Load the specified file as the kernel image.
+
+=item B<ramdisk="PATHNAME">
+
+Load the specified file as the ramdisk.
+
+=item B<cmdline="STRING">
+
+Append B<STRING> to the kernel command line. (Note: the meaning of
+this is guest specific). It can replace B<root="STRING">
+along with B<extra="STRING"> and is preferred. When B<cmdline="STRING"> is set,
+B<root="STRING"> and B<extra="STRING"> will be ignored.
+
+=item B<root="STRING">
+
+Append B<root=STRING> to the kernel command line (Note: the meaning of this
+is guest specific).
+
+=item B<extra="STRING">
+
+Append B<STRING> to the kernel command line. (Note: the meaning of this
+is guest specific).
+
+=back
+
+=head3 Non direct Kernel Boot
+
+Non direct kernel boot allows booting guests with a firmware. This can be
+used by all types of guests, although the selection of options is different
+depending on the guest type.
+
+This option provides the flexibly of letting the guest decide which kernel
+they want to boot, while preventing having to poke at the guest file
+system form the toolstack domain.
+
+=head4 PV guest options
+
+=over 4
+
+=item B<firmware="pvgrub32|pvgrub64">
+
+Boots a guest using a para-virtualized version of grub that runs inside
+of the guest. The bitness of the guest needs to be know, so that the right
+version of pvgrub can be selected.
+
+Note that xl expects to find the pvgrub32.bin and pvgrub64.bin binaries in
+F<@XENFIRMWAREDIR@>.
+
+=back
+
+=head4 HVM guest options
+
+=over 4
+
+=item B<firmware="bios">
+
+Boot the guest using the default BIOS firmware, which depends on the
+chosen device model.
+
+=item B<firmware="uefi">
+
+Boot the guest using the default UEFI firmware, currently OVMF.
+
+=item B<firmware="seabios">
+
+Boot the guest using the SeaBIOS BIOS firmware.
+
+=item B<firmware="rombios">
+
+Boot the guest using the ROMBIOS BIOS firmware.
+
+=item B<firmware="ovmf">
+
+Boot the guest using the OVMF UEFI firmware.
+
+=item B<firmware="PATH">
+
+Load the specified file as firmware for the guest.
+
+=back
+
+=head4 PVH guest options
+
+Currently there's no firmware available for PVH guests, they should be
+booted using the B<Direct Kernel Boot> method or the B<bootloader> option.
+
+=over 4
+
+=item B<pvshim=BOOLEAN>
+
+Whether to boot this guest as a PV guest within a PVH container.
+Ie, the guest will experience a PV environment,
+but
+processor hardware extensions are used to
+separate its address space
+to mitigate the Meltdown attack (CVE-2017-5754).
+
+Default is false.
+
+=item B<pvshim_path="PATH">
+
+The PV shim is a specially-built firmware-like executable
+constructed from the hypervisor source tree.
+This option specifies to use a non-default shim.
+Ignored if pvhsim is false.
+
+=item B<pvshim_cmdline="STRING">
+
+Command line for the shim.
+Default is "pv-shim console=xen,pv".
+Ignored if pvhsim is false.
+
+=item B<pvshim_extra="STRING">
+
+Extra command line arguments for the shim.
+If supplied, appended to the value for pvshim_cmdline.
+Default is empty.
+Ignored if pvhsim is false.
+
+=back
+
+=head3 Other Options
+
+=over 4
+
+=item B<uuid="UUID">
+
+Specifies the UUID of the domain. If not specified, a fresh unique
+UUID will be generated.
+
+=item B<seclabel="LABEL">
+
+Assign an XSM security label to this domain.
+
+=item B<init_seclabel="LABEL">
+
+Specify an XSM security label used for this domain temporarily during
+its build. The domain's XSM label will be changed to the execution
+seclabel (specified by B<seclabel>) once the build is complete, prior to
+unpausing the domain. With a properly constructed security policy (such
+as nomigrate_t in the example policy), this can be used to build a
+domain whose memory is not accessible to the toolstack domain.
+
+=item B<max_grant_frames=NUMBER>
+
+Specify the maximum number of grant frames the domain is allowed to have.
+This value controls how many pages the domain is able to grant access to for
+other domains, needed e.g. for the operation of paravirtualized devices.
+The default is settable via L<xl.conf(5)>.
+
+=item B<max_maptrack_frames=NUMBER>
+
+Specify the maximum number of grant maptrack frames the domain is allowed
+to have. This value controls how many pages of foreign domains can be accessed
+via the grant mechanism by this domain. The default value is settable via
+L<xl.conf(5)>.
+
+=item B<nomigrate=BOOLEAN>
+
+Disable migration of this domain. This enables certain other features
+which are incompatible with migration. Currently this is limited to
+enabling the invariant TSC feature flag in CPUID results when TSC is
+not emulated.
+
+=item B<driver_domain=BOOLEAN>
+
+Specify that this domain is a driver domain. This enables certain
+features needed in order to run a driver domain.
+
+=item B<device_tree=PATH>
+
+Specify a partial device tree (compiled via the Device Tree Compiler).
+Everything under the node "/passthrough" will be copied into the guest
+device tree. For convenience, the node "/aliases" is also copied to allow
+the user to define aliases which can be used by the guest kernel.
+
+Given the complexity of verifying the validity of a device tree, this
+option should only be used with a trusted device tree.
+
+Note that the partial device tree should avoid using the phandle 65000
+which is reserved by the toolstack.
+
+=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 host they should map to. See L<xl-disk-configuration(5)> for more
+details.
+
+=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
+
+Specifies the network interfaces (both emulated network adapters,
+and Xen virtual interfaces) which are to be provided to the guest. See
+L<xl-network-configuration(5)> for more details.
+
+=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]>
+
+Specifies the Virtual Trusted Platform module to be
+provided to the guest. See L<xen-vtpm(7)> for more details.
+
+Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings from the following list:
+
+=over 4
+
+=item B<backend=domain-id>
+
+Specifies the backend domain name or id. B<This value is required!>
+If this domain is a guest, the backend should be set to the
+vTPM domain name. If this domain is a vTPM, the
+backend should be set to the vTPM manager domain name.
+
+=item B<uuid=UUID>
+
+Specifies the UUID of this vTPM device. The UUID is used to uniquely
+identify the vTPM device. You can create one using the B<uuidgen(1)>
+program on unix systems. If left unspecified, a new UUID
+will be randomly generated every time the domain boots.
+If this is a vTPM domain, you should specify a value. The
+value is optional if this is a guest domain.
+
+=back
+
+=item B<p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]>
+
+Creates a Xen 9pfs connection to share a filesystem from the backend to the
+frontend.
+
+Each B<9PFS_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings, from the following list:
+
+=over 4
+
+=item B<tag=STRING>
+
+9pfs tag to identify the filesystem share. The tag is needed on the
+guest side to mount it.
+
+=item B<security_model="none">
+
+Only "none" is supported today, which means that the files are stored using
+the same credentials as those they have in the guest (no user ownership
+squash or remap).
+
+=item B<path=STRING>
+
+Filesystem path on the backend to export.
+
+=item B<backend=domain-id>
+
+Specify the backend domain name or id, defaults to dom0.
+
+=back
+
+=item B<pvcalls=[ "backend=domain-id", ... ]>
+
+Creates a Xen pvcalls connection to handle pvcalls requests from
+frontend to backend. It can be used as an alternative networking model.
+For more information about the protocol, see
+https://xenbits.xen.org/docs/unstable/misc/pvcalls.html.
+
+=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]>
+
+Specifies the paravirtual framebuffer devices which should be supplied
+to the domain.
+
+This option does not control the emulated graphics card presented to
+an HVM guest. See B<Emulated VGA Graphics Device> below for how to
+configure the emulated device. If B<Emulated VGA Graphics Device> options
+are used in a PV guest configuration, B<xl> will pick up B<vnc>, B<vnclisten>,
+B<vncpasswd>, B<vncdisplay>, B<vncunused>, B<sdl>, B<opengl> and
+B<keymap> to construct the paravirtual framebuffer device for the guest.
+
+Each B<VFB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings, from the following list:
+
+=over 4
+
+=item B<vnc=BOOLEAN>
+
+Allow access to the display via the VNC protocol. This enables the
+other VNC-related settings. Default is 1 (enabled).
+
+=item B<vnclisten=ADDRESS[:DISPLAYNUM]>
+
+Specifies the IP address, and optionally the VNC display number, to use.
+
+Note: if you specify the display number here, you should not use
+the B<vncdisplay> option.
+
+=item B<vncdisplay=DISPLAYNUM>
+
+Specifies the VNC display number to use. The actual TCP port number
+will be DISPLAYNUM+5900.
+
+Note: you should not use this option if you set the DISPLAYNUM in the
+B<vnclisten> option.
+
+=item B<vncunused=BOOLEAN>
+
+Requests that the VNC display setup searches for a free TCP port to use.
+The actual display used can be accessed with B<xl vncviewer>.
+
+=item B<vncpasswd=PASSWORD>
+
+Specifies the password for the VNC server. If the password is set to an
+empty string, authentication on the VNC server will be disabled,
+allowing any user to connect.
+
+=item B<sdl=BOOLEAN>
+
+Specifies that the display should be presented via an X window (using
+Simple DirectMedia Layer). The default is 0 (not enabled).
+
+=item B<display=DISPLAY>
+
+Specifies the X Window display that should be used when the B<sdl> option
+is used.
+
+=item B<xauthority=XAUTHORITY>
+
+Specifies the path to the X authority file that should be used to
+connect to the X server when the B<sdl> option is used.
+
+=item B<opengl=BOOLEAN>
+
+Enable OpenGL acceleration of the SDL display. Only effects machines
+using B<device_model_version="qemu-xen-traditional"> and only if the
+device-model was compiled with OpenGL support. The default is 0 (disabled).
+
+=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 B<Keymaps> below or consult the
+B<qemu(1)> manpage. The default is B<en-us>.
+
+=back
+
+=item B<channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]>
+
+Specifies the virtual channels to be provided to the guest. A
+channel is a low-bandwidth, bidirectional byte stream, which resembles
+a serial link. Typical uses for channels include transmitting VM
+configuration after boot and signalling to in-guest agents. Please see
+L<xen-pv-channel(7)> for more details.
+
+Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings. Leading and trailing whitespace is ignored in both KEY and
+VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'. Defined values
+are:
+
+=over 4
+
+=item B<backend=domain-id>
+
+Specifies the backend domain name or id. This parameter is optional. If
+this parameter is omitted then the toolstack domain will be assumed.
+
+=item B<name=NAME>
+
+Specifies the name for this device. B<This parameter is mandatory!>
+This should be a well-known name for a specific application (e.g.
+guest agent) and should be used by the frontend to connect the
+application to the right channel device. There is no formal registry
+of channel names, so application authors are encouraged to make their
+names unique by including the domain name and a version number in the string
+(e.g. org.mydomain.guestagent.1).
+
+=item B<connection=CONNECTION>
+
+Specifies how the backend will be implemented. The following options are
+available:
+
+=over 4
+
+=item B<SOCKET>
+
+The backend will bind a Unix domain socket (at the path given by
+B<path=PATH>), listen for and accept connections. The backend will proxy
+data between the channel and the connected socket.
+
+=item B<PTY>
+
+The backend will create a pty and proxy data between the channel and the
+master device. The command B<xl channel-list> can be used to discover the
+assigned slave device.
+
+=back
+
+=back
+
+=item B<rdm="RDM_RESERVATION_STRING">
+
+B<HVM/x86 only!> Specifies information about Reserved Device Memory (RDM),
+which is necessary to enable robust device passthrough. One example of RDM
+is reporting through the ACPI Reserved Memory Region Reporting (RMRR) structure
+on the x86 platform.
+
+B<RDM_RESERVATION_STRING> is a comma separated list of C<KEY=VALUE> settings,
+from the following list:
+
+=over 4
+
+=item B<strategy=STRING>
+
+Currently there is only one valid type, and that is "host".
+
+=over 4
+
+=item B<host>
+
+If set to "host" it means all reserved device memory on this platform should
+be checked to reserve regions in this VM's address space. This global RDM
+parameter allows the user to specify reserved regions explicitly, and using
+"host" includes all reserved regions reported on this platform, which is
+useful when doing hotplug.
+
+By default this isn't set so we don't check all RDMs. Instead, we just check
+the RDM specific to a given device if we're assigning this kind of a device.
+
+Note: this option is not recommended unless you can make sure that no
+conflicts exist.
+
+For example, you're trying to set "memory = 2800" to allocate memory to one
+given VM but the platform owns two RDM regions like:
+
+Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000 end_address ac6e6fff
+
+Device B [sbdf_B]: RMRR region_B: base_addr ad800000 end_address afffffff
+
+In this conflict case,
+
+#1. If B<strategy> is set to "host", for example:
+
+rdm = "strategy=host,policy=strict" or rdm = "strategy=host,policy=relaxed"
+
+it means all conflicts will be handled according to the policy
+introduced by B<policy> as described below.
+
+#2. If B<strategy> is not set at all, but
+
+pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
+
+it means only one conflict of region_A will be handled according to the policy
+introduced by B<rdm_policy=STRING> as described inside B<pci> options.
+
+=back
+
+=item B<policy=STRING>
+
+Specifies how to deal with conflicts when reserving already reserved device
+memory in the guest address space.
+
+=over 4
+
+=item B<strict>
+
+Specifies that in case of an unresolved conflict the VM can't be created,
+or the associated device can't be attached in the case of hotplug.
+
+=item B<relaxed>
+
+Specifies that in case of an unresolved conflict the VM is allowed to be
+created but may cause the VM to crash if a pass-through device accesses RDM.
+For example, the Windows IGD GFX driver always accesses RDM regions so it
+leads to a VM crash.
+
+Note: this may be overridden by the B<rdm_policy> option in the B<pci>
+device configuration.
+
+=back
+
+=back
+
+=item B<usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]>
+
+Specifies the USB controllers created for this guest.
+
+Each B<USBCTRL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings, from the following list:
+
+=over 4
+
+=item B<type=TYPE>
+
+Specifies the usb controller type.
+
+=over 4
+
+=item B<pv>
+
+Specifies a kernel based PVUSB backend.
+
+=item B<qusb>
+
+Specifies a QEMU based PVUSB backend.
+
+=item B<devicemodel>
+
+Specifies a USB controller emulated by QEMU.
+It will show up as a PCI-device in the guest.
+
+=item B<auto>
+
+Determines whether a kernel based backend is installed.
+If this is the case, B<pv> is used, otherwise B<qusb> will be used.
+For HVM domains B<devicemodel> will be selected.
+
+This option is the default.
+
+=back
+
+=item B<version=VERSION>
+
+Specifies the usb controller version. Possible values include
+1 (USB1.1), 2 (USB2.0) and 3 (USB3.0).
+Default is 2 (USB2.0).
+Value 3 (USB3.0) is available for the B<devicemodel> type only.
+
+=item B<ports=PORTS>
+
+Specifies the total number of ports of the usb controller. The maximum
+number is 31. The default is 8.
+With the type B<devicemodel> the number of ports is more limited:
+a USB1.1 controller always has 2 ports,
+a USB2.0 controller always has 6 ports
+and a USB3.0 controller can have up to 15 ports.
+
+USB controller ids start from 0. In line with the USB specification, however,
+ports on a controller start from 1.
+
+B<EXAMPLE>
+
+=over 2
+
+usbctrl=["version=1,ports=4", "version=2,ports=8"]
+
+The first controller is USB1.1 and has:
+
+controller id = 0, and ports 1,2,3,4.
+
+The second controller is USB2.0 and has:
+
+controller id = 1, and ports 1,2,3,4,5,6,7,8.
+
+=back
+
+=back
+
+=item B<usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]>
+
+Specifies the USB devices to be attached to the guest at boot.
+
+Each B<USBDEV_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings, from the following list:
+
+=over 4
+
+=item B<type=hostdev>
+
+Specifies USB device type. Currently only "hostdev" is supported.
+
+=item B<hostbus=busnum>
+
+Specifies busnum of the USB device from the host perspective.
+
+=item B<hostaddr=devnum>
+
+Specifies devnum of the USB device from the host perspective.
+
+=item B<controller=CONTROLLER>
+
+Specifies the USB controller id, to which controller the USB device is
+attached.
+
+If no controller is specified, an available controller:port combination
+will be used. If there are no available controller:port combinations,
+a new controller will be created.
+
+=item B<port=PORT>
+
+Specifies the USB port to which the USB device is attached. The B<port>
+option is valid only when the B<controller> option is specified.
+
+=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 of
+B<[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 the 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 B<lspci(1)> for the device in
+question.
+
+Note: by default B<lspci(1)> 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 slot 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>.
+
+=item B<permissive=BOOLEAN>
+
+By default pciback only allows PV guests to write "known safe" values
+into PCI configuration space, likewise QEMU (both qemu-xen and
+qemu-xen-traditional) imposes the same constraint on HVM guests.
+However, many devices require writes to other areas of the configuration space
+in order to operate properly. This option tells the backend (pciback or QEMU)
+to allow all writes to the PCI configuration space of this device by this
+domain.
+
+B<This option should be enabled with caution:> it gives the guest much
+more control over the device, which may have security or stability
+implications. It is recommended to only enable this option for
+trusted VMs under administrator's control.
+
+=item B<msitranslate=BOOLEAN>
+
+Specifies that MSI-INTx translation should be turned on for the PCI
+device. When enabled, MSI-INTx translation will always enable MSI on
+the PCI device regardless of whether the guest uses INTx or MSI. Some
+device drivers, such as NVIDIA's, detect an inconsistency and do not
+function when this option is enabled. Therefore the default is false (0).
+
+=item B<seize=BOOLEAN>
+
+Tells B<xl> to automatically attempt to re-assign a device to
+pciback if it is not already assigned.
+
+B<WARNING:> If you set this option, B<xl> will gladly re-assign a critical
+system device, such as a network or a disk controller being used by
+dom0 without confirmation. Please use with care.
+
+=item B<power_mgmt=BOOLEAN>
+
+B<(HVM only)> Specifies that the VM should be able to program the
+D0-D3hot power management states for the PCI device. The default is false (0).
+
+=item B<rdm_policy=STRING>
+
+B<(HVM/x86 only)> This is the same as the policy setting inside the B<rdm>
+option but just specific to a given device. The default is "relaxed".
+
+Note: this would override global B<rdm> option.
+
+=back
+
+=item B<pci_permissive=BOOLEAN>
+
+Changes the default value of B<permissive> for all PCI devices passed
+through to this VM. See B<permissive> above.
+
+=item B<pci_msitranslate=BOOLEAN>
+
+Changes the default value of B<msitranslate> for all PCI devices passed
+through to this VM. See B<msitranslate> above.
+
+=item B<pci_seize=BOOLEAN>
+
+Changes the default value of B<seize> for all PCI devices passed
+through to this VM. See B<seize> above.
+
+=item B<pci_power_mgmt=BOOLEAN>
+
+B<(HVM only)> Changes the default value of B<power_mgmt> for all PCI
+devices passed through to this VM. See B<power_mgmt>
+above.
+
+=item B<gfx_passthru=BOOLEAN|"STRING">
+
+Enable graphics device PCI passthrough. This option makes an assigned
+PCI graphics card become the primary graphics card in the VM. The QEMU
+emulated graphics adapter is disabled and the VNC console for the VM
+will not have any graphics output. All graphics output, including boot
+time QEMU BIOS messages from the VM, will go to the physical outputs
+of the passed through physical graphics card.
+
+The graphics card PCI device to pass through is chosen with the B<pci>
+option, in exactly the same way a normal Xen PCI device
+passthrough/assignment is done. Note that B<gfx_passthru> does not do
+any kind of sharing of the GPU, so you can assign the GPU to only one
+single VM at a time.
+
+B<gfx_passthru> also enables various legacy VGA memory ranges, BARs, MMIOs,
+and ioports to be passed through to the VM, since those are required
+for correct operation of things like VGA BIOS, text mode, VBE, etc.
+
+Enabling the B<gfx_passthru> option also copies the physical graphics card
+video BIOS to the guest memory, and executes the VBIOS in the guest
+to initialize the graphics card.
+
+Most graphics adapters require vendor specific tweaks for properly
+working graphics passthrough. See the XenVGAPassthroughTestedAdapters
+L<http://wiki.xen.org/wiki/XenVGAPassthroughTestedAdapters> wiki page
+for graphics cards currently supported by B<gfx_passthru>.
+
+B<gfx_passthru> is currently supported both with the qemu-xen-traditional
+device-model and upstream qemu-xen device-model.
+
+When given as a boolean the B<gfx_passthru> option either disables graphics
+card passthrough or enables autodetection.
+
+When given as a string the B<gfx_passthru> option describes the type
+of device to enable. Note that this behavior is only supported with the
+upstream qemu-xen device-model. With qemu-xen-traditional IGD (Intel Graphics
+Device) is always assumed and options other than autodetect or explicit IGD
+will result in an error.
+
+Currently, valid values for the option are:
+
+=over 4
+
+=item B<0>
+
+Disables graphics device PCI passthrough.
+
+=item B<1>, B<"default">
+
+Enables graphics device PCI passthrough and autodetects the type of device
+which is being used.
+
+=item B<"igd">
+
+Enables graphics device PCI passthrough but forcing the type of device to
+Intel Graphics Device.
+
+=back
+
+Note that some graphics cards (AMD/ATI cards, for example) do not
+necessarily require the B<gfx_passthru> option, so you can use the normal Xen
+PCI passthrough to assign the graphics card as a secondary graphics
+card to the VM. The QEMU-emulated graphics card remains the primary
+graphics card, and VNC output is available from the QEMU-emulated
+primary adapter.
+
+More information about the Xen B<gfx_passthru> feature is available
+on the XenVGAPassthrough L<http://wiki.xen.org/wiki/XenVGAPassthrough>
+wiki page.
+
+=item B<rdm_mem_boundary=MBYTES>
+
+Number of megabytes to set for a boundary when checking for RDM conflicts.
+
+When RDM conflicts with RAM, RDM is probably scattered over the whole RAM
+space. Having multiple RDM entries would worsen this and lead to a complicated
+memory layout. Here we're trying to figure out a simple solution to
+avoid breaking the existing layout. When a conflict occurs,
+
+ #1. Above a predefined boundary
+ - move lowmem_end below the reserved region to solve the conflict;
+
+ #2. Below a predefined boundary
+ - Check if the policy is strict or relaxed.
+ A "strict" policy leads to a fail in libxl.
+ Note that when both policies are specified on a given region,
+ "strict" is always preferred.
+ The "relaxed" policy issues a warning message and also masks this
+ entry INVALID to indicate we shouldn't expose this entry to
+ hvmloader.
+
+The default value is 2048.
+
+=item B<dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]>
+
+Specifies the host device tree nodes to passt hrough to this guest. Each
+DTDEV_PATH is an absolute path in the device tree.
+
+=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]>
+
+Allow the guest to access specific legacy I/O ports. Each B<IOPORT_RANGE>
+is given in hexadecimal format and may either be a range, e.g. C<2f8-2ff>
+(inclusive), or a single I/O port, e.g. C<2f8>.
+
+It is recommended to only use this option for trusted VMs under
+administrator's control.
+
+=item B<iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]", ...]>
+
+Allow auto-translated domains to access specific hardware I/O memory pages.
+
+B<IOMEM_START> is a physical page number. B<NUM_PAGES> is the number of pages,
+beginning with B<START_PAGE>, to allow access to. B<GFN> specifies the guest
+frame number where the mapping will start in the guest's address space. If
+B<GFN> is not specified, the mapping will be performed using B<IOMEM_START>
+as a start in the guest's address space, therefore performing a 1:1 mapping
+by default.
+All of these values must be given in hexadecimal format.
+
+Note that the IOMMU won't be updated with the mappings specified with this
+option. This option therefore should not be used to pass through any
+IOMMU-protected devices.
+
+It is recommended to only use this option for trusted VMs under
+administrator's control.
+
+=item B<irqs=[ NUMBER, NUMBER, ...]>
+
+Allow a guest to access specific physical IRQs.
+
+It is recommended to only use this option for trusted VMs under
+administrator's control.
+
+If vuart console is enabled then irq 32 is reserved for it. See
+L</vuart="uart"> to know how to enable vuart console.
+
+=item B<max_event_channels=N>
+
+Limit the guest to using at most N event channels (PV interrupts).
+Guests use hypervisor resources for each event channel they use.
+
+The default of 1023 should be sufficient for typical guests. The
+maximum value depends on what the guest supports. Guests supporting the
+FIFO-based event channel ABI support up to 131,071 event channels.
+Other guests are limited to 4095 (64-bit x86 and ARM) or 1023 (32-bit
+x86).
+
+=item B<vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]>
+
+Specifies the virtual display devices to be provided to the guest.
+
+Each B<VDISPL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings, from the following list:
+
+=over 4
+
+=item C<backend=DOMAIN>
+
+Specifies the backend domain name or id. If not specified Domain-0 is used.
+
+=item C<be-alloc=BOOLEAN>
+
+Indicates if backend can be a buffer provider/allocator for this domain. See
+display protocol for details.
+
+=item C<connectors=CONNECTORS>
+
+Specifies virtual connectors for the device in following format
+<id>:<W>x<H>;<id>:<W>x<H>... where:
+
+=over 4
+
+=item C<id>
+
+String connector unique id. Space, comma symbols are not allowed.
+
+=item C<W>
+
+Connector width in pixels.
+
+=item C<H>
+
+Connector height in pixels.
+
+=back
+
+B<EXAMPLE>
+
+=over 4
+
+connectors=id0:1920x1080;id1:800x600;id2:640x480
+
+=back
+
+=back
+
+=item B<dm_restrict=BOOLEAN>
+
+Restrict the device model after startup,
+to limit the consequencese of security vulnerabilities in qemu.
+
+With this feature enabled,
+a compromise of the device model,
+via such a vulnerability,
+will not provide a privilege escalation attack on the whole system.
+
+This feature is a B<technology preview>.
+There are some significant limitations:
+
+=over 4
+
+=item
+
+This is not likely to work at all for PV guests
+nor guests using qdisk backends for their block devices.
+
+=item
+
+You must have a new enough qemu.
+In particular,
+if your qemu does not have the commit
+B<xen: restrict: use xentoolcore_restrict_all>
+the restriction request will be silently ineffective!
+
+=item
+
+The mechanisms used are not effective against
+denial of service problems.
+A compromised qemu can probably still impair
+or perhaps even prevent
+the proper functioning of the whole system,
+(at the very least, but not limited to,
+through resource exhaustion).
+
+=item
+
+It is not known whether the protection is
+effective when a domain is migrated.
+
+=item
+
+Some domain management functions do not work.
+For example, cdrom insert will fail.
+
+=item
+
+You should say C<vga="none">.
+Domains with stdvga graphics cards to not work.
+Domains with cirrus vga may seem to work.
+
+=item
+
+You must create user(s) for qemu to run as.
+
+Ideally, set aside a range of 32752 uids
+(from N to N+32751)
+and create a user
+whose name is B<xen-qemuuser-range-base>
+and whose uid is N
+and whose gid is a plain unprivileged gid.
+libxl will use one such user for each domid.
+
+Alternatively, either create
+B<xen-qemuuser-domid$domid>
+for every $domid from 1 to 32751 inclusive,
+or
+B<xen-qemuuser-shared>
+(in which case different guests will not
+be protected against each other).
+
+=item
+
+There are no countermeasures taken against reuse
+of the same unix user (uid)
+for subsequent domains,
+even if the B<xen-qemuuser-domid$domid> users are created.
+So a past domain with the same domid may be able to
+interferer with future domains.
+Possibly, even after a reboot.
+
+=item
+
+A compromised qemu will be able to read world-readable
+files in the dom0 operating system.
+
+=item
+
+Because of these limitations, this functionality,
+while it may enhance your security,
+should not be relied on.
+Any further limitations discovered in the current version
+will B<not> be handled via the Xen Project Security Process.
+
+=item
+
+In the future as we enhance this feature to improve the security,
+we may break backward compatibility.
+
+=back
+
+=item B<vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]>
+
+Specifies the virtual sound cards to be provided to the guest.
+Each B<VCARD_SPEC> is a list, which has a form of
+"[VSND_ITEM_SPEC, VSND_ITEM_SPEC, ... ]" (without the quotes).
+The virtual sound card has hierarchical structure.
+Every card has a set of PCM devices and streams, each could be individually
+configured.
+
+B<VSND_ITEM_SPEC> describes individual item parameters.
+B<VSND_ITEM_SPEC> is a string of comma separated item parameters
+headed by item identifier. Each item parameter is C<KEY=VALUE> pair:
+
+=over 4
+
+"identifier, param = value, ...".
+
+=back
+
+Identifier shall be one of following values: "CARD", "PCM", "STREAM".
+The child item treated as belonging to the previously defined parent item.
+
+All parameters are optional.
+
+There are group of parameters which are common for all items.
+This group can be defined at higher level of the hierarchy and be fully or
+partially re-used by the underlying layers. These parameters are:
+
+=over 4
+
+* number of channels (min/max)
+
+* supported sample rates
+
+* supported sample formats
+
+=back
+
+E.g. one can define these values for the whole card, device or stream.
+Every underlying layer in turn can re-define some or all of them to better
+fit its needs. For example, card may define number of channels to be
+in [1; 8] range, and some particular stream may be limited to [1; 2] only.
+The rule is that the underlying layer must be a subset of the upper layer
+range.
+
+I<COMMON parameters:>
+
+=over 4
+
+=over 4
+
+=item B<sample-rates=RATES>
+
+List of integer values separated by semicolon: sample-rates=8000;22050;44100
+
+=item B<sample-formats=FORMATS>
+
+List of string values separated by semicolon: sample-formats=s16_le;s8;u32_be
+
+Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be, s24_le, s24_be,
+u24_le, u24_be, s32_le, s32_be, u32_le, u32_be, float_le, float_be,
+float64_le, float64_be, iec958_subframe_le, iec958_subframe_be,
+mu_law, a_law, ima_adpcm, mpeg, gsm
+
+=item B<channels-min=NUMBER>
+
+The minimum amount of channels.
+
+=item B<channels-max=NUMBER>
+
+The maximum amount of channels.
+
+=item B<buffer-size=NUMBER>
+
+The maximum size in octets of the buffer to allocate per stream.
+
+=back
+
+=back
+
+I<CARD specification:>
+
+=over 4
+
+=over 4
+
+=item B<backend=domain-id>
+
+Specify the backend domain name or id, defaults to dom0.
+
+=item B<short-name=STRING>
+
+Short name of the virtual sound card.
+
+=item B<long-name=STRING>
+
+Long name of the virtual sound card.
+
+=back
+
+=back
+
+I<PCM specification:>
+
+=over 4
+
+=over 4
+
+=item B<name=STRING>
+
+Name of the PCM sound device within the virtual sound card.
+
+=back
+
+=back
+
+I<STREAM specification:>
+
+=over 4
+
+=over 4
+
+=item B<unique-id=STRING>
+
+Unique stream identifier.
+
+=item B<type=TYPE>
+
+Stream type: "p" - playback stream, "c" - capture stream.
+
+=back
+
+=back
+
+I<EXAMPLE:>
+
+ vsnd = [
+ ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
+ 'PCM, name=Main',
+ 'STREAM, id=0, type=p',
+ 'STREAM, id=1, type=c, channels-max=2'
+ ],
+ ['CARD, short-name=Second',
+ 'PCM, name=Second, buffer-size=1024',
+ 'STREAM, id=2, type=p',
+ 'STREAM, id=3, type=c'
+ ]
+ ]
+
+=item B<vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]>
+
+Specifies the virtual keyboard device to be provided to the guest.
+
+Each B<VKB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
+settings from the following list:
+
+=over 4
+
+=item B<unique-id=STRING>
+
+Specifies the unique input device id.
+
+=item B<backend=domain-id>
+
+Specifies the backend domain name or id.
+
+=item B<backend-type=type>
+
+Specifies the backend type: qemu - for QEMU backend or linux - for Linux PV
+domain.
+
+=item B<feature-disable-keyboard=BOOLEAN>
+
+Indicates if keyboard device is disabled.
+
+=item B<feature-disable-pointer=BOOLEAN>
+
+Indicates if pointer device is disabled.
+
+=item B<feature-abs-pointer=BOOLEAN>
+
+Indicates if pointer device can return absolute coordinates.
+
+=item B<feature-raw-pointer=BOOLEAN>
+
+Indicates if pointer device can return raw (unscaled) absolute coordinates.
+
+=item B<feature-multi-touch=BOOLEAN>
+
+Indicates if input device supports multi touch.
+
+=item B<multi-touch-width=MULTI_TOUCH_WIDTH>
+
+Set maximum width for multi touch device.
+
+=item B<multi-touch-height=MULTI_TOUCH_HEIGHT>
+
+Set maximum height for multi touch device.
+
+=item B<multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS>
+
+Set maximum contacts number for multi touch device.
+
+=item B<width=WIDTH>
+
+Set maximum width for pointer device.
+
+=item B<height=HEIGHT>
+
+Set maximum height for pointer device.
+
+=back
+
+=back
+
+=head2 Paravirtualised (PV) Guest Specific Options
+
+The following options apply only to Paravirtual (PV) guests.
+
+=over 4
+
+=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. Either B<kernel> or B<bootloader> must be specified
+for PV guests.
+
+=item B<bootloader_args=[ "ARG", "ARG", ...]>
+
+Append B<ARG>s 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 B<(this second option is deprecated)>.
+
+=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 (0) the guest pseudo-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 laid out.
+
+Exposing the host e820 to the guest gives the guest kernel the
+opportunity to set aside the required part of its pseudo-physical
+address space in order to provide address space to map passedthrough
+PCI devices. It is guest Operating System dependent whether this
+option is required, specifically it is required when using a mainline
+Linux ("pvops") kernel. This option defaults to true (1) if any PCI
+passthrough devices are configured and false (0) 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 Fully-virtualised (HVM) guests.
+
+=head3 Boot Device
+
+=over 4
+
+=item B<boot="STRING">
+
+Specifies the emulated virtual device to boot from.
+
+Possible values are:
+
+=over 4
+
+=item B<c>
+
+Hard disk.
+
+=item B<d>
+
+CD-ROM.
+
+=item B<n>
+
+Network / PXE.
+
+=back
+
+B<Note:> multiple options can be given and will be attempted in the order they
+are given, e.g. to boot from CD-ROM but fall back to the hard disk you can
+specify it as B<dc>.
+
+The default is B<cd>, meaning try booting from the hard disk first, but fall
+back to the CD-ROM.
+
+
+=back
+
+=head3 Emulated disk controller type
+
+=over 4
+
+=item B<hdtype=STRING>
+
+Specifies the hard disk type.
+
+Possible values are:
+
+=over 4
+
+=item B<ide>
+
+If thise mode is specified B<xl> adds an emulated IDE controller, which is
+suitable even for older operation systems.
+
+=item B<ahci>
+
+If this mode is specified, B<xl> adds an ich9 disk controller in AHCI mode and
+uses it with upstream QEMU to emulate disks instead of IDE. It decreases boot
+time but may not be supported by default in older operating systems, e.g.
+Windows XP.
+
+=back
+
+The default is B<ide>.
+
+=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 cases 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. 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 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<bios="STRING">
+
+Select the virtual firmware that is exposed to the guest.
+By default, a guess is made based on the device model, but sometimes
+it may be useful to request a different one, like UEFI.
+
+=over 4
+
+=item B<rombios>
+
+Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by default
+when B<device_model_version=qemu-xen-traditional>. This is the only BIOS
+option supported when B<device_model_version=qemu-xen-traditional>. This is
+the BIOS used by all previous Xen versions.
+
+=item B<seabios>
+
+Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by default
+with device_model_version=qemu-xen.
+
+=item B<ovmf>
+
+Loads OVMF, a standard UEFI firmware by Tianocore project.
+Requires device_model_version=qemu-xen.
+
+=back
+
+=item B<bios_path_override="PATH">
+
+Override the path to the blob to be used as BIOS. The blob provided here MUST
+be consistent with the B<bios=> which you have specified. You should not
+normally need to specify this option.
+
+This option does not have any effect if using B<bios="rombios"> or
+B<device_model_version="qemu-xen-traditional">.
+
+=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.
+This option is true for x86 while it's false for ARM by default.
+
+=item B<acpi_s3=BOOLEAN>
+
+Include the S3 (suspend-to-ram) power state in the virtual firmware
+ACPI table. True (1) by default.
+
+=item B<acpi_s4=BOOLEAN>
+
+Include S4 (suspend-to-disk) power state in the virtual firmware ACPI
+table. True (1) by default.
+
+=item B<acpi_laptop_slate=BOOLEAN>
+
+Include the Windows laptop/slate mode switch device in the virtual
+firmware ACPI table. False (0) by default.
+
+=item B<apic=BOOLEAN>
+
+B<(x86 only)> 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 superseded by newer constructs within
+the ACPI tables.
+
+=item B<nx=BOOLEAN>
+
+B<(x86 only)> Hides or exposes the No-eXecute capability. This allows a guest
+Operating System to map pages in such a way that they cannot be executed which
+can enhance security. This options requires that PAE also be
+enabled.
+
+=item B<hpet=BOOLEAN>
+
+B<(x86 only)> 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.
+
+=item B<altp2m="MODE">
+
+B<(x86 only)> Specifies the access mode to the alternate-p2m capability.
+Alternate-p2m allows a guest to manage multiple p2m guest physical "memory
+views" (as opposed to a single p2m).
+You may want this option if you want to access-control/isolate
+access to specific guest physical memory pages accessed by the guest, e.g. for
+domain memory introspection or for isolation/access-control of memory between
+components within a single guest domain. This option is disabled by default.
+
+The valid values are as follows:
+
+=over 4
+
+=item B<disabled>
+
+Altp2m is disabled for the domain (default).
+
+=item B<mixed>
+
+The mixed mode allows access to the altp2m interface for both in-guest
+and external tools as well.
+
+=item B<external>
+
+Enables access to the alternate-p2m capability by external privileged tools.
+
+=item B<limited>
+
+Enables limited access to the alternate-p2m capability,
+ie. giving the guest access only to enable/disable the VMFUNC and #VE features.
+
+=back
+
+=item B<altp2mhvm=BOOLEAN>
+
+Enables or disables HVM guest access to alternate-p2m capability.
+Alternate-p2m allows a guest to manage multiple p2m guest physical
+"memory views" (as opposed to a single p2m). This option is
+disabled by default and is available only to HVM domains.
+You may want this option if you want to access-control/isolate
+access to specific guest physical memory pages accessed by
+the guest, e.g. for HVM domain memory introspection or
+for isolation/access-control of memory between components within
+a single guest HVM domain. B<This option is deprecated, use the option
+"altp2m" instead.>
+
+B<Note>: While the option "altp2mhvm" is deprecated, legacy applications for
+x86 systems will continue to work using it.
+
+=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. 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).
+This option is disabled by default.
+
+=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
+
+Configure the value returned when a guest executes the CPUID instruction.
+Two versions of config syntax are recognized: libxl and xend.
+
+The libxl syntax is a comma separated list of key=value pairs, preceded by the
+word "host". A few keys take a numerical value, all others take a single
+character which describes what to do with the feature bit.
+
+Possible values for a single feature bit:
+ '1' -> force the corresponding bit to 1
+ '0' -> force to 0
+ 'x' -> Get a safe value (pass through and mask with the default policy)
+ 'k' -> pass through the host bit value
+ 's' -> as 'k' but preserve across save/restore and migration (not implemented)
+
+Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group)
+only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the
+rest are ignored (these 8 bits signify maximum number of hypervisor leaves).
+
+List of keys taking a value:
+apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc
+proccount procpkg stepping
+
+List of keys taking a character:
+3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8 apic arat avx avx2
+avx512-4fmaps avx512-4vnniw avx512bw avx512cd avx512dq avx512er avx512f
+avx512ifma avx512pf avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
+cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl dtes64 erms est extapic
+f16c ffxsr fma fma4 fpu fsgsbase fxsr hle htt hypervisor ia64 ibs invpcid
+invtsc lahfsahf lm lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr
+mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid pclmulqdq pdcm
+perfctr_core perfctr_nb pge pku popcnt pse pse36 psn rdrand rdseed rdtscp rtm
+sha skinit smap smep smx ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a
+ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt svm_tscrate
+svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc tsc-deadline tsc_adjust
+umip vme vmx wdt x2apic xop xsave xtpr
+
+
+The xend syntax is a list of values in the form of
+'leafnum:register=bitstring,register=bitstring'
+ "leafnum" is the requested function,
+ "register" is the response register to modify
+ "bitstring" represents all bits in the register, its length must be 32 chars.
+ Each successive character represent a lesser-significant bit, possible values
+ are listed above in the libxl section.
+
+Example to hide two features from the guest: 'tm', which is bit #29 in EDX, and
+'pni' (SSE3), which is bit #0 in ECX:
+
+xend: [ "1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ]
+
+libxl: "host,tm=0,sse3=0"
+
+More info about the CPUID instruction can be found in the processor manuals,
+and on Wikipedia: L<http://en.wikipedia.org/wiki/CPUID>
+
+=item B<acpi_firmware="STRING">
+
+Specifies a path to a file that contains extra ACPI firmware tables to pass into
+a guest. The file can contain several tables in their binary AML form
+concatenated together. Each table self describes its length so no additional
+information is needed. These tables will be added to the ACPI table set in the
+guest. Note that existing tables cannot be overridden by this feature. For
+example, this cannot be used to override tables like DSDT, FADT, etc.
+
+=item B<smbios_firmware="STRING">
+
+Specifies a path to a file that contains extra SMBIOS firmware structures to
+pass into a guest. The file can contain a set of DMTF predefined structures
+which will override the internal defaults. Not all predefined structures can be
+overridden,
+only the following types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any
+number of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
+structures do not present their overall size, each entry in the file must be
+preceded by a 32b integer indicating the size of the following structure.
+
+=item B<ms_vm_genid="OPTION">
+
+Provide a VM generation ID to the guest.
+
+The VM generation ID is a 128-bit random number that a guest may use
+to determine if the guest has been restored from an earlier snapshot
+or cloned.
+
+This is required for Microsoft Windows Server 2012 (and later) domain
+controllers.
+
+Valid options are:
+
+=over 4
+
+=item B<generate>
+
+Generate a random VM generation ID every time the domain is created or
+restored.
+
+=item B<none>
+
+Do not provide a VM generation ID.
+
+=back
+
+See also "Virtual Machine Generation ID" by Microsoft:
+L<http://www.microsoft.com/en-us/download/details.aspx?id=30707>
+
+=back
+
+=head3 Guest Virtual Time Controls
+
+=over 4
+
+=item B<tsc_mode="MODE">
+
+B<(x86 only)> Specifies how the TSC (Time Stamp Counter) should be provided to
+the guest. B<Specifying this option as a number is deprecated.>
+
+Options are:
+
+=over 4
+
+=item B<default>
+
+Guest rdtsc/p is executed natively when monotonicity can be guaranteed
+and emulated otherwise (with frequency scaled if necessary).
+
+If a HVM container in B<default> TSC mode is created on a host that
+provides constant host TSC, its guest TSC frequency will be the same
+as the host. If it is later migrated to another host that provide
+constant host TSC and supports Intel VMX TSC scaling/AMD SVM TSC
+ratio, its guest TSC frequency will be the same before and after
+migration, and guest rdtsc/p will be executed natively after migration as well
+
+=item B<always_emulate>
+
+Guest rdtsc/p is 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/p is always executed natively (no monotonicity/frequency
+guarantees). Guest rdtsc/p is emulated at native frequency if unsupported
+by h/w, else executed natively.
+
+=item B<native_paravirt>
+
+This mode has been removed.
+
+=back
+
+Please see B<xen-tscmode(7)> for more information on this option.
+
+=item B<localtime=BOOLEAN>
+
+Set the real time clock to local time or to UTC. False (0) by default,
+i.e. set to UTC.
+
+=item B<rtc_timeoffset=SECONDS>
+
+Set the real time clock offset in seconds. No offset (0) by default.
+
+=item B<vpt_align=BOOLEAN>
+
+Specifies that periodic Virtual Platform Timers should be aligned to
+reduce guest interrupts. Enabling this option can reduce power
+consumption, especially when a guest uses a high timer interrupt
+frequency (HZ) values. The default is true (1).
+
+=item B<timer_mode="MODE">
+
+Specifies the mode for Virtual Timers. The valid values are as follows:
+
+=over 4
+
+=item B<delay_for_missed_ticks>
+
+Delay for missed ticks. Do not advance a vCPU's time beyond the
+correct delivery time for interrupts that have been missed due to
+preemption. Deliver missed interrupts when the vCPU is rescheduled and
+advance the vCPU's virtual time stepwise for each one.
+
+=item B<no_delay_for_missed_ticks>
+
+No delay for missed ticks. As above, missed interrupts are delivered,
+but guest time always tracks wallclock (i.e., real) time while doing
+so. This is the default.
+
+=item B<no_missed_ticks_pending>
+
+No missed interrupts are held pending. Instead, to ensure ticks are
+delivered at some non-zero rate, if we detect missed ticks then the
+internal tick alarm is not disabled if the vCPU is preempted during
+the next tick period.
+
+=item B<one_missed_tick_pending>
+
+One missed tick pending. Missed interrupts are collapsed
+together and delivered as one 'late tick'. Guest time always tracks
+wallclock (i.e., real) time.
+
+=back
+
+=back
+
+=head3 Memory layout
+
+=over 4
+
+=item B<mmio_hole=MBYTES>
+
+Specifies the size the MMIO hole below 4GiB will be. Only valid for
+B<device_model_version="qemu-xen">.
+
+Cannot be smaller than 256. Cannot be larger than 3840.
+
+Known good large value is 3072.
+
+=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>.
+
+Setting B<xen_platform_pci=0> with the default device_model "qemu-xen"
+requires at least QEMU 1.6.
+
+=item B<viridian=[ "GROUP", "GROUP", ...]> or B<viridian=BOOLEAN>
+
+The groups of Microsoft Hyper-V (AKA viridian) compatible enlightenments
+exposed to the guest. The following groups of enlightenments may be
+specified:
+
+=over 4
+
+=item B<base>
+
+This group incorporates the Hypercall MSRs, Virtual processor index MSR,
+and APIC access MSRs. These enlightenments can improve performance of
+Windows Vista and Windows Server 2008 onwards and setting this option
+for such guests is strongly recommended.
+This group is also a pre-requisite for all others. If it is disabled
+then it is an error to attempt to enable any other group.
+
+=item B<freq>
+
+This group incorporates the TSC and APIC frequency MSRs. These
+enlightenments can improve performance of Windows 7 and Windows
+Server 2008 R2 onwards.
+
+=item B<time_ref_count>
+
+This group incorporates Partition Time Reference Counter MSR. This
+enlightenment can improve performance of Windows 8 and Windows
+Server 2012 onwards.
+
+=item B<reference_tsc>
+
+This set incorporates the Partition Reference TSC MSR. This
+enlightenment can improve performance of Windows 7 and Windows
+Server 2008 R2 onwards.
+
+=item B<hcall_remote_tlb_flush>
+
+This set incorporates use of hypercalls for remote TLB flushing.
+This enlightenment may improve performance of Windows guests running
+on hosts with higher levels of (physical) CPU contention.
+
+=item B<apic_assist>
+
+This set incorporates use of the APIC assist page to avoid EOI of
+the local APIC.
+This enlightenment may improve performance of guests that make use of
+per-vCPU event channel upcall vectors.
+Note that this enlightenment will have no effect if the guest is
+using APICv posted interrupts.
+
+=item B<crash_ctl>
+
+This group incorporates the crash control MSRs. These enlightenments
+allow Windows to write crash information such that it can be logged
+by Xen.
+
+=item B<defaults>
+
+This is a special value that enables the default set of groups, which
+is currently the B<base>, B<freq>, B<time_ref_count>, B<apic_assist>
+and B<crash_ctl> groups.
+
+=item B<all>
+
+This is a special value that enables all available groups.
+
+=back
+
+Groups can be disabled by prefixing the name with '!'. So, for example,
+to enable all groups except B<freq>, specify:
+
+=over 4
+
+B<viridian=[ "all", "!freq" ]>
+
+=back
+
+For details of the enlightenments see the latest version of Microsoft's
+Hypervisor Top-Level Functional Specification.
+
+The enlightenments should be harmless for other versions of Windows
+(although they will not give any benefit) and the majority of other
+non-Windows OSes.
+However it is known that they are incompatible with some other Operating
+Systems and in some circumstance can prevent Xen's own paravirtualisation
+interfaces for HVM guests from being used.
+
+The viridian option can be specified as a boolean. A value of true (1)
+is equivalent to the list [ "defaults" ], and a value of false (0) is
+equivalent to an empty list.
+
+=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.
+
+When using the qemu-xen-traditional device-model, the default as well as
+minimum amount of video RAM for stdvga is 8 MB, which is sufficient for e.g.
+1600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and
+minimum is 16 MB.
+
+When using the emulated Cirrus graphics card (B<vga="cirrus">) and the
+qemu-xen-traditional device-model, the amount of video RAM is fixed at 4 MB,
+which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen
+device-model, the default and minimum is 8 MB.
+
+For QXL vga, both the default and minimal are 128MB.
+If B<videoram> is set less than 128MB, an error will be triggered.
+
+=item B<stdvga=BOOLEAN>
+
+Speficies a standard VGA card with VBE (VESA BIOS Extensions) as the
+emulated graphics device. If your guest supports VBE 2.0 or
+later (e.g. Windows XP onwards) then you should enable this.
+stdvga supports more video ram and bigger resolutions than Cirrus.
+The default is false (0) which means to emulate
+a Cirrus Logic GD5446 VGA card.
+B<This option is deprecated, use vga="stdvga" instead>.
+
+=item B<vga="STRING">
+
+Selects the emulated video card.
+Options are: B<none>, B<stdvga>, B<cirrus> and B<qxl>.
+The default is B<cirrus>.
+
+In general, QXL should work with the Spice remote display protocol
+for acceleration, and a QXL driver is necessary in the guest in that case.
+QXL can also work with the VNC protocol, but it will be like a standard
+VGA card without acceleration.
+
+=item B<vnc=BOOLEAN>
+
+Allow access to the display via the VNC protocol. This enables the
+other VNC-related settings. The default is (1) enabled.
+
+=item B<vnclisten="ADDRESS[:DISPLAYNUM]">
+
+Specifies the IP address and, optionally, the 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 searches for a free TCP port to use.
+The actual display used can be accessed with B<xl vncviewer>.
+
+=item B<vncpasswd="PASSWORD">
+
+Specifies the password for the VNC server. If the password is set to an
+empty string, authentication on the VNC server will be disabled
+allowing any user to connect.
+
+=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 B<Keymaps> below or consult the
+B<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 (0) not enabled.
+
+=item B<opengl=BOOLEAN>
+
+Enable OpenGL acceleration of the SDL display. Only effects machines
+using B<device_model_version="qemu-xen-traditional"> and only if the
+device-model was compiled with OpenGL support. Default is (0) false.
+
+=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">
+
+Specifies the interface address to listen on if given, otherwise any
+interface.
+
+=item B<spiceport=NUMBER>
+
+Specifies the port to listen on by the SPICE server if SPICE is
+enabled.
+
+=item B<spicetls_port=NUMBER>
+
+Specifies the secure port to listen on by the SPICE server if SPICE
+is enabled. At least one of B<spiceport> or B<spicetls_port> must be
+given if SPICE is enabled.
+
+B<Note:> the options depending on B<spicetls_port>
+have not been supported.
+
+=item B<spicedisable_ticketing=BOOLEAN>
+
+Enable clients to connect without specifying a password. When disabled,
+B<spicepasswd> must be set. The default is (0) false.
+
+=item B<spicepasswd="PASSWORD">
+
+Specify the password which is used by clients for establishing a connection.
+
+=item B<spiceagent_mouse=BOOLEAN>
+
+Whether SPICE agent is used for client mouse mode. The default is (1) true.
+
+=item B<spicevdagent=BOOLEAN>
+
+Enables the SPICE vdagent. The SPICE vdagent is an optional component for
+enhancing user experience and performing guest-oriented management
+tasks. Its features include: client mouse mode (no need to grab the mouse
+by the client, no mouse lag), automatic adjustment of screen resolution,
+copy and paste (text and image) between the client and the guest. It also
+requires the vdagent service installed on the guest OS to work.
+The default is (0) disabled.
+
+=item B<spice_clipboard_sharing=BOOLEAN>
+
+Enables SPICE clipboard sharing (copy/paste). It requires that
+B<spicevdagent> is enabled. The default is (0) false.
+
+=item B<spiceusbredirection=NUMBER>
+
+Enables SPICE USB redirection. Creates a NUMBER of USB redirection channels
+for redirecting up to 4 USB devices from the SPICE client to the guest's QEMU.
+It requires an USB controller and, if not defined, it will automatically add
+an USB2.0 controller. The default is (0) disabled.
+
+=item B<spice_image_compression="COMPRESSION">
+
+Specifies what image compression is to be used by SPICE (if given), otherwise
+the QEMU default will be used. Please see the documentation of your QEMU
+version for more details.
+
+Available options are: B<auto_glz, auto_lz, quic, glz, lz, off>.
+
+=item B<spice_streaming_video="VIDEO">
+
+Specifies what streaming video setting is to be used by SPICE (if given),
+otherwise the QEMU default will be used.
+
+Available options are: B<filter, all, off>.
+
+=back
+
+=head3 Miscellaneous Emulated Hardware
+
+=over 4
+
+=item B<serial=[ "DEVICE", "DEVICE", ...]>
+
+Redirect virtual serial ports to B<DEVICE>s. Please see the
+B<-serial> option in the B<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.
+
+The form serial=DEVICE is also accepted for backwards compatibility.
+
+=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
+B<qemu(1)> manpage for details. The default is not to export any sound
+device.
+
+=item B<usb=BOOLEAN>
+
+Enables or disables an emulated USB bus in the guest.
+
+=item B<usbversion=NUMBER>
+
+Specifies the type of an emulated USB bus in the guest, values 1 for USB1.1,
+2 for USB2.0 and 3 for USB3.0. It is available only with an upstream QEMU.
+Due to implementation limitations this is not compatible with the B<usb>
+and B<usbdevice> parameters.
+Default is (0) no USB controller defined.
+
+=item B<usbdevice=[ "DEVICE", "DEVICE", ...]>
+
+Adds B<DEVICE>s to the emulated 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 a 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.
+
+Host devices can also be passed through in this way, by specifying
+host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
+typically be found by using B<lsusb(1)> or B<usb-devices(1)>.
+
+If you wish to use the "host:bus.addr" format, remove any leading '0' from the
+bus and addr. For example, for the USB device on bus 008 dev 002, you should
+write "host:8.2".
+
+The form usbdevice=DEVICE is also accepted for backwards compatibility.
+
+More valid options can be found in the "usbdevice" section of the QEMU
+documentation.
+
+=item B<vendor_device="VENDOR_DEVICE">
+
+Selects which variant of the QEMU xen-pvdevice should be used for this
+guest. Valid values are:
+
+=over 4
+
+=item B<none>
+
+The xen-pvdevice should be omitted. This is the default.
+
+=item B<xenserver>
+
+The xenserver variant of the xen-pvdevice (device-id=C000) will be
+specified, enabling the use of XenServer PV drivers in the guest.
+
+=back
+
+This parameter only takes effect when device_model_version=qemu-xen.
+See B<xen-pci-device-reservations(7)> for more information.
+
+=back
+
+=head2 PVH Guest Specific Options
+
+=over 4
+
+=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.
+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).
+
+This option is disabled by default.
+
+=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. Either B<kernel> or B<bootloader> must be specified
+for PV guests.
+
+=item B<bootloader_args=[ "ARG", "ARG", ...]>
+
+Append B<ARG>s 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 B<(this second option is deprecated)>.
+
+=item B<timer_mode="MODE">
+
+Specifies the mode for Virtual Timers. The valid values are as follows:
+
+=over 4
+
+=item B<delay_for_missed_ticks>
+
+Delay for missed ticks. Do not advance a vCPU's time beyond the
+correct delivery time for interrupts that have been missed due to
+preemption. Deliver missed interrupts when the vCPU is rescheduled and
+advance the vCPU's virtual time stepwise for each one.
+
+=item B<no_delay_for_missed_ticks>
+
+No delay for missed ticks. As above, missed interrupts are delivered,
+but guest time always tracks wallclock (i.e., real) time while doing
+so. This is the default.
+
+=item B<no_missed_ticks_pending>
+
+No missed interrupts are held pending. Instead, to ensure ticks are
+delivered at some non-zero rate, if we detect missed ticks then the
+internal tick alarm is not disabled if the vCPU is preempted during
+the next tick period.
+
+=item B<one_missed_tick_pending>
+
+One missed tick pending. Missed interrupts are collapsed
+together and delivered as one 'late tick'. Guest time always tracks
+wallclock (i.e., real) time.
+
+=back
+
+=back
+
+=head3 Paging
+
+The following options control the mechanisms used to virtualise guest
+memory. The defaults are selected to give the best results for the
+common cases 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. 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 very large number of
+similar processes then increasing this value may improve performance.
+
+=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>
+
+Use the device-model merged into the upstream QEMU project.
+This device-model is the default for Linux dom0.
+
+=item B<qemu-xen-traditional>
+
+Use the device-model based upon the historical Xen fork of QEMU.
+This device-model is still the default for NetBSD dom0.
+
+=back
+
+It is recommended to accept the default value for new guests. If
+you have existing guests then, depending 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
+B<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_stubdomain_seclabel="LABEL">
+
+Assign an XSM security label to the device-model stubdomain.
+
+=item B<device_model_args=[ "ARG", "ARG", ...]>
+
+Pass additional arbitrary options on the device-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 device-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 device-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 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 B<qemu(1)> for more information.
+
+=head2 Architecture Specific options
+
+=head3 ARM
+
+=over 4
+
+=item B<gic_version="vN">
+
+Version of the GIC emulated for the guest.
+
+Currently, the following versions are supported:
+
+=over 4
+
+=item B<v2>
+
+Emulate a GICv2
+
+=item B<v3>
+
+Emulate a GICv3. Note that the emulated GIC does not support the
+GICv2 compatibility mode.
+
+=item B<default>
+
+Emulate the same version as the native GIC hardware used by the host where
+the domain was created.
+
+=back
+
+This requires hardware compatibility with the requested version, either
+natively or via hardware backwards compatibility support.
+
+=item B<vuart="uart">
+
+To enable vuart console, user must specify the following option in the
+VM config file:
+
+vuart = "sbsa_uart"
+
+Currently, only the "sbsa_uart" model is supported for ARM.
+
+=back
+
+=head3 x86
+
+=over 4
+
+=item B<mca_caps=[ "CAP", "CAP", ... ]>
+
+(HVM only) Enable MCA capabilities besides default ones enabled
+by Xen hypervisor for the HVM domain. "CAP" can be one in the
+following list:
+
+=over 4
+
+=item B<"lmce">
+
+Intel local MCE
+
+=item B<default>
+
+No MCA capabilities in above list are enabled.
+
+=back
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<xl(1)>
+
+=item L<xl.conf(5)>
+
+=item L<xlcpupool.cfg(5)>
+
+=item L<xl-disk-configuration(5)>
+
+=item L<xl-network-configuration(5)>
+
+=item L<xen-tscmode(7)>
+
+=back
+
+=head1 FILES
+
+F</etc/xen/NAME.cfg>
+F<@XEN_DUMP_DIR@/NAME>
+
+=head1 BUGS
+
+This document may contain items which require further
+documentation. Patches to improve incomplete items (or any other item)
+are gratefully received on the xen-devel@lists.xen.org mailing
+list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
+information on how to submit a patch to Xen.
+
+++ /dev/null
-=head1 NAME
-
-xl.cfg - xl domain configuration file syntax
-
-=head1 SYNOPSIS
-
- /etc/xen/xldomain
-
-=head1 DESCRIPTION
-
-Creating a VM (a domain in Xen terminology, sometimes called a guest)
-with xl requires the provision of a domain configuration file. Typically,
-these live in F</etc/xen/DOMAIN.cfg>, where DOMAIN is the name of the
-domain.
-
-=head1 SYNTAX
-
-A domain configuration file consists of a series of options, specified by
-using C<KEY=VALUE> pairs.
-
-Some C<KEY>s are mandatory, some are general options which apply to
-any guest type, while others relate only to specific guest types
-(e.g. PV or HVM guests).
-
-A C<VALUE> can be one of:
-
-=over 4
-
-=item B<"STRING">
-
-A string, surrounded by either single or double quotes. But if the
-STRING is part of a SPEC_STRING, the quotes should be omitted.
-
-=item B<NUMBER>
-
-A number, in either decimal, octal (using a C<0> prefix) or
-hexadecimal (using a C<0x> prefix) format.
-
-=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<VALUE>s of the above types. Lists can be heterogeneous and
-nested.
-
-=back
-
-The semantics of each C<KEY> defines which type of C<VALUE> is required.
-
-Pairs may be separated either by a newline or a semicolon. Both
-of the following are valid:
-
- name="h0"
- type="hvm"
-
- name="h0"; type="hvm"
-
-=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<type="pv">
-
-Specifies that this is to be a PV domain, suitable for hosting Xen-aware
-guest operating systems. This is the default on x86.
-
-=item B<type="pvh">
-
-Specifies that this is to be an PVH domain. That is a lightweight HVM-like
-guest without a device model and without many of the emulated devices
-available to HVM guests. Note that this mode requires a PVH aware kernel on
-x86. This is the default on Arm.
-
-=item B<type="hvm">
-
-Specifies that this is to be an HVM domain. That is, a fully virtualised
-computer with emulated BIOS, disk and network peripherals, etc.
-
-=back
-
-=head3 Deprecated guest type selection
-
-Note that the builder option is being deprecated in favor of the type
-option.
-
-=over 4
-
-=item B<builder="generic">
-
-Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest
-operating systems. 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.
-
-=back
-
-=head2 General Options
-
-The following options apply to guests of any type.
-
-=head3 CPU Allocation
-
-=over 4
-
-=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. When starting the guest, if
-B<vcpus=N> is less than B<maxvcpus=M> then the first B<N> vCPUs will be
-created online and the remainder will be created offline.
-
-=item B<cpus="CPULIST">
-
-List of host CPUs the guest is allowed to use. Default is no pinning at
-all (more on this below). A C<CPULIST> may be specified as follows:
-
-=over 4
-
-=item "all"
-
-To allow all the vCPUs of the guest to run on all the CPUs on the host.
-
-=item "0-3,5,^1"
-
-To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It is possible to
-combine this with "all", meaning "all,^7" results in all the vCPUs
-of the guest being allowed to run on all the CPUs of the host except CPU 7.
-
-=item "nodes:0-3,^node:2"
-
-To allow all the vCPUs of the guest to run on the CPUs from NUMA nodes
-0,1,3 of the host. So, if CPUs 0-3 belong to node 0, CPUs 4-7 belong
-to node 1, CPUs 8-11 to node 2 and CPUs 12-15 to node 3, the above would mean
-all the vCPUs of the guest would be allowed to run on CPUs 0-7,12-15.
-
-Combining this notation with the one above is possible. For instance,
-"1,node:1,^6", means all the vCPUs of the guest will run on CPU 1 and
-on all the CPUs of NUMA node 1, but not on CPU 6. Following the same
-example as above, that would be CPUs 1,4,5,7.
-
-Combining this with "all" is also possible, meaning "all,^node:1"
-results in all the vCPUs of the guest running on all the CPUs on the
-host, except for the CPUs belonging to the host NUMA node 1.
-
-=item ["2", "3-8,^5"]
-
-To ask for specific vCPU mapping. That means (in this example), vCPU 0
-of the guest will run on CPU 2 of the host and vCPU 1 of the guest will
-run on CPUs 3,4,6,7,8 of the host (excluding CPU 5).
-
-More complex notation can be also used, exactly as described above. So
-"all,^5-8", or just "all", or "node:0,node:2,^9-11,18-20" are all legal,
-for each element of the list.
-
-=back
-
-If this option is not specified, no vCPU to CPU pinning is established,
-and the vCPUs of the guest can run on all the CPUs of the host. If this
-option is specified, the intersection of the vCPU pinning mask, provided
-here, and the soft affinity mask, if provided via B<cpus_soft=>,
-is utilized to compute the domain node-affinity for driving memory
-allocations.
-
-=item B<cpus_soft="CPULIST">
-
-Exactly as B<cpus=>, but specifies soft affinity, rather than pinning
-(hard affinity). When using the credit scheduler, this means what CPUs
-the vCPUs of the domain prefer.
-
-A C<CPULIST> is specified exactly as for B<cpus=>, detailed earlier in the
-manual.
-
-If this option is not specified, the vCPUs of the guest will not have
-any preference regarding host CPUs. If this option is specified,
-the intersection of the soft affinity mask, provided here, and the vCPU
-pinning, if provided via B<cpus=>, is utilized to compute the
-domain node-affinity for driving memory allocations.
-
-If this option is not specified (and B<cpus=> is not specified either),
-libxl automatically tries to place the guest on the least possible
-number of nodes. A heuristic approach is used for choosing the best
-node (or set of nodes), with the goal of maximizing performance for
-the guest and, at the same time, achieving efficient utilization of
-host CPUs and memory. In that case, the soft affinity of all the vCPUs
-of the domain will be set to host CPUs belonging to NUMA nodes
-chosen during placement.
-
-For more details, see L<xl-numa-placement(7)>.
-
-=back
-
-=head3 CPU Scheduling
-
-=over 4
-
-=item B<cpu_weight=WEIGHT>
-
-A domain with a weight of 512 will get twice as much CPU as a domain
-with a weight of 256 on a contended host.
-Legal weights range from 1 to 65535 and the default is 256.
-Honoured by the credit and credit2 schedulers.
-
-=item B<cap=N>
-
-The cap optionally fixes the maximum amount of CPU a domain will be
-able to consume, even if the host system has idle CPU cycles.
-The cap is expressed as a percentage of one physical CPU:
-100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
-The default, 0, means there is no cap.
-Honoured by the credit and credit2 schedulers.
-
-B<NOTE>: Many systems have features that will scale down the computing
-power of a CPU that is not 100% utilized. This can be done in the
-operating system, but can also sometimes be done below the operating system,
-in the BIOS. If you set a cap such that individual cores are running
-at less than 100%, this may have an impact on the performance of your
-workload over and above the impact of the cap. For example, if your
-processor runs at 2GHz, and you cap a VM at 50%, the power management
-system may also reduce the clock speed to 1GHz; the effect will be
-that your VM gets 25% of the available power (50% of 1GHz) rather than
-50% (50% of 2GHz). If you are not getting the performance you expect,
-look at performance and CPU frequency options in your operating system and
-your BIOS.
-
-=back
-
-=head3 Memory Allocation
-
-=over 4
-
-=item B<memory=MBYTES>
-
-Start the guest with MBYTES megabytes of RAM.
-
-=item B<maxmem=MBYTES>
-
-Specifies the maximum amount of memory a guest can ever see.
-The value of B<maxmem=> must be equal to or greater than that of B<memory=>.
-
-In combination with B<memory=> it will start the guest "pre-ballooned",
-if the values of B<memory=> and B<maxmem=> differ.
-A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver
-it will crash.
-
-B<NOTE>: Because of the way ballooning works, the guest has to allocate
-memory to keep track of maxmem pages, regardless of how much memory it
-actually has available to it. A guest with maxmem=262144 and
-memory=8096 will report significantly less memory available for use
-than a system with maxmem=8096 memory=8096 due to the memory overhead
-of having to track the unused pages.
-
-=back
-
-=head3 Guest Virtual NUMA Configuration
-
-=over 4
-
-=item B<vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]>
-
-Specify virtual NUMA configuration with positional arguments. The
-nth B<VNODE_SPEC> in the list specifies the configuration of the nth
-virtual node.
-
-Note that virtual NUMA is not supported for PV guests yet, because
-there is an issue with the CPUID instruction handling that affects PV virtual
-NUMA. Furthermore, guests with virtual NUMA cannot be saved or migrated
-because the migration stream does not preserve node information.
-
-Each B<VNODE_SPEC> is a list, which has a form of
-"[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the quotes).
-
-For example, vnuma = [ ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ]
-means vnode 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the
-distance to itself is 10 and the distance to vnode 1 is 20.
-
-Each B<VNODE_CONFIG_OPTION> is a quoted C<KEY=VALUE> pair. Supported
-B<VNODE_CONFIG_OPTION>s are (they are all mandatory at the moment):
-
-=over 4
-
-=item B<pnode=NUMBER>
-
-Specifies which physical node this virtual node maps to.
-
-=item B<size=MBYTES>
-
-Specifies the size of this virtual node. The sum of memory sizes of all
-vnodes will become B<maxmem=>. If B<maxmem=> is specified separately,
-a check is performed to make sure the sum of all vnode memory matches
-B<maxmem=>.
-
-=item B<vcpus="CPUSTRING">
-
-Specifies which vCPUs belong to this node. B<"CPUSTRING"> is a string of numerical
-values separated by a comma. You can specify a range and/or a single CPU.
-An example would be "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5,
-and vCPU 8.
-
-=item B<vdistances=NUMBER, NUMBER, ... >
-
-Specifies the virtual distance from this node to all nodes (including
-itself) with positional arguments. For example, "vdistance=10,20"
-for vnode 0 means the distance from vnode 0 to vnode 0 is 10, from
-vnode 0 to vnode 1 is 20. The number of arguments supplied must match
-the total number of vnodes.
-
-Normally you can use the values from B<xl info -n> or B<numactl
---hardware> to fill the vdistances list.
-
-=back
-
-=back
-
-=head3 Event Actions
-
-=over 4
-
-=item B<on_poweroff="ACTION">
-
-Specifies what should be done with the domain if it shuts itself down.
-The B<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 then immediately 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 B<xl destroy>.
-
-=item B<coredump-destroy>
-
-write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then
-destroy the domain.
-
-=item B<coredump-restart>
-
-write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then
-restart the domain.
-
-=item B<soft-reset>
-
-Reset all Xen specific interfaces for the Xen-aware HVM domain allowing
-it to reestablish these interfaces and continue executing the domain. PV
-and non-Xen-aware HVM guests are not supported.
-
-=back
-
-The default for B<on_poweroff> is B<destroy>.
-
-=item B<on_reboot="ACTION">
-
-Action to take if the domain shuts down with a reason code requesting
-a reboot. Default is B<restart>.
-
-=item B<on_watchdog="ACTION">
-
-Action to take if the domain shuts down due to a Xen watchdog timeout.
-Default is B<destroy>.
-
-=item B<on_crash="ACTION">
-
-Action to take if the domain crashes. Default is B<destroy>.
-
-=item B<on_soft_reset="ACTION">
-
-Action to take if the domain performs a 'soft reset' (e.g. does B<kexec>).
-Default is B<soft-reset>.
-
-=back
-
-=head3 Direct Kernel Boot
-
-Direct kernel boot allows booting guests with a kernel and an initrd
-stored on a filesystem available to the host physical machine, allowing
-command line arguments to be passed directly. PV guest direct kernel boot is
-supported. HVM guest direct kernel boot is supported with some limitations
-(it's supported when using B<qemu-xen> and the default BIOS 'seabios',
-but not supported in case of using B<stubdom-dm> and the old 'rombios'.)
-
-=over 4
-
-=item B<kernel="PATHNAME">
-
-Load the specified file as the kernel image.
-
-=item B<ramdisk="PATHNAME">
-
-Load the specified file as the ramdisk.
-
-=item B<cmdline="STRING">
-
-Append B<STRING> to the kernel command line. (Note: the meaning of
-this is guest specific). It can replace B<root="STRING">
-along with B<extra="STRING"> and is preferred. When B<cmdline="STRING"> is set,
-B<root="STRING"> and B<extra="STRING"> will be ignored.
-
-=item B<root="STRING">
-
-Append B<root=STRING> to the kernel command line (Note: the meaning of this
-is guest specific).
-
-=item B<extra="STRING">
-
-Append B<STRING> to the kernel command line. (Note: the meaning of this
-is guest specific).
-
-=back
-
-=head3 Non direct Kernel Boot
-
-Non direct kernel boot allows booting guests with a firmware. This can be
-used by all types of guests, although the selection of options is different
-depending on the guest type.
-
-This option provides the flexibly of letting the guest decide which kernel
-they want to boot, while preventing having to poke at the guest file
-system form the toolstack domain.
-
-=head4 PV guest options
-
-=over 4
-
-=item B<firmware="pvgrub32|pvgrub64">
-
-Boots a guest using a para-virtualized version of grub that runs inside
-of the guest. The bitness of the guest needs to be know, so that the right
-version of pvgrub can be selected.
-
-Note that xl expects to find the pvgrub32.bin and pvgrub64.bin binaries in
-F<@XENFIRMWAREDIR@>.
-
-=back
-
-=head4 HVM guest options
-
-=over 4
-
-=item B<firmware="bios">
-
-Boot the guest using the default BIOS firmware, which depends on the
-chosen device model.
-
-=item B<firmware="uefi">
-
-Boot the guest using the default UEFI firmware, currently OVMF.
-
-=item B<firmware="seabios">
-
-Boot the guest using the SeaBIOS BIOS firmware.
-
-=item B<firmware="rombios">
-
-Boot the guest using the ROMBIOS BIOS firmware.
-
-=item B<firmware="ovmf">
-
-Boot the guest using the OVMF UEFI firmware.
-
-=item B<firmware="PATH">
-
-Load the specified file as firmware for the guest.
-
-=back
-
-=head4 PVH guest options
-
-Currently there's no firmware available for PVH guests, they should be
-booted using the B<Direct Kernel Boot> method or the B<bootloader> option.
-
-=over 4
-
-=item B<pvshim=BOOLEAN>
-
-Whether to boot this guest as a PV guest within a PVH container.
-Ie, the guest will experience a PV environment,
-but
-processor hardware extensions are used to
-separate its address space
-to mitigate the Meltdown attack (CVE-2017-5754).
-
-Default is false.
-
-=item B<pvshim_path="PATH">
-
-The PV shim is a specially-built firmware-like executable
-constructed from the hypervisor source tree.
-This option specifies to use a non-default shim.
-Ignored if pvhsim is false.
-
-=item B<pvshim_cmdline="STRING">
-
-Command line for the shim.
-Default is "pv-shim console=xen,pv".
-Ignored if pvhsim is false.
-
-=item B<pvshim_extra="STRING">
-
-Extra command line arguments for the shim.
-If supplied, appended to the value for pvshim_cmdline.
-Default is empty.
-Ignored if pvhsim is false.
-
-=back
-
-=head3 Other Options
-
-=over 4
-
-=item B<uuid="UUID">
-
-Specifies the UUID of the domain. If not specified, a fresh unique
-UUID will be generated.
-
-=item B<seclabel="LABEL">
-
-Assign an XSM security label to this domain.
-
-=item B<init_seclabel="LABEL">
-
-Specify an XSM security label used for this domain temporarily during
-its build. The domain's XSM label will be changed to the execution
-seclabel (specified by B<seclabel>) once the build is complete, prior to
-unpausing the domain. With a properly constructed security policy (such
-as nomigrate_t in the example policy), this can be used to build a
-domain whose memory is not accessible to the toolstack domain.
-
-=item B<max_grant_frames=NUMBER>
-
-Specify the maximum number of grant frames the domain is allowed to have.
-This value controls how many pages the domain is able to grant access to for
-other domains, needed e.g. for the operation of paravirtualized devices.
-The default is settable via L<xl.conf(5)>.
-
-=item B<max_maptrack_frames=NUMBER>
-
-Specify the maximum number of grant maptrack frames the domain is allowed
-to have. This value controls how many pages of foreign domains can be accessed
-via the grant mechanism by this domain. The default value is settable via
-L<xl.conf(5)>.
-
-=item B<nomigrate=BOOLEAN>
-
-Disable migration of this domain. This enables certain other features
-which are incompatible with migration. Currently this is limited to
-enabling the invariant TSC feature flag in CPUID results when TSC is
-not emulated.
-
-=item B<driver_domain=BOOLEAN>
-
-Specify that this domain is a driver domain. This enables certain
-features needed in order to run a driver domain.
-
-=item B<device_tree=PATH>
-
-Specify a partial device tree (compiled via the Device Tree Compiler).
-Everything under the node "/passthrough" will be copied into the guest
-device tree. For convenience, the node "/aliases" is also copied to allow
-the user to define aliases which can be used by the guest kernel.
-
-Given the complexity of verifying the validity of a device tree, this
-option should only be used with a trusted device tree.
-
-Note that the partial device tree should avoid using the phandle 65000
-which is reserved by the toolstack.
-
-=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 host they should map to. See L<xl-disk-configuration(5)> for more
-details.
-
-=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
-
-Specifies the network interfaces (both emulated network adapters,
-and Xen virtual interfaces) which are to be provided to the guest. See
-L<xl-network-configuration(5)> for more details.
-
-=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]>
-
-Specifies the Virtual Trusted Platform module to be
-provided to the guest. See L<xen-vtpm(7)> for more details.
-
-Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings from the following list:
-
-=over 4
-
-=item B<backend=domain-id>
-
-Specifies the backend domain name or id. B<This value is required!>
-If this domain is a guest, the backend should be set to the
-vTPM domain name. If this domain is a vTPM, the
-backend should be set to the vTPM manager domain name.
-
-=item B<uuid=UUID>
-
-Specifies the UUID of this vTPM device. The UUID is used to uniquely
-identify the vTPM device. You can create one using the B<uuidgen(1)>
-program on unix systems. If left unspecified, a new UUID
-will be randomly generated every time the domain boots.
-If this is a vTPM domain, you should specify a value. The
-value is optional if this is a guest domain.
-
-=back
-
-=item B<p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]>
-
-Creates a Xen 9pfs connection to share a filesystem from the backend to the
-frontend.
-
-Each B<9PFS_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings, from the following list:
-
-=over 4
-
-=item B<tag=STRING>
-
-9pfs tag to identify the filesystem share. The tag is needed on the
-guest side to mount it.
-
-=item B<security_model="none">
-
-Only "none" is supported today, which means that the files are stored using
-the same credentials as those they have in the guest (no user ownership
-squash or remap).
-
-=item B<path=STRING>
-
-Filesystem path on the backend to export.
-
-=item B<backend=domain-id>
-
-Specify the backend domain name or id, defaults to dom0.
-
-=back
-
-=item B<pvcalls=[ "backend=domain-id", ... ]>
-
-Creates a Xen pvcalls connection to handle pvcalls requests from
-frontend to backend. It can be used as an alternative networking model.
-For more information about the protocol, see
-https://xenbits.xen.org/docs/unstable/misc/pvcalls.html.
-
-=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]>
-
-Specifies the paravirtual framebuffer devices which should be supplied
-to the domain.
-
-This option does not control the emulated graphics card presented to
-an HVM guest. See B<Emulated VGA Graphics Device> below for how to
-configure the emulated device. If B<Emulated VGA Graphics Device> options
-are used in a PV guest configuration, B<xl> will pick up B<vnc>, B<vnclisten>,
-B<vncpasswd>, B<vncdisplay>, B<vncunused>, B<sdl>, B<opengl> and
-B<keymap> to construct the paravirtual framebuffer device for the guest.
-
-Each B<VFB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings, from the following list:
-
-=over 4
-
-=item B<vnc=BOOLEAN>
-
-Allow access to the display via the VNC protocol. This enables the
-other VNC-related settings. Default is 1 (enabled).
-
-=item B<vnclisten=ADDRESS[:DISPLAYNUM]>
-
-Specifies the IP address, and optionally the VNC display number, to use.
-
-Note: if you specify the display number here, you should not use
-the B<vncdisplay> option.
-
-=item B<vncdisplay=DISPLAYNUM>
-
-Specifies the VNC display number to use. The actual TCP port number
-will be DISPLAYNUM+5900.
-
-Note: you should not use this option if you set the DISPLAYNUM in the
-B<vnclisten> option.
-
-=item B<vncunused=BOOLEAN>
-
-Requests that the VNC display setup searches for a free TCP port to use.
-The actual display used can be accessed with B<xl vncviewer>.
-
-=item B<vncpasswd=PASSWORD>
-
-Specifies the password for the VNC server. If the password is set to an
-empty string, authentication on the VNC server will be disabled,
-allowing any user to connect.
-
-=item B<sdl=BOOLEAN>
-
-Specifies that the display should be presented via an X window (using
-Simple DirectMedia Layer). The default is 0 (not enabled).
-
-=item B<display=DISPLAY>
-
-Specifies the X Window display that should be used when the B<sdl> option
-is used.
-
-=item B<xauthority=XAUTHORITY>
-
-Specifies the path to the X authority file that should be used to
-connect to the X server when the B<sdl> option is used.
-
-=item B<opengl=BOOLEAN>
-
-Enable OpenGL acceleration of the SDL display. Only effects machines
-using B<device_model_version="qemu-xen-traditional"> and only if the
-device-model was compiled with OpenGL support. The default is 0 (disabled).
-
-=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 B<Keymaps> below or consult the
-B<qemu(1)> manpage. The default is B<en-us>.
-
-=back
-
-=item B<channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]>
-
-Specifies the virtual channels to be provided to the guest. A
-channel is a low-bandwidth, bidirectional byte stream, which resembles
-a serial link. Typical uses for channels include transmitting VM
-configuration after boot and signalling to in-guest agents. Please see
-L<xen-pv-channel(7)> for more details.
-
-Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings. Leading and trailing whitespace is ignored in both KEY and
-VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'. Defined values
-are:
-
-=over 4
-
-=item B<backend=domain-id>
-
-Specifies the backend domain name or id. This parameter is optional. If
-this parameter is omitted then the toolstack domain will be assumed.
-
-=item B<name=NAME>
-
-Specifies the name for this device. B<This parameter is mandatory!>
-This should be a well-known name for a specific application (e.g.
-guest agent) and should be used by the frontend to connect the
-application to the right channel device. There is no formal registry
-of channel names, so application authors are encouraged to make their
-names unique by including the domain name and a version number in the string
-(e.g. org.mydomain.guestagent.1).
-
-=item B<connection=CONNECTION>
-
-Specifies how the backend will be implemented. The following options are
-available:
-
-=over 4
-
-=item B<SOCKET>
-
-The backend will bind a Unix domain socket (at the path given by
-B<path=PATH>), listen for and accept connections. The backend will proxy
-data between the channel and the connected socket.
-
-=item B<PTY>
-
-The backend will create a pty and proxy data between the channel and the
-master device. The command B<xl channel-list> can be used to discover the
-assigned slave device.
-
-=back
-
-=back
-
-=item B<rdm="RDM_RESERVATION_STRING">
-
-B<HVM/x86 only!> Specifies information about Reserved Device Memory (RDM),
-which is necessary to enable robust device passthrough. One example of RDM
-is reporting through the ACPI Reserved Memory Region Reporting (RMRR) structure
-on the x86 platform.
-
-B<RDM_RESERVATION_STRING> is a comma separated list of C<KEY=VALUE> settings,
-from the following list:
-
-=over 4
-
-=item B<strategy=STRING>
-
-Currently there is only one valid type, and that is "host".
-
-=over 4
-
-=item B<host>
-
-If set to "host" it means all reserved device memory on this platform should
-be checked to reserve regions in this VM's address space. This global RDM
-parameter allows the user to specify reserved regions explicitly, and using
-"host" includes all reserved regions reported on this platform, which is
-useful when doing hotplug.
-
-By default this isn't set so we don't check all RDMs. Instead, we just check
-the RDM specific to a given device if we're assigning this kind of a device.
-
-Note: this option is not recommended unless you can make sure that no
-conflicts exist.
-
-For example, you're trying to set "memory = 2800" to allocate memory to one
-given VM but the platform owns two RDM regions like:
-
-Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000 end_address ac6e6fff
-
-Device B [sbdf_B]: RMRR region_B: base_addr ad800000 end_address afffffff
-
-In this conflict case,
-
-#1. If B<strategy> is set to "host", for example:
-
-rdm = "strategy=host,policy=strict" or rdm = "strategy=host,policy=relaxed"
-
-it means all conflicts will be handled according to the policy
-introduced by B<policy> as described below.
-
-#2. If B<strategy> is not set at all, but
-
-pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
-
-it means only one conflict of region_A will be handled according to the policy
-introduced by B<rdm_policy=STRING> as described inside B<pci> options.
-
-=back
-
-=item B<policy=STRING>
-
-Specifies how to deal with conflicts when reserving already reserved device
-memory in the guest address space.
-
-=over 4
-
-=item B<strict>
-
-Specifies that in case of an unresolved conflict the VM can't be created,
-or the associated device can't be attached in the case of hotplug.
-
-=item B<relaxed>
-
-Specifies that in case of an unresolved conflict the VM is allowed to be
-created but may cause the VM to crash if a pass-through device accesses RDM.
-For example, the Windows IGD GFX driver always accesses RDM regions so it
-leads to a VM crash.
-
-Note: this may be overridden by the B<rdm_policy> option in the B<pci>
-device configuration.
-
-=back
-
-=back
-
-=item B<usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]>
-
-Specifies the USB controllers created for this guest.
-
-Each B<USBCTRL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings, from the following list:
-
-=over 4
-
-=item B<type=TYPE>
-
-Specifies the usb controller type.
-
-=over 4
-
-=item B<pv>
-
-Specifies a kernel based PVUSB backend.
-
-=item B<qusb>
-
-Specifies a QEMU based PVUSB backend.
-
-=item B<devicemodel>
-
-Specifies a USB controller emulated by QEMU.
-It will show up as a PCI-device in the guest.
-
-=item B<auto>
-
-Determines whether a kernel based backend is installed.
-If this is the case, B<pv> is used, otherwise B<qusb> will be used.
-For HVM domains B<devicemodel> will be selected.
-
-This option is the default.
-
-=back
-
-=item B<version=VERSION>
-
-Specifies the usb controller version. Possible values include
-1 (USB1.1), 2 (USB2.0) and 3 (USB3.0).
-Default is 2 (USB2.0).
-Value 3 (USB3.0) is available for the B<devicemodel> type only.
-
-=item B<ports=PORTS>
-
-Specifies the total number of ports of the usb controller. The maximum
-number is 31. The default is 8.
-With the type B<devicemodel> the number of ports is more limited:
-a USB1.1 controller always has 2 ports,
-a USB2.0 controller always has 6 ports
-and a USB3.0 controller can have up to 15 ports.
-
-USB controller ids start from 0. In line with the USB specification, however,
-ports on a controller start from 1.
-
-B<EXAMPLE>
-
-=over 2
-
-usbctrl=["version=1,ports=4", "version=2,ports=8"]
-
-The first controller is USB1.1 and has:
-
-controller id = 0, and ports 1,2,3,4.
-
-The second controller is USB2.0 and has:
-
-controller id = 1, and ports 1,2,3,4,5,6,7,8.
-
-=back
-
-=back
-
-=item B<usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]>
-
-Specifies the USB devices to be attached to the guest at boot.
-
-Each B<USBDEV_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings, from the following list:
-
-=over 4
-
-=item B<type=hostdev>
-
-Specifies USB device type. Currently only "hostdev" is supported.
-
-=item B<hostbus=busnum>
-
-Specifies busnum of the USB device from the host perspective.
-
-=item B<hostaddr=devnum>
-
-Specifies devnum of the USB device from the host perspective.
-
-=item B<controller=CONTROLLER>
-
-Specifies the USB controller id, to which controller the USB device is
-attached.
-
-If no controller is specified, an available controller:port combination
-will be used. If there are no available controller:port combinations,
-a new controller will be created.
-
-=item B<port=PORT>
-
-Specifies the USB port to which the USB device is attached. The B<port>
-option is valid only when the B<controller> option is specified.
-
-=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 of
-B<[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 the 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 B<lspci(1)> for the device in
-question.
-
-Note: by default B<lspci(1)> 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 slot 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>.
-
-=item B<permissive=BOOLEAN>
-
-By default pciback only allows PV guests to write "known safe" values
-into PCI configuration space, likewise QEMU (both qemu-xen and
-qemu-xen-traditional) imposes the same constraint on HVM guests.
-However, many devices require writes to other areas of the configuration space
-in order to operate properly. This option tells the backend (pciback or QEMU)
-to allow all writes to the PCI configuration space of this device by this
-domain.
-
-B<This option should be enabled with caution:> it gives the guest much
-more control over the device, which may have security or stability
-implications. It is recommended to only enable this option for
-trusted VMs under administrator's control.
-
-=item B<msitranslate=BOOLEAN>
-
-Specifies that MSI-INTx translation should be turned on for the PCI
-device. When enabled, MSI-INTx translation will always enable MSI on
-the PCI device regardless of whether the guest uses INTx or MSI. Some
-device drivers, such as NVIDIA's, detect an inconsistency and do not
-function when this option is enabled. Therefore the default is false (0).
-
-=item B<seize=BOOLEAN>
-
-Tells B<xl> to automatically attempt to re-assign a device to
-pciback if it is not already assigned.
-
-B<WARNING:> If you set this option, B<xl> will gladly re-assign a critical
-system device, such as a network or a disk controller being used by
-dom0 without confirmation. Please use with care.
-
-=item B<power_mgmt=BOOLEAN>
-
-B<(HVM only)> Specifies that the VM should be able to program the
-D0-D3hot power management states for the PCI device. The default is false (0).
-
-=item B<rdm_policy=STRING>
-
-B<(HVM/x86 only)> This is the same as the policy setting inside the B<rdm>
-option but just specific to a given device. The default is "relaxed".
-
-Note: this would override global B<rdm> option.
-
-=back
-
-=item B<pci_permissive=BOOLEAN>
-
-Changes the default value of B<permissive> for all PCI devices passed
-through to this VM. See B<permissive> above.
-
-=item B<pci_msitranslate=BOOLEAN>
-
-Changes the default value of B<msitranslate> for all PCI devices passed
-through to this VM. See B<msitranslate> above.
-
-=item B<pci_seize=BOOLEAN>
-
-Changes the default value of B<seize> for all PCI devices passed
-through to this VM. See B<seize> above.
-
-=item B<pci_power_mgmt=BOOLEAN>
-
-B<(HVM only)> Changes the default value of B<power_mgmt> for all PCI
-devices passed through to this VM. See B<power_mgmt>
-above.
-
-=item B<gfx_passthru=BOOLEAN|"STRING">
-
-Enable graphics device PCI passthrough. This option makes an assigned
-PCI graphics card become the primary graphics card in the VM. The QEMU
-emulated graphics adapter is disabled and the VNC console for the VM
-will not have any graphics output. All graphics output, including boot
-time QEMU BIOS messages from the VM, will go to the physical outputs
-of the passed through physical graphics card.
-
-The graphics card PCI device to pass through is chosen with the B<pci>
-option, in exactly the same way a normal Xen PCI device
-passthrough/assignment is done. Note that B<gfx_passthru> does not do
-any kind of sharing of the GPU, so you can assign the GPU to only one
-single VM at a time.
-
-B<gfx_passthru> also enables various legacy VGA memory ranges, BARs, MMIOs,
-and ioports to be passed through to the VM, since those are required
-for correct operation of things like VGA BIOS, text mode, VBE, etc.
-
-Enabling the B<gfx_passthru> option also copies the physical graphics card
-video BIOS to the guest memory, and executes the VBIOS in the guest
-to initialize the graphics card.
-
-Most graphics adapters require vendor specific tweaks for properly
-working graphics passthrough. See the XenVGAPassthroughTestedAdapters
-L<http://wiki.xen.org/wiki/XenVGAPassthroughTestedAdapters> wiki page
-for graphics cards currently supported by B<gfx_passthru>.
-
-B<gfx_passthru> is currently supported both with the qemu-xen-traditional
-device-model and upstream qemu-xen device-model.
-
-When given as a boolean the B<gfx_passthru> option either disables graphics
-card passthrough or enables autodetection.
-
-When given as a string the B<gfx_passthru> option describes the type
-of device to enable. Note that this behavior is only supported with the
-upstream qemu-xen device-model. With qemu-xen-traditional IGD (Intel Graphics
-Device) is always assumed and options other than autodetect or explicit IGD
-will result in an error.
-
-Currently, valid values for the option are:
-
-=over 4
-
-=item B<0>
-
-Disables graphics device PCI passthrough.
-
-=item B<1>, B<"default">
-
-Enables graphics device PCI passthrough and autodetects the type of device
-which is being used.
-
-=item B<"igd">
-
-Enables graphics device PCI passthrough but forcing the type of device to
-Intel Graphics Device.
-
-=back
-
-Note that some graphics cards (AMD/ATI cards, for example) do not
-necessarily require the B<gfx_passthru> option, so you can use the normal Xen
-PCI passthrough to assign the graphics card as a secondary graphics
-card to the VM. The QEMU-emulated graphics card remains the primary
-graphics card, and VNC output is available from the QEMU-emulated
-primary adapter.
-
-More information about the Xen B<gfx_passthru> feature is available
-on the XenVGAPassthrough L<http://wiki.xen.org/wiki/XenVGAPassthrough>
-wiki page.
-
-=item B<rdm_mem_boundary=MBYTES>
-
-Number of megabytes to set for a boundary when checking for RDM conflicts.
-
-When RDM conflicts with RAM, RDM is probably scattered over the whole RAM
-space. Having multiple RDM entries would worsen this and lead to a complicated
-memory layout. Here we're trying to figure out a simple solution to
-avoid breaking the existing layout. When a conflict occurs,
-
- #1. Above a predefined boundary
- - move lowmem_end below the reserved region to solve the conflict;
-
- #2. Below a predefined boundary
- - Check if the policy is strict or relaxed.
- A "strict" policy leads to a fail in libxl.
- Note that when both policies are specified on a given region,
- "strict" is always preferred.
- The "relaxed" policy issues a warning message and also masks this
- entry INVALID to indicate we shouldn't expose this entry to
- hvmloader.
-
-The default value is 2048.
-
-=item B<dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]>
-
-Specifies the host device tree nodes to passt hrough to this guest. Each
-DTDEV_PATH is an absolute path in the device tree.
-
-=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]>
-
-Allow the guest to access specific legacy I/O ports. Each B<IOPORT_RANGE>
-is given in hexadecimal format and may either be a range, e.g. C<2f8-2ff>
-(inclusive), or a single I/O port, e.g. C<2f8>.
-
-It is recommended to only use this option for trusted VMs under
-administrator's control.
-
-=item B<iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]", ...]>
-
-Allow auto-translated domains to access specific hardware I/O memory pages.
-
-B<IOMEM_START> is a physical page number. B<NUM_PAGES> is the number of pages,
-beginning with B<START_PAGE>, to allow access to. B<GFN> specifies the guest
-frame number where the mapping will start in the guest's address space. If
-B<GFN> is not specified, the mapping will be performed using B<IOMEM_START>
-as a start in the guest's address space, therefore performing a 1:1 mapping
-by default.
-All of these values must be given in hexadecimal format.
-
-Note that the IOMMU won't be updated with the mappings specified with this
-option. This option therefore should not be used to pass through any
-IOMMU-protected devices.
-
-It is recommended to only use this option for trusted VMs under
-administrator's control.
-
-=item B<irqs=[ NUMBER, NUMBER, ...]>
-
-Allow a guest to access specific physical IRQs.
-
-It is recommended to only use this option for trusted VMs under
-administrator's control.
-
-If vuart console is enabled then irq 32 is reserved for it. See
-L</vuart="uart"> to know how to enable vuart console.
-
-=item B<max_event_channels=N>
-
-Limit the guest to using at most N event channels (PV interrupts).
-Guests use hypervisor resources for each event channel they use.
-
-The default of 1023 should be sufficient for typical guests. The
-maximum value depends on what the guest supports. Guests supporting the
-FIFO-based event channel ABI support up to 131,071 event channels.
-Other guests are limited to 4095 (64-bit x86 and ARM) or 1023 (32-bit
-x86).
-
-=item B<vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]>
-
-Specifies the virtual display devices to be provided to the guest.
-
-Each B<VDISPL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings, from the following list:
-
-=over 4
-
-=item C<backend=DOMAIN>
-
-Specifies the backend domain name or id. If not specified Domain-0 is used.
-
-=item C<be-alloc=BOOLEAN>
-
-Indicates if backend can be a buffer provider/allocator for this domain. See
-display protocol for details.
-
-=item C<connectors=CONNECTORS>
-
-Specifies virtual connectors for the device in following format
-<id>:<W>x<H>;<id>:<W>x<H>... where:
-
-=over 4
-
-=item C<id>
-
-String connector unique id. Space, comma symbols are not allowed.
-
-=item C<W>
-
-Connector width in pixels.
-
-=item C<H>
-
-Connector height in pixels.
-
-=back
-
-B<EXAMPLE>
-
-=over 4
-
-connectors=id0:1920x1080;id1:800x600;id2:640x480
-
-=back
-
-=back
-
-=item B<dm_restrict=BOOLEAN>
-
-Restrict the device model after startup,
-to limit the consequencese of security vulnerabilities in qemu.
-
-With this feature enabled,
-a compromise of the device model,
-via such a vulnerability,
-will not provide a privilege escalation attack on the whole system.
-
-This feature is a B<technology preview>.
-There are some significant limitations:
-
-=over 4
-
-=item
-
-This is not likely to work at all for PV guests
-nor guests using qdisk backends for their block devices.
-
-=item
-
-You must have a new enough qemu.
-In particular,
-if your qemu does not have the commit
-B<xen: restrict: use xentoolcore_restrict_all>
-the restriction request will be silently ineffective!
-
-=item
-
-The mechanisms used are not effective against
-denial of service problems.
-A compromised qemu can probably still impair
-or perhaps even prevent
-the proper functioning of the whole system,
-(at the very least, but not limited to,
-through resource exhaustion).
-
-=item
-
-It is not known whether the protection is
-effective when a domain is migrated.
-
-=item
-
-Some domain management functions do not work.
-For example, cdrom insert will fail.
-
-=item
-
-You should say C<vga="none">.
-Domains with stdvga graphics cards to not work.
-Domains with cirrus vga may seem to work.
-
-=item
-
-You must create user(s) for qemu to run as.
-
-Ideally, set aside a range of 32752 uids
-(from N to N+32751)
-and create a user
-whose name is B<xen-qemuuser-range-base>
-and whose uid is N
-and whose gid is a plain unprivileged gid.
-libxl will use one such user for each domid.
-
-Alternatively, either create
-B<xen-qemuuser-domid$domid>
-for every $domid from 1 to 32751 inclusive,
-or
-B<xen-qemuuser-shared>
-(in which case different guests will not
-be protected against each other).
-
-=item
-
-There are no countermeasures taken against reuse
-of the same unix user (uid)
-for subsequent domains,
-even if the B<xen-qemuuser-domid$domid> users are created.
-So a past domain with the same domid may be able to
-interferer with future domains.
-Possibly, even after a reboot.
-
-=item
-
-A compromised qemu will be able to read world-readable
-files in the dom0 operating system.
-
-=item
-
-Because of these limitations, this functionality,
-while it may enhance your security,
-should not be relied on.
-Any further limitations discovered in the current version
-will B<not> be handled via the Xen Project Security Process.
-
-=item
-
-In the future as we enhance this feature to improve the security,
-we may break backward compatibility.
-
-=back
-
-=item B<vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]>
-
-Specifies the virtual sound cards to be provided to the guest.
-Each B<VCARD_SPEC> is a list, which has a form of
-"[VSND_ITEM_SPEC, VSND_ITEM_SPEC, ... ]" (without the quotes).
-The virtual sound card has hierarchical structure.
-Every card has a set of PCM devices and streams, each could be individually
-configured.
-
-B<VSND_ITEM_SPEC> describes individual item parameters.
-B<VSND_ITEM_SPEC> is a string of comma separated item parameters
-headed by item identifier. Each item parameter is C<KEY=VALUE> pair:
-
-=over 4
-
-"identifier, param = value, ...".
-
-=back
-
-Identifier shall be one of following values: "CARD", "PCM", "STREAM".
-The child item treated as belonging to the previously defined parent item.
-
-All parameters are optional.
-
-There are group of parameters which are common for all items.
-This group can be defined at higher level of the hierarchy and be fully or
-partially re-used by the underlying layers. These parameters are:
-
-=over 4
-
-* number of channels (min/max)
-
-* supported sample rates
-
-* supported sample formats
-
-=back
-
-E.g. one can define these values for the whole card, device or stream.
-Every underlying layer in turn can re-define some or all of them to better
-fit its needs. For example, card may define number of channels to be
-in [1; 8] range, and some particular stream may be limited to [1; 2] only.
-The rule is that the underlying layer must be a subset of the upper layer
-range.
-
-I<COMMON parameters:>
-
-=over 4
-
-=over 4
-
-=item B<sample-rates=RATES>
-
-List of integer values separated by semicolon: sample-rates=8000;22050;44100
-
-=item B<sample-formats=FORMATS>
-
-List of string values separated by semicolon: sample-formats=s16_le;s8;u32_be
-
-Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be, s24_le, s24_be,
-u24_le, u24_be, s32_le, s32_be, u32_le, u32_be, float_le, float_be,
-float64_le, float64_be, iec958_subframe_le, iec958_subframe_be,
-mu_law, a_law, ima_adpcm, mpeg, gsm
-
-=item B<channels-min=NUMBER>
-
-The minimum amount of channels.
-
-=item B<channels-max=NUMBER>
-
-The maximum amount of channels.
-
-=item B<buffer-size=NUMBER>
-
-The maximum size in octets of the buffer to allocate per stream.
-
-=back
-
-=back
-
-I<CARD specification:>
-
-=over 4
-
-=over 4
-
-=item B<backend=domain-id>
-
-Specify the backend domain name or id, defaults to dom0.
-
-=item B<short-name=STRING>
-
-Short name of the virtual sound card.
-
-=item B<long-name=STRING>
-
-Long name of the virtual sound card.
-
-=back
-
-=back
-
-I<PCM specification:>
-
-=over 4
-
-=over 4
-
-=item B<name=STRING>
-
-Name of the PCM sound device within the virtual sound card.
-
-=back
-
-=back
-
-I<STREAM specification:>
-
-=over 4
-
-=over 4
-
-=item B<unique-id=STRING>
-
-Unique stream identifier.
-
-=item B<type=TYPE>
-
-Stream type: "p" - playback stream, "c" - capture stream.
-
-=back
-
-=back
-
-I<EXAMPLE:>
-
- vsnd = [
- ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
- 'PCM, name=Main',
- 'STREAM, id=0, type=p',
- 'STREAM, id=1, type=c, channels-max=2'
- ],
- ['CARD, short-name=Second',
- 'PCM, name=Second, buffer-size=1024',
- 'STREAM, id=2, type=p',
- 'STREAM, id=3, type=c'
- ]
- ]
-
-=item B<vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]>
-
-Specifies the virtual keyboard device to be provided to the guest.
-
-Each B<VKB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
-settings from the following list:
-
-=over 4
-
-=item B<unique-id=STRING>
-
-Specifies the unique input device id.
-
-=item B<backend=domain-id>
-
-Specifies the backend domain name or id.
-
-=item B<backend-type=type>
-
-Specifies the backend type: qemu - for QEMU backend or linux - for Linux PV
-domain.
-
-=item B<feature-disable-keyboard=BOOLEAN>
-
-Indicates if keyboard device is disabled.
-
-=item B<feature-disable-pointer=BOOLEAN>
-
-Indicates if pointer device is disabled.
-
-=item B<feature-abs-pointer=BOOLEAN>
-
-Indicates if pointer device can return absolute coordinates.
-
-=item B<feature-raw-pointer=BOOLEAN>
-
-Indicates if pointer device can return raw (unscaled) absolute coordinates.
-
-=item B<feature-multi-touch=BOOLEAN>
-
-Indicates if input device supports multi touch.
-
-=item B<multi-touch-width=MULTI_TOUCH_WIDTH>
-
-Set maximum width for multi touch device.
-
-=item B<multi-touch-height=MULTI_TOUCH_HEIGHT>
-
-Set maximum height for multi touch device.
-
-=item B<multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS>
-
-Set maximum contacts number for multi touch device.
-
-=item B<width=WIDTH>
-
-Set maximum width for pointer device.
-
-=item B<height=HEIGHT>
-
-Set maximum height for pointer device.
-
-=back
-
-=back
-
-=head2 Paravirtualised (PV) Guest Specific Options
-
-The following options apply only to Paravirtual (PV) guests.
-
-=over 4
-
-=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. Either B<kernel> or B<bootloader> must be specified
-for PV guests.
-
-=item B<bootloader_args=[ "ARG", "ARG", ...]>
-
-Append B<ARG>s 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 B<(this second option is deprecated)>.
-
-=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 (0) the guest pseudo-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 laid out.
-
-Exposing the host e820 to the guest gives the guest kernel the
-opportunity to set aside the required part of its pseudo-physical
-address space in order to provide address space to map passedthrough
-PCI devices. It is guest Operating System dependent whether this
-option is required, specifically it is required when using a mainline
-Linux ("pvops") kernel. This option defaults to true (1) if any PCI
-passthrough devices are configured and false (0) 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 Fully-virtualised (HVM) guests.
-
-=head3 Boot Device
-
-=over 4
-
-=item B<boot="STRING">
-
-Specifies the emulated virtual device to boot from.
-
-Possible values are:
-
-=over 4
-
-=item B<c>
-
-Hard disk.
-
-=item B<d>
-
-CD-ROM.
-
-=item B<n>
-
-Network / PXE.
-
-=back
-
-B<Note:> multiple options can be given and will be attempted in the order they
-are given, e.g. to boot from CD-ROM but fall back to the hard disk you can
-specify it as B<dc>.
-
-The default is B<cd>, meaning try booting from the hard disk first, but fall
-back to the CD-ROM.
-
-
-=back
-
-=head3 Emulated disk controller type
-
-=over 4
-
-=item B<hdtype=STRING>
-
-Specifies the hard disk type.
-
-Possible values are:
-
-=over 4
-
-=item B<ide>
-
-If thise mode is specified B<xl> adds an emulated IDE controller, which is
-suitable even for older operation systems.
-
-=item B<ahci>
-
-If this mode is specified, B<xl> adds an ich9 disk controller in AHCI mode and
-uses it with upstream QEMU to emulate disks instead of IDE. It decreases boot
-time but may not be supported by default in older operating systems, e.g.
-Windows XP.
-
-=back
-
-The default is B<ide>.
-
-=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 cases 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. 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 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<bios="STRING">
-
-Select the virtual firmware that is exposed to the guest.
-By default, a guess is made based on the device model, but sometimes
-it may be useful to request a different one, like UEFI.
-
-=over 4
-
-=item B<rombios>
-
-Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by default
-when B<device_model_version=qemu-xen-traditional>. This is the only BIOS
-option supported when B<device_model_version=qemu-xen-traditional>. This is
-the BIOS used by all previous Xen versions.
-
-=item B<seabios>
-
-Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by default
-with device_model_version=qemu-xen.
-
-=item B<ovmf>
-
-Loads OVMF, a standard UEFI firmware by Tianocore project.
-Requires device_model_version=qemu-xen.
-
-=back
-
-=item B<bios_path_override="PATH">
-
-Override the path to the blob to be used as BIOS. The blob provided here MUST
-be consistent with the B<bios=> which you have specified. You should not
-normally need to specify this option.
-
-This option does not have any effect if using B<bios="rombios"> or
-B<device_model_version="qemu-xen-traditional">.
-
-=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.
-This option is true for x86 while it's false for ARM by default.
-
-=item B<acpi_s3=BOOLEAN>
-
-Include the S3 (suspend-to-ram) power state in the virtual firmware
-ACPI table. True (1) by default.
-
-=item B<acpi_s4=BOOLEAN>
-
-Include S4 (suspend-to-disk) power state in the virtual firmware ACPI
-table. True (1) by default.
-
-=item B<acpi_laptop_slate=BOOLEAN>
-
-Include the Windows laptop/slate mode switch device in the virtual
-firmware ACPI table. False (0) by default.
-
-=item B<apic=BOOLEAN>
-
-B<(x86 only)> 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 superseded by newer constructs within
-the ACPI tables.
-
-=item B<nx=BOOLEAN>
-
-B<(x86 only)> Hides or exposes the No-eXecute capability. This allows a guest
-Operating System to map pages in such a way that they cannot be executed which
-can enhance security. This options requires that PAE also be
-enabled.
-
-=item B<hpet=BOOLEAN>
-
-B<(x86 only)> 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.
-
-=item B<altp2m="MODE">
-
-B<(x86 only)> Specifies the access mode to the alternate-p2m capability.
-Alternate-p2m allows a guest to manage multiple p2m guest physical "memory
-views" (as opposed to a single p2m).
-You may want this option if you want to access-control/isolate
-access to specific guest physical memory pages accessed by the guest, e.g. for
-domain memory introspection or for isolation/access-control of memory between
-components within a single guest domain. This option is disabled by default.
-
-The valid values are as follows:
-
-=over 4
-
-=item B<disabled>
-
-Altp2m is disabled for the domain (default).
-
-=item B<mixed>
-
-The mixed mode allows access to the altp2m interface for both in-guest
-and external tools as well.
-
-=item B<external>
-
-Enables access to the alternate-p2m capability by external privileged tools.
-
-=item B<limited>
-
-Enables limited access to the alternate-p2m capability,
-ie. giving the guest access only to enable/disable the VMFUNC and #VE features.
-
-=back
-
-=item B<altp2mhvm=BOOLEAN>
-
-Enables or disables HVM guest access to alternate-p2m capability.
-Alternate-p2m allows a guest to manage multiple p2m guest physical
-"memory views" (as opposed to a single p2m). This option is
-disabled by default and is available only to HVM domains.
-You may want this option if you want to access-control/isolate
-access to specific guest physical memory pages accessed by
-the guest, e.g. for HVM domain memory introspection or
-for isolation/access-control of memory between components within
-a single guest HVM domain. B<This option is deprecated, use the option
-"altp2m" instead.>
-
-B<Note>: While the option "altp2mhvm" is deprecated, legacy applications for
-x86 systems will continue to work using it.
-
-=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. 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).
-This option is disabled by default.
-
-=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
-
-Configure the value returned when a guest executes the CPUID instruction.
-Two versions of config syntax are recognized: libxl and xend.
-
-The libxl syntax is a comma separated list of key=value pairs, preceded by the
-word "host". A few keys take a numerical value, all others take a single
-character which describes what to do with the feature bit.
-
-Possible values for a single feature bit:
- '1' -> force the corresponding bit to 1
- '0' -> force to 0
- 'x' -> Get a safe value (pass through and mask with the default policy)
- 'k' -> pass through the host bit value
- 's' -> as 'k' but preserve across save/restore and migration (not implemented)
-
-Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group)
-only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the
-rest are ignored (these 8 bits signify maximum number of hypervisor leaves).
-
-List of keys taking a value:
-apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc
-proccount procpkg stepping
-
-List of keys taking a character:
-3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8 apic arat avx avx2
-avx512-4fmaps avx512-4vnniw avx512bw avx512cd avx512dq avx512er avx512f
-avx512ifma avx512pf avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
-cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl dtes64 erms est extapic
-f16c ffxsr fma fma4 fpu fsgsbase fxsr hle htt hypervisor ia64 ibs invpcid
-invtsc lahfsahf lm lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr
-mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid pclmulqdq pdcm
-perfctr_core perfctr_nb pge pku popcnt pse pse36 psn rdrand rdseed rdtscp rtm
-sha skinit smap smep smx ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a
-ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt svm_tscrate
-svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc tsc-deadline tsc_adjust
-umip vme vmx wdt x2apic xop xsave xtpr
-
-
-The xend syntax is a list of values in the form of
-'leafnum:register=bitstring,register=bitstring'
- "leafnum" is the requested function,
- "register" is the response register to modify
- "bitstring" represents all bits in the register, its length must be 32 chars.
- Each successive character represent a lesser-significant bit, possible values
- are listed above in the libxl section.
-
-Example to hide two features from the guest: 'tm', which is bit #29 in EDX, and
-'pni' (SSE3), which is bit #0 in ECX:
-
-xend: [ "1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ]
-
-libxl: "host,tm=0,sse3=0"
-
-More info about the CPUID instruction can be found in the processor manuals,
-and on Wikipedia: L<http://en.wikipedia.org/wiki/CPUID>
-
-=item B<acpi_firmware="STRING">
-
-Specifies a path to a file that contains extra ACPI firmware tables to pass into
-a guest. The file can contain several tables in their binary AML form
-concatenated together. Each table self describes its length so no additional
-information is needed. These tables will be added to the ACPI table set in the
-guest. Note that existing tables cannot be overridden by this feature. For
-example, this cannot be used to override tables like DSDT, FADT, etc.
-
-=item B<smbios_firmware="STRING">
-
-Specifies a path to a file that contains extra SMBIOS firmware structures to
-pass into a guest. The file can contain a set of DMTF predefined structures
-which will override the internal defaults. Not all predefined structures can be
-overridden,
-only the following types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any
-number of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
-structures do not present their overall size, each entry in the file must be
-preceded by a 32b integer indicating the size of the following structure.
-
-=item B<ms_vm_genid="OPTION">
-
-Provide a VM generation ID to the guest.
-
-The VM generation ID is a 128-bit random number that a guest may use
-to determine if the guest has been restored from an earlier snapshot
-or cloned.
-
-This is required for Microsoft Windows Server 2012 (and later) domain
-controllers.
-
-Valid options are:
-
-=over 4
-
-=item B<generate>
-
-Generate a random VM generation ID every time the domain is created or
-restored.
-
-=item B<none>
-
-Do not provide a VM generation ID.
-
-=back
-
-See also "Virtual Machine Generation ID" by Microsoft:
-L<http://www.microsoft.com/en-us/download/details.aspx?id=30707>
-
-=back
-
-=head3 Guest Virtual Time Controls
-
-=over 4
-
-=item B<tsc_mode="MODE">
-
-B<(x86 only)> Specifies how the TSC (Time Stamp Counter) should be provided to
-the guest. B<Specifying this option as a number is deprecated.>
-
-Options are:
-
-=over 4
-
-=item B<default>
-
-Guest rdtsc/p is executed natively when monotonicity can be guaranteed
-and emulated otherwise (with frequency scaled if necessary).
-
-If a HVM container in B<default> TSC mode is created on a host that
-provides constant host TSC, its guest TSC frequency will be the same
-as the host. If it is later migrated to another host that provide
-constant host TSC and supports Intel VMX TSC scaling/AMD SVM TSC
-ratio, its guest TSC frequency will be the same before and after
-migration, and guest rdtsc/p will be executed natively after migration as well
-
-=item B<always_emulate>
-
-Guest rdtsc/p is 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/p is always executed natively (no monotonicity/frequency
-guarantees). Guest rdtsc/p is emulated at native frequency if unsupported
-by h/w, else executed natively.
-
-=item B<native_paravirt>
-
-This mode has been removed.
-
-=back
-
-Please see B<xen-tscmode(7)> for more information on this option.
-
-=item B<localtime=BOOLEAN>
-
-Set the real time clock to local time or to UTC. False (0) by default,
-i.e. set to UTC.
-
-=item B<rtc_timeoffset=SECONDS>
-
-Set the real time clock offset in seconds. No offset (0) by default.
-
-=item B<vpt_align=BOOLEAN>
-
-Specifies that periodic Virtual Platform Timers should be aligned to
-reduce guest interrupts. Enabling this option can reduce power
-consumption, especially when a guest uses a high timer interrupt
-frequency (HZ) values. The default is true (1).
-
-=item B<timer_mode="MODE">
-
-Specifies the mode for Virtual Timers. The valid values are as follows:
-
-=over 4
-
-=item B<delay_for_missed_ticks>
-
-Delay for missed ticks. Do not advance a vCPU's time beyond the
-correct delivery time for interrupts that have been missed due to
-preemption. Deliver missed interrupts when the vCPU is rescheduled and
-advance the vCPU's virtual time stepwise for each one.
-
-=item B<no_delay_for_missed_ticks>
-
-No delay for missed ticks. As above, missed interrupts are delivered,
-but guest time always tracks wallclock (i.e., real) time while doing
-so. This is the default.
-
-=item B<no_missed_ticks_pending>
-
-No missed interrupts are held pending. Instead, to ensure ticks are
-delivered at some non-zero rate, if we detect missed ticks then the
-internal tick alarm is not disabled if the vCPU is preempted during
-the next tick period.
-
-=item B<one_missed_tick_pending>
-
-One missed tick pending. Missed interrupts are collapsed
-together and delivered as one 'late tick'. Guest time always tracks
-wallclock (i.e., real) time.
-
-=back
-
-=back
-
-=head3 Memory layout
-
-=over 4
-
-=item B<mmio_hole=MBYTES>
-
-Specifies the size the MMIO hole below 4GiB will be. Only valid for
-B<device_model_version="qemu-xen">.
-
-Cannot be smaller than 256. Cannot be larger than 3840.
-
-Known good large value is 3072.
-
-=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>.
-
-Setting B<xen_platform_pci=0> with the default device_model "qemu-xen"
-requires at least QEMU 1.6.
-
-=item B<viridian=[ "GROUP", "GROUP", ...]> or B<viridian=BOOLEAN>
-
-The groups of Microsoft Hyper-V (AKA viridian) compatible enlightenments
-exposed to the guest. The following groups of enlightenments may be
-specified:
-
-=over 4
-
-=item B<base>
-
-This group incorporates the Hypercall MSRs, Virtual processor index MSR,
-and APIC access MSRs. These enlightenments can improve performance of
-Windows Vista and Windows Server 2008 onwards and setting this option
-for such guests is strongly recommended.
-This group is also a pre-requisite for all others. If it is disabled
-then it is an error to attempt to enable any other group.
-
-=item B<freq>
-
-This group incorporates the TSC and APIC frequency MSRs. These
-enlightenments can improve performance of Windows 7 and Windows
-Server 2008 R2 onwards.
-
-=item B<time_ref_count>
-
-This group incorporates Partition Time Reference Counter MSR. This
-enlightenment can improve performance of Windows 8 and Windows
-Server 2012 onwards.
-
-=item B<reference_tsc>
-
-This set incorporates the Partition Reference TSC MSR. This
-enlightenment can improve performance of Windows 7 and Windows
-Server 2008 R2 onwards.
-
-=item B<hcall_remote_tlb_flush>
-
-This set incorporates use of hypercalls for remote TLB flushing.
-This enlightenment may improve performance of Windows guests running
-on hosts with higher levels of (physical) CPU contention.
-
-=item B<apic_assist>
-
-This set incorporates use of the APIC assist page to avoid EOI of
-the local APIC.
-This enlightenment may improve performance of guests that make use of
-per-vCPU event channel upcall vectors.
-Note that this enlightenment will have no effect if the guest is
-using APICv posted interrupts.
-
-=item B<crash_ctl>
-
-This group incorporates the crash control MSRs. These enlightenments
-allow Windows to write crash information such that it can be logged
-by Xen.
-
-=item B<defaults>
-
-This is a special value that enables the default set of groups, which
-is currently the B<base>, B<freq>, B<time_ref_count>, B<apic_assist>
-and B<crash_ctl> groups.
-
-=item B<all>
-
-This is a special value that enables all available groups.
-
-=back
-
-Groups can be disabled by prefixing the name with '!'. So, for example,
-to enable all groups except B<freq>, specify:
-
-=over 4
-
-B<viridian=[ "all", "!freq" ]>
-
-=back
-
-For details of the enlightenments see the latest version of Microsoft's
-Hypervisor Top-Level Functional Specification.
-
-The enlightenments should be harmless for other versions of Windows
-(although they will not give any benefit) and the majority of other
-non-Windows OSes.
-However it is known that they are incompatible with some other Operating
-Systems and in some circumstance can prevent Xen's own paravirtualisation
-interfaces for HVM guests from being used.
-
-The viridian option can be specified as a boolean. A value of true (1)
-is equivalent to the list [ "defaults" ], and a value of false (0) is
-equivalent to an empty list.
-
-=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.
-
-When using the qemu-xen-traditional device-model, the default as well as
-minimum amount of video RAM for stdvga is 8 MB, which is sufficient for e.g.
-1600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and
-minimum is 16 MB.
-
-When using the emulated Cirrus graphics card (B<vga="cirrus">) and the
-qemu-xen-traditional device-model, the amount of video RAM is fixed at 4 MB,
-which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen
-device-model, the default and minimum is 8 MB.
-
-For QXL vga, both the default and minimal are 128MB.
-If B<videoram> is set less than 128MB, an error will be triggered.
-
-=item B<stdvga=BOOLEAN>
-
-Speficies a standard VGA card with VBE (VESA BIOS Extensions) as the
-emulated graphics device. If your guest supports VBE 2.0 or
-later (e.g. Windows XP onwards) then you should enable this.
-stdvga supports more video ram and bigger resolutions than Cirrus.
-The default is false (0) which means to emulate
-a Cirrus Logic GD5446 VGA card.
-B<This option is deprecated, use vga="stdvga" instead>.
-
-=item B<vga="STRING">
-
-Selects the emulated video card.
-Options are: B<none>, B<stdvga>, B<cirrus> and B<qxl>.
-The default is B<cirrus>.
-
-In general, QXL should work with the Spice remote display protocol
-for acceleration, and a QXL driver is necessary in the guest in that case.
-QXL can also work with the VNC protocol, but it will be like a standard
-VGA card without acceleration.
-
-=item B<vnc=BOOLEAN>
-
-Allow access to the display via the VNC protocol. This enables the
-other VNC-related settings. The default is (1) enabled.
-
-=item B<vnclisten="ADDRESS[:DISPLAYNUM]">
-
-Specifies the IP address and, optionally, the 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 searches for a free TCP port to use.
-The actual display used can be accessed with B<xl vncviewer>.
-
-=item B<vncpasswd="PASSWORD">
-
-Specifies the password for the VNC server. If the password is set to an
-empty string, authentication on the VNC server will be disabled
-allowing any user to connect.
-
-=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 B<Keymaps> below or consult the
-B<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 (0) not enabled.
-
-=item B<opengl=BOOLEAN>
-
-Enable OpenGL acceleration of the SDL display. Only effects machines
-using B<device_model_version="qemu-xen-traditional"> and only if the
-device-model was compiled with OpenGL support. Default is (0) false.
-
-=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">
-
-Specifies the interface address to listen on if given, otherwise any
-interface.
-
-=item B<spiceport=NUMBER>
-
-Specifies the port to listen on by the SPICE server if SPICE is
-enabled.
-
-=item B<spicetls_port=NUMBER>
-
-Specifies the secure port to listen on by the SPICE server if SPICE
-is enabled. At least one of B<spiceport> or B<spicetls_port> must be
-given if SPICE is enabled.
-
-B<Note:> the options depending on B<spicetls_port>
-have not been supported.
-
-=item B<spicedisable_ticketing=BOOLEAN>
-
-Enable clients to connect without specifying a password. When disabled,
-B<spicepasswd> must be set. The default is (0) false.
-
-=item B<spicepasswd="PASSWORD">
-
-Specify the password which is used by clients for establishing a connection.
-
-=item B<spiceagent_mouse=BOOLEAN>
-
-Whether SPICE agent is used for client mouse mode. The default is (1) true.
-
-=item B<spicevdagent=BOOLEAN>
-
-Enables the SPICE vdagent. The SPICE vdagent is an optional component for
-enhancing user experience and performing guest-oriented management
-tasks. Its features include: client mouse mode (no need to grab the mouse
-by the client, no mouse lag), automatic adjustment of screen resolution,
-copy and paste (text and image) between the client and the guest. It also
-requires the vdagent service installed on the guest OS to work.
-The default is (0) disabled.
-
-=item B<spice_clipboard_sharing=BOOLEAN>
-
-Enables SPICE clipboard sharing (copy/paste). It requires that
-B<spicevdagent> is enabled. The default is (0) false.
-
-=item B<spiceusbredirection=NUMBER>
-
-Enables SPICE USB redirection. Creates a NUMBER of USB redirection channels
-for redirecting up to 4 USB devices from the SPICE client to the guest's QEMU.
-It requires an USB controller and, if not defined, it will automatically add
-an USB2.0 controller. The default is (0) disabled.
-
-=item B<spice_image_compression="COMPRESSION">
-
-Specifies what image compression is to be used by SPICE (if given), otherwise
-the QEMU default will be used. Please see the documentation of your QEMU
-version for more details.
-
-Available options are: B<auto_glz, auto_lz, quic, glz, lz, off>.
-
-=item B<spice_streaming_video="VIDEO">
-
-Specifies what streaming video setting is to be used by SPICE (if given),
-otherwise the QEMU default will be used.
-
-Available options are: B<filter, all, off>.
-
-=back
-
-=head3 Miscellaneous Emulated Hardware
-
-=over 4
-
-=item B<serial=[ "DEVICE", "DEVICE", ...]>
-
-Redirect virtual serial ports to B<DEVICE>s. Please see the
-B<-serial> option in the B<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.
-
-The form serial=DEVICE is also accepted for backwards compatibility.
-
-=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
-B<qemu(1)> manpage for details. The default is not to export any sound
-device.
-
-=item B<usb=BOOLEAN>
-
-Enables or disables an emulated USB bus in the guest.
-
-=item B<usbversion=NUMBER>
-
-Specifies the type of an emulated USB bus in the guest, values 1 for USB1.1,
-2 for USB2.0 and 3 for USB3.0. It is available only with an upstream QEMU.
-Due to implementation limitations this is not compatible with the B<usb>
-and B<usbdevice> parameters.
-Default is (0) no USB controller defined.
-
-=item B<usbdevice=[ "DEVICE", "DEVICE", ...]>
-
-Adds B<DEVICE>s to the emulated 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 a 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.
-
-Host devices can also be passed through in this way, by specifying
-host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
-typically be found by using B<lsusb(1)> or B<usb-devices(1)>.
-
-If you wish to use the "host:bus.addr" format, remove any leading '0' from the
-bus and addr. For example, for the USB device on bus 008 dev 002, you should
-write "host:8.2".
-
-The form usbdevice=DEVICE is also accepted for backwards compatibility.
-
-More valid options can be found in the "usbdevice" section of the QEMU
-documentation.
-
-=item B<vendor_device="VENDOR_DEVICE">
-
-Selects which variant of the QEMU xen-pvdevice should be used for this
-guest. Valid values are:
-
-=over 4
-
-=item B<none>
-
-The xen-pvdevice should be omitted. This is the default.
-
-=item B<xenserver>
-
-The xenserver variant of the xen-pvdevice (device-id=C000) will be
-specified, enabling the use of XenServer PV drivers in the guest.
-
-=back
-
-This parameter only takes effect when device_model_version=qemu-xen.
-See B<xen-pci-device-reservations(7)> for more information.
-
-=back
-
-=head2 PVH Guest Specific Options
-
-=over 4
-
-=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.
-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).
-
-This option is disabled by default.
-
-=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. Either B<kernel> or B<bootloader> must be specified
-for PV guests.
-
-=item B<bootloader_args=[ "ARG", "ARG", ...]>
-
-Append B<ARG>s 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 B<(this second option is deprecated)>.
-
-=item B<timer_mode="MODE">
-
-Specifies the mode for Virtual Timers. The valid values are as follows:
-
-=over 4
-
-=item B<delay_for_missed_ticks>
-
-Delay for missed ticks. Do not advance a vCPU's time beyond the
-correct delivery time for interrupts that have been missed due to
-preemption. Deliver missed interrupts when the vCPU is rescheduled and
-advance the vCPU's virtual time stepwise for each one.
-
-=item B<no_delay_for_missed_ticks>
-
-No delay for missed ticks. As above, missed interrupts are delivered,
-but guest time always tracks wallclock (i.e., real) time while doing
-so. This is the default.
-
-=item B<no_missed_ticks_pending>
-
-No missed interrupts are held pending. Instead, to ensure ticks are
-delivered at some non-zero rate, if we detect missed ticks then the
-internal tick alarm is not disabled if the vCPU is preempted during
-the next tick period.
-
-=item B<one_missed_tick_pending>
-
-One missed tick pending. Missed interrupts are collapsed
-together and delivered as one 'late tick'. Guest time always tracks
-wallclock (i.e., real) time.
-
-=back
-
-=back
-
-=head3 Paging
-
-The following options control the mechanisms used to virtualise guest
-memory. The defaults are selected to give the best results for the
-common cases 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. 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 very large number of
-similar processes then increasing this value may improve performance.
-
-=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>
-
-Use the device-model merged into the upstream QEMU project.
-This device-model is the default for Linux dom0.
-
-=item B<qemu-xen-traditional>
-
-Use the device-model based upon the historical Xen fork of QEMU.
-This device-model is still the default for NetBSD dom0.
-
-=back
-
-It is recommended to accept the default value for new guests. If
-you have existing guests then, depending 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
-B<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_stubdomain_seclabel="LABEL">
-
-Assign an XSM security label to the device-model stubdomain.
-
-=item B<device_model_args=[ "ARG", "ARG", ...]>
-
-Pass additional arbitrary options on the device-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 device-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 device-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 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 B<qemu(1)> for more information.
-
-=head2 Architecture Specific options
-
-=head3 ARM
-
-=over 4
-
-=item B<gic_version="vN">
-
-Version of the GIC emulated for the guest.
-
-Currently, the following versions are supported:
-
-=over 4
-
-=item B<v2>
-
-Emulate a GICv2
-
-=item B<v3>
-
-Emulate a GICv3. Note that the emulated GIC does not support the
-GICv2 compatibility mode.
-
-=item B<default>
-
-Emulate the same version as the native GIC hardware used by the host where
-the domain was created.
-
-=back
-
-This requires hardware compatibility with the requested version, either
-natively or via hardware backwards compatibility support.
-
-=item B<vuart="uart">
-
-To enable vuart console, user must specify the following option in the
-VM config file:
-
-vuart = "sbsa_uart"
-
-Currently, only the "sbsa_uart" model is supported for ARM.
-
-=back
-
-=head3 x86
-
-=over 4
-
-=item B<mca_caps=[ "CAP", "CAP", ... ]>
-
-(HVM only) Enable MCA capabilities besides default ones enabled
-by Xen hypervisor for the HVM domain. "CAP" can be one in the
-following list:
-
-=over 4
-
-=item B<"lmce">
-
-Intel local MCE
-
-=item B<default>
-
-No MCA capabilities in above list are enabled.
-
-=back
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item L<xl(1)>
-
-=item L<xl.conf(5)>
-
-=item L<xlcpupool.cfg(5)>
-
-=item L<xl-disk-configuration(5)>
-
-=item L<xl-network-configuration(5)>
-
-=item L<xen-tscmode(7)>
-
-=back
-
-=head1 FILES
-
-F</etc/xen/NAME.cfg>
-F<@XEN_DUMP_DIR@/NAME>
-
-=head1 BUGS
-
-This document may contain items which require further
-documentation. Patches to improve incomplete items (or any other item)
-are gratefully received on the xen-devel@lists.xen.org mailing
-list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
-information on how to submit a patch to Xen.
-
--- /dev/null
+=head1 NAME
+
+/etc/xen/xl.conf - XL Global/Host Configuration
+
+=head1 DESCRIPTION
+
+The F<xl.conf> file allows configuration of hostwide C<xl> toolstack
+options.
+
+For details of per-domain configuration options please see
+L<xl.cfg(5)>.
+
+=head1 SYNTAX
+
+The config file consists of a series of C<KEY=VALUE> pairs.
+
+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
+
+=over 4
+
+=item B<autoballoon="off"|"on"|"auto">
+
+If set to "on" then C<xl> will automatically reduce the amount of
+memory assigned to domain 0 in order to free memory for new domains.
+
+If set to "off" then C<xl> will not automatically reduce the amount of
+domain 0 memory.
+
+If set to "auto" then auto-ballooning will be disabled if the
+C<dom0_mem> option was provided on the Xen command line.
+
+You are strongly recommended to set this to C<"off"> (or C<"auto">) if
+you use the C<dom0_mem> hypervisor command line to reduce the amount
+of memory given to domain 0 by default.
+
+Default: C<"auto">
+
+=item B<run_hotplug_scripts=BOOLEAN>
+
+If disabled hotplug scripts will be called from udev, as it used to
+be in the previous releases. With the default option, hotplug scripts
+will be launched by xl directly.
+
+Default: C<1>
+
+=item B<lockfile="PATH">
+
+Sets the path to the lock file used by xl to serialise certain
+operations (primarily domain creation).
+
+Default: C</var/lock/xl>
+
+=item B<max_grant_frames=NUMBER>
+
+Sets the default value for the C<max_grant_frames> domain config value.
+
+Default: C<32> on hosts up to 16TB of memory, C<64> on hosts larger than 16TB
+
+=item B<max_maptrack_frames=NUMBER>
+
+Sets the default value for the C<max_maptrack_frames> domain config value.
+
+Default: C<1024>
+
+=item B<vif.default.script="PATH">
+
+Configures the default hotplug script used by virtual network devices.
+
+The old B<vifscript> option is deprecated and should not be used.
+
+Default: C</etc/xen/scripts/vif-bridge>
+
+=item B<vif.default.bridge="NAME">
+
+Configures the default bridge to set for virtual network devices.
+
+The old B<defaultbridge> option is deprecated and should not be used.
+
+Default: C<xenbr0>
+
+=item B<vif.default.backend="NAME">
+
+Configures the default backend to set for virtual network devices.
+
+Default: C<0>
+
+=item B<vif.default.gatewaydev="NAME">
+
+Configures the default gateway device to set for virtual network devices.
+
+Default: C<None>
+
+=item B<remus.default.netbufscript="PATH">
+
+Configures the default script used by Remus to setup network buffering.
+
+Default: C</etc/xen/scripts/remus-netbuf-setup>
+
+=item B<colo.default.proxyscript="PATH">
+
+Configures the default script used by COLO to setup colo-proxy.
+
+Default: C</etc/xen/scripts/colo-proxy-setup>
+
+=item B<output_format="json|sxp">
+
+Configures the default output format used by xl when printing "machine
+readable" information. The default is to use the C<JSON>
+L<http://www.json.org/> syntax. However for compatibility with the
+previous C<xm> toolstack this can be configured to use the old C<SXP>
+(S-Expression-like) syntax instead.
+
+Default: C<json>
+
+=item B<blkdev_start="NAME">
+
+Configures the name of the first block device to be used for temporary
+block device allocations by the toolstack.
+The default choice is "xvda".
+
+=item B<claim_mode=BOOLEAN>
+
+If this option is enabled then when a guest is created there will be an
+guarantee that there is memory available for the guest. This is an
+particularly acute problem on hosts with memory over-provisioned guests
+that use tmem and have self-balloon enabled (which is the default
+option). The self-balloon mechanism can deflate/inflate the balloon
+quickly and the amount of free memory (which C<xl info> can show) is
+stale the moment it is printed. When claim is enabled a reservation for
+the amount of memory (see 'memory' in xl.conf(5)) is set, which is then
+reduced as the domain's memory is populated and eventually reaches zero.
+The free memory in C<xl info> is the combination of the hypervisor's
+free heap memory minus the outstanding claims value.
+
+If the reservation cannot be meet the guest creation fails immediately
+instead of taking seconds/minutes (depending on the size of the guest)
+while the guest is populated.
+
+Note that to enable tmem type guests, one needs to provide C<tmem> on the
+Xen hypervisor argument and as well on the Linux kernel command line.
+
+Default: C<1>
+
+=over 4
+
+=item C<0>
+
+No claim is made. Memory population during guest creation will be
+attempted as normal and may fail due to memory exhaustion.
+
+=item C<1>
+
+Normal memory and freeable pool of ephemeral pages (tmem) is used when
+calculating whether there is enough memory free to launch a guest.
+This guarantees immediate feedback whether the guest can be launched due
+to memory exhaustion (which can take a long time to find out if launching
+massively huge guests).
+
+=back
+
+=item B<vm.cpumask>="CPULIST"
+
+=item B<vm.hvm.cpumask>="CPULIST"
+
+=item B<vm.pv.cpumask>="CPULIST"
+
+Global masks that are applied when creating guests and pinning vcpus
+to indicate which cpus they are allowed to run on. Specifically,
+C<vm.cpumask> applies to all guest types, C<vm.hvm.cpumask> applies to
+both HVM and PVH guests and C<vm.pv.cpumask> applies to PV guests.
+
+The hard affinity of guest's vcpus are logical-AND'ed with respective
+masks. If the resulting affinity mask is empty, operation will fail.
+
+Use --ignore-global-affinity-masks to skip applying global masks.
+
+The default value for these masks are all 1's, i.e. all cpus are allowed.
+
+Due to bug(s), these options may not interact well with other options
+concerning CPU affinity. One example is CPU pools. Users should always double
+check that the required affinity has taken effect.
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<xl(1)>
+
+=item L<xl.cfg(5)>
+
+=item http://www.json.org/
+
+=back
+++ /dev/null
-=head1 NAME
-
-/etc/xen/xl.conf - XL Global/Host Configuration
-
-=head1 DESCRIPTION
-
-The F<xl.conf> file allows configuration of hostwide C<xl> toolstack
-options.
-
-For details of per-domain configuration options please see
-L<xl.cfg(5)>.
-
-=head1 SYNTAX
-
-The config file consists of a series of C<KEY=VALUE> pairs.
-
-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
-
-=over 4
-
-=item B<autoballoon="off"|"on"|"auto">
-
-If set to "on" then C<xl> will automatically reduce the amount of
-memory assigned to domain 0 in order to free memory for new domains.
-
-If set to "off" then C<xl> will not automatically reduce the amount of
-domain 0 memory.
-
-If set to "auto" then auto-ballooning will be disabled if the
-C<dom0_mem> option was provided on the Xen command line.
-
-You are strongly recommended to set this to C<"off"> (or C<"auto">) if
-you use the C<dom0_mem> hypervisor command line to reduce the amount
-of memory given to domain 0 by default.
-
-Default: C<"auto">
-
-=item B<run_hotplug_scripts=BOOLEAN>
-
-If disabled hotplug scripts will be called from udev, as it used to
-be in the previous releases. With the default option, hotplug scripts
-will be launched by xl directly.
-
-Default: C<1>
-
-=item B<lockfile="PATH">
-
-Sets the path to the lock file used by xl to serialise certain
-operations (primarily domain creation).
-
-Default: C</var/lock/xl>
-
-=item B<max_grant_frames=NUMBER>
-
-Sets the default value for the C<max_grant_frames> domain config value.
-
-Default: C<32> on hosts up to 16TB of memory, C<64> on hosts larger than 16TB
-
-=item B<max_maptrack_frames=NUMBER>
-
-Sets the default value for the C<max_maptrack_frames> domain config value.
-
-Default: C<1024>
-
-=item B<vif.default.script="PATH">
-
-Configures the default hotplug script used by virtual network devices.
-
-The old B<vifscript> option is deprecated and should not be used.
-
-Default: C</etc/xen/scripts/vif-bridge>
-
-=item B<vif.default.bridge="NAME">
-
-Configures the default bridge to set for virtual network devices.
-
-The old B<defaultbridge> option is deprecated and should not be used.
-
-Default: C<xenbr0>
-
-=item B<vif.default.backend="NAME">
-
-Configures the default backend to set for virtual network devices.
-
-Default: C<0>
-
-=item B<vif.default.gatewaydev="NAME">
-
-Configures the default gateway device to set for virtual network devices.
-
-Default: C<None>
-
-=item B<remus.default.netbufscript="PATH">
-
-Configures the default script used by Remus to setup network buffering.
-
-Default: C</etc/xen/scripts/remus-netbuf-setup>
-
-=item B<colo.default.proxyscript="PATH">
-
-Configures the default script used by COLO to setup colo-proxy.
-
-Default: C</etc/xen/scripts/colo-proxy-setup>
-
-=item B<output_format="json|sxp">
-
-Configures the default output format used by xl when printing "machine
-readable" information. The default is to use the C<JSON>
-L<http://www.json.org/> syntax. However for compatibility with the
-previous C<xm> toolstack this can be configured to use the old C<SXP>
-(S-Expression-like) syntax instead.
-
-Default: C<json>
-
-=item B<blkdev_start="NAME">
-
-Configures the name of the first block device to be used for temporary
-block device allocations by the toolstack.
-The default choice is "xvda".
-
-=item B<claim_mode=BOOLEAN>
-
-If this option is enabled then when a guest is created there will be an
-guarantee that there is memory available for the guest. This is an
-particularly acute problem on hosts with memory over-provisioned guests
-that use tmem and have self-balloon enabled (which is the default
-option). The self-balloon mechanism can deflate/inflate the balloon
-quickly and the amount of free memory (which C<xl info> can show) is
-stale the moment it is printed. When claim is enabled a reservation for
-the amount of memory (see 'memory' in xl.conf(5)) is set, which is then
-reduced as the domain's memory is populated and eventually reaches zero.
-The free memory in C<xl info> is the combination of the hypervisor's
-free heap memory minus the outstanding claims value.
-
-If the reservation cannot be meet the guest creation fails immediately
-instead of taking seconds/minutes (depending on the size of the guest)
-while the guest is populated.
-
-Note that to enable tmem type guests, one needs to provide C<tmem> on the
-Xen hypervisor argument and as well on the Linux kernel command line.
-
-Default: C<1>
-
-=over 4
-
-=item C<0>
-
-No claim is made. Memory population during guest creation will be
-attempted as normal and may fail due to memory exhaustion.
-
-=item C<1>
-
-Normal memory and freeable pool of ephemeral pages (tmem) is used when
-calculating whether there is enough memory free to launch a guest.
-This guarantees immediate feedback whether the guest can be launched due
-to memory exhaustion (which can take a long time to find out if launching
-massively huge guests).
-
-=back
-
-=item B<vm.cpumask>="CPULIST"
-
-=item B<vm.hvm.cpumask>="CPULIST"
-
-=item B<vm.pv.cpumask>="CPULIST"
-
-Global masks that are applied when creating guests and pinning vcpus
-to indicate which cpus they are allowed to run on. Specifically,
-C<vm.cpumask> applies to all guest types, C<vm.hvm.cpumask> applies to
-both HVM and PVH guests and C<vm.pv.cpumask> applies to PV guests.
-
-The hard affinity of guest's vcpus are logical-AND'ed with respective
-masks. If the resulting affinity mask is empty, operation will fail.
-
-Use --ignore-global-affinity-masks to skip applying global masks.
-
-The default value for these masks are all 1's, i.e. all cpus are allowed.
-
-Due to bug(s), these options may not interact well with other options
-concerning CPU affinity. One example is CPU pools. Users should always double
-check that the required affinity has taken effect.
-
-=back
-
-=head1 SEE ALSO
-
-=over 4
-
-=item L<xl(1)>
-
-=item L<xl.cfg(5)>
-
-=item http://www.json.org/
-
-=back
+++ /dev/null
-=head1 NAME
-
-xl - Xen management tool, based on LibXenlight
-
-=head1 SYNOPSIS
-
-B<xl> I<subcommand> [I<args>]
-
-=head1 DESCRIPTION
-
-The B<xl> program is the new tool for managing Xen guest
-domains. The program can be used to create, pause, and shutdown
-domains. It can also be used to list current domains, enable or pin
-VCPUs, and attach or detach virtual block devices.
-
-The basic structure of every B<xl> command is almost always:
-
-=over 2
-
-B<xl> I<subcommand> [I<OPTIONS>] I<domain-id>
-
-=back
-
-Where I<subcommand> is one of the subcommands listed below, I<domain-id>
-is the numeric domain id, or the domain name (which will be internally
-translated to domain id), and I<OPTIONS> are subcommand specific
-options. There are a few exceptions to this rule in the cases where
-the subcommand in question acts on all domains, the entire machine,
-or directly on the Xen hypervisor. Those exceptions will be clear for
-each of those subcommands.
-
-=head1 NOTES
-
-=over 4
-
-=item start the script B</etc/init.d/xencommons> at boot time
-
-Most B<xl> operations rely upon B<xenstored> and B<xenconsoled>: make
-sure you start the script B</etc/init.d/xencommons> at boot time to
-initialize all the daemons needed by B<xl>.
-
-=item setup a B<xenbr0> bridge in dom0
-
-In the most common network configuration, you need to setup a bridge in dom0
-named B<xenbr0> in order to have a working network in the guest domains.
-Please refer to the documentation of your Linux distribution to know how to
-setup the bridge.
-
-=item B<autoballoon>
-
-If you specify the amount of memory dom0 has, passing B<dom0_mem> to
-Xen, it is highly recommended to disable B<autoballoon>. Edit
-B</etc/xen/xl.conf> and set it to 0.
-
-=item run xl as B<root>
-
-Most B<xl> commands require root privileges to run due to the
-communications channels used to talk to the hypervisor. Running as
-non root will return an error.
-
-=back
-
-=head1 GLOBAL OPTIONS
-
-Some global options are always available:
-
-=over 4
-
-=item B<-v>
-
-Verbose.
-
-=item B<-N>
-
-Dry run: do not actually execute the command.
-
-=item B<-f>
-
-Force execution: xl will refuse to run some commands if it detects that xend is
-also running, this option will force the execution of those commands, even
-though it is unsafe.
-
-=item B<-t>
-
-Always use carriage-return-based overwriting for displaying progress
-messages without scrolling the screen. Without -t, this is done only
-if stderr is a tty.
-
-=back
-
-=head1 DOMAIN SUBCOMMANDS
-
-The following subcommands manipulate domains directly. As stated
-previously, most commands take I<domain-id> as the first parameter.
-
-=over 4
-
-=item B<button-press> I<domain-id> I<button>
-
-I<This command is deprecated. Please use C<xl trigger> instead.>
-
-Indicate an ACPI button press to the domain, where I<button> can be 'power' or
-'sleep'. This command is only available for HVM domains.
-
-=item B<create> [I<configfile>] [I<OPTIONS>]
-
-The create subcommand takes a config file as its first argument: see
-L<xl.cfg(5)> for full details of the file format and possible options.
-If I<configfile> is missing B<xl> creates the domain assuming the default
-values for every option.
-
-I<configfile> has to be an absolute path to a file.
-
-Create will return B<as soon> as the domain is started. This B<does
-not> mean the guest OS in the domain has actually booted, or is
-available for input.
-
-If the I<-F> option is specified, create will start the domain and not
-return until its death.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-q>, B<--quiet>
-
-No console output.
-
-=item B<-f=FILE>, B<--defconfig=FILE>
-
-Use the given configuration file.
-
-=item B<-p>
-
-Leave the domain paused after it is created.
-
-=item B<-F>
-
-Run in foreground until death of the domain.
-
-=item B<-V>, B<--vncviewer>
-
-Attach to domain's VNC server, forking a vncviewer process.
-
-=item B<-A>, B<--vncviewer-autopass>
-
-Pass the VNC password to vncviewer via stdin.
-
-=item B<-c>
-
-Attach console to the domain as soon as it has started. This is
-useful for determining issues with crashing domains and just as a
-general convenience since you often want to watch the
-domain boot.
-
-=item B<key=value>
-
-It is possible to pass I<key=value> pairs on the command line to provide
-options as if they were written in the configuration file; these override
-whatever is in the I<configfile>.
-
-NB: Many config options require characters such as quotes or brackets
-which are interpreted by the shell (and often discarded) before being
-passed to xl, resulting in xl being unable to parse the value
-correctly. A simple work-around is to put all extra options within a
-single set of quotes, separated by semicolons. (See below for an example.)
-
-=back
-
-B<EXAMPLES>
-
-=over 4
-
-=item I<with config file>
-
- xl create DebianLenny
-
-This creates a domain with the file /etc/xen/DebianLenny, and returns as
-soon as it is run.
-
-=item I<with extra parameters>
-
- xl create hvm.cfg 'cpus="0-3"; pci=["01:05.1","01:05.2"]'
-
-This creates a domain with the file hvm.cfg, but additionally pins it to
-cpus 0-3, and passes through two PCI devices.
-
-=back
-
-=item B<config-update> I<domain-id> [I<configfile>] [I<OPTIONS>]
-
-Update the saved configuration for a running domain. This has no
-immediate effect but will be applied when the guest is next
-restarted. This command is useful to ensure that runtime modifications
-made to the guest will be preserved when the guest is restarted.
-
-Since Xen 4.5 xl has improved capabilities to handle dynamic domain
-configuration changes and will preserve any changes made at runtime
-when necessary. Therefore it should not normally be necessary to use
-this command any more.
-
-I<configfile> has to be an absolute path to a file.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-f=FILE>, B<--defconfig=FILE>
-
-Use the given configuration file.
-
-=item B<key=value>
-
-It is possible to pass I<key=value> pairs on the command line to
-provide options as if they were written in the configuration file;
-these override whatever is in the I<configfile>. Please see the note
-under I<create> on handling special characters when passing
-I<key=value> pairs on the command line.
-
-=back
-
-=item B<console> [I<OPTIONS>] I<domain-id>
-
-Attach to the console of a domain specified by I<domain-id>. If you've set up
-your domains to have a traditional login console this will look much like a
-normal text login screen.
-
-Use the key combination Ctrl+] to detach from the domain console.
-
-B<OPTIONS>
-
-=over 4
-
-=item I<-t [pv|serial]>
-
-Connect to a PV console or connect to an emulated serial console.
-PV consoles are the only consoles available for PV domains while HVM
-domains can have both. If this option is not specified it defaults to
-emulated serial for HVM guests and PV console for PV guests.
-
-=item I<-n NUM>
-
-Connect to console number I<NUM>. Console numbers start from 0.
-
-=back
-
-=item B<destroy> [I<OPTIONS>] I<domain-id>
-
-Immediately terminate the domain specified by I<domain-id>. This doesn't give
-the domain OS any chance to react, and is the equivalent of ripping the power
-cord out on a physical machine. In most cases you will want to use the
-B<shutdown> command instead.
-
-B<OPTIONS>
-
-=over 4
-
-=item I<-f>
-
-Allow domain 0 to be destroyed. Because a domain cannot destroy itself, this
-is only possible when using a disaggregated toolstack, and is most useful when
-using a hardware domain separated from domain 0.
-
-=back
-
-=item B<domid> I<domain-name>
-
-Converts a domain name to a domain id.
-
-=item B<domname> I<domain-id>
-
-Converts a domain id to a domain name.
-
-=item B<rename> I<domain-id> I<new-name>
-
-Change the domain name of a domain specified by I<domain-id> to I<new-name>.
-
-=item B<dump-core> I<domain-id> [I<filename>]
-
-Dumps the virtual machine's memory for the specified domain to the
-I<filename> specified, without pausing the domain. The dump file will
-be written to a distribution specific directory for dump files, for example:
-@XEN_DUMP_DIR@/dump.
-
-=item B<help> [I<--long>]
-
-Displays the short help message (i.e. common commands) by default.
-
-If the I<--long> option is specified, it displays the complete set of B<xl>
-subcommands, grouped by function.
-
-=item B<list> [I<OPTIONS>] [I<domain-id> ...]
-
-Displays information about one or more domains. If no domains are
-specified it displays information about all domains.
-
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-l>, B<--long>
-
-The output for B<xl list> is not the table view shown below, but
-instead presents the data as a JSON data structure.
-
-=item B<-Z>, B<--context>
-
-Also displays the security labels.
-
-=item B<-v>, B<--verbose>
-
-Also displays the domain UUIDs, the shutdown reason and security labels.
-
-=item B<-c>, B<--cpupool>
-
-Also displays the cpupool the domain belongs to.
-
-=item B<-n>, B<--numa>
-
-Also displays the domain NUMA node affinity.
-
-=back
-
-B<EXAMPLE>
-
-An example format for the list is as follows:
-
- Name ID Mem VCPUs State Time(s)
- Domain-0 0 750 4 r----- 11794.3
- win 1 1019 1 r----- 0.3
- linux 2 2048 2 r----- 5624.2
-
-Name is the name of the domain. ID the numeric domain id. Mem is the
-desired amount of memory to allocate to the domain (although it may
-not be the currently allocated amount). VCPUs is the number of
-virtual CPUs allocated to the domain. State is the run state (see
-below). Time is the total run time of the domain as accounted for by
-Xen.
-
-B<STATES>
-
-The State field lists 6 states for a Xen domain, and which ones the
-current domain is in.
-
-=over 4
-
-=item B<r - running>
-
-The domain is currently running on a CPU.
-
-=item B<b - blocked>
-
-The domain is blocked, and not running or runnable. This can be because the
-domain is waiting on IO (a traditional wait state) or has
-gone to sleep because there was nothing else for it to do.
-
-=item B<p - paused>
-
-The domain has been paused, usually occurring through the administrator
-running B<xl pause>. When in a paused state the domain will still
-consume allocated resources (like memory), but will not be eligible for
-scheduling by the Xen hypervisor.
-
-=item B<s - shutdown>
-
-The guest OS has shut down (SCHEDOP_shutdown has been called) but the
-domain is not dying yet.
-
-=item B<c - crashed>
-
-The domain has crashed, which is always a violent ending. Usually
-this state only occurs if the domain has been configured not to
-restart on a crash. See L<xl.cfg(5)> for more info.
-
-=item B<d - dying>
-
-The domain is in the process of dying, but hasn't completely shut down or
-crashed.
-
-=back
-
-B<NOTES>
-
-=over 4
-
-The Time column is deceptive. Virtual IO (network and block devices)
-used by the domains requires coordination by Domain0, which means that
-Domain0 is actually charged for much of the time that a DomainU is
-doing IO. Use of this time value to determine relative utilizations
-by domains is thus very unreliable, as a high IO workload may show as
-less utilized than a high CPU workload. Consider yourself warned.
-
-=back
-
-=item B<mem-max> I<domain-id> I<mem>
-
-Specify the maximum amount of memory the domain is able to use, appending 't'
-for terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b'
-for bytes.
-
-The mem-max value may not correspond to the actual memory used in the
-domain, as it may balloon down its memory to give more back to the OS.
-
-The value given just sets the memory amount the domain is allowed to allocate
-in the hypervisor. It can't be set lower than the current reservation, but
-it is allowed to be higher than the configured maximum memory size of the
-domain (B<maxmem> parameter in the domain's configuration). Using B<xl mem-max>
-to set the maximum memory above the initial B<maxmem> value will not allow the
-additional memory to be used via B<xl mem-set>. The initial B<maxmem> value is
-still used as an upper limit for B<xl mem-set>.
-
-The domain will not receive any signal regarding the changed memory limit.
-
-=item B<mem-set> I<domain-id> I<mem>
-
-Set the domain's used memory using the balloon driver; append 't' for
-terabytes, 'g' for gigabytes, 'm' for megabytes, 'k' for kilobytes and 'b' for
-bytes.
-
-Because this operation requires cooperation from the domain operating
-system, there is no guarantee that it will succeed. This command will
-definitely not work unless the domain has the required paravirt
-driver.
-
-B<Warning:> There is no good way to know in advance how small of a
-mem-set will make a domain unstable and cause it to crash. Be very
-careful when using this command on running domains.
-
-=item B<migrate> [I<OPTIONS>] I<domain-id> I<host>
-
-Migrate a domain to another host machine. By default B<xl> relies on ssh as a
-transport mechanism between the two hosts.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-s> I<sshcommand>
-
-Use <sshcommand> instead of ssh. String will be passed to sh. If empty, run
-<host> instead of ssh <host> xl migrate-receive [-d -e].
-
-=item B<-e>
-
-On the new <host>, do not wait in the background for the death of the
-domain. See the corresponding option of the I<create> subcommand.
-
-=item B<-C> I<config>
-
-Send the specified <config> file instead of the file used on creation of the
-domain.
-
-=item B<--debug>
-
-Display huge (!) amount of debug information during the migration process.
-
-=item B<-p>
-
-Leave the domain on the receive side paused after migration.
-
-=back
-
-=item B<remus> [I<OPTIONS>] I<domain-id> I<host>
-
-Enable Remus HA or COLO HA for domain. By default B<xl> relies on ssh as a
-transport mechanism between the two hosts.
-
-B<NOTES>
-
-=over 4
-
-Remus support in xl is still in experimental (proof-of-concept) phase.
-Disk replication support is limited to DRBD disks.
-
-COLO support in xl is still in experimental (proof-of-concept)
-phase. All options are subject to change in the future.
-
-=back
-
-COLO disk configuration looks like:
-
- disk = ['...,colo,colo-host=xxx,colo-port=xxx,colo-export=xxx,active-disk=xxx,hidden-disk=xxx...']
-
-The supported options are:
-
-=over 4
-
-=item B<colo-host> : Secondary host's ip address.
-
-=item B<colo-port> : Secondary host's port, we will run a nbd server on the
-secondary host, and the nbd server will listen on this port.
-
-=item B<colo-export> : Nbd server's disk export name of the secondary host.
-
-=item B<active-disk> : Secondary's guest write will be buffered to this disk,
-and it's used by the secondary.
-
-=item B<hidden-disk> : Primary's modified contents will be buffered in this
-disk, and it's used by the secondary.
-
-=back
-
-COLO network configuration looks like:
-
- vif = [ '...,forwarddev=xxx,...']
-
-The supported options are:
-
-=over 4
-
-=item B<forwarddev> : Forward devices for the primary and the secondary, they
-are directly connected.
-
-
-=back
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-i> I<MS>
-
-Checkpoint domain memory every MS milliseconds (default 200ms).
-
-=item B<-u>
-
-Disable memory checkpoint compression.
-
-=item B<-s> I<sshcommand>
-
-Use <sshcommand> instead of ssh. String will be passed to sh.
-If empty, run <host> instead of ssh <host> xl migrate-receive -r [-e].
-
-=item B<-e>
-
-On the new <host>, do not wait in the background for the death of the domain.
-See the corresponding option of the I<create> subcommand.
-
-=item B<-N> I<netbufscript>
-
-Use <netbufscript> to setup network buffering instead of the
-default script (/etc/xen/scripts/remus-netbuf-setup).
-
-=item B<-F>
-
-Run Remus in unsafe mode. Use this option with caution as failover may
-not work as intended.
-
-=item B<-b>
-
-Replicate memory checkpoints to /dev/null (blackhole).
-Generally useful for debugging. Requires enabling unsafe mode.
-
-=item B<-n>
-
-Disable network output buffering. Requires enabling unsafe mode.
-
-=item B<-d>
-
-Disable disk replication. Requires enabling unsafe mode.
-
-=item B<-c>
-
-Enable COLO HA. This conflicts with B<-i> and B<-b>, and memory
-checkpoint compression must be disabled.
-
-=item B<-p>
-
-Use userspace COLO Proxy. This option must be used in conjunction
-with B<-c>.
-
-=back
-
-=item B<pause> I<domain-id>
-
-Pause a domain. When in a paused state the domain will still consume
-allocated resources (such as memory), but will not be eligible for
-scheduling by the Xen hypervisor.
-
-=item B<reboot> [I<OPTIONS>] I<domain-id>
-
-Reboot a domain. This acts just as if the domain had the B<reboot>
-command run from the console. The command returns as soon as it has
-executed the reboot action, which may be significantly earlier than when the
-domain actually reboots.
-
-For HVM domains this requires PV drivers to be installed in your guest
-OS. If PV drivers are not present but you have configured the guest OS
-to behave appropriately you may be able to use the I<-F> option to
-trigger a reset button press.
-
-The behavior of what happens to a domain when it reboots is set by the
-B<on_reboot> parameter of the domain configuration file when the
-domain was created.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-F>
-
-If the guest does not support PV reboot control then fallback to
-sending an ACPI power event (equivalent to the I<reset> option to
-I<trigger>).
-
-You should ensure that the guest is configured to behave as expected
-in response to this event.
-
-=back
-
-=item B<restore> [I<OPTIONS>] [I<configfile>] I<checkpointfile>
-
-Build a domain from an B<xl save> state file. See B<save> for more info.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-p>
-
-Do not unpause the domain after restoring it.
-
-=item B<-e>
-
-Do not wait in the background for the death of the domain on the new host.
-See the corresponding option of the I<create> subcommand.
-
-=item B<-d>
-
-Enable debug messages.
-
-=item B<-V>, B<--vncviewer>
-
-Attach to the domain's VNC server, forking a vncviewer process.
-
-=item B<-A>, B<--vncviewer-autopass>
-
-Pass the VNC password to vncviewer via stdin.
-
-
-
-=back
-
-=item B<save> [I<OPTIONS>] I<domain-id> I<checkpointfile> [I<configfile>]
-
-Saves a running domain to a state file so that it can be restored
-later. Once saved, the domain will no longer be running on the
-system, unless the -c or -p options are used.
-B<xl restore> restores from this checkpoint file.
-Passing a config file argument allows the user to manually select the VM config
-file used to create the domain.
-
-=over 4
-
-=item B<-c>
-
-Leave the domain running after creating the snapshot.
-
-=item B<-p>
-
-Leave the domain paused after creating the snapshot.
-
-=back
-
-=item B<sharing> [I<domain-id>]
-
-Display the number of shared pages for a specified domain. If no domain is
-specified it displays information about all domains.
-
-=item B<shutdown> [I<OPTIONS>] I<-a|domain-id>
-
-Gracefully shuts down a domain. This coordinates with the domain OS
-to perform graceful shutdown, so there is no guarantee that it will
-succeed, and may take a variable length of time depending on what
-services must be shut down in the domain.
-
-For HVM domains this requires PV drivers to be installed in your guest
-OS. If PV drivers are not present but you have configured the guest OS
-to behave appropriately you may be able to use the I<-F> option to
-trigger a power button press.
-
-The command returns immediately after signaling the domain unless the
-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 domain configuration file when the
-domain was created.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-a>, B<--all>
-
-Shutdown all guest domains. Often used when doing a complete shutdown
-of a Xen system.
-
-=item B<-w>, B<--wait>
-
-Wait for the domain to complete shutdown before returning.
-
-=item B<-F>
-
-If the guest does not support PV shutdown control then fallback to
-sending an ACPI power event (equivalent to the I<power> option to
-I<trigger>).
-
-You should ensure that the guest is configured to behave as expected
-in response to this event.
-
-=back
-
-=item B<sysrq> I<domain-id> I<letter>
-
-Send a <Magic System Request> to the domain, each type of request is
-represented by a different letter.
-It can be used to send SysRq requests to Linux guests, see sysrq.txt in
-your Linux Kernel sources for more information.
-It requires PV drivers to be installed in your guest OS.
-
-=item B<trigger> I<domain-id> I<nmi|reset|init|power|sleep|s3resume> [I<VCPU>]
-
-Send a trigger to a domain, where the trigger can be: nmi, reset, init, power
-or sleep. Optionally a specific vcpu number can be passed as an argument.
-This command is only available for HVM domains.
-
-=item B<unpause> I<domain-id>
-
-Moves a domain out of the paused state. This will allow a previously
-paused domain to now be eligible for scheduling by the Xen hypervisor.
-
-=item B<vcpu-set> I<domain-id> I<vcpu-count>
-
-Enables the I<vcpu-count> virtual CPUs for the domain in question.
-Like mem-set, this command can only allocate up to the maximum virtual
-CPU count configured at boot for the domain.
-
-If the I<vcpu-count> is smaller than the current number of active
-VCPUs, the highest number VCPUs will be hotplug removed. This may be
-important for pinning purposes.
-
-Attempting to set the VCPUs to a number larger than the initially
-configured VCPU count is an error. Trying to set VCPUs to < 1 will be
-quietly ignored.
-
-Some guests may need to actually bring the newly added CPU online
-after B<vcpu-set>, go to B<SEE ALSO> section for information.
-
-=item B<vcpu-list> [I<domain-id>]
-
-Lists VCPU information for a specific domain. If no domain is
-specified, VCPU information for all domains will be provided.
-
-=item B<vcpu-pin> [I<-f|--force>] I<domain-id> I<vcpu> I<cpus hard> I<cpus soft>
-
-Set hard and soft affinity for a I<vcpu> of <domain-id>. Normally VCPUs
-can float between available CPUs whenever Xen deems a different run state
-is appropriate.
-
-Hard affinity can be used to restrict this, by ensuring certain VCPUs
-can only run on certain physical CPUs. Soft affinity specifies a I<preferred>
-set of CPUs. Soft affinity needs special support in the scheduler, which is
-only provided in credit1.
-
-The keyword B<all> can be used to apply the hard and soft affinity masks to
-all the VCPUs in the domain. The symbol '-' can be used to leave either
-hard or soft affinity alone.
-
-For example:
-
- xl vcpu-pin 0 3 - 6-9
-
-will set soft affinity for vCPU 3 of domain 0 to pCPUs 6,7,8 and 9,
-leaving its hard affinity untouched. On the other hand:
-
- xl vcpu-pin 0 3 3,4 6-9
-
-will set both hard and soft affinity, the former to pCPUs 3 and 4, the
-latter to pCPUs 6,7,8, and 9.
-
-Specifying I<-f> or I<--force> will remove a temporary pinning done by the
-operating system (normally this should be done by the operating system).
-In case a temporary pinning is active for a vcpu the affinity of this vcpu
-can't be changed without this option.
-
-=item B<vm-list>
-
-Prints information about guests. This list excludes information about
-service or auxiliary domains such as dom0 and stubdoms.
-
-B<EXAMPLE>
-
-An example format for the list is as follows:
-
- UUID ID name
- 59e1cf6c-6ab9-4879-90e7-adc8d1c63bf5 2 win
- 50bc8f75-81d0-4d53-b2e6-95cb44e2682e 3 linux
-
-=item B<vncviewer> [I<OPTIONS>] I<domain-id>
-
-Attach to the domain's VNC server, forking a vncviewer process.
-
-B<OPTIONS>
-
-=over 4
-
-=item I<--autopass>
-
-Pass the VNC password to vncviewer via stdin.
-
-=back
-
-=back
-
-=head1 XEN HOST SUBCOMMANDS
-
-=over 4
-
-=item B<debug-keys> I<keys>
-
-Send debug I<keys> to Xen. It is the same as pressing the Xen
-"conswitch" (Ctrl-A by default) three times and then pressing "keys".
-
-=item B<set-parameters> I<params>
-
-Set hypervisor parameters as specified in I<params>. This allows for some
-boot parameters of the hypervisor to be modified in the running systems.
-
-=item B<dmesg> [I<OPTIONS>]
-
-Reads the Xen message buffer, similar to dmesg on a Linux system. The
-buffer contains informational, warning, and error messages created
-during Xen's boot process. If you are having problems with Xen, this
-is one of the first places to look as part of problem determination.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-c>, B<--clear>
-
-Clears Xen's message buffer.
-
-=back
-
-=item B<info> [I<OPTIONS>]
-
-Print information about the Xen host in I<name : value> format. When
-reporting a Xen bug, please provide this information as part of the
-bug report. See I<http://wiki.xen.org/xenwiki/ReportingBugs> on how to
-report Xen bugs.
-
-Sample output looks as follows:
-
- host : scarlett
- release : 3.1.0-rc4+
- version : #1001 SMP Wed Oct 19 11:09:54 UTC 2011
- machine : x86_64
- nr_cpus : 4
- nr_nodes : 1
- cores_per_socket : 4
- threads_per_core : 1
- cpu_mhz : 2266
- hw_caps : bfebfbff:28100800:00000000:00003b40:009ce3bd:00000000:00000001:00000000
- virt_caps : hvm hvm_directio
- total_memory : 6141
- free_memory : 4274
- free_cpus : 0
- outstanding_claims : 0
- xen_major : 4
- xen_minor : 2
- xen_extra : -unstable
- xen_caps : xen-3.0-x86_64 xen-3.0-x86_32p hvm-3.0-x86_32 hvm-3.0-x86_32p hvm-3.0-x86_64
- xen_scheduler : credit
- xen_pagesize : 4096
- platform_params : virt_start=0xffff800000000000
- xen_changeset : Wed Nov 02 17:09:09 2011 +0000 24066:54a5e994a241
- xen_commandline : com1=115200,8n1 guest_loglvl=all dom0_mem=750M console=com1
- cc_compiler : gcc version 4.4.5 (Debian 4.4.5-8)
- cc_compile_by : sstabellini
- cc_compile_domain : uk.xensource.com
- cc_compile_date : Tue Nov 8 12:03:05 UTC 2011
- xend_config_format : 4
-
-
-B<FIELDS>
-
-Not all fields will be explained here, but some of the less obvious
-ones deserve explanation:
-
-=over 4
-
-=item B<hw_caps>
-
-A vector showing what hardware capabilities are supported by your
-processor. This is equivalent to, though more cryptic, the flags
-field in /proc/cpuinfo on a normal Linux machine: they both derive from
-the feature bits returned by the cpuid command on x86 platforms.
-
-=item B<free_memory>
-
-Available memory (in MB) not allocated to Xen, or any other domains, or
-claimed for domains.
-
-=item B<outstanding_claims>
-
-When a claim call is done (see L<xl.conf>) a reservation for a specific
-amount of pages is set and also a global value is incremented. This
-global value (outstanding_claims) is then reduced as the domain's memory
-is populated and eventually reaches zero. Most of the time the value will
-be zero, but if you are launching multiple guests, and B<claim_mode> is
-enabled, this value can increase/decrease. Note that the value also
-affects the B<free_memory> - as it will reflect the free memory
-in the hypervisor minus the outstanding pages claimed for guests.
-See xl I<info> B<claims> parameter for detailed listing.
-
-=item B<xen_caps>
-
-The Xen version and architecture. Architecture values can be one of:
-x86_32, x86_32p (i.e. PAE enabled), x86_64, ia64.
-
-=item B<xen_changeset>
-
-The Xen mercurial changeset id. Very useful for determining exactly
-what version of code your Xen system was built from.
-
-=back
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-n>, B<--numa>
-
-List host NUMA topology information
-
-=back
-
-=item B<top>
-
-Executes the B<xentop(1)> command, which provides real time monitoring of
-domains. Xentop has a curses interface, and is reasonably self explanatory.
-
-=item B<uptime>
-
-Prints the current uptime of the domains running.
-
-=item B<claims>
-
-Prints information about outstanding claims by the guests. This provides
-the outstanding claims and currently populated memory count for the guests.
-These values added up reflect the global outstanding claim value, which
-is provided via the I<info> argument, B<outstanding_claims> value.
-The B<Mem> column has the cumulative value of outstanding claims and
-the total amount of memory that has been right now allocated to the guest.
-
-B<EXAMPLE>
-
-An example format for the list is as follows:
-
- Name ID Mem VCPUs State Time(s) Claimed
- Domain-0 0 2047 4 r----- 19.7 0
- OL5 2 2048 1 --p--- 0.0 847
- OL6 3 1024 4 r----- 5.9 0
- Windows_XP 4 2047 1 --p--- 0.0 1989
-
-In which it can be seen that the OL5 guest still has 847MB of claimed
-memory (out of the total 2048MB where 1191MB has been allocated to
-the guest).
-
-=back
-
-=head1 SCHEDULER SUBCOMMANDS
-
-Xen ships with a number of domain schedulers, which can be set at boot
-time with the B<sched=> parameter on the Xen command line. By
-default B<credit> is used for scheduling.
-
-=over 4
-
-=item B<sched-credit> [I<OPTIONS>]
-
-Set or get credit (aka credit1) scheduler parameters. The credit scheduler is
-a proportional fair share CPU scheduler built from the ground up to be
-work conserving on SMP hosts.
-
-Each domain (including Domain0) is assigned a weight and a cap.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-d DOMAIN>, B<--domain=DOMAIN>
-
-Specify domain for which scheduler parameters are to be modified or retrieved.
-Mandatory for modifying scheduler parameters.
-
-=item B<-w WEIGHT>, B<--weight=WEIGHT>
-
-A domain with a weight of 512 will get twice as much CPU as a domain
-with a weight of 256 on a contended host. Legal weights range from 1
-to 65535 and the default is 256.
-
-=item B<-c CAP>, B<--cap=CAP>
-
-The cap optionally fixes the maximum amount of CPU a domain will be
-able to consume, even if the host system has idle CPU cycles. The cap
-is expressed in percentage of one physical CPU: 100 is 1 physical CPU,
-50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is
-no upper cap.
-
-NB: Many systems have features that will scale down the computing
-power of a cpu that is not 100% utilized. This can be in the
-operating system, but can also sometimes be below the operating system
-in the BIOS. If you set a cap such that individual cores are running
-at less than 100%, this may have an impact on the performance of your
-workload over and above the impact of the cap. For example, if your
-processor runs at 2GHz, and you cap a vm at 50%, the power management
-system may also reduce the clock speed to 1GHz; the effect will be
-that your VM gets 25% of the available power (50% of 1GHz) rather than
-50% (50% of 2GHz). If you are not getting the performance you expect,
-look at performance and cpufreq options in your operating system and
-your BIOS.
-
-=item B<-p CPUPOOL>, B<--cpupool=CPUPOOL>
-
-Restrict output to domains in the specified cpupool.
-
-=item B<-s>, B<--schedparam>
-
-Specify to list or set pool-wide scheduler parameters.
-
-=item B<-t TSLICE>, B<--tslice_ms=TSLICE>
-
-Timeslice tells the scheduler how long to allow VMs to run before
-pre-empting. The default is 30ms. Valid ranges are 1ms to 1000ms.
-The length of the timeslice (in ms) must be higher than the length of
-the ratelimit (see below).
-
-=item B<-r RLIMIT>, B<--ratelimit_us=RLIMIT>
-
-Ratelimit attempts to limit the number of schedules per second. It
-sets a minimum amount of time (in microseconds) a VM must run before
-we will allow a higher-priority VM to pre-empt it. The default value
-is 1000 microseconds (1ms). Valid range is 100 to 500000 (500ms).
-The ratelimit length must be lower than the timeslice length.
-
-=item B<-m DELAY>, B<--migration_delay_us=DELAY>
-
-Migration delay specifies for how long a vCPU, after it stopped running should
-be considered "cache-hot". Basically, if less than DELAY us passed since when
-the vCPU was executing on a CPU, it is likely that most of the vCPU's working
-set is still in the CPU's cache, and therefore the vCPU is not migrated.
-
-Default is 0. Maximum is 100 ms. This can be effective at preventing vCPUs
-to bounce among CPUs too quickly, but, at the same time, the scheduler stops
-being fully work-conserving.
-
-=back
-
-B<COMBINATION>
-
-The following is the effect of combining the above options:
-
-=over 4
-
-=item B<E<lt>nothingE<gt>> : List all domain params and sched params from all pools
-
-=item B<-d [domid]> : List domain params for domain [domid]
-
-=item B<-d [domid] [params]> : Set domain params for domain [domid]
-
-=item B<-p [pool]> : list all domains and sched params for [pool]
-
-=item B<-s> : List sched params for poolid 0
-
-=item B<-s [params]> : Set sched params for poolid 0
-
-=item B<-p [pool] -s> : List sched params for [pool]
-
-=item B<-p [pool] -s [params]> : Set sched params for [pool]
-
-=item B<-p [pool] -d>... : Illegal
-
-=back
-
-=item B<sched-credit2> [I<OPTIONS>]
-
-Set or get credit2 scheduler parameters. The credit2 scheduler is a
-proportional fair share CPU scheduler built from the ground up to be
-work conserving on SMP hosts.
-
-Each domain (including Domain0) is assigned a weight.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-d DOMAIN>, B<--domain=DOMAIN>
-
-Specify domain for which scheduler parameters are to be modified or retrieved.
-Mandatory for modifying scheduler parameters.
-
-=item B<-w WEIGHT>, B<--weight=WEIGHT>
-
-A domain with a weight of 512 will get twice as much CPU as a domain
-with a weight of 256 on a contended host. Legal weights range from 1
-to 65535 and the default is 256.
-
-=item B<-p CPUPOOL>, B<--cpupool=CPUPOOL>
-
-Restrict output to domains in the specified cpupool.
-
-=item B<-s>, B<--schedparam>
-
-Specify to list or set pool-wide scheduler parameters.
-
-=item B<-r RLIMIT>, B<--ratelimit_us=RLIMIT>
-
-Attempts to limit the rate of context switching. It is basically the same
-as B<--ratelimit_us> in B<sched-credit>
-
-=back
-
-=item B<sched-rtds> [I<OPTIONS>]
-
-Set or get rtds (Real Time Deferrable Server) scheduler parameters.
-This rt scheduler applies Preemptive Global Earliest Deadline First
-real-time scheduling algorithm to schedule VCPUs in the system.
-Each VCPU has a dedicated period, budget and extratime.
-While scheduled, a VCPU burns its budget.
-A VCPU has its budget replenished at the beginning of each period;
-Unused budget is discarded at the end of each period.
-A VCPU with extratime set gets extra time from the unreserved system resource.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-d DOMAIN>, B<--domain=DOMAIN>
-
-Specify domain for which scheduler parameters are to be modified or retrieved.
-Mandatory for modifying scheduler parameters.
-
-=item B<-v VCPUID/all>, B<--vcpuid=VCPUID/all>
-
-Specify vcpu for which scheduler parameters are to be modified or retrieved.
-
-=item B<-p PERIOD>, B<--period=PERIOD>
-
-Period of time, in microseconds, over which to replenish the budget.
-
-=item B<-b BUDGET>, B<--budget=BUDGET>
-
-Amount of time, in microseconds, that the VCPU will be allowed
-to run every period.
-
-=item B<-e Extratime>, B<--extratime=Extratime>
-
-Binary flag to decide if the VCPU will be allowed to get extra time from
-the unreserved system resource.
-
-=item B<-c CPUPOOL>, B<--cpupool=CPUPOOL>
-
-Restrict output to domains in the specified cpupool.
-
-=back
-
-B<EXAMPLE>
-
-=over 4
-
-1) Use B<-v all> to see the budget and period of all the VCPUs of
-all the domains:
-
- xl sched-rtds -v all
- Cpupool Pool-0: sched=RTDS
- Name ID VCPU Period Budget Extratime
- Domain-0 0 0 10000 4000 yes
- vm1 2 0 300 150 yes
- vm1 2 1 400 200 yes
- vm1 2 2 10000 4000 yes
- vm1 2 3 1000 500 yes
- vm2 4 0 10000 4000 yes
- vm2 4 1 10000 4000 yes
-
-Without any arguments, it will output the default scheduling
-parameters for each domain:
-
- xl sched-rtds
- Cpupool Pool-0: sched=RTDS
- Name ID Period Budget Extratime
- Domain-0 0 10000 4000 yes
- vm1 2 10000 4000 yes
- vm2 4 10000 4000 yes
-
-
-2) Use, for instance, B<-d vm1, -v all> to see the budget and
-period of all VCPUs of a specific domain (B<vm1>):
-
- xl sched-rtds -d vm1 -v all
- Name ID VCPU Period Budget Extratime
- vm1 2 0 300 150 yes
- vm1 2 1 400 200 yes
- vm1 2 2 10000 4000 yes
- vm1 2 3 1000 500 yes
-
-To see the parameters of a subset of the VCPUs of a domain, use:
-
- xl sched-rtds -d vm1 -v 0 -v 3
- Name ID VCPU Period Budget Extratime
- vm1 2 0 300 150 yes
- vm1 2 3 1000 500 yes
-
-If no B<-v> is specified, the default scheduling parameters for the
-domain are shown:
-
- xl sched-rtds -d vm1
- Name ID Period Budget Extratime
- vm1 2 10000 4000 yes
-
-
-3) Users can set the budget and period of multiple VCPUs of a
-specific domain with only one command,
-e.g., "xl sched-rtds -d vm1 -v 0 -p 100 -b 50 -e 1 -v 3 -p 300 -b 150 -e 0".
-
-To change the parameters of all the VCPUs of a domain, use B<-v all>,
-e.g., "xl sched-rtds -d vm1 -v all -p 500 -b 250 -e 1".
-
-=back
-
-=back
-
-=head1 CPUPOOLS COMMANDS
-
-Xen can group the physical cpus of a server in cpu-pools. Each physical CPU is
-assigned at most to one cpu-pool. Domains are each restricted to a single
-cpu-pool. Scheduling does not cross cpu-pool boundaries, so each cpu-pool has
-its own scheduler.
-Physical cpus and domains can be moved from one cpu-pool to another only by an
-explicit command.
-Cpu-pools can be specified either by name or by id.
-
-=over 4
-
-=item B<cpupool-create> [I<OPTIONS>] [I<configfile>] [I<variable=value> ...]
-
-Create a cpu pool based an config from a I<configfile> or command-line
-parameters. Variable settings from the I<configfile> may be altered
-by specifying new or additional assignments on the command line.
-
-See the L<xlcpupool.cfg(5)> manpage for more information.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-f=FILE>, B<--defconfig=FILE>
-
-Use the given configuration file.
-
-=back
-
-=item B<cpupool-list> [I<OPTIONS>] [I<cpu-pool>]
-
-List CPU pools on the host.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-c>, B<--cpus>
-
-If this option is specified, B<xl> prints a list of CPUs used by I<cpu-pool>.
-
-=back
-
-=item B<cpupool-destroy> I<cpu-pool>
-
-Deactivates a cpu pool.
-This is possible only if no domain is active in the cpu-pool.
-
-=item B<cpupool-rename> I<cpu-pool> <newname>
-
-Renames a cpu-pool to I<newname>.
-
-=item B<cpupool-cpu-add> I<cpu-pool> I<cpus|node:nodes>
-
-Adds one or more CPUs or NUMA nodes to I<cpu-pool>. CPUs and NUMA
-nodes can be specified as single CPU/node IDs or as ranges.
-
-For example:
-
- (a) xl cpupool-cpu-add mypool 4
- (b) xl cpupool-cpu-add mypool 1,5,10-16,^13
- (c) xl cpupool-cpu-add mypool node:0,nodes:2-3,^10-12,8
-
-means adding CPU 4 to mypool, in (a); adding CPUs 1,5,10,11,12,14,15
-and 16, in (b); and adding all the CPUs of NUMA nodes 0, 2 and 3,
-plus CPU 8, but keeping out CPUs 10,11,12, in (c).
-
-All the specified CPUs that can be added to the cpupool will be added
-to it. If some CPU can't (e.g., because they're already part of another
-cpupool), an error is reported about each one of them.
-
-=item B<cpupool-cpu-remove> I<cpus|node:nodes>
-
-Removes one or more CPUs or NUMA nodes from I<cpu-pool>. CPUs and NUMA
-nodes can be specified as single CPU/node IDs or as ranges, using the
-exact same syntax as in B<cpupool-cpu-add> above.
-
-=item B<cpupool-migrate> I<domain-id> I<cpu-pool>
-
-Moves a domain specified by domain-id or domain-name into a cpu-pool.
-Domain-0 can't be moved to another cpu-pool.
-
-=item B<cpupool-numa-split>
-
-Splits up the machine into one cpu-pool per numa node.
-
-=back
-
-=head1 VIRTUAL DEVICE COMMANDS
-
-Most virtual devices can be added and removed while guests are
-running, assuming that the necessary support exists in the guest OS. The
-effect to the guest OS is much the same as any hotplug event.
-
-=head2 BLOCK DEVICES
-
-=over 4
-
-=item B<block-attach> I<domain-id> I<disc-spec-component(s)> ...
-
-Create a new virtual block device and attach it to the specified domain.
-A disc specification is in the same format used for the B<disk> variable in
-the domain config file. See L<xl-disk-configuration(5)>. This will trigger a
-hotplug event for the guest.
-
-Note that only PV block devices are supported by block-attach.
-Requests to attach emulated devices (eg, vdev=hdc) will result in only
-the PV view being available to the guest.
-
-=item B<block-detach> I<domain-id> I<devid> [I<OPTIONS>]
-
-Detach a domain's virtual block device. I<devid> may be the symbolic
-name or the numeric device id given to the device by domain 0. You
-will need to run B<xl block-list> to determine that number.
-
-Detaching the device requires the cooperation of the domain. If the
-domain fails to release the device (perhaps because the domain is hung
-or is still using the device), the detach will fail.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<--force>
-
-If this parameter is specified the device will be forcefully detached, which
-may cause IO errors in the domain.
-
-=back
-
-
-
-=item B<block-list> I<domain-id>
-
-List virtual block devices for a domain.
-
-=item B<cd-insert> I<domain-id> I<virtualdevice> I<target>
-
-Insert a cdrom into a guest domain's existing virtual cd drive. The
-virtual drive must already exist but can be empty. How the device should be
-presented to the guest domain is specified by the I<virtualdevice> parameter;
-for example "hdc". Parameter I<target> is the target path in the backend domain
-(usually domain 0) to be exported; can be a block device or a file etc.
-See B<target> in L<xl-disk-configuration(5)>.
-
-Only works with HVM domains.
-
-
-=item B<cd-eject> I<domain-id> I<virtualdevice>
-
-Eject a cdrom from a guest domain's virtual cd drive, specified by
-I<virtualdevice>. Only works with HVM domains.
-
-=back
-
-=head2 NETWORK DEVICES
-
-=over 4
-
-=item B<network-attach> I<domain-id> I<network-device>
-
-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<xl.cfg(5)> and
-L<xl-network-configuration(5)>
-for more information.
-
-Note that only attaching PV network interfaces is supported.
-
-=item B<network-detach> I<domain-id> I<devid|mac>
-
-Removes the network device from the domain specified by I<domain-id>.
-I<devid> is the virtual interface device number within the domain
-(i.e. the 3 in vif22.3). Alternatively, the I<mac> address can be used to
-select the virtual interface to detach.
-
-=item B<network-list> I<domain-id>
-
-List virtual network interfaces for a domain.
-
-=back
-
-=head2 CHANNEL DEVICES
-
-=over 4
-
-=item B<channel-list> I<domain-id>
-
-List virtual channel interfaces for a domain.
-
-=back
-
-=head2 VIRTUAL TRUSTED PLATFORM MODULE (vTPM) DEVICES
-
-=over 4
-
-=item B<vtpm-attach> I<domain-id> I<vtpm-device>
-
-Creates a new vtpm (virtual Trusted Platform Module) device in the domain
-specified by I<domain-id>. I<vtpm-device> describes the device to attach,
-using the same format as the B<vtpm> string in the domain config file.
-See L<xl.cfg(5)> for more information.
-
-=item B<vtpm-detach> I<domain-id> I<devid|uuid>
-
-Removes the vtpm device from the domain specified by I<domain-id>.
-I<devid> is the numeric device id given to the virtual Trusted
-Platform Module device. You will need to run B<xl vtpm-list> to determine that
-number. Alternatively, the I<uuid> of the vtpm can be used to
-select the virtual device to detach.
-
-=item B<vtpm-list> I<domain-id>
-
-List virtual Trusted Platform Modules for a domain.
-
-=back
-
-=head2 VDISPL DEVICES
-
-=over 4
-
-=item B<vdispl-attach> I<domain-id> I<vdispl-device>
-
-Creates a new vdispl device in the domain specified by I<domain-id>.
-I<vdispl-device> describes the device to attach, using the same format as the
-B<vdispl> string in the domain config file. See L<xl.cfg> for
-more information.
-
-B<NOTES>
-
-=over 4
-
-As in I<vdispl-device> string semicolon is used then put quotes or escaping
-when using from the shell.
-
-B<EXAMPLE>
-
-=over 4
-
-xl vdispl-attach DomU connectors='id0:1920x1080;id1:800x600;id2:640x480'
-
-or
-
-xl vdispl-attach DomU connectors=id0:1920x1080\;id1:800x600\;id2:640x480
-
-=back
-
-=back
-
-=item B<vdispl-detach> I<domain-id> I<dev-id>
-
-Removes the vdispl device specified by I<dev-id> from the domain specified by I<domain-id>.
-
-=item B<vdispl-list> I<domain-id>
-
-List virtual displays for a domain.
-
-=back
-
-=head2 VSND DEVICES
-
-=over 4
-
-=item B<vsnd-attach> I<domain-id> I<vsnd-item> I<vsnd-item> ...
-
-Creates a new vsnd device in the domain specified by I<domain-id>.
-I<vsnd-item>'s describe the vsnd device to attach, using the same format as the
-B<VSND_ITEM_SPEC> string in the domain config file. See L<xl.cfg> for
-more information.
-
-B<EXAMPLE>
-
-=over 4
-
-xl vsnd-attach DomU 'CARD, short-name=Main, sample-formats=s16_le;s8;u32_be'
-'PCM, name=Main' 'STREAM, id=0, type=p' 'STREAM, id=1, type=c, channels-max=2'
-
-=back
-
-=item B<vsnd-detach> I<domain-id> I<dev-id>
-
-Removes the vsnd device specified by I<dev-id> from the domain specified by I<domain-id>.
-
-=item B<vsnd-list> I<domain-id>
-
-List vsnd devices for a domain.
-
-=back
-
-=head2 KEYBOARD DEVICES
-
-=over 4
-
-=item B<vkb-attach> I<domain-id> I<vkb-device>
-
-Creates a new keyboard device in the domain specified by I<domain-id>.
-I<vkb-device> describes the device to attach, using the same format as the
-B<VKB_SPEC_STRING> string in the domain config file. See L<xl.cfg(5)>
-for more informations.
-
-=item B<vkb-detach> I<domain-id> I<devid>
-
-Removes the keyboard device from the domain specified by I<domain-id>.
-I<devid> is the virtual interface device number within the domain
-
-=item B<vkb-list> I<domain-id>
-
-List virtual network interfaces for a domain.
-
-=back
-
-=head1 PCI PASS-THROUGH
-
-=over 4
-
-=item B<pci-assignable-list>
-
-List all the assignable PCI devices.
-These are devices in the system which are configured to be
-available for passthrough and are bound to a suitable PCI
-backend driver in domain 0 rather than a real driver.
-
-=item B<pci-assignable-add> I<BDF>
-
-Make the device at PCI Bus/Device/Function BDF assignable to guests.
-This will bind the device to the pciback driver. If it is already
-bound to a driver, it will first be unbound, and the original driver
-stored so that it can be re-bound to the same driver later if desired.
-If the device is already bound, it will return success.
-
-CAUTION: This will make the device unusable by Domain 0 until it is
-returned with pci-assignable-remove. Care should therefore be taken
-not to do this on a device critical to domain 0's operation, such as
-storage controllers, network interfaces, or GPUs that are currently
-being used.
-
-=item B<pci-assignable-remove> [I<-r>] I<BDF>
-
-Make the device at PCI Bus/Device/Function BDF not assignable to guests. This
-will at least unbind the device from pciback. If the -r option is specified,
-it will also attempt to re-bind the device to its original driver, making it
-usable by Domain 0 again. If the device is not bound to pciback, it will
-return success.
-
-=item B<pci-attach> I<domain-id> I<BDF>
-
-Hot-plug a new pass-through pci device to the specified domain.
-B<BDF> is the PCI Bus/Device/Function of the physical device to pass-through.
-
-=item B<pci-detach> [I<OPTIONS>] I<domain-id> I<BDF>
-
-Hot-unplug a previously assigned pci device from a domain. B<BDF> is the PCI
-Bus/Device/Function of the physical device to be removed from the guest domain.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-f>
-
-If this parameter is specified, B<xl> is going to forcefully remove the device
-even without guest domain's collaboration.
-
-=back
-
-=item B<pci-list> I<domain-id>
-
-List pass-through pci devices for a domain.
-
-=back
-
-=head1 USB PASS-THROUGH
-
-=over 4
-
-=item B<usbctrl-attach> I<domain-id> I<usbctrl-device>
-
-Create a new USB controller in the domain specified by I<domain-id>,
-I<usbctrl-device> describes the device to attach, using form
-C<KEY=VALUE KEY=VALUE ...> where B<KEY=VALUE> has the same
-meaning as the B<usbctrl> description in the domain config file.
-See L<xl.cfg(5)> for more information.
-
-=item B<usbctrl-detach> I<domain-id> I<devid>
-
-Destroy a USB controller from the specified domain.
-B<devid> is devid of the USB controller.
-
-=item B<usbdev-attach> I<domain-id> I<usbdev-device>
-
-Hot-plug a new pass-through USB device to the domain specified by
-I<domain-id>, I<usbdev-device> describes the device to attach, using
-form C<KEY=VALUE KEY=VALUE ...> where B<KEY=VALUE> has the same
-meaning as the B<usbdev> description in the domain config file.
-See L<xl.cfg(5)> for more information.
-
-=item B<usbdev-detach> I<domain-id> I<controller=devid> I<port=number>
-
-Hot-unplug a previously assigned USB device from a domain.
-B<controller=devid> and B<port=number> is USB controller:port in the guest
-domain the USB device is attached to.
-
-=item B<usb-list> I<domain-id>
-
-List pass-through usb devices for a domain.
-
-=back
-
-=head1 DEVICE-MODEL CONTROL
-
-=over 4
-
-=item B<qemu-monitor-command> I<domain-id> I<command>
-
-Issue a monitor command to the device model of the domain specified by
-I<domain-id>. I<command> can be any valid command qemu understands. This
-can be e.g. used to add non-standard devices or devices with non-standard
-parameters to a domain. The output of the command is printed to stdout.
-
-B<Warning:> This qemu monitor access is provided for convenience when
-debugging, troubleshooting, and experimenting. Its use is not
-supported by the Xen Project.
-
-Specifically, not all information displayed by the qemu monitor will
-necessarily be accurate or complete, because in a Xen system qemu
-does not have a complete view of the guest.
-
-Furthermore, modifying the guest's setup via the qemu monitor may
-conflict with the Xen toolstack's assumptions. Resulting problems
-may include, but are not limited to: guest crashes; toolstack error
-messages; inability to migrate the guest; and security
-vulnerabilities which are not covered by the Xen Project security
-response policy.
-
-B<EXAMPLE>
-
-Obtain information of USB devices connected as such via the device model
-(only!) to a domain:
-
- xl qemu-monitor-command vm1 'info usb'
- Device 0.2, Port 5, Speed 480 Mb/s, Product Mass Storage
-
-=back
-
-=head1 TRANSCENDENT MEMORY (TMEM)
-
-=over 4
-
-=item B<tmem-list> I<[OPTIONS]> I<domain-id>
-
-List tmem pools.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-l>
-
-If this parameter is specified, also list tmem stats.
-
-=back
-
-=item B<tmem-freeze> I<domain-id>
-
-Freeze tmem pools.
-
-=item B<tmem-thaw> I<domain-id>
-
-Thaw tmem pools.
-
-=item B<tmem-set> I<domain-id> [I<OPTIONS>]
-
-Change tmem settings.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-w> I<WEIGHT>
-
-Weight (int)
-
-=item B<-p> I<COMPRESS>
-
-Compress (int)
-
-=back
-
-=item B<tmem-shared-auth> I<domain-id> [I<OPTIONS>]
-
-De/authenticate shared tmem pool.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-u> I<UUID>
-
-Specify uuid (abcdef01-2345-6789-1234-567890abcdef)
-
-=item B<-a> I<AUTH>
-
-0=auth,1=deauth
-
-=back
-
-=item B<tmem-freeable>
-
-Get information about how much freeable memory (MB) is in-use by tmem.
-
-=back
-
-=head1 FLASK
-
-B<FLASK> is a security framework that defines a mandatory access control policy
-providing fine-grained controls over Xen domains, allowing the policy writer
-to define what interactions between domains, devices, and the hypervisor are
-permitted. Some example of what you can do using XSM/FLASK:
- - Prevent two domains from communicating via event channels or grants
- - Control which domains can use device passthrough (and which devices)
- - Restrict or audit operations performed by privileged domains
- - Prevent a privileged domain from arbitrarily mapping pages from other
- domains.
-
-You can find more details on how to use FLASK and an example security
-policy here: L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
-
-=over 4
-
-=item B<getenforce>
-
-Determine if the FLASK security module is loaded and enforcing its policy.
-
-=item B<setenforce> I<1|0|Enforcing|Permissive>
-
-Enable or disable enforcing of the FLASK access controls. The default is
-permissive, but this can be changed to enforcing by specifying "flask=enforcing"
-or "flask=late" on the hypervisor's command line.
-
-=item B<loadpolicy> I<policy-file>
-
-Load FLASK policy from the given policy file. The initial policy is provided to
-the hypervisor as a multiboot module; this command allows runtime updates to the
-policy. Loading new security policy will reset runtime changes to device labels.
-
-=back
-
-=head1 PLATFORM SHARED RESOURCE MONITORING/CONTROL
-
-Intel Haswell and later server platforms offer shared resource monitoring
-and control technologies. The availability of these technologies and the
-hardware capabilities can be shown with B<psr-hwinfo>.
-
-See L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html> for more
-information.
-
-=over 4
-
-=item B<psr-hwinfo> [I<OPTIONS>]
-
-Show Platform Shared Resource (PSR) hardware information.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-m>, B<--cmt>
-
-Show Cache Monitoring Technology (CMT) hardware information.
-
-=item B<-a>, B<--cat>
-
-Show Cache Allocation Technology (CAT) hardware information.
-
-=back
-
-=back
-
-=head2 CACHE MONITORING TECHNOLOGY
-
-Intel Haswell and later server platforms offer monitoring capability in each
-logical processor to measure specific platform shared resource metric, for
-example, L3 cache occupancy. In the Xen implementation, the monitoring
-granularity is domain level. To monitor a specific domain, just attach the
-domain id with the monitoring service. When the domain doesn't need to be
-monitored any more, detach the domain id from the monitoring service.
-
-Intel Broadwell and later server platforms also offer total/local memory
-bandwidth monitoring. Xen supports per-domain monitoring for these two
-additional monitoring types. Both memory bandwidth monitoring and L3 cache
-occupancy monitoring share the same set of underlying monitoring service. Once
-a domain is attached to the monitoring service, monitoring data can be shown
-for any of these monitoring types.
-
-There is no cache monitoring and memory bandwidth monitoring on L2 cache so
-far.
-
-=over 4
-
-=item B<psr-cmt-attach> I<domain-id>
-
-attach: Attach the platform shared resource monitoring service to a domain.
-
-=item B<psr-cmt-detach> I<domain-id>
-
-detach: Detach the platform shared resource monitoring service from a domain.
-
-=item B<psr-cmt-show> I<psr-monitor-type> [I<domain-id>]
-
-Show monitoring data for a certain domain or all domains. Current supported
-monitor types are:
- - "cache-occupancy": showing the L3 cache occupancy(KB).
- - "total-mem-bandwidth": showing the total memory bandwidth(KB/s).
- - "local-mem-bandwidth": showing the local memory bandwidth(KB/s).
-
-=back
-
-=head2 CACHE ALLOCATION TECHNOLOGY
-
-Intel Broadwell and later server platforms offer capabilities to configure and
-make use of the Cache Allocation Technology (CAT) mechanisms, which enable more
-cache resources (i.e. L3/L2 cache) to be made available for high priority
-applications. In the Xen implementation, CAT is used to control cache allocation
-on VM basis. To enforce cache on a specific domain, just set capacity bitmasks
-(CBM) for the domain.
-
-Intel Broadwell and later server platforms also offer Code/Data Prioritization
-(CDP) for cache allocations, which support specifying code or data cache for
-applications. CDP is used on a per VM basis in the Xen implementation. To
-specify code or data CBM for the domain, CDP feature must be enabled and CBM
-type options need to be specified when setting CBM, and the type options (code
-and data) are mutually exclusive. There is no CDP support on L2 so far.
-
-=over 4
-
-=item B<psr-cat-set> [I<OPTIONS>] I<domain-id> I<cbm>
-
-Set cache capacity bitmasks(CBM) for a domain. For how to specify I<cbm>
-please refer to L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-s SOCKET>, B<--socket=SOCKET>
-
-Specify the socket to process, otherwise all sockets are processed.
-
-=item B<-l LEVEL>, B<--level=LEVEL>
-
-Specify the cache level to process, otherwise the last level cache (L3) is
-processed.
-
-=item B<-c>, B<--code>
-
-Set code CBM when CDP is enabled.
-
-=item B<-d>, B<--data>
-
-Set data CBM when CDP is enabled.
-
-=back
-
-=item B<psr-cat-show> [I<OPTIONS>] [I<domain-id>]
-
-Show CAT settings for a certain domain or all domains.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-l LEVEL>, B<--level=LEVEL>
-
-Specify the cache level to process, otherwise the last level cache (L3) is
-processed.
-
-=back
-
-=back
-
-=head2 Memory Bandwidth Allocation
-
-Intel Skylake and later server platforms offer capabilities to configure and
-make use of the Memory Bandwidth Allocation (MBA) mechanisms, which provides
-OS/VMMs the ability to slow misbehaving apps/VMs by using a credit-based
-throttling mechanism. In the Xen implementation, MBA is used to control memory
-bandwidth on VM basis. To enforce bandwidth on a specific domain, just set
-throttling value (THRTL) for the domain.
-
-=over 4
-
-=item B<psr-mba-set> [I<OPTIONS>] I<domain-id> I<thrtl>
-
-Set throttling value (THRTL) for a domain. For how to specify I<thrtl>
-please refer to L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>.
-
-B<OPTIONS>
-
-=over 4
-
-=item B<-s SOCKET>, B<--socket=SOCKET>
-
-Specify the socket to process, otherwise all sockets are processed.
-
-=back
-
-=item B<psr-mba-show> [I<domain-id>]
-
-Show MBA settings for a certain domain or all domains. For linear mode, it
-shows the decimal value. For non-linear mode, it shows hexadecimal value.
-
-=back
-
-=head1 IGNORED FOR COMPATIBILITY WITH XM
-
-xl is mostly command-line compatible with the old xm utility used with
-the old Python xend. For compatibility, the following options are
-ignored:
-
-=over 4
-
-=item B<xl migrate --live>
-
-=back
-
-=head1 TO BE DOCUMENTED
-
-We need better documentation for:
-
-=over 4
-
-=item B<tmem>
-
-Transcendent Memory.
-
-=back
-
-=head1 SEE ALSO
-
-The following man pages:
-
-L<xl.cfg>(5), L<xlcpupool.cfg>(5), L<xentop>(1), L<xl-disk-configuration(5)>
-L<xl-network-configuration(5)>
-
-And the following documents on the xen.org website:
-
-L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
-L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
-
-For systems that don't automatically bring the CPU online:
-
-L<http://wiki.xen.org/wiki/Paravirt_Linux_CPU_Hotplug>
-
-=head1 BUGS
-
-Send bugs to xen-devel@lists.xen.org, see
-http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
--- /dev/null
+=head1 NAME
+
+xlcpupool.cfg - XL Cpupool Configuration File Syntax
+
+=head1 SYNOPSIS
+
+ /etc/xen/xlcpupool
+
+=head1 DESCRIPTION
+
+To create a Cpupool with xl requires the provision of a cpupool config
+file. Typically these live in `/etc/xen/CPUPOOL.cfg` where CPUPOOL is
+the name of the cpupool.
+
+=head1 SYNTAX
+
+A cpupool config file consists of a series of C<KEY=VALUE> pairs.
+
+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<[ 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 cpupool:
+
+=over 4
+
+=item B<name="NAME">
+
+Specifies the name of the cpupool. Names of cpupools existing on a
+single host must be unique.
+
+=back
+
+=head2 Optional Configuration Items
+
+The following options apply to guests of any type.
+
+=over 4
+
+=item B<sched="SCHED">
+
+Specifies the scheduler which is used for the cpupool. Valid
+values for C<SCHED> are:
+
+=over 4
+
+=item B<credit>
+
+the credit scheduler
+
+=item B<credit2>
+
+the credit2 scheduler
+
+=item B<rtds>
+
+the RTDS scheduler
+
+=back
+
+The default scheduler is the one used for C<Pool-0> specified as
+boot parameter of the hypervisor.
+
+=item B<nodes="NODES">
+
+Specifies the cpus of the NUMA-nodes given in C<NODES> (an integer or
+a list of integers) to be member of the cpupool. The free cpus in the
+specified nodes are allocated in the new cpupool.
+
+=item B<cpus="CPU-LIST">
+
+Specifies the cpus that will be member of the cpupool. All the specified
+cpus must be free, or creation will fail. C<CPU-LIST> may be specified
+as follows:
+
+=over 4
+
+=item ["2", "3", "5"]
+
+means that cpus 2,3,5 will be member of the cpupool.
+
+=item "0-3,5,^1"
+
+means that cpus 0,2,3 and 5 will be member of the cpupool. A "node:" or
+"nodes:" modifier can be used. E.g., "0,node:1,nodes:2-3,^10-13" means
+that pcpus 0, plus all the cpus of NUMA nodes 1,2,3 with the exception
+of cpus 10,11,12,13 will be memeber of the cpupool.
+
+=back
+
+If neither B<nodes> nor B<cpus> are specified only the first free cpu
+found will be allocated in the new cpupool.
+
+=back
+
+=head1 FILES
+
+F</etc/xen/CPUPOOL.cfg>
+
+=head1 BUGS
+
+This document is a work in progress and contains items which require
+further documentation and which are generally incomplete (marked with
+XXX). However all options are included here whether or not they are
+fully documented.
+
+Patches to improve incomplete items (or any other item) would be
+gratefully received on the xen-devel@lists.xen.org mailing
+list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
+information on how to submit a patch to Xen.
+
+++ /dev/null
-=head1 NAME
-
-xlcpupool.cfg - XL Cpupool Configuration File Syntax
-
-=head1 SYNOPSIS
-
- /etc/xen/xlcpupool
-
-=head1 DESCRIPTION
-
-To create a Cpupool with xl requires the provision of a cpupool config
-file. Typically these live in `/etc/xen/CPUPOOL.cfg` where CPUPOOL is
-the name of the cpupool.
-
-=head1 SYNTAX
-
-A cpupool config file consists of a series of C<KEY=VALUE> pairs.
-
-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<[ 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 cpupool:
-
-=over 4
-
-=item B<name="NAME">
-
-Specifies the name of the cpupool. Names of cpupools existing on a
-single host must be unique.
-
-=back
-
-=head2 Optional Configuration Items
-
-The following options apply to guests of any type.
-
-=over 4
-
-=item B<sched="SCHED">
-
-Specifies the scheduler which is used for the cpupool. Valid
-values for C<SCHED> are:
-
-=over 4
-
-=item B<credit>
-
-the credit scheduler
-
-=item B<credit2>
-
-the credit2 scheduler
-
-=item B<rtds>
-
-the RTDS scheduler
-
-=back
-
-The default scheduler is the one used for C<Pool-0> specified as
-boot parameter of the hypervisor.
-
-=item B<nodes="NODES">
-
-Specifies the cpus of the NUMA-nodes given in C<NODES> (an integer or
-a list of integers) to be member of the cpupool. The free cpus in the
-specified nodes are allocated in the new cpupool.
-
-=item B<cpus="CPU-LIST">
-
-Specifies the cpus that will be member of the cpupool. All the specified
-cpus must be free, or creation will fail. C<CPU-LIST> may be specified
-as follows:
-
-=over 4
-
-=item ["2", "3", "5"]
-
-means that cpus 2,3,5 will be member of the cpupool.
-
-=item "0-3,5,^1"
-
-means that cpus 0,2,3 and 5 will be member of the cpupool. A "node:" or
-"nodes:" modifier can be used. E.g., "0,node:1,nodes:2-3,^10-13" means
-that pcpus 0, plus all the cpus of NUMA nodes 1,2,3 with the exception
-of cpus 10,11,12,13 will be memeber of the cpupool.
-
-=back
-
-If neither B<nodes> nor B<cpus> are specified only the first free cpu
-found will be allocated in the new cpupool.
-
-=back
-
-=head1 FILES
-
-F</etc/xen/CPUPOOL.cfg>
-
-=head1 BUGS
-
-This document is a work in progress and contains items which require
-further documentation and which are generally incomplete (marked with
-XXX). However all options are included here whether or not they are
-fully documented.
-
-Patches to improve incomplete items (or any other item) would be
-gratefully received on the xen-devel@lists.xen.org mailing
-list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
-information on how to submit a patch to Xen.
-
projects / people / sstabellini / xen-unstable.git / .git / commitdiff