From: Ian Campbell <ian.campbell@citrix.com>
Date: Thu, 28 Jan 2016 11:19:25 +0000 (+0000)
Subject: libxendevicemodel: placeholders docs for xencall style forking restrictions
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=28cbfbcfaf0fd52b1a8cd79750ddb1d1cfa0875c;p=people%2Fliuw%2Flibxenctrl-split%2Fxen.git

libxendevicemodel: placeholders docs for xencall style forking restrictions

XXX TBD
libxendevicemodel needs to use xencall_alloc_buffer_pages, so is
subject to those constraints. Need to figure out exact wording.
---

diff --git a/tools/libs/devicemodel/include/xendevicemodel.h b/tools/libs/devicemodel/include/xendevicemodel.h
index 331e6e42b8..f859e023cb 100644
--- a/tools/libs/devicemodel/include/xendevicemodel.h
+++ b/tools/libs/devicemodel/include/xendevicemodel.h
@@ -57,6 +57,28 @@ typedef struct xendevicemodel_handle xendevicemodel_handle;
  * failure to restrict will be fatal. xendevicemodel_open() will
  * return NULL setting errno to EPERM. In this case *r_restricted will
  * not be updated.
+ *
+ * XXX boilerplate from xencall TBD properly once it's clear if this
+ * handle will be capable of establishing any complicated mappings.
+ *
+ * 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 xendevicemodel_handle in the parent.
+ *
+ * A child which does not call exec(2) may safely call xencall_close()
+ * on a xendevicemodel_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
+ * xendevicemodel_handle which has been inherited.
  */
 xendevicemodel_handle *xendevicemodel_open(struct xentoollog_logger *logger,
                                            domid_t domid,
@@ -65,6 +87,18 @@ xendevicemodel_handle *xendevicemodel_open(struct xentoollog_logger *logger,
 
 /*
  * Close a handle previously allocated with xendevicemodel_open().
+ *
+ * XXX boilerplate from xencall TBD properly once it is clear what if
+ * any mappings might be established.
+ *
+ * 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
+ * xendevicemodel_handle in a child after a fork. xencall_free_*() must not
+ * be called under such circumstances.
  */
 int xendevicemodel_close(xendevicemodel_handle *dm);