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 331e6e42b8f9f676a344bded0a7f957483b0afd5..f859e023cbed33a369969024b8d11123d84f6002 100644 (file)
--- 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);