core-agent-linux/README.pvusb

Installation
~~~~~~~~~~~~

In dom0, once:
 qvm-create -l red usbvm

 # FIXME: use your own PCI device IDs
 qvm-pci -a usbvm 00:1d.0
 qvm-pci -a usbvm 00:1d.1
 qvm-pci -a usbvm 00:1d.2
 qvm-pci -a usbvm 00:1d.7

In dom0, after each dom0 reboot:
 sudo ./install-pvusb-dom0.sh
 qvm-start usbvm

In dom0, after each usbvm reboot:
 usbvm_xid=`xl list | awk '($1=="usbvm"){print $2}'`
 xenstore-write /local/domain/${usbvm_xid}/qubes-usb-devices ''
 xenstore-chmod /local/domain/${usbvm_xid}/qubes-usb-devices n0 b${usbvm_xid}

In usbvm, after each reboot:
 sudo ./install-pvusb-backend.sh 

In appvms, after each reboot:
 sudo ./install-pvusb-frontend.sh 

In dom0, after each usbvm and appvm reboot (FIXME):
 sudo ../pvusb-scripts/initpv.py <backend-id> <frontend-id> <device-id>

After the above is done:
 'qvm-usb -l' in usbvm displays a list of local USB devices
 'lsusb' in appvm displays an entry for the root hub

Attach
~~~~~~

In dom0:
 qvm-usb -a [-b <usbvm-name>] [-f <frontend-controller> [--p <frontend-port>]] [--no-auto-detach] <vm-name> <controller>-<port>

Defaults:
 usbvm-name = 'usbvm'
 frontend-controller = 0
 frontend-port = first unused between 1 and 8

Example:
 qvm-usb -a netvm usbvm:4-1

List
~~~~

In dom0:
 qvm-usb -l

Example output:
 usbvm:4-1 1234:5678 My Bluetooth Dongle
 usbvm:4-2 5678:1234 My Wireless Adapter (attached to 'netvm' as '0-1')

Detach
~~~~~~

In dom0:
 qvm-usb -d <vm-name>:<vusb-controller>-<vusb-port>
 qvm-usb -d <vm-name>

Example:
 qvm-usb -d netvm:0-1

Known issues
~~~~~~~~~~~~

* The content of backend/vusb does not get cleaned on domain shutdown (no impact on functionality)
* System keyboard / mouse are listed and can be detached away
* Virtual USB devices (ones created by PVUSB frontend) may be listed
* The installation/configuration is not persistent, not retained between reboots
* No logging / audit trail?
* When an attached device is physically unplugged, USB port remains mapped but not displayed in the list. If device is plugged back it continues to work. Unlisted device cannot be detached.
* We are not attaching actual devices, but USB ports (different behavior from VMWare, might be confusing)
* After device is detached from the frontend and returned back to the backend it is not usable there