- 3Alternate way: pass the USB port to the guest
- 4Assigning Devices to VMs
- 4.1In Configuration
- 4.1.3USB3.0
- 4.2Assign Devices to an already Running VM
- 4.1In Configuration
Introduction
The FTDI USB Slave driver is a peripheral driver that controls the USB slave ports on Vinculum II (VNC2). As a peripheral driver, the USB Slave driver exposes the standard device driver interface accessed via the Device Manager to an application. It is the purpose of this application note to describe the USB Slave driver interface. A bus driver drives an individual I/O bus device and provides per-slot functionality that is device-independent. Bus drivers also detect and report child devices that are connected to the bus. A function driver drives an individual device. A filter driver filters I/O requests for a device, a class of devices, or a bus. The Storport driver is a more efficient, higher performance driver than SCSI Port. Therefore you should develop miniport drivers that work with the Storport driver whenever possible. It is particularly important to use Storport with high performance devices, such as host-based RAID and fibre channel adapters.
There can be good reasons to access to USB hardware directly from a guest as it would be part of the VM itself, e.g.:
A device driver is the lowest level of the software that runs on a computer, as it is directly bound to the hardware features of the device. The concept of “device driver” is quite abstract, actually, and the kernel can be considered like it was a big device driver for a device called “computer”. In addition, you can often download the latest drivers directly from the manufacturer of a device. Your starting point for all driver-related activity is the Windows 10 Device Manager (Devmgmt.msc).
Saet I.s Port Devices Drivers
- Storage exclusively for the VM
- Separate NIC for the VM, but Direct I/O not avaiable
- Special device which needs a driver which exists only in the VM
The assignment of such devices can be predefined in the configuration file or 'plugged' into the VM while it is running.
Simple Way: pass the USB device ID to the guest
Assigning an Alcor memory stick connected to the host to VM 804.
Figure out in the host the Device Type by
The result is
Assign it to the VM by
Shutdown the VM (if running) and start it again.
Alternate way: pass the USB port to the guest
Example
In order to demonstrate how devices, physically connected to the host can be identified it´s assumed the following 7 USB devices are currently connected:
- External HD Toshiba USB 3.0
- memory stick Cruzer Blade USB 2.0
- memory stick SanDisk USB 2.0
- memory stick SanDisk USB 2.0 behind a USB hub
- memory stick Alcor behind the same USB hub as above
- Ethernet Network adapter USB 1.1 behind the same USB hub as above
- External HD Western Digital USB 3.0
Show Device Types
This is the simplest form and sufficient in most cases.
The result is
The numbers on the far right refer to the previously defined example. The other entries are the USB hubs of the system.
Note that the 'Device' number is just a number assigned automatically by the host, independent where the device is connected to. If the device is removed and plugged in again it gets a new number.
Show Device Map and Types
Sometimes it is necessary to specify where a device is physically connected. This information can be obtained by
where '804' is the ID of a running VM - regardless which VM is specified, the following command inside of the monitor reports always the same
in case of our example it is
Saet I.s Port Devices Driver Ed
The devices behind the external hub have port addresses 1.2.x
This form shows also the currently used USB protocol (btw: even the device (6) calls itself 'USB 2.0 10/100M Ethernet Adaptor' it works only as USB 1.1 device)
- 12 MB/s = USB 1.1
- 480 Mb/s = USB 2.0
- 5000 Mb/s = USB 3.0
Just the map can be displayed by
but it´s sometimes not complete and not recommended.
Complete Information
which contains everything but i´s a little bit difficult to read - for the current subject it´s sufficient to use the qm monitor as described above. The only one thing is a running VM must exist when processing the command.
Assigning Devices to VMs
Note that only 'real' devices can be assigned, i.e. assigning of USB hubs is not possible.
In Configuration
General Remark
Using the below mentioned 'qm set' command has the same effect as writing directly into the conf file. Moreover a preconfigured usb configuration file /usr/share/qemu-server/pve-usb.cfg could be adapted. But in order to avoid confusion this article recommends to use only the 'qm set' command.
USB1.x, USB2.0
The syntax for assigning in configuration is (see also man page for qm)
qm set <VM-ID> -usb[<n>] host={ <bus>-<port>(.<port>)* | <vendor-id>:<product-id> }
According to the above example let´s say the Alcor stick and the Cruzer Edge connected to the external hub (which is device (4) from the example) should be assigned to VM 804:
For the Alcor stick (as already shown):
For the Cruzer Edge this form will not be sufficient - there are two devices from the same type. Therefore the form specifying bus and port is used:
More details about ports can be found here - but note as already mentioned the 'lsusb -t' call is not reliable. Use 'qm monitor' and 'info usbhost' instead!
When the usb devices have to be removed from configuration the conf file has to be changed. In our example remove in /etc/pve/qemu-server/804.conf the following two lines:
USB3.0
since qemu-server package version 4.0-55 you also can set USB3 devices directly via the command line
it will automatically add the appropriate xhci controller at an available pci address
for any version <4.0-55 you can use the following instructions
1 Device
The external Toshiba drive should be assigned VM 804 and work with USB 3.0 protocol on a USB 3.0 port.
Note that 'addr=0x5' works only if there is no other device assigned to this address. If a failure occurs because of double use of this address choose another one.
When the usb device has to be removed from configuration the conf file has to be changed. In our example remove in /etc/pve/qemu-server/804.conf the following line:
More Devices
For one machine only one '-args' argument is possible. If already an '-args' advice was given giving another one overwrites the first. Moreover, the usb3 driver needs only to be defined once. In the following example 2 USB3 devices are assigned to the VM, the second one has the ID 1058:0820
Assign Devices to an already Running VM
How to connect devices to a running machine without shutting it down is demonstrated by the examples from above. If device is assigned in that way the assignment is valid until the machine stops. The assignment is independent of the actual status of the device (whether it´s currently plugged in or not), i.e. it can be plugged in and out multiple times and will be always assigned to the VM; regardless if the 'Productid' or 'busaddress' method is used.
USB1.x, USB2.0
Note that the 'usb_add' command offered in 'qm monitor' is NOT FUNCTIONING for this case!
someid and someotherid are ids of your choice, those can later be used to remove the usb device from the guest
USB3.0
anotherid is chosen by you, so the device can later be removed again
Reassign to Host
To remove an USB device from a guest do the following:
- make sure the USB device is not in use in your guest operating system (e.g. with 'Remove USB device' in Windows)
- connect to the qemu monitor for the vm either on the command line
- qm monitor VMID
- or on the web interface under VM->Monitor
- enter the following and replace <idofyourdevice> with the id of the usb device (e.g. usb0)
now your USB device should be removed from your guest and reappear on the host, until you stop and start the VM again
to remove the USB device from the config of a VM, do
where usbX is the id of the USB device
caution: this does not remove the usb device from a running VM