[Xen-changelog] [xen master] tools/libs/{call, evtchn}: Document requirements around forking.

[patchbot@xxxxxxx]

commit 0bd2a73ef234ce28dda1e990de2724a36765ec6e
Author:     Ian Campbell <ian.campbell@xxxxxxxxxx>
AuthorDate: Fri Dec 11 17:31:26 2015 +0000
Commit:     Ian Campbell <ian.campbell@xxxxxxxxxx>
CommitDate: Fri Jan 22 12:24:21 2016 +0000

    tools/libs/{call,evtchn}: Document requirements around forking.
    
    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@xxxxxxxxxx>
    Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
---
 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 428d54c..4d26161 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);
--
generated by git-patchbot for /home/xen/git/xen.git#master

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog