[RFC] libxc: xc_hvm_build_with_params() proposal

[David Vrabel <david.vrabel@citrix.com>]

I needed to add another parameter to the xc_hvm_build*() family of
functions (the size of the MMIO region) and I has having trouble coming
up with a new name (xc_hvm_build_target_mmio()?) and more parameters
would require even more new names
(xc_hvm_build_target_mem_mmio_colour_wibblyness...) so here's a proposal
for a xc_hvm_build_with_params() call that takes a structure of
parameters for the new HVM domain.

It's a bit clunkly as a bunch of function are added to set parameters in
an opaque structure but this does allow the interface to be backwards
compatible,

Thoughts?  Suggestions on a better pattern?

David

diff -r 2d2825c7ee00 tools/libxc/xenguest.h
--- a/tools/libxc/xenguest.h	Thu Feb 09 19:35:11 2012 +0000
+++ b/tools/libxc/xenguest.h	Thu Feb 23 18:26:38 2012 +0000
@@ -164,6 +164,71 @@ int xc_linux_build_mem(xc_interface *xch
                        unsigned int console_evtchn,
                        unsigned long *console_mfn);

+struct xc_hvm_params;
+
+/**
+ * Allocate the HVM parameters for use in a subsequent
+ * xc_hvm_build_from_params() call.
+ * @parm xch libxc context.
+ *
+ * The parameters are all initialized to default values.
+ *
+ * @return the allocated structure or NULL if insufficient memory was
+ * available.
+ */
+struct xc_hvm_params *xc_hvm_params_alloc(xc_interface *xch);
+
+/**
+ * Free the structure previously allocated with xc_hvm_params_alloc().
+ * @parm xch    libxc context.
+ * @parm params the parameters to free.
+ */
+void xc_hvm_params_free(xc_interface *xch, struct xc_hvm_params *params);
+
+/**
+ * Set the memory size parameter.
+ * @parm params   the HVM parameters.
+ * @parm mem_size memory size in \em bytes.
+ */
+void xc_hvm_param_set_mem_size(struct xc_hvm_params *params,
+                               uint64_t mem_size);
+
+/**
+ * Set the memory target parameter.
+ * @parm params    the HVM parameters.
+ * @parm mem_target memory target in \em bytes.
+ */
+void xc_hvm_param_set_mem_target(struct xc_hvm_params *params,
+                                 uint64_t mem_target);
+
+/**
+ * Set the minimum MMIO hole size parameter.
+ * @parm params    the HVM parameters.
+ * @parm mmio_size size of the MMIO hole in \em bytes or 0 to use the
+ *                 default size.
+ */
+void xc_hvm_param_set_mmio_size(struct xc_hvm_params *params,
+                                uint64_t mmio_size);
+
+void xc_hvm_param_set_image(struct xc_hvm_params *params,
+                            void *image, size_t image_size);
+void xc_hvm_param_set_image_file_name(struct xc_hvm_params *params,
+                                      const char *image_file_name);
+
+/**
+ * Build a HVM domain using a set of parameters.
+ * @parm xch    libxc context handle.
+ * @parm domid  domain ID for the new domain.
+ * @parm params parameters for the new domain.
+ *
+ * The memory size and image parameters are required and should be set
+ * with xc_hvm_param_set_mem_size() and xc_hvm_param_set_image() (or
+ * xc_hvm_param_set_image_file()).
+ */
+int xc_hvm_build_with_params(xc_interface *xch,
+                             uint32_t domid,
+                             const struct xc_hvm_params *params);
+
 int xc_hvm_build(xc_interface *xch,
                  uint32_t domid,
                  int memsize,