Re: [PATCH V3 3/6] libxl: add pvusb API

[Ian Campbell <ian.campbell@citrix.com>]

On Tue, 2015-05-19 at 19:06 +0100, George Dunlap wrote:
> > diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
> > index 6bc75c5..cbe3519 100644
> > --- a/tools/libxl/libxl.h
> > +++ b/tools/libxl/libxl.h
> > @@ -114,6 +114,12 @@
> >  #define LIBXL_HAVE_DOMAIN_NODEAFFINITY 1
> >
> >  /*
> > + * LIBXL_HAVE_PVUSB indicates the functions for doing hot-plug of
> > + * USB devices through pvusb.
> > + */
> > +#define LIBXL_HAVE_PVUSB 1
> 
> It seems like we should document somewhere how we expect these to be
> used -- namely the connection between usbctrl and usb devices.  In
> particular, that you can either add a usbctrl, and then add a usb
> device to it specifically; or if you don't specify a usbctrl when
> calling usb_add, it will find the most reasonable one to add it to,
> even creating one for you if you didn't have one.

(I've not checked if this exists in the series yet, but...)

I'd like to see some docs added to libxl.h as an addendum to the
existing:

 * Devices
 * =======
 *
 * Each device is represented by a libxl_device_<TYPE> data structure
 ...

stuff which describes the general form of interfaces used for those
classes of device which distinguish the controller from the devices
themselves in the libxl API.

The new docs should then be applicable to e..g the pvscsi stuff as well.

The goal is to avoid having numerous subtly different style of device
interaction in the libxl API by grouping them into the least number of
logical groups (thus far 2: ones with explicit controllers and those
without) each with a consistent API.

Ian.