diff options
Diffstat (limited to 'docs/system/usb.texi')
| -rw-r--r-- | docs/system/usb.texi | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/docs/system/usb.texi b/docs/system/usb.texi new file mode 100644 index 0000000000..840adac978 --- /dev/null +++ b/docs/system/usb.texi @@ -0,0 +1,115 @@ +@node pcsys_usb +@section USB emulation + +QEMU can emulate a PCI UHCI, OHCI, EHCI or XHCI USB controller. You can +plug virtual USB devices or real host USB devices (only works with certain +host operating systems). QEMU will automatically create and connect virtual +USB hubs as necessary to connect multiple USB devices. + +@menu +* usb_devices:: +* host_usb_devices:: +@end menu +@node usb_devices +@subsection Connecting USB devices + +USB devices can be connected with the @option{-device usb-...} command line +option or the @code{device_add} monitor command. Available devices are: + +@table @code +@item usb-mouse +Virtual Mouse. This will override the PS/2 mouse emulation when activated. +@item usb-tablet +Pointer device that uses absolute coordinates (like a touchscreen). +This means QEMU is able to report the mouse position without having +to grab the mouse. Also overrides the PS/2 mouse emulation when activated. +@item usb-storage,drive=@var{drive_id} +Mass storage device backed by @var{drive_id} (@pxref{disk_images}) +@item usb-uas +USB attached SCSI device, see +@url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt} +for details +@item usb-bot +Bulk-only transport storage device, see +@url{https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt,usb-storage.txt} +for details here, too +@item usb-mtp,rootdir=@var{dir} +Media transfer protocol device, using @var{dir} as root of the file tree +that is presented to the guest. +@item usb-host,hostbus=@var{bus},hostaddr=@var{addr} +Pass through the host device identified by @var{bus} and @var{addr} +@item usb-host,vendorid=@var{vendor},productid=@var{product} +Pass through the host device identified by @var{vendor} and @var{product} ID +@item usb-wacom-tablet +Virtual Wacom PenPartner tablet. This device is similar to the @code{tablet} +above but it can be used with the tslib library because in addition to touch +coordinates it reports touch pressure. +@item usb-kbd +Standard USB keyboard. Will override the PS/2 keyboard (if present). +@item usb-serial,chardev=@var{id} +Serial converter. This emulates an FTDI FT232BM chip connected to host character +device @var{id}. +@item usb-braille,chardev=@var{id} +Braille device. This will use BrlAPI to display the braille output on a real +or fake device referenced by @var{id}. +@item usb-net[,netdev=@var{id}] +Network adapter that supports CDC ethernet and RNDIS protocols. @var{id} +specifies a netdev defined with @code{-netdev @dots{},id=@var{id}}. +For instance, user-mode networking can be used with +@example +@value{qemu_system} [...] -netdev user,id=net0 -device usb-net,netdev=net0 +@end example +@item usb-ccid +Smartcard reader device +@item usb-audio +USB audio device +@end table + +@node host_usb_devices +@subsection Using host USB devices on a Linux host + +WARNING: this is an experimental feature. QEMU will slow down when +using it. USB devices requiring real time streaming (i.e. USB Video +Cameras) are not supported yet. + +@enumerate +@item If you use an early Linux 2.4 kernel, verify that no Linux driver +is actually using the USB device. A simple way to do that is simply to +disable the corresponding kernel module by renaming it from @file{mydriver.o} +to @file{mydriver.o.disabled}. + +@item Verify that @file{/proc/bus/usb} is working (most Linux distributions should enable it by default). You should see something like that: +@example +ls /proc/bus/usb +001 devices drivers +@end example + +@item Since only root can access to the USB devices directly, you can either launch QEMU as root or change the permissions of the USB devices you want to use. For testing, the following suffices: +@example +chown -R myuid /proc/bus/usb +@end example + +@item Launch QEMU and do in the monitor: +@example +info usbhost + Device 1.2, speed 480 Mb/s + Class 00: USB device 1234:5678, USB DISK +@end example +You should see the list of the devices you can use (Never try to use +hubs, it won't work). + +@item Add the device in QEMU by using: +@example +device_add usb-host,vendorid=0x1234,productid=0x5678 +@end example + +Normally the guest OS should report that a new USB device is plugged. +You can use the option @option{-device usb-host,...} to do the same. + +@item Now you can try to use the host USB device in QEMU. + +@end enumerate + +When relaunching QEMU, you may have to unplug and plug again the USB +device to make it work again (this is a bug). + |