This document attempts to defines all the paths which are in common use by either guests, front-/back-end drivers, toolstacks etc.
The XenStore wire protocol itself is described in xenstore.txt.
This document is intended to be partially machine readable, such that test system etc can use it to validate whether the xenstore paths used by a test are allowable etc.
Therefore the following notation conventions apply:
A xenstore path is generically defined as:
PATH = VALUES [TAGS]
PATH/* [TAGS]
The first syntax defines a simple path with a single value. The second syntax defines an aggregated set of paths which are usually described externally to this document. The text will give a pointer to the appropriate external documentation.
PATH can contain simple regex constructs following the Perl compatible regexp syntax described in pcre(3) or perlre(1). In addition the following additional wild card names are defined and are evaluated before regexp expansion:
VALUES are strings and can take the following forms:
DISTRIBUTION -- information about a software distribution, comprised of 3 or 4 space separated UTF-8 strings as follows:
VENDOR -- Commonly used vendor short name,
e.g "Citrix" rather than "Citrix Systems
Inc."
PRODUCT -- Commonly used product (e.g. driver) name
without version information.
If the toolstack needs to match on either of the above
values it should support Unix glob style matching.
VERSION -- A version number that will sort properly
under coreutils version sorting (sort -V)
rules.
ATTRIBUTES -- Optional human readable text to denote
attributes of the software, e.g. "debug".
This text is freeform and no meaning
should be inferred. It is intended for
display purposes only.
MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':', specifying an IEEE 802.3 ethernet MAC address.
Additional TAGS may follow as a comma separated set of the following tags enclosed in square brackets.
Owning domain means the domain whose home path this tag is found under.
Lack of either a HVM or PV tag indicates that the path is valid for either type of domain (including PVonHVM and similar mixed domain types).
Every domain has a home path within the xenstore hierarchy. This is the path where the majority of the domain-visible information about each domain is stored.
This path is:
/local/domain/$DOMID
All non-absolute paths are relative to this path.
Although this path could be considered a "Home Directory" for the domain it would not usually be writable by the domain. The tools will create writable subdirectories as necessary.
A pointer back to the domain's /vm/$UUID path (described below).
The guests name.
The domain's own ID.
The process ID of the device model associated with this domain, if it has one.
One node for each virtual CPU up to the guest's configured maximum. Valid values are "online" and "offline". The guest is expected to react to changes in this path by bringing the appropriate VCPU on or offline using the VCPUOP interface described in xen/include/public/vcpu.h
This protocol is not currently well documented.
Specifies a static maximum amount memory which this domain should expect to be given. In the absence of in-guest memory hotplug support this set on domain boot and is usually the maximum amount of RAM which a guest can make use of. See docs/misc/libxl_memory.txt for a description of how memory is accounted for in toolstacks using the libxl library.
The current balloon target for the domain. The balloon driver within the guest is expected to make every effort to every effort use no more than this amount of RAM.
The size of the video RAM this domain is configured with.
The domain's suspend event channel. The toolstack will create this path with an empty value which the guest may choose to overwrite.
If the guest overwrites this, it will be with the number of an unbound event channel port it has acquired. The toolstack is expected to use an interdomain bind, and then, when it wishes to ask the guest to suspend, to signal the event channel.
The guest does not need to explicitly acknowledge the request; indeed,
there is no explicit signalling by the guest in the reverse direction.
The guest, when it is ready, simply shuts down (SCHEDOP_shutdown)
with reason code SHUTDOWN_suspend. The toolstack is expected to use
XEN_DOMCTL_subscribe to be alerted to guest state changes, and
XEN_SYSCTL_getdomaininfolist to verify that the domain has
suspended.
Note that the use of this event channel suspend protocol is optional for both sides. By writing a non-empty string to the node, the guest is advertising its support. However, the toolstack is at liberty to use the xenstore-based protocol instead (see ~/control/shutdown, below) even if the guest has advertised support for the event channel protocol.
If the default low MMIO hole (below 4GiB) is not big enough for all the devices, this indicates if hvmloader should relocate guest memory into the high memory region (above 4GiB). If "1", hvmloader will relocate memory as needed, until 2GiB is reached; if "0", hvmloader will not relocate guest memory.
The BIOS used by this domain.
Various boolean platform properties.
The lower and upper 64-bit words of the 128-bit VM Generation ID.
This key is used by hvmloader to create the ACPI VM Generation ID device. It initialises a 16 octet region of guest memory with this value. The guest physical address of this region is saved in the HVMPARAMVMGENERATIONID_ADDR HVM parameter.
If this key is not present, is empty, or is all-zeros ("0:0") then the ACPI device is not created.
When restoring a guest, the toolstack may (in certain circumstances) need generate a new random generation ID and write it to guest memory at the guest physical address in HVMPARAMVMGENERATIONID_ADDR.
See Microsoft's "Virtual Machine Generation ID" specification for the circumstances where the generation ID needs to be changed.
Paravirtual device frontends are generally specified by their own directory within the XenStore hierarchy. Usually this is under ~/device/$TYPE/$DEVID although there are exceptions, e.g. ~/console for the first PV console.
A virtual block device frontend. Described by xen/include/public/io/blkif.h
A virtual framebuffer frontend. Described by xen/include/public/io/fbif.h
A virtual keyboard device frontend. Described by xen/include/public/io/kbdif.h
A virtual network device frontend. Described by xen/include/public/io/netif.h
A virtual scsi device frontend. Described by xen/include/public/io/vscsiif.h
A virtual usb device frontend. Described by xen/include/public/io/usbif.h
The primary PV console device. Described in console.txt
A secondary PV console device. Described in console.txt
An emulated serial device. Described in console.txt
The event channel used by the domain's connection to XenStore.
This path is deprecated since the same information is provided via the start_info for PV guests and as an HVM param for HVM guests. There is an obvious chicken and egg problem with extracting this value from xenstore in order to setup the xenstore communication ring.
The grant reference of the domain's XenStore ring.
As with ~/store/port this path is deprecated.
Paravirtual device backends are generally specified by their own directory within the XenStore hierarchy. Usually this is under ~/backend/$TYPE/$DOMID/$DEVID.
A virtual block device backend. Described by xen/include/public/io/blkif.h
Uses the in-kernel blkback driver.
A virtual block device backend. Described by xen/include/public/io/blkif.h
Uses the qemu based disk backend.
A virtual block device backend. Described by xen/include/public/io/blkif.h
Uses the in-kernel blktap (v1) disk backend (deprecated).
A virtual framebuffer backend. Described by xen/include/public/io/fbif.h
A virtual keyboard device backend. Described by xen/include/public/io/kbdif.h
A virtual network device backend. Described by xen/include/public/io/netif.h
A PV SCSI backend.
A PV USB backend. Described by xen/include/public/io/usbif.h
A PV console backend. Described in console.txt
A PV USB device backend. Described by xen/include/public/io/usbif.h
Uses the qemu based USB backend.
Information relating to device models running in the domain. $DOMID is the target domain of the device model.
Indicates whether device hotplug scripts in this domain should be run by udev ("0") or will be run by the toolstack directly ("1").
This is the PV shutdown control node. A toolstack can write various commands here to cause various guest shutdown, reboot or suspend activities. The guest acknowledges a request by writing the empty string back to the command node.
The precise protocol is not yet documented.
These may be initialized to "" by the toolstack and may then be set to 0 or 1 by a guest to indicate whether it is capable or incapable, respectively, of responding to the corresponding command when written to ~/control/shutdown. A toolstack may then sample the feature- value at the point of issuing a PV control command and respond accordingly:
"0" -> the frontend should not be expected to respond, so fail the control operation "1" -> the frontend should be expected to respond, so wait for it to do so and maybe fail the control operation after some reasonable timeout. "" -> the frontend may or may not respond, so wait for it to do so and then maybe try an alternative control mechanism after some reasonable timeout.
Since a toolstack may not initialize these paths, and the parent ~/control path is read-only to a guest, a guest should not expect a write to succeed. If it fails the guest may log the failure but should continue to process the corresponding command when written to ~/control/shutdown regardless.
These purpose of these feature flags is identical to feature-poweroff, feature-reboot and feature-suspend above but concern triggering the S3 or S4 power states of HVM guests. A toolstack may create these values, but should not sample them unless the corresponding acpi_ feature flag is set in ~/platform.
Indicates to the guest that this platform supports the multiprocessor suspend feature.
Indicates to the guest that this platform supports the XSRESETWATCHES xenstore message. See xen/include/public/io/xs_wire.h for the XenStore wire protocol definition.
A domain writable path. Available for arbitrary domain use.
A domain may write information about installed PV drivers using paths of this form.
By setting these paths to "1" a guest can indicate to a toolstack that it is capable of responding immediately to instantiation of, respectively, new vif by bringing online a new PV network device or a new vbd by bringing online a new PV block device. If the guest sets this path to "0" then it is indicating that it is definitely unable to respond immediately and hence the toolstack should defer instantiaton to the next VM start. However, if the path is absent then the toolstack may attempt the operation.
A domain may write its internal 'friendly' name for a network device using this path using UTF-8 encoding. A toolstack or UI may use this for display purposes. No particular meaning should be inferred from the name.
Paths of this form may be written by the guest to indicate MAC addresses it is currently using. These may be multicast or unicast addresses. For any of the paths the value of $INDEX is arbitrary. The values written are primarily for display purposes and must not be used for packet filtering or routing purposes.
Paths of this form may be written by the guest to indicate IP addresses in use by the stack bound to the network frontend. For any of the paths the value of $INDEX is arbitrary. The values written are primarily for display purposes and must not be used for packet filtering or routing purposes. A toolstack may attempt to use an address written in one of these paths to, for example, establish a VNC session to the guest (although clearly some level of trust is placed in the value supplied by the guest in this case).
Contains the status of the device models running on the domain.
Backend types the device model is supporting. Each entry below backends is a directory which may contain further nodes specific to the backend type. The name of each backend directory is the same as the backend type (e.g. "qdisk").
Contains the PIDs of the device models running on the domain.
The /vm/$UUID namespace is used by toolstacks to store various information relating to the domain which is not intended to be guest visible (hence they are all tagged [n,INTERNAL]).
Several of the keys here are not well defined and/or not well located and are liable to be replaced with more fully defined paths in the future.
Value is the same UUID as the path.
The domain's name.
Various information relating to the domain builder used for this guest.
The time which the guest was started in SECONDS.MICROSECONDS format
The guest's virtual time offset from UTC in seconds.
Created by libxl for every frontend/backend pair created for $DOMID. Used by libxl for enumeration and management of the device.
Path in xenstore to the frontend, normally /local/domain/$DOMID/device/$KIND/$DEVID
Path in xenstore to the backend, normally /local/domain/$BACKEND_DOMID/backend/$KIND/$DOMID/$DEVID
Trustworthy copy of /local/domain/$DOMID/backend/$KIND/$DEVID/$NODE.
The device model version for a domain.
ifb device used by Remus to buffer network output from the associated vif.
The /tool/xenstored namespace is created by the xenstore daemon or domain for the toolstack to obtain e.g. the domain id of a xenstore domain.
Domain Id of the xenstore domain in case xenstore is provided via a domain instead of a daemon in dom0.