How do I assign a specific USB device to a specific USB controller in a KVM guest?

Resolution

Edit the guest definition with the command: virsh edit guestname

Define the default USB1 (UHCI) controller, and an additional USB2 (EHCI) controller:

    <controller type='usb' index='0' model='piix3-uhci'>
    </controller>
    <controller type='usb' index='1' model='ehci'>
    </controller>

(note: do not add PCI addresses for the controllers, libvirt handles this automatically)

Define a host USB1 device to pass through to the guest (replace AAAA with your USB1 device IDs):

    <hostdev mode='subsystem' type='usb' managed='yes'>
      <source>
        <vendor id='0xAAAA'/>
        <product id='0xAAAA'/>
      </source>
      <address type='usb' bus='0' port='2'/>
    </hostdev>

Define a host USB2 device to pass through to the guest (replace BBBB with your USB2 device IDs):

    <hostdev mode='subsystem' type='usb' managed='yes'>
      <source>
        <vendor id='0xBBBB'/>
        <product id='0xBBBB'/>
      </source>
      <address type='usb' bus='1' port='1'/>
    </hostdev>

Note that the index of the USB controller becomes the destination bus of the device. The USB1 controller is on Index 0 so the USB1 device is on Bus 0. Likewise, the USB2 controller is on Index 1, so the USB2 device is on Bus 1.

Port 0 on any USB controller is always the USB Root Hub, so start adding devices in Port 1 and later.

If your guest has the emulated USB Tablet configured, which qemu-kvm uses for seamless mouse integration, then you must have a UHCI controller defined, and you must add devices to that controller starting at Port 2. The emulated USB Tablet is hard-coded to require a UHCI USB1 controller, and is hard coded to always appear on Port 1 of that controller.

To pass through multiple devices of the same Vendor and Product ID, an additional line is required to address each device individually.

Given the following USB device addressing on the host:

host# lsusb
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 002 Device 004: ID 0781:5530 SanDisk Corp. Cruzer                      ## this is the device to pass through

Add an address line to the source in the hostdev, for example:

    <hostdev mode='subsystem' type='usb' managed='yes'>
      <source>
        <vendor id='0x0781'/>
        <product id='0x5530'/>
        <address bus='2' device='4'/>
      </source>
      <address type='usb' bus='1' port='2'/>
    </hostdev>

Additional USB devices of the same ID can be passed through to different guests by specifying their host USB Bus and Device addresses in each guest's config files.

The Bus 002 in lsusb becomes bus='2' in the source address, and Device 004 in lsusb becomes device='4' in the source address. Additional Device entries in the host's lsusb specify the device number within each guest.

For example, given the following USB device addressing on the host:

host# lsusb
Bus 002 Device 004: ID 0781:5530 SanDisk Corp. Cruzer
Bus 002 Device 005: ID 0781:5530 SanDisk Corp. Cruzer
Bus 002 Device 006: ID 0781:5530 SanDisk Corp. Cruzer
Bus 002 Device 007: ID 0781:5530 SanDisk Corp. Cruzer

Each guest would have a different address line within hostdev. The first guest would have device='4', the second guest would have device='5', and so on.

It is required to power off the guest (ie: stop the qemu-kvm process running the guest) to make the changes to USB controllers, as the controllers are not hot-pluggable items.