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

[Ian Campbell <ian.campbell@xxxxxxxxxx>]

On Tue, 2015-11-24 at 14:40 +0000, George Dunlap wrote:
> 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@xxxxxxxxxx>

With the previously reported (by Juergen and Chyn Yan) typoes fixed:

Acked-by: Ian Campbell <ian.campbell@xxxxxxxxxx>>Â

FWIW (which may not be much) some dev types (e.g. PCI) collapse one or more
of your "<levels>" into a single one by having multiple devid things
encoded in one way or another in the struct, e.g. libxl_device_pci has bus,
device, func etc as fields.

Not sure if that is worth mentioning (or encouraging) as a possibility for
other device types (assuming it makes sense in that schema)

> ---
> 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>
> 
> Changes in v1 (since the RFC):
> 
> - Use <class> rather than <type>, and <level> rather than specifying
> Â controller and device.ÂÂThe idea being to allow SCSI to use
> Â terminology more natural to it (i.e., scsihost, scsitarget, scsilun)
> Â rather than naming things after USB (controller & device).
> 
> - Do not require each <level> to have a deviceid, but just a unique
> Â naming schema.
> 
> - Allow multiple levels.
> 
> - Include the paragraph about domain configuration lists.
> ---
> Âtools/libxl/libxl.h | 65
> +++++++++++++++++++++++++++++++++++++++++++++++++++++
> Â1 file changed, 65 insertions(+)
> 
> diff --git a/tools/libxl/libxl.h b/tools/libxl/libxl.h
> index 6b73848..46bcfe8 100644
> --- a/tools/libxl/libxl.h
> +++ b/tools/libxl/libxl.h
> @@ -1396,6 +1396,71 @@ 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 classes of device,
> + * however, like USB or SCSI, inherently have the need to have a
> + * heiarchy of different levels, with lower-level devices "attached"
> + * to higher-level ones.ÂÂUSB for instance has "controllers" at the
> + * top, which have busses, on which are devices, which consist of
> + * multiple interfaces.ÂÂSCSI has "hosts" at the top, then busses,
> + * targets, and LUNs.
> + *
> + * In that case, for each <class>, there will be a set of funcitons
> + * and types for each <level>.ÂÂFor example, for <class>=usb, there
> + * may be <levels> ctrl (controller) and dev (device), with ctrl being
> + * level 0.
> + *
> + * libxl_device_<class><level0>_<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><level0> libxl_devid namespace.
> + *
> + * Lower-level devices must have a unique way to be identified.ÂÂOne
> + * way to do this would be to name it via the name of the next level
> + * up plus an index; for instance, <ctrl devid, port number>.ÂÂAnother
> + * way would be to have another devid namespace for that level.ÂÂThis
> + * identifier will be used for queries and removals.
> + *
> + * Lower-level devices will will include in their
> + * libxl_device_<class><level> struct a field referring to the unique
> + * index of the level above.ÂÂFor instance, libxl_device_usbdev might
> + * contain the controller devid.
> + *
> + * 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_<class><level>_add receives an empty reference to
> + * the level above, it may return an error.ÂÂOr it may (but is not
> + * required to) automatically choose a suitable device in the level
> + * above to which to attach the new device at this level.ÂÂIt may also
> + * (but is not required to) automatically create a new device at the
> + * level above if no suitable devices exist.ÂÂEach class should
> + * document its behavior.
> + *
> + * libxl_device_<class><level>_list will list all devices of <class>
> + * at <level> in the domain.ÂÂFor example, libxl_class_usbctrl_list
> + * will list all usb controllers; libxl_class_usbdev_list will list
> + * all usb devices across all controllers.
> + *
> + * For each class, the domain config file will contain a single list
> + * for each level.ÂÂlibxl will first iterate through the list of
> + * top-level devices, then iterate through each level down in turn,
> + * adding devices to devices in the level above.ÂÂFor instance, there
> + * will be one list for all usb controllers, and one list for all usb
> + * devices.
> + * 
> + * If libxl_device_<class><level>_add automatically creates
> + * higher-level devices as necessary, then it is permissible for the
> + * higher-level lists to be empty and the device list to have devices
> + * with the field containing a reference to the higher level device
> + * uninitialized.
> Â */
> Â
> Â/* Disks */

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