Re: [PATCH spice-space-pages v3] Update usbredir documentation

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Tue, 2017-04-18 at 12:08 +0300, Snir Sheriber wrote:
> ---
> Several fixes and typos
> ---
>  page/UsbRedir.rst | 186
> +++++++++++++++++++++++++++++++++++++++++++++++++++---
>  1 file changed, 177 insertions(+), 9 deletions(-)
> 
> diff --git a/page/UsbRedir.rst b/page/UsbRedir.rst
> index 958a086..5009970 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,197 @@ 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. 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 (companion UHCI
> is needed
> +in order to support also USB1.x devices). For USB3 support, an XHCI
> controller
> +is required.
> +It also needs to have Spice channels for USB redirection. The number
> of such
> +channels determine the number of USB devices that it's 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. 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 "USB Redirection" items
> as the
> +number of USB devices you want to be able to redirect
> simultaneously.
> +
> +Using libvirt
> ++++++++++++++
> +
> +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 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
> +++++++++++
> +
> +The following libvirt XML will configure a guest with USB2 support
> and the
> +ability to redirect 3 devices simultaneously

Looks like a little copy/paste error here. Should be "commandline" or
"qemu options" or something similar instead of "libvirt XML"

Aside from that, the rest looks good to me.

Acked-by: Jonathon Jongsma <jjongsma@xxxxxxxxxx>


> +
> +.. 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 USB3 support, the configuration can be simplified to:
> +
> +.. 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" 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 used to set blocking or autoconnect rules for USB
> devices. It
> +consists of one or more rules, where each rule has the form of:
> +
> +**<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**
> +
> +A client's default auto-connect filter string is 0x03,-1,-1,-1,0|-
> 1,-1,-1,-1,1
> +
> +This 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 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 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 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>`__,
_______________________________________________
Spice-devel mailing list
Spice-devel@xxxxxxxxxxxxxxxxxxxxx
https://lists.freedesktop.org/mailman/listinfo/spice-devel




[Index of Archives]     [Linux ARM Kernel]     [Linux ARM]     [Linux Omap]     [Fedora ARM]     [IETF Annouce]     [Security]     [Bugtraq]     [Linux]     [Linux OMAP]     [Linux MIPS]     [ECOS]     [Asterisk Internet PBX]     [Linux API]     [Monitors]