[PATCH 14/32] docs: formatdomain-devices: Split out <redirdev>

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- docs/formatdomain-devices-redirdev.rst | 50 +++++++++++++++++++++++++ docs/formatdomain-devices.rst | 52 +------------------------- docs/meson.build | 1 + 3 files changed, 52 insertions(+), 51 deletions(-) create mode 100644 docs/formatdomain-devices-redirdev.rst diff --git a/docs/formatdomain-devices-redirdev.rst b/docs/formatdomain-devices-redirdev.rst new file mode 100644 index 0000000000..d2a4de8595 --- /dev/null +++ b/docs/formatdomain-devices-redirdev.rst @@ -0,0 +1,50 @@ +:anchor:`<a id="elementsRedir"/>` + +Redirected devices +~~~~~~~~~~~~~~~~~~ + +USB device redirection through a character device is supported :since:`since +after 0.9.5 (KVM only)` : + +:: + + ... + <devices> + <redirdev bus='usb' type='tcp'> + <source mode='connect' host='localhost' service='4000'/> + <boot order='1'/> + </redirdev> + <redirfilter> + <usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/> + <usbdev allow='no'/> + </redirfilter> + </devices> + ... + +``redirdev`` + The ``redirdev`` element is the main container for describing redirected + devices. ``bus`` must be "usb" for a USB device. An additional attribute + ``type`` is required, matching one of the supported `serial + device <#elementsConsole>`__ types, to describe the host side of the tunnel; + ``type='tcp'`` or ``type='spicevmc'`` (which uses the usbredir channel of a + `SPICE graphics device <#elementsGraphics>`__) are typical. The redirdev + element has an optional sub-element ``<address>`` which can tie the device to + a particular controller. Further sub-elements, such as ``<source>``, may be + required according to the given type, although a ``<target>`` sub-element is + not required (since the consumer of the character device is the hypervisor + itself, rather than a device visible in the guest). +``boot`` + Specifies that the device is bootable. The ``order`` attribute determines the + order in which devices will be tried during boot sequence. The per-device + ``boot`` elements cannot be used together with general boot elements in `BIOS + bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) +``redirfilter`` + The\ ``redirfilter``\ element is used for creating the filter rule to filter + out certain devices from redirection. It uses sub-element ``<usbdev>`` to + define each filter rule. ``class`` attribute is the USB Class code, for + example, 0x08 represents mass storage devices. The USB device can be + addressed by vendor / product id using the ``vendor`` and ``product`` + attributes. ``version`` is the device revision from the bcdDevice field (not + the version of the USB protocol). These four attributes are optional and + ``-1`` can be used to allow any value for them. ``allow`` attribute is + mandatory, 'yes' means allow, 'no' for deny. diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst index 3a678a387d..052d325a56 100644 --- a/docs/formatdomain-devices.rst +++ b/docs/formatdomain-devices.rst @@ -46,57 +46,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0` .. include:: formatdomain-devices-controller.rst .. include:: formatdomain-devices-lease.rst .. include:: formatdomain-devices-hostdev.rst - -:anchor:`<a id="elementsRedir"/>` - -Redirected devices -~~~~~~~~~~~~~~~~~~ - -USB device redirection through a character device is supported :since:`since -after 0.9.5 (KVM only)` : - -:: - - ... - <devices> - <redirdev bus='usb' type='tcp'> - <source mode='connect' host='localhost' service='4000'/> - <boot order='1'/> - </redirdev> - <redirfilter> - <usbdev class='0x08' vendor='0x1234' product='0xbeef' version='2.56' allow='yes'/> - <usbdev allow='no'/> - </redirfilter> - </devices> - ... - -``redirdev`` - The ``redirdev`` element is the main container for describing redirected - devices. ``bus`` must be "usb" for a USB device. An additional attribute - ``type`` is required, matching one of the supported `serial - device <#elementsConsole>`__ types, to describe the host side of the tunnel; - ``type='tcp'`` or ``type='spicevmc'`` (which uses the usbredir channel of a - `SPICE graphics device <#elementsGraphics>`__) are typical. The redirdev - element has an optional sub-element ``<address>`` which can tie the device to - a particular controller. Further sub-elements, such as ``<source>``, may be - required according to the given type, although a ``<target>`` sub-element is - not required (since the consumer of the character device is the hypervisor - itself, rather than a device visible in the guest). -``boot`` - Specifies that the device is bootable. The ``order`` attribute determines the - order in which devices will be tried during boot sequence. The per-device - ``boot`` elements cannot be used together with general boot elements in `BIOS - bootloader <#elementsOSBIOS>`__ section. ( :since:`Since 1.0.1` ) -``redirfilter`` - The\ ``redirfilter``\ element is used for creating the filter rule to filter - out certain devices from redirection. It uses sub-element ``<usbdev>`` to - define each filter rule. ``class`` attribute is the USB Class code, for - example, 0x08 represents mass storage devices. The USB device can be - addressed by vendor / product id using the ``vendor`` and ``product`` - attributes. ``version`` is the device revision from the bcdDevice field (not - the version of the USB protocol). These four attributes are optional and - ``-1`` can be used to allow any value for them. ``allow`` attribute is - mandatory, 'yes' means allow, 'no' for deny. +.. include:: formatdomain-devices-redirdev.rst :anchor:`<a id="elementsSmartcard"/>` diff --git a/docs/meson.build b/docs/meson.build index 9b65954a51..4ed30cc737 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -131,6 +131,7 @@ docs_rst_files = [ 'formatdomain-devices-controller.rst', 'formatdomain-devices-lease.rst', 'formatdomain-devices-hostdev.rst', + 'formatdomain-devices-redirdev.rst', ] }, { 'name': 'hacking' }, -- 2.26.2