[libvirt] USB2 controllers & domain XML

[Daniel P. Berrange]

On Thu, Aug 18, 2011 at 05:18:46PM +0200, Marc-André Lureau wrote:
> Hi
> 
> I have started looking at: https://bugzilla.redhat.com/show_bug.cgi?id=725670
> 
> My initial thought was to just add a new type of controller:
> 
> <controller type='usb2' index='0'/>
> 
> But it also needs the 3 companion UHCI controllers (see bug). We can
> either include them implicitely (not really elegant in libvirt, but
> doable), or with more flexibility list all the controllers in the XML:
> 
> <controller type='ich9-usb-ehci1' index='0'/>
> <controller type='ich9-usb-uhci1' index='0' masterbus='0' firstport='0'>
> <controller type='ich9-usb-uhci2' index='0' masterbus='0' firstport='2'>
> <controller type='ich9-usb-uhci3' index='0' masterbus='0' firstport='4'>
> 
> Any other idea?
> Daniel, have you also started working on USB2 & usb-redir support?

I'm not actively doing any work on it, merely experimenting with QEMU
to understand how everything fits together.

There are some key observations I have

 - A guest can have multiple USB controllers, either USB1 or USB2.
   The USB1 controller may be a function on the PIIX, or it may
   be a dedicate card

 - Since the companion controllers have associated PCI addresses,
   we must represent them explicitly in the XML, so it is clear
   to apps what PCI slots/functions are used.

 - Historically QEMU would auto-create hubs. For migration stability
   we must not let it do this. We must create any neccessary hubs
   ourself.

 - QEMU does not currently have any USB2 hub, and when it does, it
   will likely be USB2 only, no USB1 support. This makes hubs less
   desirable than multiple controllers, since you'd need to choose
   between USB1 or USB2 when creating the hub, while a controller
   can dynamically switch between USB1 & 2 thanks to the companion
   controllers.

 - Since there can be multiple controllers, we need a way specify
   physical addressing for USB devices, to ensure stablility
   across migration and hotplug/unplug. This needs to include the
   controller index, and the port number. The control index needs
   to span across USB1 and USB2 controllers.

What all this means....

 1. Add a new controller type 'usb'

      <controller type='usb' index='0' />

 2. Add a 'model' for the usb controller type, allowing things like
    piix3-uhci, uhci, ich9-ehci, etc. If none is specified, then
    we need to auto-fill the basic default (piix3-uchi).

     <controller type='usb' index='0' model='ich9-ehci'/>

 3. A USB controller will have a PCI address child element.

     <controller type='usb' index='0' model='ich9-ehci'>
       <address type='pci' domain='0' bus='0' slot='4' function='7'/>
     </controller>

 4. All USB devices will gain a new USB address child element.

      <input type='tablet' bus='usb'>
         <address type='usb' bus='0' port='4'/>
      </input>


  5. USB companion controllers use type='usb' too, but with an
     extra 'master' attribute to associate them


       <controller type='usb' index='0' model='ich9-ehci'>
         <address type='pci' domain='0' bus='0' slot='4' function='7'/>
       </controller>
       <controller type='usb' index='0' model='ich9-ehci1'>
         <master startport='0'/>
         <address type='pci' domain='0' bus='0' slot='4' function='1'/>
       </controller>
       <controller type='usb' index='0' model='ich9-uhci2'>
         <master startport='2'/>
         <address type='pci' domain='0' bus='0' slot='4' function='2'/>
       </controller>
       <controller type='usb' index='0' model='ich9-uhci3'>
         <master startport='4'/>
         <address type='pci' domain='0' bus='0' slot='4' function='2'/>
       </controller>

  6. A USB hub should appear as a normal device

      <hub type='usb'>
         <address type='usb' bus='0' port='1'/>
      </hub>

  7. A USB device address port should include the hub path

     eg. Plug a hub into port 1 of the first USB bus

      <hub type='usb'>
         <address type='usb' bus='0' port='1'/>
      </hub>

      then put a device and another hub into that hub:

      <input type='mouse' type='usb'>
         <address type='usb' bus='0' port='1.1'/>
      </hub>
      <hub type='usb'>
         <address type='usb' bus='0' port='1.2'/>
      </hub>

       Finally add 2 more devices into the second hub

      <input type='mouse' type='usb'>
         <address type='usb' bus='0' port='1.2.1'/>
      </hub>
      <input type='mouse' type='usb'>
         <address type='usb' bus='0' port='1.2.2'/>
      </hub>


  7. If no USB controller is in the XML, we need to prefill
     the default PIIX3 controller

  8. If no USB addresses are specified, we should autoassign
     addrs starting against the first controller.

A complex example. We create the default USB1 controllers, and two USB2
controllers. We put a USB tablet on the USB1 controller, and then
create a USB smartcards on one of the USB2 controllers, and assign two
host devices to the other USB2 controller:

     <controller type='usb' index='0' model='piix3-uhci'>
       <address type='pci' domain='0' bus='0' slot='1' function='3'/>
     </controller>

     <controller type='usb' index='1' model='ich9-ehci'>
       <address type='pci' domain='0' bus='0' slot='4' function='7'/>
     </controller>
     <controller type='usb' index='0' model='ich9-ehci1'>
       <master startport='0'/>
       <address type='pci' domain='0' bus='0' slot='4' function='1'/>
     </controller>
     <controller type='usb' index='0' model='ich9-uhci2'>
       <master startport='2'/>
       <address type='pci' domain='0' bus='0' slot='4' function='2'/>
     </controller>
     <controller type='usb' index='0' model='ich9-uhci3'>
       <master startport='4'/>
       <address type='pci' domain='0' bus='0' slot='4' function='3'/>
     </controller>

     <controller type='usb' index='2' model='ich9-ehci'>
       <address type='pci' domain='0' bus='0' slot='5' function='7'/>
     </controller>
     <controller type='usb' index='2' model='ich9-ehci1'>
       <master startport='0'/>
       <address type='pci' domain='0' bus='0' slot='5' function='1'/>
     </controller>
     <controller type='usb' index='2' model='ich9-uhci2'>
       <master startport='2'/>
       <address type='pci' domain='0' bus='0' slot='5' function='2'/>
     </controller>
     <controller type='usb' index='2' model='ich9-uhci3'>
       <master startport='4'/>
       <address type='pci' domain='0' bus='0' slot='5' function='3'/>
     </controller>

      <input type='tablet' bus='usb'>
         <address type='usb' bus='0' port='4'/>
      </input>

      <smartcard>
         <address type='usb' bus='1' port='1'/>
      </input>

      <hostdev mode=subsys type=usb>
         <source>
           <address bus='14' device='6'/>
         </source>
         <address type='usb' bus='2' port='1'/>
      </input>

      <hostdev mode=subsys type=usb>
         <source>
           <address bus='14' device='6'/>
         </source>
         <address type='usb' bus='2' port='2'/>
      </input>


Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|