]>
Commit | Line | Data |
---|---|---|
324b2298 PB |
1 | .. _pcsys_005fusb: |
2 | ||
3 | USB emulation | |
4 | ------------- | |
5 | ||
6 | QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can | |
7 | plug virtual USB devices or real host USB devices (only works with | |
8 | certain host operating systems). QEMU will automatically create and | |
9 | connect virtual USB hubs as necessary to connect multiple USB devices. | |
10 | ||
923e9311 | 11 | .. _Connecting USB devices: |
324b2298 PB |
12 | |
13 | Connecting USB devices | |
14 | ~~~~~~~~~~~~~~~~~~~~~~ | |
15 | ||
16 | USB devices can be connected with the ``-device usb-...`` command line | |
17 | option or the ``device_add`` monitor command. Available devices are: | |
18 | ||
19 | ``usb-mouse`` | |
20 | Virtual Mouse. This will override the PS/2 mouse emulation when | |
21 | activated. | |
22 | ||
23 | ``usb-tablet`` | |
24 | Pointer device that uses absolute coordinates (like a touchscreen). | |
25 | This means QEMU is able to report the mouse position without having | |
26 | to grab the mouse. Also overrides the PS/2 mouse emulation when | |
27 | activated. | |
28 | ||
29 | ``usb-storage,drive=drive_id`` | |
923e9311 TH |
30 | Mass storage device backed by drive_id (see the :ref:`disk images` |
31 | chapter in the System Emulation Users Guide) | |
324b2298 PB |
32 | |
33 | ``usb-uas`` | |
34 | USB attached SCSI device, see | |
35 | `usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__ | |
36 | for details | |
37 | ||
38 | ``usb-bot`` | |
39 | Bulk-only transport storage device, see | |
40 | `usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__ | |
41 | for details here, too | |
42 | ||
43 | ``usb-mtp,rootdir=dir`` | |
44 | Media transfer protocol device, using dir as root of the file tree | |
45 | that is presented to the guest. | |
46 | ||
47 | ``usb-host,hostbus=bus,hostaddr=addr`` | |
48 | Pass through the host device identified by bus and addr | |
49 | ||
50 | ``usb-host,vendorid=vendor,productid=product`` | |
51 | Pass through the host device identified by vendor and product ID | |
52 | ||
53 | ``usb-wacom-tablet`` | |
54 | Virtual Wacom PenPartner tablet. This device is similar to the | |
55 | ``tablet`` above but it can be used with the tslib library because in | |
56 | addition to touch coordinates it reports touch pressure. | |
57 | ||
58 | ``usb-kbd`` | |
59 | Standard USB keyboard. Will override the PS/2 keyboard (if present). | |
60 | ||
61 | ``usb-serial,chardev=id`` | |
62 | Serial converter. This emulates an FTDI FT232BM chip connected to | |
63 | host character device id. | |
64 | ||
65 | ``usb-braille,chardev=id`` | |
66 | Braille device. This will use BrlAPI to display the braille output on | |
67 | a real or fake device referenced by id. | |
68 | ||
69 | ``usb-net[,netdev=id]`` | |
70 | Network adapter that supports CDC ethernet and RNDIS protocols. id | |
71 | specifies a netdev defined with ``-netdev …,id=id``. For instance, | |
72 | user-mode networking can be used with | |
73 | ||
74 | .. parsed-literal:: | |
75 | ||
76 | |qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0 | |
77 | ||
78 | ``usb-ccid`` | |
79 | Smartcard reader device | |
80 | ||
81 | ``usb-audio`` | |
82 | USB audio device | |
83 | ||
15e557b7 CB |
84 | ``u2f-{emulated,passthru}`` |
85 | Universal Second Factor device | |
86 | ||
324b2298 PB |
87 | .. _host_005fusb_005fdevices: |
88 | ||
89 | Using host USB devices on a Linux host | |
90 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
91 | ||
92 | WARNING: this is an experimental feature. QEMU will slow down when using | |
93 | it. USB devices requiring real time streaming (i.e. USB Video Cameras) | |
94 | are not supported yet. | |
95 | ||
96 | 1. If you use an early Linux 2.4 kernel, verify that no Linux driver is | |
97 | actually using the USB device. A simple way to do that is simply to | |
98 | disable the corresponding kernel module by renaming it from | |
99 | ``mydriver.o`` to ``mydriver.o.disabled``. | |
100 | ||
101 | 2. Verify that ``/proc/bus/usb`` is working (most Linux distributions | |
102 | should enable it by default). You should see something like that: | |
103 | ||
104 | :: | |
105 | ||
106 | ls /proc/bus/usb | |
107 | 001 devices drivers | |
108 | ||
109 | 3. Since only root can access to the USB devices directly, you can | |
110 | either launch QEMU as root or change the permissions of the USB | |
111 | devices you want to use. For testing, the following suffices: | |
112 | ||
113 | :: | |
114 | ||
115 | chown -R myuid /proc/bus/usb | |
116 | ||
117 | 4. Launch QEMU and do in the monitor: | |
118 | ||
119 | :: | |
120 | ||
121 | info usbhost | |
122 | Device 1.2, speed 480 Mb/s | |
123 | Class 00: USB device 1234:5678, USB DISK | |
124 | ||
125 | You should see the list of the devices you can use (Never try to use | |
126 | hubs, it won't work). | |
127 | ||
128 | 5. Add the device in QEMU by using: | |
129 | ||
130 | :: | |
131 | ||
132 | device_add usb-host,vendorid=0x1234,productid=0x5678 | |
133 | ||
134 | Normally the guest OS should report that a new USB device is plugged. | |
135 | You can use the option ``-device usb-host,...`` to do the same. | |
136 | ||
137 | 6. Now you can try to use the host USB device in QEMU. | |
138 | ||
139 | When relaunching QEMU, you may have to unplug and plug again the USB | |
140 | device to make it work again (this is a bug). |