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

[Paul Durrant <paul.durrant@citrix.com>]

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