docs: Document event-channel-based suspend protocol

Document the event channel protocol in xenstore-paths.markdown, in the
section for ~/device/suspend/event-channel.

Protocol reverse-engineered from commentary and commit messages of
  4539594d46f9  Add facility to get notification of domain suspend ...
  17636f47a474  Teach xc_save to use event-channel-based ...
and implementations in
  xc_save (current version)
  libxl (current version)
  linux-2.6.18-xen (mercurial 1241:2993033a77ca)

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
Acked-by: Ian Campbell <ian.campbell@citrix.com>
CC: Keir Fraser <keir@xen.org>
CC: Shriram Rajagopalan <rshriram@cs.ubc.ca>

diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown
index a0fc003a646d806873379f40b4b3b31eddd99409..70ab7f40d34211bff0718649beb76d415a273b0f 100644 (file)
--- a/docs/misc/xenstore-paths.markdown
+++ b/docs/misc/xenstore-paths.markdown
@@ -143,10 +143,29 @@ The size of the video RAM this domain is configured with.
 
 #### ~/device/suspend/event-channel = ""|EVTCHN [w]
 
-The domain's suspend event channel. The use of a suspend event channel
-is optional at the domain's discretion. The toolstack will create this
+The domain's suspend event channel. The toolstack will create this
 path with an empty value which the guest may choose to overwrite.
 
+If the guest overwrites this, it will be with the number of an unbound
+event channel port it has acquired.  The toolstack is expected to use
+an interdomain bind, and then, when it wishes to ask the guest to
+suspend, to signal the event channel.
+
+The guest does not need to explicitly acknowledge the request; indeed,
+there is no explicit signalling by the guest in the reverse direction.
+The guest, when it is ready, simply shuts down (`SCHEDOP_shutdown`)
+with reason code `SHUTDOWN_suspend`.  The toolstack is expected to use
+`XEN_DOMCTL_subscribe` to be alerted to guest state changes, and
+`XEN_SYSCTL_getdomaininfolist` to verify that the domain has
+suspended.
+
+Note that the use of this event channel suspend protocol is optional
+for both sides.  By writing a non-empty string to the node, the guest
+is advertising its support.  However, the toolstack is at liberty to
+use the xenstore-based protocol instead (see ~/control/shutdown,
+below) even if the guest has advertised support for the event channel
+protocol.
+
 #### ~/hvmloader/generation-id-address = ADDRESS [r,HVM,INTERNAL]
 
 The hexadecimal representation of the address of the domain's