[Xen-changelog] [xen master] tools/libs/foreignmemory: Mention restrictions on fork in docs.

[patchbot@xxxxxxx]

commit c4f9e14dea6bf9723775332721af736f615cf24d
Author:     Ian Campbell <ian.campbell@xxxxxxxxxx>
AuthorDate: Thu Sep 24 17:14:45 2015 +0100
Commit:     Ian Campbell <ian.campbell@xxxxxxxxxx>
CommitDate: Fri Jan 22 12:24:18 2016 +0000

    tools/libs/foreignmemory: Mention restrictions on fork in docs.
    
    Signed-off-by: Ian Campbell <ian.campbell@xxxxxxxxxx>
    Acked-by: Wei Liu <wei.liu2@xxxxxxxxxx>
---
 .../libs/foreignmemory/include/xenforeignmemory.h  |   33 +++++++++++++++++++-
 1 files changed, 32 insertions(+), 1 deletions(-)

diff --git a/tools/libs/foreignmemory/include/xenforeignmemory.h 
b/tools/libs/foreignmemory/include/xenforeignmemory.h
index 04ff548..a6d1bdb 100644
--- a/tools/libs/foreignmemory/include/xenforeignmemory.h
+++ b/tools/libs/foreignmemory/include/xenforeignmemory.h
@@ -32,13 +32,44 @@ typedef struct xentoollog_logger xentoollog_logger;
 typedef struct xenforeignmemory_handle xenforeignmemory_handle;
 
 /*
- * Return a handle onto the hypercall driver.  Logs errors.
+ * Return a handle onto the foreign memory mapping driver.  Logs errors.
+ *
+ * Note: After fork(2) a child process must not use any opened
+ * foreignmemory 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
+ * foreignmemory.
+ *
+ * Calling exec(2) in a child will safely (and reliably) reclaim any
+ * resources which were allocated via a xenforeignmemory_handle in the
+ * parent.
+ *
+ * A child which does not call exec(2) may safely call
+ * xenforeignmemory_close() on a xenforeignmemory_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 xenforeignmemory_close() is the only safe operation on a
+ * xenforeignmemory_handle which has been inherited.
  */
 xenforeignmemory_handle *xenforeignmemory_open(xentoollog_logger *logger,
                                                unsigned open_flags);
 
 /*
  * Close a handle previously allocated with xenforeignmemory_open().
+ *
+ * Under normal circumstances (i.e. not in the child after a fork)
+ * xenforeignmemory_unmap() should be used on all mappings allocated
+ * by xenforeignmemory_map() 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
+ * xenforeignmemory_handle in a child after a
+ * fork. xenforeignmemory_unmap() must not be called under such
+ * circumstances.
  */
 int xenforeignmemory_close(xenforeignmemory_handle *fmem);
 
--
generated by git-patchbot for /home/xen/git/xen.git#master

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