Re: [Xen-devel] [DOCDAY PATCH] docs: initial documentation for xenstore paths

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Mon, 2012-07-30 at 15:03 +0100, Ian Campbell wrote:
> This is based upon my inspection of a system with a single PV domain running
> and is therefore very incomplete.
> 
> There are several things I'm not sure of here, mostly marked with XXX in the
> text.
> 
> In particular:
> 
>  - We seem to expose various things to the guest which really it has no need 
> to
>    know (at least not via xenstore). e.g. its own domid, its device model pid,
>    the size of the video ram, store port and gref.
>  - Missing reference for ~/device-model/*
>  - Missing protocol reference for ~/control/shutdown
>  - What is the distinction between /vm/UUID and /local/domain/DOMID
> 
> Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>

Any thoughts on this or the follow up?

Ian J is this machine-readable in a way which is useful for whatever it
is you wanted to machine read it into?

> ---
>  docs/INDEX                        |    1 +
>  docs/misc/xenstore-paths.markdown |  294 
> +++++++++++++++++++++++++++++++++++++
>  2 files changed, 295 insertions(+), 0 deletions(-)
> 
> 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/xenstore-paths.markdown 
> b/docs/misc/xenstore-paths.markdown
> index e69de29..967ed7b 100644
> --- a/docs/misc/xenstore-paths.markdown
> +++ b/docs/misc/xenstore-paths.markdown
> @@ -0,0 +1,294 @@
> +# 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 POSIX regexp
> +syntax described in regexp(7). 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 -- the decimal representation of an integer.
> + * 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 locationsare read only for the
> +  domain.
> +* 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)
> +
> +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.
> +
> +XXX why is this exposed to the guest here?
> +
> +#### ~/image/device-model-pid = INTEGER   [r]
> +
> +The process ID of the device model associated with this domain, if it
> +has one.
> +
> +XXX why is this visible to the guest?
> +
> +#### ~/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". 
> +
> +#### ~/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 .
> +
> +#### ~/memory/target = MEMKB []
> +
> +The current balloon target for the domain. The balloon driver within the 
> guest is expected to make every effort 
> +
> +#### ~/memory/videoram = MEMKB [HVM]
> +
> +The size of the video RAM this domain is configured with.
> +
> +XXX why is this exposed to the guest here instead of as a PCI BAR or
> +some other property of the virtual GFX card? Perhaps should be
> +non-guest visible.
> +
> +#### ~/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 discression. If it is not used then this
> +path will be left blank.
> +
> +### 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
> +
> +#### ~/store/port = EVTCHN []
> +
> +The event channel used by the domains connection to XenStore.
> +
> +XXX why is this exposed to the guest?
> +
> +#### ~/store/ring-ref = GNTREF []
> +
> +The grant reference of the domain's XenStore ring.
> +
> +XXX why is this exposed to the guest?
> +
> +### 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]
> +
> +#### ~/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/* []
> +
> +Information relating to device models running in the domain. $DOMID is
> +the target domain of the device model.
> +
> +XXX where is the contents of this directory specified?
> +
> +#### ~/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.
> +
> +XXX where is this protocol and the valid keys defined?
> +
> +#### ~/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
> +for the XenStore wire protocol definition.
> +
> +### Domain Controlled Paths
> +
> +#### ~/data/* [w]
> +
> +A domain writable path. Available for arbitrary domain use.
> +
> +## Virtual Machine paths
> +
> +XXX somehow describe how /vm is different to /local/domain/
> +
> +### /vm/$UUID/uuid = UUID []
> +
> +Value is the same UUID as the path.
> +
> +### /vm/$UUID/name = STRING []
> +
> +The domains name.
> +
> +### /vm/$UUID/image/* []
> +
> +Various information relating to the domain builder.
> +
> +### /vm/$UUID/start_time = INTEGER "." INTEGER []
> +
> +The time which the guest was started in SECONDS.MICROSECONDS format
> +
> +## Platform-Level paths
> +
> +### libxl Specific Paths
> +
> +#### /libxl/$DOMID/dm-version ("qemu_xen"|"qemu_xen_traditional") = []
> +
> +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
> +[KBDIF]: 
> http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,kbdif.h.html
> +[NETIF]: 
> http://xenbits.xen.org/docs/unstable/hypercall/include,public,io,netif.h.html



_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel