From f63b6c6ddcb44b5551e2f7748b0f5de6d73b35e5 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 17 Dec 2013 18:35:15 +0000 Subject: [PATCH] xen: Document XEN_DOMCTL_subscribe 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 Acked-by: 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 6e58ebeb5e..096a590301 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 01a3652a5f..91f01facf7 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 */ -- 2.39.5