[Xen-changelog] [xen master] docs: Introduce xenstore paths for PV control features

[patchbot@xxxxxxx]

commit 85e3b08eb73cd7ea0578807e4fd666ecbbca143e
Author:     Paul Durrant <paul.durrant@xxxxxxxxxx>
AuthorDate: Tue Nov 17 11:32:02 2015 +0000
Commit:     Ian Campbell <ian.campbell@xxxxxxxxxx>
CommitDate: Tue Nov 24 16:19:00 2015 +0000

    docs: Introduce xenstore paths for PV control features
    
    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@xxxxxxxxxx>
    Cc: Ian Campbell <ian.campbell@xxxxxxxxxx>
    Acked-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
    Cc: Jan Beulich <jbeulich@xxxxxxxx>
    Cc: Keir Fraser <keir@xxxxxxx>
    Cc: Tim Deegan <tim@xxxxxxx>
---
 docs/misc/xenstore-paths.markdown |   39 +++++++++++++++++++++++++++++++++++-
 1 files 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
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog