[PATCH XEN v7 26/29] tools/libs/{call, evtchn}: Document requirements around forking.

[Ian Campbell <ian.campbell@citrix.com>]

Much like for gnttab and foreignmemory xencall hypercall buffers need
care.

Evtchn is a bit simpler (no magic mappings) but may not work from
parent + child simultaneously, document "parent only" since it is
consistent with the others.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
---
v7: New
---
 tools/libs/call/include/xencall.h     | 28 ++++++++++++++++++++++++++++
 tools/libs/evtchn/include/xenevtchn.h | 23 +++++++++++++++++++----
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/tools/libs/call/include/xencall.h b/tools/libs/call/include/xencall.h
index 3f325f0..559624a 100644
--- a/tools/libs/call/include/xencall.h
+++ b/tools/libs/call/include/xencall.h
@@ -36,11 +36,39 @@ typedef struct xencall_handle xencall_handle;
 
 /*
  * Return a handle onto the hypercall driver.  Logs errors.
+ * *
+ * Note: After fork(2) a child process must not use any opened
+ * xencall handle inherited from their parent, nor access any
+ * hypercall argument buffers associated with that handle.
+ *
+ * The child must open a new handle if they want to interact with
+ * xencall.
+ *
+ * Calling exec(2) in a child will safely (and reliably) reclaim any
+ * resources which were allocated via a xencall_handle in the parent.
+ *
+ * A child which does not call exec(2) may safely call xencall_close()
+ * on a xencall_handle inherited from their parent. This will attempt
+ * to reclaim any resources associated with that handle. Note that in
+ * some implementations this reclamation may not be completely
+ * effective, in this case any affected resources remain allocated.
+ *
+ * Calling xencall_close() is the only safe operation on a
+ * xencall_handle which has been inherited.
  */
 xencall_handle *xencall_open(xentoollog_logger *logger, unsigned open_flags);
 
 /*
  * Close a handle previously allocated with xencall_open().
+ *
+ * Under normal circumstances (i.e. not in the child after a fork) any
+ * allocated hypercall argument buffers should be freed using the
+ * appropriate xencall_free_*() prior to closing the handle in order
+ * to free up resources associated with those mappings.
+ *
+ * This is the only function which may be safely called on a
+ * xencall_handle in a child after a fork. xencall_free_*() must not
+ * be called under such circumstances.
  */
 int xencall_close(xencall_handle *xcall);
 
diff --git a/tools/libs/evtchn/include/xenevtchn.h b/tools/libs/evtchn/include/xenevtchn.h
index 60da2a3..bb24462 100644
--- a/tools/libs/evtchn/include/xenevtchn.h
+++ b/tools/libs/evtchn/include/xenevtchn.h
@@ -45,10 +45,25 @@ typedef struct xentoollog_logger xentoollog_logger;
  * Return a handle to the event channel driver, or NULL on failure, in
  * which case errno will be set appropriately.
  *
- * Note:
- * After fork a child process must not use any opened evtchn
- * handle inherited from their parent. They must open a new handle if
- * they want to interact with evtchn.
+ * Note: After fork(2) a child process must not use any opened evtchn
+ * handle inherited from their parent, nor access any grant mapped
+ * areas associated with that handle.
+ *
+ * The child must open a new handle if they want to interact with
+ * evtchn.
+ *
+ * Calling exec(2) in a child will safely (and reliably) reclaim any
+ * allocated resources via a xenevtchn_handle in the parent.
+ *
+ * A child which does not call exec(2) may safely call
+ * xenevtchn_close() on a xenevtchn_handle inherited from their
+ * parent. This will attempt to reclaim any resources associated with
+ * that handle. Note that in some implementations this reclamation may
+ * not be completely effective, in this case any affected resources
+ * remain allocated.
+ *
+ * Calling xenevtchn_close() is the only safe operation on a
+ * xenevtchn_handle which has been inherited.
  */
 /* Currently no flags are defined */
 xenevtchn_handle *xenevtchn_open(xentoollog_logger *logger, unsigned open_flags);
-- 
2.1.4