From c4f9e14dea6bf9723775332721af736f615cf24d Mon Sep 17 00:00:00 2001 From: Ian Campbell Date: Thu, 24 Sep 2015 17:14:45 +0100 Subject: [PATCH] tools/libs/foreignmemory: Mention restrictions on fork in docs. Signed-off-by: Ian Campbell Acked-by: Wei Liu --- .../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 04ff548b45..a6d1bdb3a7 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); -- 2.30.2