From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ian Jackson Subject: [PATCH 01/23] xen: Document XEN_DOMCTL_subscribe Date: Tue, 17 Dec 2013 18:35:15 +0000 Message-ID: <1387305337-15355-2-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: Ian Campbell , Stefano Stabellini , George Dunlap , Ian Jackson , Jan Beulich , Shriram Rajagopalan List-Id: xen-devel@lists.xenproject.org Arguably this domctl is misnamed. But, for now, document its actual behaviour (reverse-engineered from the code and found in the commit message for 4539594d46f9) under its actual name. Signed-off-by: Ian Jackson CC: Stefano Stabellini CC: Ian Campbell CC: Shriram Rajagopalan CC: Jan Beulich --- tools/libxc/xenctrl.h | 4 +++- xen/include/public/domctl.h | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/tools/libxc/xenctrl.h b/tools/libxc/xenctrl.h index 6e58ebe..096a590 100644 --- a/tools/libxc/xenctrl.h +++ b/tools/libxc/xenctrl.h @@ -1452,8 +1452,10 @@ int xc_version(xc_interface *xch, int cmd, void *arg); int xc_flask_op(xc_interface *xch, xen_flask_op_t *op); /* - * Subscribe to state changes in a domain via evtchn. + * Subscribe to domain suspend via evtchn. * Returns -1 on failure, in which case errno will be set appropriately. + * Just calls XEN_DOMCTL_subscribe - see the caveats for that domctl + * (in its doc comment in domctl.h). */ int xc_domain_subscribe_for_suspend( xc_interface *xch, domid_t domid, evtchn_port_t port); diff --git a/xen/include/public/domctl.h b/xen/include/public/domctl.h index 01a3652..91f01fa 100644 --- a/xen/include/public/domctl.h +++ b/xen/include/public/domctl.h @@ -619,6 +619,22 @@ typedef struct xen_domctl_cpuid xen_domctl_cpuid_t; DEFINE_XEN_GUEST_HANDLE(xen_domctl_cpuid_t); #endif +/* + * Arranges that if the domain suspends (specifically, if it shuts + * down with code SHUTDOWN_suspend), this event channel will be + * notified. + * + * This is _instead of_ the usual notification to the global + * VIRQ_DOM_EXC. (In most systems that pirq is owned by xenstored.) + * + * Only one subscription per domain is possible. Last subscriber + * wins; others are silently displaced. + * + * NB that contrary to the rather general name, it only applies to + * domain shutdown with code suspend. Shutdown for other reasons + * (including crash), and domain death, are notified to VIRQ_DOM_EXC + * regardless. + */ /* XEN_DOMCTL_subscribe */ struct xen_domctl_subscribe { uint32_t port; /* IN */ -- 1.7.10.4