Signed-off-by: Ian Campbell <ian.campb...@citrix.com>
---
v6: Also discuss recovering the memory.
v7: Further clarifications regarding forking based on ML discussions.
(Dropped Wei's ack)
---
.../libs/foreignmemory/include/xenforeignmemory.h | 33 +++++++++++++++++++++-
1 file changed, 32 insertions(+), 1 deletion(-)
diff --git a/tools/libs/foreignmemory/include/xenforeignmemory.h
b/tools/libs/foreignmemory/include/xenforeignmemory.h
index 87f72fd..36f3753 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 *xmem);
--
2.1.4
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xen.org
http://lists.xen.org/xen-devel
