[PATCH 02/23] xen: Document that EVTCHNOP_bind_interdomain signals

[Ian Jackson <ian.jackson@eu.citrix.com>]

EVTCHNOP_bind_interdomain signals the event channel.  Document this.

Also explain the usual use pattern.

Signed-off-by: Ian Jackson <Ian.Jackson@eu.citrix.com>
CC: Keir Fraser <keir@xen.org>
CC: Jan Beulich <JBeulich@suse.com>
---
 xen/include/public/event_channel.h |   11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/xen/include/public/event_channel.h b/xen/include/public/event_channel.h
index b78ee32..49ac8cc 100644
--- a/xen/include/public/event_channel.h
+++ b/xen/include/public/event_channel.h
@@ -101,6 +101,17 @@ typedef struct evtchn_alloc_unbound evtchn_alloc_unbound_t;
  * a port that is unbound and marked as accepting bindings from the calling
  * domain. A fresh port is allocated in the calling domain and returned as
  * <local_port>.
+ *
+ * In case the peer domain has already tried to set our event channel
+ * pending, before it was bound, EVTCHNOP_bind_interdomain always sets
+ * the local event channel pending.
+ *
+ * The usual pattern of use, in the guest's upcall (or subsequent
+ * handler) is as follows: (Re-enable the event channel for subsequent
+ * signalling and then) check for the existence of whatever condition
+ * is being waited for by other means, and take whatever action is
+ * needed (if any).
+ *
  * NOTES:
  *  1. <remote_dom> may be DOMID_SELF, allowing loopback connections.
  */
-- 
1.7.10.4