[PATCH v5 0/4] docs: Document xenstore paths

[PATCH v5 0/4] docs: Document xenstore paths

[Paul Durrant]

Patch #1 documents paths, some already in used by XenServer, which can be
used by guests to advertise contol capabilities.

Patch #2 documents paths which can be used to advertise PV driver versions.

Patch #3 documents paths which can be used by guests to advertise hotplug
capabilities.

Patch #4 documents paths which can be used by guests to advertise network
addresses.

[PATCH v5 1/4] docs: Introduce xenstore paths for PV control features

[Paul Durrant]

XenServer already makes use of ~/control/feature-suspend being written
to advertise guest capability of responding to 'suspend' when written to
~/control/shutdown and, since they are derived from XenServer drivers,
the Xen Project Windows PV drivers attempt to write this value. The write
currently fails for libxl provisioned VMs because ~/control is read-only
to the guest (only ~/control/shutdown is writable, for ackowledgement
purposes).

This patch documents feature-suspend and also a set of similar control
feature flags, so that that they may be added to libxl provisioned
guests by subsequent patches:

feature-poweroff: PV drivers/agent can shut down the guest
feature-reboot: PV drivers/agent can reboot the guest
feature-s3: PV drivers/agent can trigger guest sleep (HVM only)
feature-s4: PV drivers/agent can trigger guest hibernate (HVM only)

The patch (bacause it adds features relating to S3 and S4 power states)
also clarifies that the initial set of platform properties mentioned are
booleans, and updates the specifier accordingly.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>
Cc: Tim Deegan <tim@xen.org>
---

v4:
 - Clarify use of control features

v3:
 - Changed feature-halt to feature-poweroff since writing 'poweroff' to
   control/shutdown is the currently implemented method of PV domain
   shutdown
---
 docs/misc/xenstore-paths.markdown | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index d94ea9d..2d2ce46 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -178,9 +178,9 @@ will not relocate guest memory.
 
 The BIOS used by this domain.
 
-#### ~/platform/* [HVM,INTERNAL]
+#### ~/platform/* = ("0"|"1") [HVM,INTERNAL]
 
-Various platform properties.
+Various boolean platform properties.
 
 * acpi -- is ACPI enabled for this domain
 * acpi_s3 -- is ACPI S3 support enabled for this domain
@@ -327,6 +327,41 @@ string back to the command node.
 
 The precise protocol is not yet documented.
 
+#### ~/control/feature-poweroff = (""|"0"|"1") [w]
+#### ~/control/feature-reboot = (""|"0"|"1") [w]
+#### ~/control/feature-suspend = (""|"0"|"1") [w]
+
+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.
+
+#### ~/control/feature-s3 = (""|"0"|"1") [w,HVM]
+#### ~/control/feature-s4 = (""|"0"|"1") [w,HVM]
+
+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.
+
 #### ~/control/platform-feature-multiprocessor-suspend = (0|1) []
 
 Indicates to the guest that this platform supports the multiprocessor
-- 
2.1.4

[PATCH v5 2/4] docs: Introduce xenstore paths for PV driver information

[Paul Durrant]

For domain management purposes it is convenient to be able to see
information about PV drivers in xenstore. The XAPI toolstack in
XenServer has always created a ~/drivers path for this purpose.

This patch documents that path and also adds a specification of how
it should be used.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>
Cc: Tim Deegan <tim@xen.org>
---

v5:
 - Add more clarification to DISTRIBUTION section.

v4:
 - Rather than just version information, expand the definition of paths
   under ~/drivers to include full distribution information, including
   vendor name.

v2:
 - Modify version specifier to allow for single-part version numbers
   and also arbitrary string suffix (e.g. '-debug')
---
 docs/misc/xenstore-paths.markdown | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index 2d2ce46..b8788f2 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -37,6 +37,8 @@ before regexp expansion:
   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
+* $INDEX -- an integer used as part of a path when listing a set of
+            values. Typically these integers are contiguous.
 
 VALUES are strings and can take the following forms:
 
@@ -51,6 +53,28 @@ VALUES are strings and can take the following forms:
 * (VALUE | VALUE | ... ) -- a set of alternatives. Alternatives are
   separated by a "|" and all the alternatives are enclosed in "(" and
   ")".
+* 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.
 
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
@@ -380,6 +404,11 @@ protocol definition.
 
 A domain writable path. Available for arbitrary domain use.
 
+#### ~/drivers/$INDEX = DISTRIBUTION [w]
+
+A domain may write information about installed PV drivers using
+paths of this form.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

[PATCH v5 3/4] docs: Introduce xenstore paths for hotplug features

[Paul Durrant]

Without some indication from a guest it is not possible for a
toolstack to know whether instantiation of a new vbd or vif should
result in a new PV device of the appropriate type being brought online.
(In other words whether guest PV drivers are present and functioning).

This patch documents two paths which vif and vbd frontend drivers can
use to advertise their ability to respond to new vif or vbd
instantiations.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>
Cc: Tim Deegan <tim@xen.org>
---

v4:
 - Clarify use of the hotplug feature paths

v2:
 - Drop HVM restriction
---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index b8788f2..624b7fd 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -409,6 +409,18 @@ A domain writable path. Available for arbitrary domain use.
 A domain may write information about installed PV drivers using
 paths of this form.
 
+#### ~/feature/hotplug/vif = ("0"|"1") [w]
+#### ~/feature/hotplug/vbd = ("0"|"1") [w]
+
+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.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

[PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

[Paul Durrant]

It is useful for a toolstack to be able to see the network addresses
in use by a domain for a particular vif in xenstore for display
purposes and, for example, so that a VNC session can be established
to the guest GUI.

This patch documents paths to allow a domain to advertise an interface
name, MAC (unicast and multicast) and IP (version 4 and 6) address
information.

Signed-off-by: Paul Durrant <paul.durrant@citrix.com>
Cc: Ian Campbell <ian.campbell@citrix.com>
Cc: Ian Jackson <ian.jackson@eu.citrix.com>
Cc: Jan Beulich <jbeulich@suse.com>
Cc: Keir Fraser <keir@xen.org>
Cc: Tim Deegan <tim@xen.org>
---

v5:
 - Add references for MAC and IP address formats
 - Further clarification of attr paths

v4:
 - Add clarification of use and level of trust that should be placed
   on the various paths

v2:
 - Allow for compression of IPv6 addresses
---
 docs/misc/xenstore-paths.markdown | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index 624b7fd..197bb0f 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -76,6 +76,15 @@ VALUES are strings and can take the following forms:
                                 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.
+* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.',
+                  specifying an IP version 4 address as described
+                  IETF RFC 791.
+* IPV6_ADDRESS -- Up to 8 integers, in hexadecimal form, separated
+                  by ':', specifying an IP version 6 address as
+                  described in IETF RFC 4291.
+
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
 
@@ -421,6 +430,33 @@ 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.
 
+#### ~/attr/vif/$DEVID/name = STRING [w]
+
+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.
+
+#### ~/attr/vif/$DEVID/mac/$INDEX = MAC_ADDRESS [w]
+
+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.
+
+#### ~/attr/vif/$DEVID/ipv4/$INDEX = IPV4_ADDRESS [w]
+#### ~/attr/vif/$DEVID/ipv6/$INDEX = IPV6_ADDRESS [w]
+
+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).
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

[Olaf Hering]

On Tue, Nov 17, Paul Durrant wrote:

> This patch documents paths to allow a domain to advertise an interface
> name, MAC (unicast and multicast) and IP (version 4 and 6) address
> information.

How does the domU do that in practice?
With some variant of xenstore-write or with the PV vif driver?
Last time I tried to use xenstore* commands in domU it was unable to use
relative paths, which forced me to specify the domid value for the
paths. Might be a usage error on my side, or just a bug in the xenstore
commands.


Olaf

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

[Paul Durrant]

> -----Original Message-----
> From: Olaf Hering [mailto:olaf@aepfle.de]
> Sent: 18 November 2015 12:00
> To: Paul Durrant
> Cc: xen-devel@lists.xenproject.org; Keir (Xen.org); Ian Campbell; Tim
> (Xen.org); Ian Jackson; Jan Beulich
> Subject: Re: [Xen-devel] [PATCH v5 4/4] docs: Introduce xenstore paths for
> guest network address information
> 
> On Tue, Nov 17, Paul Durrant wrote:
> 
> > This patch documents paths to allow a domain to advertise an interface
> > name, MAC (unicast and multicast) and IP (version 4 and 6) address
> > information.
> 
> How does the domU do that in practice?
> With some variant of xenstore-write or with the PV vif driver?

In the case of Windows, the IP helper is available to the XENVIF driver so it will do the xenstore writes using the XENBUS_STORE interface provided by the XENBUS driver.

> Last time I tried to use xenstore* commands in domU it was unable to use
> relative paths, which forced me to specify the domid value for the
> paths. Might be a usage error on my side, or just a bug in the xenstore
> commands.
> 

I've not had an issue with using relative paths in Windows so I guess it's an implementation issue in whatever frontend OS you are using.

  Paul

> 
> Olaf

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

[Andrew Cooper]

On 18/11/15 12:00, Olaf Hering wrote:
> On Tue, Nov 17, Paul Durrant wrote:
>
>> This patch documents paths to allow a domain to advertise an interface
>> name, MAC (unicast and multicast) and IP (version 4 and 6) address
>> information.
> How does the domU do that in practice?
> With some variant of xenstore-write or with the PV vif driver?
> Last time I tried to use xenstore* commands in domU it was unable to use
> relative paths, which forced me to specify the domid value for the
> paths. Might be a usage error on my side, or just a bug in the xenstore
> commands.

Where possible, the frontends themselves ought to be in charge of
keeping this information up to date.

This will reduce the dependence on an ancillary userspace component, and
make it less likely for the information to go stale.

~Andrew

Re: [PATCH v5 2/4] docs: Introduce xenstore paths for PV driver information

[Ian Jackson]

Paul Durrant writes ("[PATCH v5 2/4] docs: Introduce xenstore paths for PV driver information"):
> For domain management purposes it is convenient to be able to see
> information about PV drivers in xenstore. The XAPI toolstack in
> XenServer has always created a ~/drivers path for this purpose.
> 
> This patch documents that path and also adds a specification of how
> it should be used.

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Re: [PATCH v5 3/4] docs: Introduce xenstore paths for hotplug features

[Ian Jackson]

Paul Durrant writes ("[PATCH v5 3/4] docs: Introduce xenstore paths for hotplug features"):
> Without some indication from a guest it is not possible for a
> toolstack to know whether instantiation of a new vbd or vif should
> result in a new PV device of the appropriate type being brought online.
> (In other words whether guest PV drivers are present and functioning).
> 
> This patch documents two paths which vif and vbd frontend drivers can
> use to advertise their ability to respond to new vif or vbd
> instantiations.

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Re: [PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information

[Ian Jackson]

Paul Durrant writes ("[PATCH v5 4/4] docs: Introduce xenstore paths for guest network address information"):
> It is useful for a toolstack to be able to see the network addresses
> in use by a domain for a particular vif in xenstore for display
> purposes and, for example, so that a VNC session can be established
> to the guest GUI.
> 
> This patch documents paths to allow a domain to advertise an interface
> name, MAC (unicast and multicast) and IP (version 4 and 6) address
> information.

Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

Re: [PATCH v5 0/4] docs: Document xenstore paths

[Ian Campbell]

On Tue, 2015-11-17 at 11:32 +0000, Paul Durrant wrote:

All applied with Ian's acks.

> Patch #1 documents paths, some already in used by XenServer, which can be
> used by guests to advertise contol capabilities.
> 
> Patch #2 documents paths which can be used to advertise PV driver
> versions.
> 
> Patch #3 documents paths which can be used by guests to advertise hotplug
> capabilities.
> 
> Patch #4 documents paths which can be used by guests to advertise network
> addresses.
> 
> _______________________________________________
> Xen-devel mailing list
> Xen-devel@lists.xen.org
> http://lists.xen.org/xen-devel