[Xen-devel] [PATCH RFC v1] libxl: Introduce a template for devices with a controller

[George Dunlap <george.dunlap@xxxxxxxxxxxxx>]

We have several outstanding patch series which add devices that have
two levels: a controller and individual devices attached to that
controller.

In the interest of consistency, this patch introduces a section that
sketches out a template for interfaces for such devices.

Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxxxxx>
---
CC: Ian Campbell <ian.campbell@xxxxxxxxxx>
CC: Ian Jackson <ian.jackson@xxxxxxxxxx>
CC: Wei Liu <wei.liu2@xxxxxxxxxx>
CC: Juergen Gross <jgross@xxxxxxxx>
CC: Chun Yan Liu <cyliu@xxxxxxxx>
CC: Olaf Hering <olaf@xxxxxxxxx>

So, this is definitely RFC -- I tried to spec things out in a way that
made sense, but I often just chose something that I thought would be a
sensible starting point for discussion.

This spec looks a lot more like the PVUSB spec than the PVSCSI spec,
in part because I think the PVUSB spec has already had a lot more
thought that's gone into it.

A couple of random points to discuss:

* Calling things "controllers", using <type>ctrl for the device name,
  and using "ctrl" as the field name for the devid of the controller
  in the individual devices.

* I've said that having an index (port, lun, whatever) is optional.
  Do we want to make that requred?  Do we want it to have a consistent
  name?  In the case of emulated USB, we can't really specify to qemu
  what port the device gets attached to, so I'm tempted to say it's
  not required; but even there we could always give it a port number
  just for name's sake.

* Naming sub-devices.  We need to have a way to uniquely name both
  controllers and subdevices.  Here I've said that we will have both
  <type>ctrl and <type> devid namespaces, mainly because in the
  previous point I opted not to require an index.  Another option
  would be not to have another devid namespace, but to use
  <ctrl,index> as the unique identifier.  (This would mean requiring
  the index/port/lun specification above.)

* libxl_device_<type>_list listing devices across all controllers.  I
  think this is the most practical thing to do, but one could imagine
  wanting to query by controller ID instead.

Feedback welcome.
---
 tools/libxl/libxl.h | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
index 2ed7194..d757845 100644
--- a/tools/libxl/libxl.h
+++ b/tools/libxl/libxl.h
@@ -1234,6 +1234,52 @@ void libxl_vtpminfo_list_free(libxl_vtpminfo *, int 
nr_vtpms);
  *
  *   This function does not interact with the guest and therefore
  *   cannot block on the guest.
+ *
+ * Controllers
+ * -----------
+ *
+ * Most devices are treated individually.  Some devices however, like
+ * USB or SCSI, inherently have the need to have "busses" or
+ * "controllers" to which individual devices can be attached.
+ *
+ * In that case, for each <type>, there will be two sets of the
+ * functions, types, and devid namespaces outlined above: one based on
+ * '<type>', and one based on '<type>ctrl'.
+ *
+ * In those cases, libxl_device_<type>ctrl_<function> will act more or
+ * less like top-level non-bus devices: they will either create or
+ * accept a libxl_devid which will be unique within the
+ * <type>ctrl libxl_devid namespace.
+ *
+ * Second-level devices which will be attached to a controller will
+ * include in their libxl_device_<type> a field called ctrl, which
+ * will be the libxl_devid of the corresponding controller.  It may also
+ * include an index onto that bus, that represents (for example) a USB
+ * port or a SCSI LUN.
+ *
+ * These second-level devices will also have their own devid which
+ * will be unique within the <type> devid namespace, and will be used
+ * for queries or removals.
+ *
+ * In the case where there are multiple different ways to implement a
+ * given device -- for instance, one which is fully PV and one which
+ * uses an emulator -- the controller will contain a field which
+ * specifies what type of implementation is used.  The implementations
+ * of individual devices will be known by the controller to which they are
+ * attached.
+ *
+ * If libxl_device_<type>_add receives an uninitialized ctrl devid, it
+ * may return an error.  Or it may (but is not required to) choose to
+ * automatically choose a suitable controller to which to attach the
+ * new device.  It may also (but is not required to) automatically
+ * create a new controller if no suitable controllers exist.
+ * Individual devices should document their behavior.
+ *
+ * libxl_device_<type>ctrl_list will list all controllers for the domain.
+ *
+ * libxl_device_<type>_list will list all devices for all controllers
+ * for the domain.  The individual libxl_device_<type> will include
+ * the devid of the controller to which it is attached.
  */
 
 /* Disks */
-- 
1.9.1


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel