tools/libs/foreignmemory: Mention restrictions on fork in docs.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Wei Liu <wei.liu2@citrix.com>

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);