qemu/docs/system/usb.rst

141 lines
4.3 KiB
ReStructuredText
Raw Normal View History

docs/system: convert Texinfo documentation to rST Apart from targets.rst, which was written by hand, this is an automated conversion obtained with the following command: makeinfo --force -o - --docbook \ -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \ -D 'qemu_system QEMU_SYSTEM_MACRO' \ $texi | pandoc -f docbook -t rst+smart | perl -e ' $/=undef; $_ = <>; s/^- − /- /gm; s/QEMU_SYSTEM_MACRO/|qemu_system|/g; s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g; s/(?=::\n\n +\|qemu)/.. parsed-literal/g; s/:\n\n::$/::/gm; print' > $rst In addition, the following changes were made manually: - target-i386.rst and target-mips.rst: replace CPU model documentation with an include directive - monitor.rst: replace the command section with a comment - images.rst: add toctree - target-arm.rst: Replace use of :math: (which Sphinx complains about) with :sup:, and hide it behind |I2C| and |I2C| substitutions. Content that is not @included remains exclusive to qemu-doc.texi. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-20-peter.maydell@linaro.org Message-id: 20200226113034.6741-19-pbonzini@redhat.com [PMM: Fixed target-arm.rst use of :math:; remove out of date note about images.rst from commit message; fixed expansion of |qemu_system_x86|; use parsed-literal in invocation.rst when we want to use |qemu_system_x86|; fix incorrect subsection level for "OS requirements" in target-i386.rst; fix incorrect syntax for making links to other sections of the manual] Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 18:36:05 +03:00
.. _pcsys_005fusb:
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.
.. _Connecting USB devices:
docs/system: convert Texinfo documentation to rST Apart from targets.rst, which was written by hand, this is an automated conversion obtained with the following command: makeinfo --force -o - --docbook \ -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \ -D 'qemu_system QEMU_SYSTEM_MACRO' \ $texi | pandoc -f docbook -t rst+smart | perl -e ' $/=undef; $_ = <>; s/^- − /- /gm; s/QEMU_SYSTEM_MACRO/|qemu_system|/g; s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g; s/(?=::\n\n +\|qemu)/.. parsed-literal/g; s/:\n\n::$/::/gm; print' > $rst In addition, the following changes were made manually: - target-i386.rst and target-mips.rst: replace CPU model documentation with an include directive - monitor.rst: replace the command section with a comment - images.rst: add toctree - target-arm.rst: Replace use of :math: (which Sphinx complains about) with :sup:, and hide it behind |I2C| and |I2C| substitutions. Content that is not @included remains exclusive to qemu-doc.texi. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-20-peter.maydell@linaro.org Message-id: 20200226113034.6741-19-pbonzini@redhat.com [PMM: Fixed target-arm.rst use of :math:; remove out of date note about images.rst from commit message; fixed expansion of |qemu_system_x86|; use parsed-literal in invocation.rst when we want to use |qemu_system_x86|; fix incorrect subsection level for "OS requirements" in target-i386.rst; fix incorrect syntax for making links to other sections of the manual] Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 18:36:05 +03:00
Connecting USB devices
~~~~~~~~~~~~~~~~~~~~~~
USB devices can be connected with the ``-device usb-...`` command line
option or the ``device_add`` monitor command. Available devices are:
``usb-mouse``
Virtual Mouse. This will override the PS/2 mouse emulation when
activated.
``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.
``usb-storage,drive=drive_id``
Mass storage device backed by drive_id (see the :ref:`disk images`
chapter in the System Emulation Users Guide)
docs/system: convert Texinfo documentation to rST Apart from targets.rst, which was written by hand, this is an automated conversion obtained with the following command: makeinfo --force -o - --docbook \ -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \ -D 'qemu_system QEMU_SYSTEM_MACRO' \ $texi | pandoc -f docbook -t rst+smart | perl -e ' $/=undef; $_ = <>; s/^- − /- /gm; s/QEMU_SYSTEM_MACRO/|qemu_system|/g; s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g; s/(?=::\n\n +\|qemu)/.. parsed-literal/g; s/:\n\n::$/::/gm; print' > $rst In addition, the following changes were made manually: - target-i386.rst and target-mips.rst: replace CPU model documentation with an include directive - monitor.rst: replace the command section with a comment - images.rst: add toctree - target-arm.rst: Replace use of :math: (which Sphinx complains about) with :sup:, and hide it behind |I2C| and |I2C| substitutions. Content that is not @included remains exclusive to qemu-doc.texi. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-20-peter.maydell@linaro.org Message-id: 20200226113034.6741-19-pbonzini@redhat.com [PMM: Fixed target-arm.rst use of :math:; remove out of date note about images.rst from commit message; fixed expansion of |qemu_system_x86|; use parsed-literal in invocation.rst when we want to use |qemu_system_x86|; fix incorrect subsection level for "OS requirements" in target-i386.rst; fix incorrect syntax for making links to other sections of the manual] Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 18:36:05 +03:00
``usb-uas``
USB attached SCSI device, see
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
for details
``usb-bot``
Bulk-only transport storage device, see
`usb-storage.txt <https://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/usb-storage.txt>`__
for details here, too
``usb-mtp,rootdir=dir``
Media transfer protocol device, using dir as root of the file tree
that is presented to the guest.
``usb-host,hostbus=bus,hostaddr=addr``
Pass through the host device identified by bus and addr
``usb-host,vendorid=vendor,productid=product``
Pass through the host device identified by vendor and product ID
``usb-wacom-tablet``
Virtual Wacom PenPartner tablet. This device is similar to the
``tablet`` above but it can be used with the tslib library because in
addition to touch coordinates it reports touch pressure.
``usb-kbd``
Standard USB keyboard. Will override the PS/2 keyboard (if present).
``usb-serial,chardev=id``
Serial converter. This emulates an FTDI FT232BM chip connected to
host character device id.
``usb-braille,chardev=id``
Braille device. This will use BrlAPI to display the braille output on
a real or fake device referenced by id.
``usb-net[,netdev=id]``
Network adapter that supports CDC ethernet and RNDIS protocols. id
specifies a netdev defined with ``-netdev …,id=id``. For instance,
user-mode networking can be used with
.. parsed-literal::
|qemu_system| [...] -netdev user,id=net0 -device usb-net,netdev=net0
``usb-ccid``
Smartcard reader device
``usb-audio``
USB audio device
``u2f-{emulated,passthru}``
Universal Second Factor device
docs/system: convert Texinfo documentation to rST Apart from targets.rst, which was written by hand, this is an automated conversion obtained with the following command: makeinfo --force -o - --docbook \ -D 'qemu_system_x86 QEMU_SYSTEM_X86_MACRO' \ -D 'qemu_system QEMU_SYSTEM_MACRO' \ $texi | pandoc -f docbook -t rst+smart | perl -e ' $/=undef; $_ = <>; s/^- − /- /gm; s/QEMU_SYSTEM_MACRO/|qemu_system|/g; s/QEMU_SYSTEM_X86_MACRO/|qemu_system_x86|/g; s/(?=::\n\n +\|qemu)/.. parsed-literal/g; s/:\n\n::$/::/gm; print' > $rst In addition, the following changes were made manually: - target-i386.rst and target-mips.rst: replace CPU model documentation with an include directive - monitor.rst: replace the command section with a comment - images.rst: add toctree - target-arm.rst: Replace use of :math: (which Sphinx complains about) with :sup:, and hide it behind |I2C| and |I2C| substitutions. Content that is not @included remains exclusive to qemu-doc.texi. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-20-peter.maydell@linaro.org Message-id: 20200226113034.6741-19-pbonzini@redhat.com [PMM: Fixed target-arm.rst use of :math:; remove out of date note about images.rst from commit message; fixed expansion of |qemu_system_x86|; use parsed-literal in invocation.rst when we want to use |qemu_system_x86|; fix incorrect subsection level for "OS requirements" in target-i386.rst; fix incorrect syntax for making links to other sections of the manual] Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-02-28 18:36:05 +03:00
.. _host_005fusb_005fdevices:
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.
1. 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
``mydriver.o`` to ``mydriver.o.disabled``.
2. Verify that ``/proc/bus/usb`` is working (most Linux distributions
should enable it by default). You should see something like that:
::
ls /proc/bus/usb
001 devices drivers
3. 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:
::
chown -R myuid /proc/bus/usb
4. Launch QEMU and do in the monitor:
::
info usbhost
Device 1.2, speed 480 Mb/s
Class 00: USB device 1234:5678, USB DISK
You should see the list of the devices you can use (Never try to use
hubs, it won't work).
5. Add the device in QEMU by using:
::
device_add usb-host,vendorid=0x1234,productid=0x5678
Normally the guest OS should report that a new USB device is plugged.
You can use the option ``-device usb-host,...`` to do the same.
6. Now you can try to use the host USB device in QEMU.
When relaunching QEMU, you may have to unplug and plug again the USB
device to make it work again (this is a bug).