[PATCH 0/4] docs: Document xenstore paths

[PATCH 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 1/4] docs: Document control features the can be advertised by guests...

[Paul Durrant]

...via xenstore.

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-halt: PV drivers/agent can halt 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>
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>
---
 docs/misc/xenstore-paths.markdown | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index d94ea9d..ec3cc5f 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
@@ -321,12 +321,44 @@ by udev ("0") or will be run by the toolstack directly ("1").
 #### ~/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
+commands here to cause various guest halt, 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/feature-halt = (""|"0"|"1") [w]
+
+This is initialized to "" by the toolstack but may be set to 0 or 1 by
+a guest to indicate that it is capable or incapable, respectively, of
+halting if 'halt' is written to ~/control/shutdown.
+
+#### ~/control/feature-reboot = (""|"0"|"1") [w]
+
+This is initialized to "" by the toolstack but may be set to 0 or 1 by
+a guest to indicate that it is capable or incapable, respectively, of
+rebooting if 'reboot' is written to ~/control/shutdown.
+
+#### ~/control/feature-suspend = (""|"0"|"1") [w]
+
+This is initialized to "" by the toolstack but may be set to 0 or 1 by
+a guest to indicate that it is capable or incapable, respectively, of
+suspending if 'suspend' is written to ~/control/shutdown.
+
+#### ~/control/feature-s3 = (""|"0"|"1") [w,HVM]
+
+This is initialized to "" by the toolstack but may be set to 0 or 1 by
+a guest to indicate that it is capable or incapable, respectively, of
+triggering a guest sleep if 's3' is written to ~/control/shutdown and
+~/platform/acpi_s3 is 1.
+
+#### ~/control/feature-s4 = (""|"0"|"1") [w,HVM]
+
+This is initialized to "" by the toolstack but may be set to 0 or 1 by
+a guest to indicate that it is capable or incapable, respectively, of
+triggering a guest hibernate if 's4' is written to ~/control/shutdown
+and ~/platform/acpi_s4 is 1.
+
 #### ~/control/platform-feature-multiprocessor-suspend = (0|1) []
 
 Indicates to the guest that this platform supports the multiprocessor
-- 
2.1.4

[PATCH 2/4] docs: Document a path for PV driver version information...

[Paul Durrant]

...to be advertised by a guest.

For domain management purposes it is convenient to be able to see
PV driver version information 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>
---
 docs/misc/xenstore-paths.markdown | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index ec3cc5f..7701632 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
+* $NAME -- a string identifying an object within a domain. Typically
+  comprising only alphanumeric characters.
 
 VALUES are strings and can take the following forms:
 
@@ -51,6 +53,9 @@ 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
   ")".
+* VERSION -- 2 or 3 integers, in decimal form separated by ".",
+             specifying major version, minor version, and then
+	     (optionally) micro version.
 
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
@@ -377,6 +382,11 @@ protocol definition.
 
 A domain writable path. Available for arbitrary domain use.
 
+#### ~/drivers/$NAME/version = VERSION [w]
+
+A domain may write version information for PV driver $NAME using
+this path.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

[PATCH 2/4] docs: Document a xenstore path for PV driver version information...

[Paul Durrant]

...to be advertised by a guest.

For domain management purposes it is convenient to be able to see
PV driver version information 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>
---
 docs/misc/xenstore-paths.markdown | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index ec3cc5f..7701632 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
+* $NAME -- a string identifying an object within a domain. Typically
+  comprising only alphanumeric characters.
 
 VALUES are strings and can take the following forms:
 
@@ -51,6 +53,9 @@ 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
   ")".
+* VERSION -- 2 or 3 integers, in decimal form separated by ".",
+             specifying major version, minor version, and then
+	     (optionally) micro version.
 
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
@@ -377,6 +382,11 @@ protocol definition.
 
 A domain writable path. Available for arbitrary domain use.
 
+#### ~/drivers/$NAME/version = VERSION [w]
+
+A domain may write version information for PV driver $NAME using
+this path.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

[PATCH 3/4] docs: Document xenstore paths for domain hotplug features

[Paul Durrant]

Without some indication from an HVM domain 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 instantiated
in a guest. (In other words whether PV drivers are present and
functioning).

This patch document 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>
---
 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 7701632..9e98d6f 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary domain use.
 A domain may write version information for PV driver $NAME using
 this path.
 
+#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]
+
+An HVM domain can indicate to a toolstack that it is capable
+of responding to instantiation of a new vif by bringing online a
+new PV network device without the need for a reboot.
+
+#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM]
+
+An HVM domain can indicate to a toolstack that it is capable
+of responding to instantiation of a new vbd by bringing online a
+new PV block device without the need for a reboot.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

[PATCH 4/4] docs: Document xenstore paths for domain network address information

[Paul Durrant]

It is useful to be able to see the network addresses in use by a domain
for a particular vif in xenstore, for example so that ssh can be invoked
by a toolstack to log into the guest domain.

This patch documents paths to allow a domain to advertise MAC (unicast
and multicast) and IP (versions 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>
---
 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 9e98d6f..68d3dbf 100644
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -39,6 +39,8 @@ before regexp expansion:
 * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 * $NAME -- a string identifying an object within a domain. Typically
   comprising only alphanumeric characters.
+* $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:
 
@@ -56,6 +58,13 @@ VALUES are strings and can take the following forms:
 * VERSION -- 2 or 3 integers, in decimal form separated by ".",
              specifying major version, minor version, and then
 	     (optionally) micro version.
+* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':',
+                 specifying an ethernet MAC address.
+* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.',
+                  specifying an IP version 4 address.
+* IPV6_ADDRESS -- 8 integers, in hexadecimal form, separated by ':',
+                  specifying an IP version 6 address. (There should
+                  be strictly 8 integers i.e. '::' compression).
 
 Additional TAGS may follow as a comma separated set of the following
 tags enclosed in square brackets.
@@ -399,6 +408,26 @@ An HVM domain can indicate to a toolstack that it is capable
 of responding to instantiation of a new vbd by bringing online a
 new PV block device without the need for a reboot.
 
+#### ~/attr/vif/$DEVID/name = STRING [w]
+
+A domain may write its internal 'friendly' name for a network device
+using this path.
+
+#### ~/attr/vif/$DEVID/mac/$INDEX = MAC_ADDRESS [w]
+
+A domain may write the set of MAC addresses (unicast and multicast)
+in use by the network frontend using paths of this form.
+
+#### ~/attr/vif/$DEVID/ipv4/$INDEX = IPV4_ADDRESS [w]
+
+A domain may write the set of IP version 4 addresses in use by the
+stack bound to the network frontend using paths of this form.
+
+#### ~/attr/vif/$DEVID/ipv6/$INDEX = IPV6_ADDRESS [w]
+
+A domain may write the set of IP version 6 addresses in use by the
+stack bound to the network frontend using paths of this form.
+
 ### Paths private to the toolstack
 
 #### ~/device-model/$DOMID/state [w]
-- 
2.1.4

Re: [PATCH 2/4] docs: Document a path for PV driver version information...

[Paul Durrant]

> -----Original Message-----
> From: Paul Durrant [mailto:paul.durrant@citrix.com]
> Sent: 06 November 2015 17:22
> To: xen-devel@lists.xenproject.org
> Cc: Paul Durrant
> Subject: [PATCH 2/4] docs: Document a path for PV driver version
> information...
> 
> ...to be advertised by a guest.
> 
> For domain management purposes it is convenient to be able to see
> PV driver version information 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>

Sorry, this one is stale. It should not have been sent... Sorry for the noise.

  Paul

> ---
>  docs/misc/xenstore-paths.markdown | 10 ++++++++++
>  1 file changed, 10 insertions(+)
> 
> diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-
> paths.markdown
> index ec3cc5f..7701632 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
> +* $NAME -- a string identifying an object within a domain. Typically
> +  comprising only alphanumeric characters.
> 
>  VALUES are strings and can take the following forms:
> 
> @@ -51,6 +53,9 @@ 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
>    ")".
> +* VERSION -- 2 or 3 integers, in decimal form separated by ".",
> +             specifying major version, minor version, and then
> +	     (optionally) micro version.
> 
>  Additional TAGS may follow as a comma separated set of the following
>  tags enclosed in square brackets.
> @@ -377,6 +382,11 @@ protocol definition.
> 
>  A domain writable path. Available for arbitrary domain use.
> 
> +#### ~/drivers/$NAME/version = VERSION [w]
> +
> +A domain may write version information for PV driver $NAME using
> +this path.
> +
>  ### Paths private to the toolstack
> 
>  #### ~/device-model/$DOMID/state [w]
> --
> 2.1.4

Re: [PATCH 2/4] docs: Document a xenstore path for PV driver version information...

[Andrew Cooper]

On 06/11/15 17:21, Paul Durrant wrote:
> ...to be advertised by a guest.
>
> For domain management purposes it is convenient to be able to see
> PV driver version information 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>
> ---
>  docs/misc/xenstore-paths.markdown | 10 ++++++++++
>  1 file changed, 10 insertions(+)
>
> diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
> index ec3cc5f..7701632 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
> +* $NAME -- a string identifying an object within a domain. Typically
> +  comprising only alphanumeric characters.
>  
>  VALUES are strings and can take the following forms:
>  
> @@ -51,6 +53,9 @@ 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
>    ")".
> +* VERSION -- 2 or 3 integers, in decimal form separated by ".",
> +             specifying major version, minor version, and then
> +	     (optionally) micro version.

I am not sure version should come with a restriction like this.  For
debug builds, it might be common to have a suffix.  Furthermore, not all
software conforms to the $MAJOR.$MINOR.$MICRO scheme.

I would just leave it specified as a "string which identifies the
version of the driver", without any specific restrictions

~Andrew

Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features

[Andrew Cooper]

On 06/11/15 17:21, Paul Durrant wrote:
> Without some indication from an HVM domain 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 instantiated
> in a guest. (In other words whether PV drivers are present and
> functioning).
>
> This patch document 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>
> ---
>  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 7701632..9e98d6f 100644
> --- a/docs/misc/xenstore-paths.markdown
> +++ b/docs/misc/xenstore-paths.markdown
> @@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary domain use.
>  A domain may write version information for PV driver $NAME using
>  this path.
>  
> +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]
> +
> +An HVM domain can indicate to a toolstack that it is capable
> +of responding to instantiation of a new vif by bringing online a
> +new PV network device without the need for a reboot.
> +
> +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM]
> +
> +An HVM domain can indicate to a toolstack that it is capable
> +of responding to instantiation of a new vbd by bringing online a
> +new PV block device without the need for a reboot.

These flags are not inherently restricted to HVM guests.  Therefore, I
would avoid specifying them as such.  (It is quite possible for a PV
guest not to be able to hotplug a vbd for example.)

~Andrew

Re: [PATCH 4/4] docs: Document xenstore paths for domain network address information

[Andrew Cooper]

On 06/11/15 17:21, Paul Durrant wrote:
> It is useful to be able to see the network addresses in use by a domain
> for a particular vif in xenstore, for example so that ssh can be invoked
> by a toolstack to log into the guest domain.
>
> This patch documents paths to allow a domain to advertise MAC (unicast
> and multicast) and IP (versions 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>
> ---
>  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 9e98d6f..68d3dbf 100644
> --- a/docs/misc/xenstore-paths.markdown
> +++ b/docs/misc/xenstore-paths.markdown
> @@ -39,6 +39,8 @@ before regexp expansion:
>  * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
>  * $NAME -- a string identifying an object within a domain. Typically
>    comprising only alphanumeric characters.
> +* $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:
>  
> @@ -56,6 +58,13 @@ VALUES are strings and can take the following forms:
>  * VERSION -- 2 or 3 integers, in decimal form separated by ".",
>               specifying major version, minor version, and then
>  	     (optionally) micro version.
> +* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':',
> +                 specifying an ethernet MAC address.
> +* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.',
> +                  specifying an IP version 4 address.
> +* IPV6_ADDRESS -- 8 integers, in hexadecimal form, separated by ':',
> +                  specifying an IP version 6 address. (There should
> +                  be strictly 8 integers i.e. '::' compression).

Given the "strictly", I presume you mean no "::" compression?

But why enforce that restriction? "::" compression is unambiguous and
typically makes the addresses rather more human readable.

~Andrew

Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features

[Paul Durrant]

> -----Original Message-----
> From: Andrew Cooper [mailto:andrew.cooper3@citrix.com]
> Sent: 06 November 2015 18:08
> To: Paul Durrant; xen-devel@lists.xenproject.org
> Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
> Subject: Re: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for
> domain hotplug features
> 
> On 06/11/15 17:21, Paul Durrant wrote:
> > Without some indication from an HVM domain 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 instantiated
> > in a guest. (In other words whether PV drivers are present and
> > functioning).
> >
> > This patch document 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>
> > ---
> >  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 7701632..9e98d6f 100644
> > --- a/docs/misc/xenstore-paths.markdown
> > +++ b/docs/misc/xenstore-paths.markdown
> > @@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary
> domain use.
> >  A domain may write version information for PV driver $NAME using
> >  this path.
> >
> > +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]
> > +
> > +An HVM domain can indicate to a toolstack that it is capable
> > +of responding to instantiation of a new vif by bringing online a
> > +new PV network device without the need for a reboot.
> > +
> > +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM]
> > +
> > +An HVM domain can indicate to a toolstack that it is capable
> > +of responding to instantiation of a new vbd by bringing online a
> > +new PV block device without the need for a reboot.
> 
> These flags are not inherently restricted to HVM guests.  Therefore, I
> would avoid specifying them as such.  (It is quite possible for a PV
> guest not to be able to hotplug a vbd for example.)

I wasn't sure that was true. My belief was that all pure PV guests would have frontends handling hot attach. I'm happy to drop the HVM tag in v2 though.

  Paul

> 
> ~Andrew

Re: [PATCH 4/4] docs: Document xenstore paths for domain network address information

[Paul Durrant]

> -----Original Message-----
> From: Andrew Cooper [mailto:andrew.cooper3@citrix.com]
> Sent: 06 November 2015 18:17
> To: Paul Durrant; xen-devel@lists.xenproject.org
> Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
> Subject: Re: [Xen-devel] [PATCH 4/4] docs: Document xenstore paths for
> domain network address information
> 
> On 06/11/15 17:21, Paul Durrant wrote:
> > It is useful to be able to see the network addresses in use by a domain
> > for a particular vif in xenstore, for example so that ssh can be invoked
> > by a toolstack to log into the guest domain.
> >
> > This patch documents paths to allow a domain to advertise MAC (unicast
> > and multicast) and IP (versions 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>
> > ---
> >  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 9e98d6f..68d3dbf 100644
> > --- a/docs/misc/xenstore-paths.markdown
> > +++ b/docs/misc/xenstore-paths.markdown
> > @@ -39,6 +39,8 @@ before regexp expansion:
> >  * $UUID -- a UUID in the form xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
> >  * $NAME -- a string identifying an object within a domain. Typically
> >    comprising only alphanumeric characters.
> > +* $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:
> >
> > @@ -56,6 +58,13 @@ VALUES are strings and can take the following forms:
> >  * VERSION -- 2 or 3 integers, in decimal form separated by ".",
> >               specifying major version, minor version, and then
> >  	     (optionally) micro version.
> > +* MAC_ADDRESS -- 6 integers, in hexadecimal form, separated by ':',
> > +                 specifying an ethernet MAC address.
> > +* IPV4_ADDRESS -- 4 integers, in decimal form, separated by '.',
> > +                  specifying an IP version 4 address.
> > +* IPV6_ADDRESS -- 8 integers, in hexadecimal form, separated by ':',
> > +                  specifying an IP version 6 address. (There should
> > +                  be strictly 8 integers i.e. '::' compression).
> 
> Given the "strictly", I presume you mean no "::" compression?

Yes, I missed the 'no'

> 
> But why enforce that restriction? "::" compression is unambiguous and
> typically makes the addresses rather more human readable.
> 

That's true but I didn't want to put the coding burden on the frontend. Defining it this way makes it a trivial printf into xenstore. Whatever picks the address up can do the compression afterwards before display. I suppose it would be better to allow compression but state that it's not required.

  Paul

> ~Andrew

Re: [PATCH 1/4] docs: Document control features the can be advertised by guests...

[Jan Beulich]

>>> On 06.11.15 at 18:21, <paul.durrant@citrix.com> wrote:
> ...via xenstore.
> 
> 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).

If these can't be set by a guest with the current default toolstack
anyway, what's the point of documenting them (the more without
warning about that fact in the text being added)?

Jan

Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features

[Jan Beulich]

>>> On 09.11.15 at 10:51, <Paul.Durrant@citrix.com> wrote:
>>  -----Original Message-----
>> From: Andrew Cooper [mailto:andrew.cooper3@citrix.com]
>> Sent: 06 November 2015 18:08
>> To: Paul Durrant; xen-devel@lists.xenproject.org 
>> Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
>> Subject: Re: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for
>> domain hotplug features
>> 
>> On 06/11/15 17:21, Paul Durrant wrote:
>> > Without some indication from an HVM domain 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 instantiated
>> > in a guest. (In other words whether PV drivers are present and
>> > functioning).
>> >
>> > This patch document 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>
>> > ---
>> >  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 7701632..9e98d6f 100644
>> > --- a/docs/misc/xenstore-paths.markdown
>> > +++ b/docs/misc/xenstore-paths.markdown
>> > @@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary
>> domain use.
>> >  A domain may write version information for PV driver $NAME using
>> >  this path.
>> >
>> > +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]
>> > +
>> > +An HVM domain can indicate to a toolstack that it is capable
>> > +of responding to instantiation of a new vif by bringing online a
>> > +new PV network device without the need for a reboot.
>> > +
>> > +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM]
>> > +
>> > +An HVM domain can indicate to a toolstack that it is capable
>> > +of responding to instantiation of a new vbd by bringing online a
>> > +new PV block device without the need for a reboot.
>> 
>> These flags are not inherently restricted to HVM guests.  Therefore, I
>> would avoid specifying them as such.  (It is quite possible for a PV
>> guest not to be able to hotplug a vbd for example.)
> 
> I wasn't sure that was true. My belief was that all pure PV guests would 
> have frontends handling hot attach. I'm happy to drop the HVM tag in v2 
> though.

With intermediate steps between HVM and PVH planned to become
possible, I think not overly limiting the scope of such entries would
indeed desirable.

Jan

Re: [PATCH 1/4] docs: Document control features the can be advertised by guests...

[Paul Durrant]

> -----Original Message-----
> From: Jan Beulich [mailto:JBeulich@suse.com]
> Sent: 09 November 2015 10:44
> To: Paul Durrant
> Cc: Ian Campbell; Ian Jackson; xen-devel@lists.xenproject.org; Keir
> (Xen.org); Tim (Xen.org)
> Subject: Re: [PATCH 1/4] docs: Document control features the can be
> advertised by guests...
> 
> >>> On 06.11.15 at 18:21, <paul.durrant@citrix.com> wrote:
> > ...via xenstore.
> >
> > 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).
> 
> If these can't be set by a guest with the current default toolstack
> anyway, what's the point of documenting them (the more without
> warning about that fact in the text being added)?
>

Because I want to add them to libxl.

  Paul

 
> Jan

Re: [PATCH 3/4] docs: Document xenstore paths for domain hotplug features

[Paul Durrant]

> -----Original Message-----
> From: Jan Beulich [mailto:JBeulich@suse.com]
> Sent: 09 November 2015 10:50
> To: Andrew Cooper; Paul Durrant; xen-devel@lists.xenproject.org
> Cc: Ian Campbell; Ian Jackson; Keir (Xen.org); Tim (Xen.org)
> Subject: RE: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for
> domain hotplug features
> 
> >>> On 09.11.15 at 10:51, <Paul.Durrant@citrix.com> wrote:
> >>  -----Original Message-----
> >> From: Andrew Cooper [mailto:andrew.cooper3@citrix.com]
> >> Sent: 06 November 2015 18:08
> >> To: Paul Durrant; xen-devel@lists.xenproject.org
> >> Cc: Keir (Xen.org); Ian Campbell; Tim (Xen.org); Ian Jackson; Jan Beulich
> >> Subject: Re: [Xen-devel] [PATCH 3/4] docs: Document xenstore paths for
> >> domain hotplug features
> >>
> >> On 06/11/15 17:21, Paul Durrant wrote:
> >> > Without some indication from an HVM domain 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 instantiated
> >> > in a guest. (In other words whether PV drivers are present and
> >> > functioning).
> >> >
> >> > This patch document 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>
> >> > ---
> >> >  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 7701632..9e98d6f 100644
> >> > --- a/docs/misc/xenstore-paths.markdown
> >> > +++ b/docs/misc/xenstore-paths.markdown
> >> > @@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary
> >> domain use.
> >> >  A domain may write version information for PV driver $NAME using
> >> >  this path.
> >> >
> >> > +#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]
> >> > +
> >> > +An HVM domain can indicate to a toolstack that it is capable
> >> > +of responding to instantiation of a new vif by bringing online a
> >> > +new PV network device without the need for a reboot.
> >> > +
> >> > +#### ~/feature/hotplug/vbd = ("0"|"1") [w,HVM]
> >> > +
> >> > +An HVM domain can indicate to a toolstack that it is capable
> >> > +of responding to instantiation of a new vbd by bringing online a
> >> > +new PV block device without the need for a reboot.
> >>
> >> These flags are not inherently restricted to HVM guests.  Therefore, I
> >> would avoid specifying them as such.  (It is quite possible for a PV
> >> guest not to be able to hotplug a vbd for example.)
> >
> > I wasn't sure that was true. My belief was that all pure PV guests would
> > have frontends handling hot attach. I'm happy to drop the HVM tag in v2
> > though.
> 
> With intermediate steps between HVM and PVH planned to become
> possible, I think not overly limiting the scope of such entries would
> indeed desirable.
> 

Ok.

  Paul

> Jan