From: Ian Jackson Date: Tue, 17 Dec 2013 18:35:17 +0000 (+0000) Subject: docs: Document event-channel-based suspend protocol X-Git-Tag: archive/raspbian/4.8.0-1+rpi1~1^2~5714 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=a8da8249506b55fe9314462e90cc6749fd50a5fa;p=xen.git 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 Acked-by: Ian Campbell CC: Keir Fraser CC: Shriram Rajagopalan --- diff --git a/docs/misc/xenstore-paths.markdown b/docs/misc/xenstore-paths.markdown index a0fc003a64..70ab7f40d3 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