libxl: Document _init/_dispose/_setdefault functions.

Subsequent patches will transition to them.

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>

2 files changed, 60 insertions, 6 deletions

diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
index 9eb8347bbb..fb2c44c597 100644
--- a/tools/libxl/libxl.h
+++ b/tools/libxl/libxl.h
@@ -124,6 +124,50 @@
  * Therefore public functions which initialize a libxl__gc MUST call
  * libxl__free_all() before returning.
  */
+/*
+ * libxl types
+ *
+ * Most libxl types are defined by the libxl IDL (see
+ * libxl_types.idl). The library provides a common set of methods for
+ * initialising and freeing these types.
+ *
+ * void libxl_<type>_init(<type> *p):
+ *
+ *    Initialises the members of "p" to all defaults. These may either
+ *    be special value which indicates to the library that it should
+ *    select an appropriate default when using this field or actual
+ *    default values.
+ *
+ *    Some fields within a data type (e.g. unions) cannot be sensibly
+ *    initialised without further information. In these cases a
+ *    separate subfield initialisation function is provided (see
+ *    below).
+ *
+ *    An instance which has been initialised using this method can
+ *    always be safely passed to the dispose function (see
+ *    below). This is true even if the data type contains fields which
+ *    require a separate call to a subfield initialisation function.
+ *
+ *    This method is provided for any aggregate type which is used as
+ *    an input parameter.
+ *
+ * void libxl_<type>_init_<subfield>(<type> *p, subfield):
+ *
+ *    Initialise those parts of "p" which are not initialised by the
+ *    main init function due to the unknown value of "subfield". Sets
+ *    p->subfield as well as initialising any fields to their default
+ *    values.
+ *
+ *    p->subfield must not have been previously initialised.
+ *
+ *    This method is provided for any aggregate type.
+ *
+ * void libxl_<type>_dispose(instance *p):
+ *
+ *    Frees any dynamically allocated memory used by the members of
+ *    "p" but not the storage used by "p" itself (this allows for the
+ *    allocation of arrays of types and for the composition of types).
+ */
 #ifndef LIBXL_H
 #define LIBXL_H
 
@@ -405,8 +449,9 @@ void libxl_vminfo_list_free(libxl_vminfo *list, int nr);
  * additional data type libxl_device_<TYPE>_getinfo which contains
  * further runtime information about the device.
  *
- * A common set of methods are available for each device type. These
- * are described below.
+ * In addition to the general methods available for libxl types (see
+ * "libxl types" above) a common set of methods are available for each
+ * device type. These are described below.
  *
  * Querying
  * --------
@@ -424,10 +469,6 @@ void libxl_vminfo_list_free(libxl_vminfo *list, int nr);
  * Creation / Control
  * ------------------
  *
- * libxl_device_<type>_init(ctx, device):
- *
- *    Initalises device to a default configuration.
- *
  * libxl_device_<type>_add(ctx, domid, device):
  *
  *   Adds the given device to the specified domain. This can be called
diff --git a/tools/libxl/libxl_internal.h b/tools/libxl/libxl_internal.h
index 46e131abc7..467bedee71 100644
--- a/tools/libxl/libxl_internal.h
+++ b/tools/libxl/libxl_internal.h
@@ -665,6 +665,19 @@ _hidden int libxl__device_destroy(libxl__gc *gc, libxl__device *dev);
 _hidden int libxl__devices_destroy(libxl__gc *gc, uint32_t domid);
 _hidden int libxl__wait_for_backend(libxl__gc *gc, char *be_path, char *state);
 
+/*
+ * For each aggregate type which can be used as an input we provide:
+ *
+ * int libxl__<type>_setdefault(gc, <type> *p):
+ *
+ *     Idempotently sets any members of "p" which is currently set to
+ *     a special value indicating that the defaults should be used
+ *     (per libxl_<type>_init) to a specific value.
+ *
+ *     All libxl API functions are expected to have arranged for this
+ *     to be called before using any values within these structures.
+ */
+
 /* Arranges that dev will be removed from its guest.  When
  * this is done, the ao will be completed.  An error
  * return from libxl__initiate_device_remove means that the ao