@@ -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);
@@ -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);
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 <ian.campbell@citrix.com> --- v7: New --- tools/libs/call/include/xencall.h | 28 ++++++++++++++++++++++++++++ tools/libs/evtchn/include/xenevtchn.h | 23 +++++++++++++++++++---- 2 files changed, 47 insertions(+), 4 deletions(-)