This is based upon my inspection of a system with a single PV domain
and a single HVM domain running and is therefore very incomplete.
Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
---
In v2:
- Fold in HVM patch.
- Address review feedback from Ian Jackson.
- Moved libxl_memory.txt from tools/libxl to docs/misc. Noone can
ever find it in its current home and it is easier to refer to
here (and this patch now does)
- Mark various paths as INTERNAL or DEPRECATED plus introduce "n"
(following xs perms notation) to indicate that a path is not guest
readable.
- Various clarifications and cross-referencing.
- Typos
---
docs/INDEX | 1 +
docs/misc/libxl_memory.txt | 70 ++++++++
docs/misc/xenstore-paths.markdown | 353 +++++++++++++++++++++++++++++++++++++
tools/libxl/libxl_memory.txt | 70 --------
4 files changed, 424 insertions(+), 70 deletions(-)
create mode 100644 docs/misc/libxl_memory.txt
delete mode 100644 tools/libxl/libxl_memory.txt
diff --git a/docs/INDEX b/docs/INDEX
index 5a0a2c2..f5ccae2 100644
--- a/docs/INDEX
+++ b/docs/INDEX
@@ -12,6 +12,7 @@ misc/kexec_and_kdump Kexec and Kdump for Xen
misc/tscmode TSC Mode HOWTO
misc/vbd-interface Xen Guest Disk (VBD) Interface
misc/xenstore Xenstore protocol specification
+misc/xenstore-paths Xenstore path documentation
misc/xl-disk-configuration XL Disk Configuration
misc/xl-network-configuration XL Network Configuration
misc/distro_mapping Distro Directory Layouts
diff --git a/docs/misc/libxl_memory.txt b/docs/misc/libxl_memory.txt
new file mode 100644
index 0000000..253476d
--- /dev/null
+++ b/docs/misc/libxl_memory.txt
@@ -0,0 +1,70 @@
+/* === Domain memory breakdown: HVM guests =================================+
+ + +----------+ +
+ | | shadow | |
+ | +----------+ |
+ overhead | | extra | |
+ | | external | |
+ | +----------+ + |
+ | | extra | | |
+ | | internal | | |
+ + +----------+ + | | footprint
+ | | video | | | |
+ | +----------+ + + | | xen |
+ | | | | | | actual | maximum |
+ | | | | | | target | |
+ | | guest | | | build | | |
+ | | | | | start | | |
+ static | | | | | | | |
+ maximum | +----------+ | + + + +
+ | | | |
+ | | | |
+ | | balloon | | build
+ | | | | maximum
+ | | | |
+ + +----------+ +
+
+
+ extra internal = LIBXL_MAXMEM_CONSTANT
+ extra external = LIBXL_HVM_EXTRA_MEMORY
+ shadow = libxl_domain_build_info.shadow_memkb
+ static maximum = libxl_domain_build_info.max_memkb
+ video = libxl_domain_build_info.video_memkb
+ build start = libxl_domain_build_info.target_memkb
+ libxl_domain_setmaxmem -> xen maximum
+ libxl_set_memory_target -> actual target
+
+
+ === Domain memory breakdown: PV guests =================================+
+
+ + +----------+ +
+ overhead | | extra | |
+ | | external | |
+ | +----------+ + |
+ | | extra | | |
+ | | internal | | |
+ + +----------+ + + + | | footprint
+ | | | | | | | xen |
+ | | | | | | actual | maximum |
+ | | guest | | | build | target | |
+ | | | | | start | | |
+ static | | | | | | | |
+ maximum | +----------+ | + + + +
+ | | | |
+ | | | |
+ | | balloon | | build
+ | | | | maximum
+ | | | |
+ + +----------+ +
+
+
+ extra internal = LIBXL_MAXMEM_CONSTANT
+ extra external = LIBXL_PV_EXTRA_MEMORY
+ static maximum = libxl_domain_build_info.max_memkb
+ build start = libxl_domain_build_info.target_memkb
+ libxl_domain_setmaxmem -> xen maximum
+ libxl_set_memory_target -> actual target
+
+
+ ========================================================================= */
diff --git a/docs/misc/xenstore-paths.markdown
b/docs/misc/xenstore-paths.markdown
index e69de29..09e551b 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -0,0 +1,353 @@
+# XenStore Paths
+
+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](xenstore.txt).
+
+## Notation
+
+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:
+
+* ~ -- expands to an arbitrary a domain''s home path (described below).
+ Only valid at the begining of a path.
+* $DEVID -- a per-device type device identifier. Typically an integer.
+* $DOMID -- a domain identifier, an integer. Typically this refers to
+ the "other" domain. i.e. ~ refers to the domain providing a service
+ while $DOMID is the consumer of that service.
+* $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+
+VALUES are strings and can take the following forms:
+
+* PATH -- a XenStore path.
+* STRING -- an arbitrary string.
+* INTEGER -- An integer, in decimal representation unless otherwise
+ noted.
+ * MEMKB -- the decimal representation of a number of kilobytes.
+ * EVTCHN -- the decimal representation of an event channel.
+ * GNTREF -- the decimal representation of a grant reference.
+* "a literal string" -- literal strings are contained within quotes.
+* (VALUE | VALUE | ... ) -- a set of alternatives. Alternatives are
+ separated by a "|" and all the alternatives are enclosed in
"(" and
+ ")".
+
+Additional TAGS may follow as a comma separated set of the following
+tags enclosed in square brackets.
+
+* w -- Path is writable by the containing domain, that is the domain
+ whose home path ~ this key is under or which /vm/$UUID refers to. By
+ default paths under both of these locations are read only for the
+ domain.
+* n -- Path is neither readable nor writeable for guest domains.
+* HVM -- Path is valid for HVM domains only
+* PV -- Path is valid for PV domains only
+* BACKEND -- Path is valid for a backend domain (AKA driver domain)
+* INTERNAL -- Although a path is visible to the domain its use is
+ reserved for the virtual firmware or Xen platform code. Guest
+ Operating Systems must not read this key or otherwise rely on its
+ presence or contents.
+* DEPRECATED -- This path is deprecated and may be removed in its
+ current form in the future. Guests should not add new dependencies
+ on such paths.
+
+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).
+
+## Domain Home Path
+
+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.
+
+## Per Domain Paths
+
+## General Paths
+
+#### ~/vm = PATH []
+
+A pointer back to the domain''s /vm/$UUID path (described below).
+
+#### ~/name = STRING []
+
+The guests name.
+
+#### ~/domid = INTEGER []
+
+The domain''s own ID.
+
+#### ~/image/device-model-pid = INTEGER [INTERNAL]
+
+The process ID of the device model associated with this domain, if it
+has one.
+
+#### ~/cpu/[0-9]+/availability = ("online"|"offline") [PV]
+
+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][VCPU]
+
+This protocol is not currently well documented.
+
+#### ~/memory/static-max = MEMKB []
+
+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][LIBXLMEM]
+for a description of how memory is accounted for in toolstacks using
+the libxl library.
+
+#### ~/memory/target = MEMKB []
+
+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.
+
+#### ~/memory/videoram = MEMKB [HVM,INTERNAL]
+
+The size of the video RAM this domain is configured with.
+
+#### ~/device/suspend/event-channel = ""|EVTCHN [w]
+
+The domain''s suspend event channel. The use of a suspend event channel
+is optional at the domain''s discretion. The toolstack will create this
+path with an empty value which the guest may choose to overwrite.
+
+#### ~/hvmloader/generation-id-address = ADDRESS [r,HVM,INTERNAL]
+
+The hexadecimal representation of the address of the domain''s
+"generation id".
+
+#### ~/hvmloader/bios =
("rombios"|"seabios"|"OVMF") [HVM,INTERNAL]
+
+The BIOS used by this domain.
+
+#### ~/platform/* [HVM,INTERNAL]
+
+Various platform properties.
+
+* acpi -- is ACPI enabled for this domain
+* acpi_s3 -- is ACPI S3 support enabled for this domain
+* acpi_s4 -- is ACPI S4 support enabled for this domain
+
+### Frontend device paths
+
+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.
+
+#### ~/device/vbd/$DEVID/* []
+
+A virtual block device frontend. Described by
+[xen/include/public/io/blkif.h][BLKIF]
+
+#### ~/device/vfb/$DEVID/* []
+
+A virtual framebuffer frontend. Described by
+[xen/include/public/io/fbif.h][FBIF]
+
+#### ~/device/vkbd/$DEVID/* []
+
+A virtual keyboard device frontend. Described by
+[xen/include/public/io/kbdif.h][KBDIF]
+
+#### ~/device/vif/$DEVID/* []
+
+A virtual network device frontend. Described by
+[xen/include/public/io/netif.h][NETIF]
+
+#### ~/console/* []
+
+The primary PV console device. Described in [console.txt](console.txt)
+
+#### ~/device/console/$DEVID/* []
+
+A secondary PV console device. Described in [console.txt](console.txt)
+
+#### ~/device/serial/$DEVID/* [HVM]
+
+An emulated serial device. Described in [console.txt](console.txt)
+
+#### ~/store/port = EVTCHN [DEPRECATED]
+
+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][SI] for PV guests and as an [HVM param][HVMPARAMS] 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.
+
+#### ~/store/ring-ref = GNTREF [DEPRECATED]
+
+The grant reference of the domain''s XenStore ring.
+
+As with ~/store/port this path is deprecated.
+
+### Backend Device Paths
+
+Paravirtual device backends are generally specified by their own
+directory within the XenStore hierarchy. Usually this is under
+~/backend/$TYPE/$DOMID/$DEVID.
+
+#### ~/backend/vbd/$DOMID/$DEVID/* []
+
+A virtual block device backend. Described by
+[xen/include/public/io/blkif.h][BLKIF]
+
+Uses the in-kernel blkback driver.
+
+#### ~/backend/qdisk/$DOMID/$DEVID/* []
+
+A virtual block device backend. Described by
+[xen/include/public/io/blkif.h][BLKIF]
+
+Uses the qemu based disk backend.
+
+#### ~/backend/tap/$DOMID/$DEVID/* []
+
+A virtual block device backend. Described by
+[xen/include/public/io/blkif.h][BLKIF]
+
+Uses the in-kernel blktap (v1) disk backend (deprecated).
+
+#### ~/backend/vfb/$DOMID/$DEVID/* []
+
+A virtual framebuffer backend. Described by
+[xen/include/public/io/fbif.h][FBIF]
+
+#### ~/backend/vkbd/$DOMID/$DEVID/* []
+
+A virtual keyboard device backend. Described by
+[xen/include/public/io/kbdif.h][KBDIF]
+
+#### ~/backend/vif/$DOMID/$DEVID/* []
+
+A virtual network device backend. Described by
+[xen/include/public/io/netif.h][NETIF]
+
+#### ~/backend/console/$DOMID/$DEVID/* []
+
+A PV console backend. Described in [console.txt](console.txt)
+
+#### ~/device-model/$DOMID/* [INTERNAL]
+
+Information relating to device models running in the domain. $DOMID is
+the target domain of the device model.
+
+#### ~/libxl/disable_udev = ("1"|"0") []
+
+Indicates whether device hotplug scripts in this domain should be run
+by udev ("0") or will be run by the toolstack directly
("1").
+
+### Platform Feature and Control Paths
+
+#### ~/control/shutdown = (""|COMMAND) [w]
+
+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.
+
+#### ~/control/platform-feature-multiprocessor-suspend = (0|1) []
+
+Indicates to the guest that this platform supports the multiprocessor
+suspend feature.
+
+#### ~/control/platform-feature-xs\_reset\_watches = (0|1) []
+
+Indicates to the guest that this platform supports the
+XS_RESET_WATCHES xenstore message. See
+[xen/include/public/io/xs\_wire.h][XSWIRE] for the XenStore wire
+protocol definition.
+
+### Domain Controlled Paths
+
+#### ~/data/* [w]
+
+A domain writable path. Available for arbitrary domain use.
+
+## Virtual Machine Paths
+
+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.
+
+### /vm/$UUID/uuid = UUID [n,INTERNAL]
+
+Value is the same UUID as the path.
+
+### /vm/$UUID/name = STRING [n,INTERNAL]
+
+The domain''s name.
+
+### /vm/$UUID/image/* [n,INTERNAL]
+
+Various information relating to the domain builder used for this guest.
+
+### /vm/$UUID/start_time = INTEGER "." INTEGER [n,INTERNAL]
+
+The time which the guest was started in SECONDS.MICROSECONDS format
+
+### /vm/$UUID/rtc/timeoffset = ""|INTEGER [n,HVM,INTERNAL]
+
+The guest''s virtual time offset from UTC in seconds.
+
+## Platform-Level paths
+
+### libxl Specific Paths
+
+#### /libxl/$DOMID/dm-version
("qemu\_xen"|"qemu\_xen\_traditional") = [n,INTERNAL]
+
+The device model version for a domain.
+
+[BLKIF]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,blkif.h.html
+[FBIF]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,fbif.h.html
+[HVMPARAMS]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,hvm,params.h.html
+[KBDIF]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,kbdif.h.html
+[LIBXLMEM]: http://xenbits.xen.org/docs/unstable/misc/libxl_memory.txt
+[NETIF]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,netif.h.html
+[SI]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,xen.h.html#Struct_start_info
+[VCPU]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,vcpu.h.html
+[XSWIRE]:
http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,xs_wire.h.html
diff --git a/tools/libxl/libxl_memory.txt b/tools/libxl/libxl_memory.txt
deleted file mode 100644
index 253476d..0000000
--- a/tools/libxl/libxl_memory.txt
+++ /dev/null
@@ -1,70 +0,0 @@
-/* === Domain memory breakdown: HVM guests =================================-
- + +----------+ +
- | | shadow | |
- | +----------+ |
- overhead | | extra | |
- | | external | |
- | +----------+ + |
- | | extra | | |
- | | internal | | |
- + +----------+ + | | footprint
- | | video | | | |
- | +----------+ + + | | xen |
- | | | | | | actual | maximum |
- | | | | | | target | |
- | | guest | | | build | | |
- | | | | | start | | |
- static | | | | | | | |
- maximum | +----------+ | + + + +
- | | | |
- | | | |
- | | balloon | | build
- | | | | maximum
- | | | |
- + +----------+ +
-
-
- extra internal = LIBXL_MAXMEM_CONSTANT
- extra external = LIBXL_HVM_EXTRA_MEMORY
- shadow = libxl_domain_build_info.shadow_memkb
- static maximum = libxl_domain_build_info.max_memkb
- video = libxl_domain_build_info.video_memkb
- build start = libxl_domain_build_info.target_memkb
- libxl_domain_setmaxmem -> xen maximum
- libxl_set_memory_target -> actual target
-
-
- === Domain memory breakdown: PV guests =================================-
-
- + +----------+ +
- overhead | | extra | |
- | | external | |
- | +----------+ + |
- | | extra | | |
- | | internal | | |
- + +----------+ + + + | | footprint
- | | | | | | | xen |
- | | | | | | actual | maximum |
- | | guest | | | build | target | |
- | | | | | start | | |
- static | | | | | | | |
- maximum | +----------+ | + + + +
- | | | |
- | | | |
- | | balloon | | build
- | | | | maximum
- | | | |
- + +----------+ +
-
-
- extra internal = LIBXL_MAXMEM_CONSTANT
- extra external = LIBXL_PV_EXTRA_MEMORY
- static maximum = libxl_domain_build_info.max_memkb
- build start = libxl_domain_build_info.target_memkb
- libxl_domain_setmaxmem -> xen maximum
- libxl_set_memory_target -> actual target
-
-
- ========================================================================= */
--
1.7.2.5
Ian Jackson
2012-Sep-24 16:45 UTC
Re: [PATCH] docs: initial documentation for xenstore paths
Ian Campbell writes ("[PATCH] docs: initial documentation for xenstore
paths"):> This is based upon my inspection of a system with a single PV domain
> and a single HVM domain running and is therefore very incomplete.
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Ian Jackson
2012-Oct-01 16:54 UTC
Re: [PATCH] docs: initial documentation for xenstore paths
Ian Jackson writes ("Re: [Xen-devel] [PATCH] docs: initial documentation
for xenstore paths"):> Ian Campbell writes ("[PATCH] docs: initial documentation for xenstore
paths"):
> > This is based upon my inspection of a system with a single PV domain
> > and a single HVM domain running and is therefore very incomplete.
>
> Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
Ian Campbell
2012-Oct-02 10:46 UTC
Re: [PATCH] docs: initial documentation for xenstore paths
On Mon, 2012-10-01 at 17:54 +0100, Ian Jackson wrote:> Ian Jackson writes ("Re: [Xen-devel] [PATCH] docs: initial documentation for xenstore paths"): > > Ian Campbell writes ("[PATCH] docs: initial documentation for xenstore paths"): > > > This is based upon my inspection of a system with a single PV domain > > > and a single HVM domain running and is therefore very incomplete. > > > > Acked-by: Ian Jackson <ian.jackson@eu.citrix.com> > > Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>Thanks, looks like I committed but forgot to push both this and George''s sched related cmdline patch before I went on vacation. Ian.