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

["Chun Yan Liu" <cyliu@xxxxxxxx>]

>>> On 11/24/2015 at 10:40 PM, in message
<1448376011-20217-1-git-send-email-george.dunlap@xxxxxxxxxxxxx>, George Dunlap
<george.dunlap@xxxxxxxxxxxxx> 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.

Some typos. Otherwise, agreed.

- Chunyan
 
>  
> Signed-off-by: George Dunlap <george.dunlap@xxxxxxxxxx> 
> --- 
> 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
                                                                                
    ^^^ functions
> + * 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. 
         <class><level0> ?
> + * 
> + * 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 
                                      ^^^^^ s/will will/will/
> + * 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 
                                                                  
libxl_device_usbctrl_list
> + * will list all usb controllers; libxl_class_usbdev_list will list 
                                               libxl_device_usbdev_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