[Libvir] RFC: format for mapping host devices to guest

I'm considering the problem of mapping host USB devices through to the guest as one of the 2 remaining bits of USB support needed (the other being the mapping disks through as USB mass storage). I have previously mentioned some ideas in this mail, though looking back on this I don't much like them https://www.redhat.com/archives/libvir-list/2007-March/msg00205.html Also, there was just the message about a desire to support mapping of PCI devices. The USB stuff I want todo with both Xen and QEMU. In Xen, USB device passthrough is based on: usbdevice=host:[bus id].[device id] eg usbdevice=host:003.001 Or usbdevice=host:[vendor id]:[product id] eg usbdevice=host:0483:2016 In QEMU, USB device passthrough is pretty much the same with command line args: -usbdevice host:[bus id].[device id] eg -usbdevice host:003.001 Or -usbdevice host:[vendor id]:[product id] eg -usbdevice host:0483:2016 Finally, in Xen, PCI device passthrough is done with pci=['pci device id',....] eg pci=['00:1f.3'] So we need some form of element under the <devices> section per device to map through. At minimum this will need the source device info. If we are to support unplugging of USB devices in QEMU it is neccessary to have the target device id - this is generated by QEMU when attaching the USB device. So to attach a device: <host bus='usb'> <source device="003.001"/> </host> Or <host bus='usb'> <source vendor='0483' product='2016'> </host> The first form is useful for live hotplug - where you know the exact device instance. The second form is useful for permanent config - you don't know what device id it'll have since it may be plugged into the host in any order. When splitting the XML back out, QEMU would fill in the target info giving us either: <host bus='usb'> <source dev='003.001'/> <target dev='001.005'/> </host> Or <host bus='usb'> <source vendor='0483' product='2016'/> <target dev='001.005'/> </host> This is suitable for giving to virDomainDetachDevice() - we use the target dev for the QEMU monitor 'usb-detach' command. Now PCI would be similar - no hotplug to worry about here though, and no need (or availability) or target info. So the XML would simply be <host bus='pci'> <source dev='00:1f.3'/> </host> NB I choose 'host' as the element name since we're basically giving the guest an arbitrary host device. My previous email had thought about calling it 'bus' but we're not really defining a bus in this context and there may very well be some scenario in the future where we do need to represent the concept of a 'bus' in the XML directly. Dan. -- |=- Red Hat, Engineering, Emerging Technologies, Boston. +1 978 392 2496 -=| |=- Perl modules: http://search.cpan.org/~danberr/ -=| |=- Projects: http://freshmeat.net/~danielpb/ -=| |=- GnuPG: 7D3B9505 F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 -=|

On Thu, Jul 19, 2007 at 01:17:37AM +0100, Daniel P. Berrange wrote:
So we need some form of element under the <devices> section per device to map through. At minimum this will need the source device info. If we are to support unplugging of USB devices in QEMU it is neccessary to have the target device id - this is generated by QEMU when attaching the USB device.
So to attach a device:
<host bus='usb'> <source device="003.001"/> </host>
Or
<host bus='usb'> <source vendor='0483' product='2016'> </host>
The first form is useful for live hotplug - where you know the exact device instance. The second form is useful for permanent config - you don't know what device id it'll have since it may be plugged into the host in any order.
When splitting the XML back out, QEMU would fill in the target info giving us either:
<host bus='usb'> <source dev='003.001'/> <target dev='001.005'/> </host>
Or
<host bus='usb'> <source vendor='0483' product='2016'/> <target dev='001.005'/> </host>
This is suitable for giving to virDomainDetachDevice() - we use the target dev for the QEMU monitor 'usb-detach' command.
Hum, that's the usual internal/external naming problem. Both have different context of use and life span. The vendor/product identifies the kind of device, it may not be sufficient to actually identify one of them (one could perfectly plug two usb mouse one for each side of keyboard), but it's the identifier which describe the functional requirement. And the other one is an internal name which may change over time. IMHO you should output both, then depending how you will reuse that XML fragment one or the other may be used, this could actually be one argument to split the device definition entry point and the device modification. For the definition you would use the vendor/product identifiers, while for example to simulate a disk change on an USB CDRom reader you would use device numbers. <host bus='usb'> <device vendor='0471' product='0311' name='Philips PCVC740K ToUcam Pro'/> <source dev='003.001'/> <target dev='001.005'/> </host> At the XML format you would require device or source to be present, possibly both and name would be an optional attribute (which need to be XML escaped).
Now PCI would be similar - no hotplug to worry about here though, and no need (or availability) or target info. So the XML would simply be
<host bus='pci'> <source dev='00:1f.3'/> </host>
You may still have twice the same kind of card plugged on a PCI bus so just vendor/product doesn't sound sufficient to me. PCI device are more likely to be static, I would consider vendor/product to be user informations, but the code would always use the device if present.
NB I choose 'host' as the element name since we're basically giving the guest an arbitrary host device. My previous email had thought about calling it 'bus' but we're not really defining a bus in this context and there may very well be some scenario in the future where we do need to represent the concept of a 'bus' in the XML directly.
Fine by me. Daniel -- Red Hat Virtualization group http://redhat.com/virtualization/ Daniel Veillard | virtualization library http://libvirt.org/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/

On Thu, Jul 19, 2007 at 06:17:29AM -0400, Daniel Veillard wrote:
On Thu, Jul 19, 2007 at 01:17:37AM +0100, Daniel P. Berrange wrote:
So to attach a device:
<host bus='usb'> <source device="003.001"/> </host>
Or
<host bus='usb'> <source vendor='0483' product='2016'> </host>
The first form is useful for live hotplug - where you know the exact device instance. The second form is useful for permanent config - you don't know what device id it'll have since it may be plugged into the host in any order.
When splitting the XML back out, QEMU would fill in the target info giving us either:
<host bus='usb'> <source dev='003.001'/> <target dev='001.005'/> </host>
Or
<host bus='usb'> <source vendor='0483' product='2016'/> <target dev='001.005'/> </host>
This is suitable for giving to virDomainDetachDevice() - we use the target dev for the QEMU monitor 'usb-detach' command.
Hum, that's the usual internal/external naming problem. Both have different context of use and life span. The vendor/product identifies the kind of device, it may not be sufficient to actually identify one of them (one could perfectly plug two usb mouse one for each side of keyboard), but it's the identifier which describe the functional requirement. And the other one is an internal name which may change over time.
Yep, I realize you could plug two of the same thing in - there's unfortunately no way to distinguish. AFAIK qemu will just attach teh first device with matching product & name, which is pretty much the best you can do. If you need reliable naming then you'd have to do hotplug once the domain is running using the actual device id instead of vendor+product.
IMHO you should output both, then depending how you will reuse that XML fragment one or the other may be used, this could actually be one argument to split the device definition entry point and the device modification. For the definition you would use the vendor/product identifiers, while for example to simulate a disk change on an USB CDRom reader you would use device numbers.
<host bus='usb'> <device vendor='0471' product='0311' name='Philips PCVC740K ToUcam Pro'/> <source dev='003.001'/> <target dev='001.005'/> </host>
At the XML format you would require device or source to be present, possibly both and name would be an optional attribute (which need to be XML escaped).
The name doesn't belong here. I've got a separate email to write about a way to enumerate devices on the host - currently virt-manager just calls HAL which obviously doesn't work for remote management. So we need an API for enumerating physical devices - the 'name' attribute for the devices is better placed in there, rather the duplicating in the per-VM config.
Now PCI would be similar - no hotplug to worry about here though, and no need (or availability) or target info. So the XML would simply be
<host bus='pci'> <source dev='00:1f.3'/> </host>
You may still have twice the same kind of card plugged on a PCI bus so just vendor/product doesn't sound sufficient to me. PCI device are more likely to be static, I would consider vendor/product to be user informations, but the code would always use the device if present.
That PCI dev ID is unique AFAIK - the 3 components uniquely identify the PCI device encoding bus+slot or something like that - this is basically the info from 'lspci' on Linux. Dan. -- |=- Red Hat, Engineering, Emerging Technologies, Boston. +1 978 392 2496 -=| |=- Perl modules: http://search.cpan.org/~danberr/ -=| |=- Projects: http://freshmeat.net/~danielpb/ -=| |=- GnuPG: 7D3B9505 F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 -=|

On Thu, Jul 19, 2007 at 02:28:00PM +0100, Daniel P. Berrange wrote:
On Thu, Jul 19, 2007 at 06:17:29AM -0400, Daniel Veillard wrote:
IMHO you should output both, then depending how you will reuse that XML fragment one or the other may be used, this could actually be one argument to split the device definition entry point and the device modification. For the definition you would use the vendor/product identifiers, while for example to simulate a disk change on an USB CDRom reader you would use device numbers.
<host bus='usb'> <device vendor='0471' product='0311' name='Philips PCVC740K ToUcam Pro'/> <source dev='003.001'/> <target dev='001.005'/> </host>
At the XML format you would require device or source to be present, possibly both and name would be an optional attribute (which need to be XML escaped).
The name doesn't belong here. I've got a separate email to write about a way to enumerate devices on the host - currently virt-manager just calls HAL which obviously doesn't work for remote management. So we need an API for enumerating physical devices - the 'name' attribute for the devices is better placed in there, rather the duplicating in the per-VM config.
Well, to me it's a way to express you want such or such functionality in a VM. I would not expect duplication in all instances. But if the user visible string can be accessed from somewhere else, fine, as I said I consider this optional.
Now PCI would be similar - no hotplug to worry about here though, and no need (or availability) or target info. So the XML would simply be
<host bus='pci'> <source dev='00:1f.3'/> </host>
You may still have twice the same kind of card plugged on a PCI bus so just vendor/product doesn't sound sufficient to me. PCI device are more likely to be static, I would consider vendor/product to be user informations, but the code would always use the device if present.
That PCI dev ID is unique AFAIK - the 3 components uniquely identify the PCI device encoding bus+slot or something like that - this is basically the info from 'lspci' on Linux.
Agreed you can use it as the identifier, that should not change (unless card is unplugged/replugged). Daniel -- Red Hat Virtualization group http://redhat.com/virtualization/ Daniel Veillard | virtualization library http://libvirt.org/ veillard@redhat.com | libxml GNOME XML XSLT toolkit http://xmlsoft.org/ http://veillard.com/ | Rpmfind RPM search engine http://rpmfind.net/
participants (2)
-
Daniel P. Berrange
-
Daniel Veillard