[Spice-devel] [PATCH spice-space-pages v2] Update usbredir documentation
Jonathon Jongsma
jjongsma at redhat.com
Wed Apr 12 17:19:08 UTC 2017
On Wed, 2017-04-12 at 15:39 +0300, Snir Sheriber wrote:
> ---
>
> Changes from v1: adding xhci configuration and some fixes
>
> ---
> page/UsbRedir.rst | 184
> +++++++++++++++++++++++++++++++++++++++++++++++++++---
> 1 file changed, 175 insertions(+), 9 deletions(-)
>
> diff --git a/page/UsbRedir.rst b/page/UsbRedir.rst
> index 958a086..3a09967 100644
> --- a/page/UsbRedir.rst
> +++ b/page/UsbRedir.rst
> @@ -1,10 +1,8 @@
> usbredir
> ####################################################################
> ###########
>
> -:slug: usbredir
>
> -
> -usbredir is the name of a network protocol for sending usb device
> +usbredir is the name of a network protocol for sending USB device
> traffic over a network connection. It is also the name of the
> software
> package offering a parsing library, a usbredirhost library and
> several
> utilities implementing this protocol.
> @@ -16,27 +14,195 @@ this document also explains what is meant with a
> usbhost and a usbguest.
> usbredir was created for use with Spice, which is why it is hosted
> on
> spice-space.org, but the protocol and the usbredirhost are
> completely
> independent of spice, they could for example also be used to create
> a
> -vnc extension for redirecting usb devices over a vnc connection to a
> +vnc extension for redirecting USB devices over a vnc connection to a
> qemu virtual machine.
>
> The usbguest side is currently only implemented for qemu, and
> shipped as
> part of qemu (enabling this in qemu requires the libusbredirparser
> library to be available when building qemu).
>
> -usbredir supports USB device filtering configurable by `filter
> -string <http://people.fedoraproject.org/~jwrdegoede/spice-reference/
> SpiceUsbDeviceManager.html#SpiceUsbDeviceManager--auto-connect-
> filter>`__.
> +usbredir supports USB device filtering configurable by a filter
> string
> +
> +
> +Host Configuration
> +^^^^^^^^^^^^^^^^^^
> +
> +For redirection to work, the virtual machine must have a supported
> USB
> +controller (EHCI controller + companion UHCI controllers setup is
> recommended).
Perhaps add here some information about USB2 vs USB3. For example
something like:
"For redirection to work, the virtual machine must have a supported USB
controller. Qemu supports both USB2 and USB3, but at the time of
writing, USB3 has had less testing. For USB2 support, the guest must
have a EHCI controller and companion UHCI controller. For USB3 support,
an XHCI controller is required. "
Then the sections below explaining how to configure it in different
applications can be shortened a bit.
> +It also needs to have Spice channels for USB redirection. The number
> of such
> +channels correspond to the number of USB devices that it will be
I think I would make this a little bit stronger. Instead of:
"The number of such channels correspond to the number of USB
devices..."
perhaps:
"The number of such channels determine the number of USB devices..." ?
> possible to
> +redirect at the same time.
> +
> +More information about USB controllers in qemu could be found
> +`here <http://git.qemu-project.org/?p=qemu.git;a=blob_plain;f=docs/u
> sb2.txt;hb=HEAD>`__.
> +
> +Using virt-manager
> +++++++++++++++++++
> +Virtual machines created with virt-manager should have a USB
> controller by
> +default. In the virtual machine details, select "Controller USB" in
> the left
> +pane, and make sure its model is set to "USB2". You can then click
> on "Add
> +Hardware" and add as many "USB Redirection" items as the number of
> USB devices
> +you want to be able to redirect simultaneously.
> +
> +For USB version 3.0 you may want to give a try to the XHCI
> controller (less
> +tested), therefore you should select "USB3" in the model type
> instead of "USB2".
If you took my suggestion above, you can assume that the user already
knows about the fact that USB3 requires xhci and is less well-tested.
So this section could be simplified to something like:
<<<
Virtual machines created with virt-manager should have a USB controller
by default. In the virtual machine details, select "Controller USB" in
the left pane. If you only need to support USB2 devices, make sure its
model is set to "USB2". For USB 3.0 support, select "USB3" for the
model type.
You can then click on "Add Hardware" and add as many "USB Redirection"
items as the number of USB devices you want to be able to redirect
simultaneously.
>>>
> +
> +Using libvirt
> ++++++++++++++
> +
> +Up to 3 simultaneously redirected devices configuration
suggested re-wording:
"The following libvirt XML will configure a guest with USB2 support and
the ability to redirect 3 devices simultaneously"
> +
> +.. code-block:: sh
> +
> + <controller type='usb' index='0' model='ich9-ehci1'/>
> + <controller type='usb' index='0' model='ich9-uhci1'>
> + <master startport='0'/>
> + </controller>
> + <controller type='usb' index='0' model='ich9-uhci2'>
> + <master startport='2'/>
> + </controller>
> + <controller type='usb' index='0' model='ich9-uhci3'>
> + <master startport='4'/>
> + </controller>
> + <redirdev bus='usb' type='spicevmc'/>
> + <redirdev bus='usb' type='spicevmc'/>
> + <redirdev bus='usb' type='spicevmc'/>
> +
> +For USB version 3.0 you may want to give a try to the XHCI
> controller (less
> +tested) instead
"For USB3 support, the configuration can be simplified to:"
> +
> +.. code-block:: sh
> +
> + <controller type='usb' index='0' model='nec-xhci'/>
> + <redirdev bus='usb' type='spicevmc'/>
> + <redirdev bus='usb' type='spicevmc'/>
> + <redirdev bus='usb' type='spicevmc'/>
> +
> +Using QEMU
> +++++++++++
> +
> +Up to 3 simultaneously redirected devices configuration
Similar re-wording to the livirt section above
> +
> +.. code-block:: sh
> +
> + -device ich9-usb-ehci1,id=usb \
> + -device ich9-usb-
> uhci1,masterbus=usb.0,firstport=0,multifunction=on \
> + -device ich9-usb-uhci2,masterbus=usb.0,firstport=2 \
> + -device ich9-usb-uhci3,masterbus=usb.0,firstport=4 \
> + -chardev spicevmc,name=usbredir,id=usbredirchardev1 \
> + -device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \
> + -chardev spicevmc,name=usbredir,id=usbredirchardev2 \
> + -device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \
> + -chardev spicevmc,name=usbredir,id=usbredirchardev3 \
> + -device usb-redir,chardev=usbredirchardev3,id=usbredirdev3
> +
> +For USB version 3.0 you may want to give a try to the XHCI
> controller (less
> +tested) instead
as above
> +
> +.. code-block:: sh
> +
> + -device nec-usb-xhci,id=usb \
> + -chardev spicevmc,name=usbredir,id=usbredirchardev1 \
> + -device usb-redir,chardev=usbredirchardev1,id=usbredirdev1 \
> + -chardev spicevmc,name=usbredir,id=usbredirchardev2 \
> + -device usb-redir,chardev=usbredirchardev2,id=usbredirdev2 \
> + -chardev spicevmc,name=usbredir,id=usbredirchardev3 \
> + -device usb-redir,chardev=usbredirchardev3,id=usbredirdev3
> +
> +Client Configuration
> +^^^^^^^^^^^^^^^^^^^^
> +
> +The client needs to have support for USB redirection. In remote-
> viewer, you can
> +select which USB devices to redirect under the "File->USB device
> selection" manu
manu -> menu
> +once the Spice connection is established. There are also various
> command line
> +redirection options which are described below and when running
> remote-viewer
> +with --help-spice.
> +
> +To get USB redirection working on Windows clients, you need to
> install
> +`UsbDk <http://www.spice-space.org/download/windows/usbdk/>`__
> +
> +Filter String Format
> +^^^^^^^^^^^^^^^^^^^^
> +
> +A filter is being used for setting blocking or autoconnect rules for
> USB
change "a filter is being used for setting" to "A filter is used to
set"
> +devices. It consists of one or more rules, where each rule has the
> form of:
> +
> +**@class, at vendor, at product, at version, at allow**
It looks like this documentation was borrowed from the gtk-doc
documentation for the SpiceUsbManager::auto-connect-filter property.
That's fine, but in gtk-doc syntax the '@' symbol is used to indicate
that something is an argument so that it is formatted a certain way. In
this documentation, I think the '@' symbol may be a bit confusing, so
I'd probably remove it or indicate it a different way (e.g. perhaps
something like "<class>,<vendor>,<product>,<version>,<allow>"?)
> +
> +Use -1 for @class/@vendor/@product/@version to accept any value.
> +
> +And the rules themselves are concatenated like this:
> +
> +**@rule1|@rule2|@rule3**
> +
> +E.g. client's default setting filters out HID (class 0x03) USB
> devices from
> +auto connect and auto connects anything else. Note the explicit
> allow rule at
> +the end, this is necessary since by default all devices without a
> matching
> +filter rule will not auto-connect.
> +
> +Client's default filter string is 0x03,-1,-1,-1,0|-1,-1,-1,-1,1
I think I would introduce the filter string first, and then explain it,
rather than explaining it, and then introducing it. In other words:
"A client's default filter string is 0x03,-1,-1,-1,0|-1,-1,-1,-1,1.
This filters out HID (class 0x03) USB devices..."
Actually, this should probably be moved down to the "Client" section
below.
> +
> +
> +Client
> +^^^^^^
Perhaps rename this subsection "Client Filtering"?
> +
> +Set a string specifying a filter to use to determine which USB
> devices
> +are **allowed\\blocked** to redirect USB traffic to the guest.
> +
> +.. code-block:: sh
> +
> + remote-viewer --spice-usbredir-auto-redirect-filter="0x03,-1,-1,-
> 1,0|-1,-1,-1,-1,1"
> +
> +Set a string specifying a filter to use to determine which USB
> devices
> +to **autoconnect** when plugged in.
> +
> +.. code-block:: sh
> +
> + remote-viewer --spice-usbredir-redirect-on-connect="0x03,-1,-1,-
> 1,0|-1,-1,-1,-1,1"
> +
> +Host
> +^^^^
"Host Filtering"?
> +
> +Set a string specifying a filter to use to determine which USB
> devices
> +are **allowed\\blocked** to redirect USB traffic to the guest.
> +
> +
> +
> +Using QEMU
> +++++++++++
> +.. code-block:: sh
> +
> + -device usb-redir,filter='0x03:-1:-1:-1:0|-1:-1:-1:-
> 1:1',chardev=usbredirchardev1,id=usbredirdev1
> +
> +Note that filter string in QEMU cmd should be used with **':'**
> rules separator.
"Note that in a QEMU command, the filter string should use a **':'**
character as a separator within the rule."
> +
> +Using libvirt
> ++++++++++++++
> +
> +.. code-block:: XML
> +
> + ...
> + <devices>
> + ...
> + <redirfilter>
> + <usbdev class='0x08' vendor='0x1234' product='0xbeef'
> version='2.56' allow='yes'/>
> + <usbdev allow='no'/>
> + </redirfilter>
> + </devices>
> + ...
>
> -download
> -++++++++
> +Download
> +^^^^^^^^
>
> Latest versions:
>
> - For use with qemu 1.3 and newer:
> - `usbredir-0.7.tar.bz2 <http://spice-space.org/download/usbredir/u
> sbredir-0.7.tar.bz2>`__
> + `usbredir-0.7.1.tar.bz2 <http://www.spice-space.org/download/usbr
> edir/usbredir-0.7.1.tar.bz2>`__
> - For use with qemu 1.0 / 1.1 / 1.2 release:
> `usbredir-0.4.4.tar.bz2 <http://spice-space.org/download/usbredir
> /usbredir-0.4.4.tar.bz2>`__
>
> Older versions:
> +`0.7 <http://spice-space.org/download/usbredir/usbredir-0.7.tar.bz2>
> `__,
> `0.6 <http://spice-space.org/download/usbredir/usbredir-0.6.tar.bz2>
> `__,
> `0.5.2 <http://spice-space.org/download/usbredir/usbredir-0.5.2.tar.
> bz2>`__,
> `0.5.1 <http://spice-space.org/download/usbredir/usbredir-0.5.1.tar.
> bz2>`__,
Jonathon
More information about the Spice-devel
mailing list