Skip to contentSkip to conversation

docs: Document xenstore paths

PATCH Superseded Paul Durrant 3 participants 16 messages Nov 6, 2015 – Nov 9, 2015

v1 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

cover docs: Document xenstore paths

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.

#1 lore raw

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

...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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)
docs/misc/xenstore-paths.markdown +35 -3
index d94ea9d..ec3cc5f 100644
@@ -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
Signature · 1 line
2.1.4
#2 lore raw

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

Quoted 10 lines
Quoted 1 line
Quoted 1 line · On 06.11.15 at 18:21, <[email protected]> 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

#3 lore raw

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

Quoted 20 lines

-----Original Message-----
From: Jan Beulich [mailto:[email protected]]
Sent: 09 November 2015 10:44
To: Paul Durrant
Cc: Ian Campbell; Ian Jackson; [email protected]; Keir (Xen.org); Tim (Xen.org)
Subject: Re: [PATCH 1/4] docs: Document control features the can be advertised by guests...

Quoted 10 lines
Quoted 1 line
Quoted 1 line · On 06.11.15 at 18:21, <[email protected]> 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).

Quoted 4 lines

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

Quoted 1 line

Jan

#4 lore raw

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

In reply to 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 10 ++++++++++
 1 file changed, 10 insertions(+)
docs/misc/xenstore-paths.markdown +10 -0
index ec3cc5f..7701632 100644
@@ -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]
Signature · 1 line
2.1.4
#5 lore raw

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

Quoted 33 lines · 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 10 ++++++++++
 1 file changed, 10 insertions(+)
docs/misc/xenstore-paths.markdown +2 -0
index ec3cc5f..7701632 100644
@@ -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:
 

docs/misc/xenstore-paths.markdown VALUES are strings and can take the following forms: · line 58

Quoted 6 lines
docs/misc/xenstore-paths.markdown +3 -0
@@ -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

#6 lore raw

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

In reply to 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.

---
 docs/misc/xenstore-paths.markdown | 10 ++++++++++
 1 file changed, 10 insertions(+)
docs/misc/xenstore-paths.markdown +10 -0
index ec3cc5f..7701632 100644
@@ -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]
Signature · 1 line
2.1.4
#7 lore raw

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

Quoted 10 lines

-----Original Message-----
From: Paul Durrant [mailto:[email protected]]
Sent: 06 November 2015 17:22
To: [email protected]
Cc: Paul Durrant
Subject: [PATCH 2/4] docs: Document a path for PV driver version information...

...to be advertised by a guest.

Quoted 8 lines

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.

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

Paul

Quoted 42 lines
---
 docs/misc/xenstore-paths.markdown | 10 ++++++++++
 1 file changed, 10 insertions(+)
docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0 -0

paths.markdown
index ec3cc5f..7701632 100644

docs/misc/xenstore-paths.markdown +10 -1
@@ -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

#8 lore raw

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

In reply to 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)
docs/misc/xenstore-paths.markdown +12 -0
index 7701632..9e98d6f 100644
@@ -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]
Signature · 1 line
2.1.4
#9 lore raw

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

Quoted 29 lines · 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)
docs/misc/xenstore-paths.markdown +1 -0
index 7701632..9e98d6f 100644
@@ -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]

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400

Quoted 10 lines
docs/misc/xenstore-paths.markdown +10 -0
+
+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

#10 lore raw

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

Quoted 39 lines

-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:08
To: Paul Durrant; [email protected]
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

docs/misc/xenstore-

Quoted 21 lines · 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)
docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0 -0

paths.markdown

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary

Quoted 4 lines

index 7701632..9e98d6f 100644

docs/misc/xenstore-paths.markdown +0 -0
@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary

domain use.

Quoted 3 lines
docs/misc/xenstore-paths.markdown +0 -0
 A domain may write version information for PV driver $NAME using
 this path.
 
Quoted 15 lines

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400

Quoted 11 lines
docs/misc/xenstore-paths.markdown +11 -0
+#### ~/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

Quoted 2 lines

~Andrew

#11 lore raw

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

Quoted 56 lines
Quoted 40 lines
Quoted 1 line · On 09.11.15 at 10:51, <[email protected]> wrote:

-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:08
To: Paul Durrant; [email protected]
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

docs/misc/xenstore-

Quoted 21 lines · 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)
docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0 -0

paths.markdown

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary

Quoted 4 lines

index 7701632..9e98d6f 100644

docs/misc/xenstore-paths.markdown +0 -0
@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary

domain use.

Quoted 3 lines
docs/misc/xenstore-paths.markdown +0 -0
 A domain may write version information for PV driver $NAME using
 this path.
 
Quoted 15 lines

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400

Quoted 11 lines
docs/misc/xenstore-paths.markdown +11 -0
+#### ~/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.)

Quoted 3 lines

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

#12 lore raw

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

Quoted 64 lines

-----Original Message-----
From: Jan Beulich [mailto:[email protected]]
Sent: 09 November 2015 10:50
To: Andrew Cooper; Paul Durrant; [email protected]
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

Quoted 56 lines
Quoted 55 lines
Quoted 1 line · On 09.11.15 at 10:51, <[email protected]> wrote:

-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:08
To: Paul Durrant; [email protected]
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

docs/misc/xenstore-

Quoted 21 lines · 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 12 ++++++++++++
 1 file changed, 12 insertions(+)
docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0 -0

paths.markdown

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary

Quoted 4 lines

index 7701632..9e98d6f 100644

docs/misc/xenstore-paths.markdown +0 -0
@@ -387,6 +387,18 @@ A domain writable path. Available for arbitrary

domain use.

Quoted 4 lines
docs/misc/xenstore-paths.markdown +1 -0
 A domain may write version information for PV driver $NAME using
 this path.
 
+#### ~/feature/hotplug/vif = ("0"|"1") [w,HVM]

docs/misc/xenstore-paths.markdown A domain writable path. Available for arbitrary domain use. · line 400

Quoted 10 lines
docs/misc/xenstore-paths.markdown +10 -0
+
+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.)

Quoted 8 lines
Quoted 3 lines

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

Quoted 1 line

Jan

#13 lore raw

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

In reply to 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
docs/misc/xenstore-paths.markdown +29 -0
index 9e98d6f..68d3dbf 100644
@@ -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]
Signature · 1 line
2.1.4
#14 lore raw

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

Quoted 31 lines · 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.

Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)
docs/misc/xenstore-paths.markdown +2 -0
index 9e98d6f..68d3dbf 100644
@@ -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:
 

docs/misc/xenstore-paths.markdown VALUES are strings and can take the following forms: · line 67

Quoted 10 lines
docs/misc/xenstore-paths.markdown +7 -0
@@ -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

#15 lore raw

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

Quoted 41 lines

-----Original Message-----
From: Andrew Cooper [mailto:[email protected]]
Sent: 06 November 2015 18:17
To: Paul Durrant; [email protected]
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

Quoted 7 lines · 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.

Quoted 8 lines
Cc Ian Campbell <[email protected]>
Cc Ian Jackson <[email protected]>
Cc Jan Beulich <[email protected]>
Cc Keir Fraser <[email protected]>
Cc Tim Deegan <[email protected]>
---
 docs/misc/xenstore-paths.markdown | 29

+++++++++++++++++++++++++++++

docs/misc/xenstore-

Quoted 3 lines
 1 file changed, 29 insertions(+)
docs/misc/xenstore- renamed from docs/misc/xenstore-paths.markdown +0 -0

paths.markdown

Quoted 12 lines

index 9e98d6f..68d3dbf 100644

docs/misc/xenstore-paths.markdown +2 -0
@@ -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:
 
Quoted 13 lines

docs/misc/xenstore-paths.markdown VALUES are strings and can take the following forms: · line 67

Quoted 11 lines
docs/misc/xenstore-paths.markdown +7 -0
@@ -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'

Quoted 4 lines

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

Quoted 1 line

~Andrew