From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ian Campbell Subject: [PATCH XEN v7 26/29] tools/libs/{call, evtchn}: Document requirements around forking. Date: Wed, 16 Dec 2015 12:31:33 +0000 Message-ID: <1450269096-27598-27-git-send-email-ian.campbell@citrix.com> References: <1450269007.4053.48.camel@citrix.com> <1450269096-27598-1-git-send-email-ian.campbell@citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1450269096-27598-1-git-send-email-ian.campbell@citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: ian.jackson@eu.citrix.com, wei.liu2@citrix.com, xen-devel@lists.xen.org Cc: Ian Campbell List-Id: xen-devel@lists.xenproject.org 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 --- v7: New --- 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 60da2a3..bb24462 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); -- 2.1.4