From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ian Jackson Subject: [PATCH 03/23] docs: Document event-channel-based suspend protocol Date: Tue, 17 Dec 2013 18:35:17 +0000 Message-ID: <1387305337-15355-4-git-send-email-ian.jackson@eu.citrix.com> References: <1387305337-15355-1-git-send-email-ian.jackson@eu.citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1387305337-15355-1-git-send-email-ian.jackson@eu.citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: xen-devel@lists.xensource.com Cc: Keir Fraser , Ian Campbell , Stefano Stabellini , George Dunlap , Ian Jackson , Shriram Rajagopalan List-Id: xen-devel@lists.xenproject.org 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 CC: Keir Fraser CC: Shriram Rajagopalan --- docs/misc/xenstore-paths.markdown | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown index a0fc003..70ab7f4 100644 --- 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 -- 1.7.10.4