[PATCH 13/32] docs: formatdomain-devices: Split out <hostdev>

Peter Krempa pkrempa at redhat.com
Thu Jul 23 13:21:18 UTC 2020


Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatdomain-devices-hostdev.rst | 337 +++++++++++++++++++++++++
 docs/formatdomain-devices.rst         | 339 +-------------------------
 docs/meson.build                      |   1 +
 3 files changed, 339 insertions(+), 338 deletions(-)
 create mode 100644 docs/formatdomain-devices-hostdev.rst

diff --git a/docs/formatdomain-devices-hostdev.rst b/docs/formatdomain-devices-hostdev.rst
new file mode 100644
index 0000000000..859c4b4ec5
--- /dev/null
+++ b/docs/formatdomain-devices-hostdev.rst
@@ -0,0 +1,337 @@
+:anchor:`<a id="elementsHostDev"/>`
+
+Host device assignment
+~~~~~~~~~~~~~~~~~~~~~~
+
+:anchor:`<a id="elementsHostDevSubsys"/>`
+
+USB / PCI / SCSI devices
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+USB, PCI and SCSI devices attached to the host can be passed through to the
+guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0
+for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` :
+
+::
+
+   ...
+   <devices>
+     <hostdev mode='subsystem' type='usb'>
+       <source startupPolicy='optional'>
+         <vendor id='0x1234'/>
+         <product id='0xbeef'/>
+       </source>
+       <boot order='2'/>
+     </hostdev>
+   </devices>
+   ...
+
+or:
+
+::
+
+   ...
+   <devices>
+     <hostdev mode='subsystem' type='pci' managed='yes'>
+       <source>
+         <address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/>
+       </source>
+       <boot order='1'/>
+       <rom bar='on' file='/etc/fake/boot.bin'/>
+     </hostdev>
+   </devices>
+   ...
+
+or:
+
+::
+
+   ...
+   <devices>
+     <hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'>
+       <source>
+         <adapter name='scsi_host0'/>
+         <address bus='0' target='0' unit='0'/>
+       </source>
+       <readonly/>
+       <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+     </hostdev>
+   </devices>
+   ...
+
+or:
+
+::
+
+   ...
+   <devices>
+     <hostdev mode='subsystem' type='scsi'>
+       <source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'>
+         <host name='example.com' port='3260'/>
+         <auth username='myuser'>
+           <secret type='iscsi' usage='libvirtiscsi'/>
+         </auth>
+       </source>
+       <address type='drive' controller='0' bus='0' target='0' unit='0'/>
+     </hostdev>
+   </devices>
+   ...
+
+or:
+
+::
+
+     ...
+     <devices>
+       <hostdev mode='subsystem' type='scsi_host'>
+         <source protocol='vhost' wwpn='naa.50014057667280d8'/>
+       </hostdev>
+     </devices>
+     ...
+
+or:
+
+::
+
+     ...
+     <devices>
+       <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
+       <source>
+         <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/>
+       </source>
+       </hostdev>
+       <hostdev mode='subsystem' type='mdev' model='vfio-ccw'>
+       <source>
+         <address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/>
+       </source>
+       <address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/>
+       </hostdev>
+     </devices>
+     ...
+
+``hostdev``
+   The ``hostdev`` element is the main container for describing host devices.
+   For each device, the ``mode`` is always "subsystem" and the ``type`` is one
+   of the following values with additional attributes noted.
+
+   ``usb``
+      USB devices are detached from the host on guest startup and reattached
+      after the guest exits or the device is hot-unplugged.
+   ``pci``
+      For PCI devices, when ``managed`` is "yes" it is detached from the host
+      before being passed on to the guest and reattached to the host after the
+      guest exits. If ``managed`` is omitted or "no", the user is responsible to
+      call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before
+      starting the guest or hot-plugging the device and
+      ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
+      or stopping the guest.
+   ``scsi``
+      For SCSI devices, user is responsible to make sure the device is not used
+      by host. If supported by the hypervisor and OS, the optional ``sgio`` (
+      :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO
+      commands are filtered for the disk. Valid settings are "filtered" or
+      "unfiltered", where the default is "filtered". The optional ``rawio`` (
+      :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio
+      capability. Valid settings are "yes" or "no". See the rawio description
+      within the `disk <#elementsDisks>`__ section. If a disk lun in the domain
+      already has the rawio capability, then this setting not required.
+   ``scsi_host``
+      :since:`since 2.5.0` For SCSI devices, user is responsible to make sure
+      the device is not used by host. This ``type`` passes all LUNs presented by
+      a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attribute
+      can be specified further with "virtio-transitional",
+      "virtio-non-transitional", or "virtio". See `Virtio transitional
+      devices <#elementsVirtioTransitional>`__ for more details.
+   ``mdev``
+      For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute
+      specifies the device API which determines how the host's vfio driver will
+      expose the device to the guest. Currently, ``model='vfio-pci'``,
+      ``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` (
+      :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__
+      section provides more information about mediated devices as well as how to
+      create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an
+      optional ``display`` attribute may be used to enable or disable support
+      for an accelerated remote desktop backed by a mediated device (such as
+      NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video
+      devices <#elementsVideo>`__. This attribute is limited to
+      ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off``
+      (default is 'off'). It is required to use a `graphical
+      framebuffer <#elementsGraphics>`__ in order to use this attribute,
+      currently only supported with VNC, Spice and egl-headless graphics
+      devices. :since:`Since version 5.10.0` , there is an optional ``ramfb``
+      attribute for devices with ``model='vfio-pci'``. Supported values are
+      either ``on`` or ``off`` (default is 'off'). When enabled, this attribute
+      provides a memory framebuffer device to the guest. This framebuffer will
+      be used as a boot display when a vgpu device is the primary display.
+
+      Note: There are also some implications on the usage of guest's address
+      type depending on the ``model`` attribute, see the ``address`` element
+      below.
+
+   Note: The ``managed`` attribute is only used with ``type='pci'`` and is
+   ignored by all the other device types, thus setting ``managed`` explicitly
+   with other than a PCI device has the same effect as omitting it. Similarly,
+   ``model`` attribute is only supported by mediated devices and ignored by all
+   other device types.
+
+``source``
+   The source element describes the device as seen from the host using the
+   following mechanism to describe:
+
+   ``usb``
+      The USB device can either be addressed by vendor / product id using the
+      ``vendor`` and ``product`` elements or by the device's address on the host
+      using the ``address`` element.
+
+      :since:`Since 1.0.0` , the ``source`` element of USB devices may contain
+      ``startupPolicy`` attribute which can be used to define policy what to do
+      if the specified host USB device is not found. The attribute accepts the
+      following values:
+
+      ========= =====================================================================
+      mandatory fail if missing for any reason (the default)
+      requisite fail if missing on boot up, drop if missing on migrate/restore/revert
+      optional  drop if missing at any start attempt
+      ========= =====================================================================
+
+   ``pci``
+      PCI devices can only be described by their ``address``.
+   ``scsi``
+      SCSI devices are described by both the ``adapter`` and ``address``
+      elements. The ``address`` element includes a ``bus`` attribute (a 2-digit
+      bus number), a ``target`` attribute (a 10-digit target number), and a
+      ``unit`` attribute (a 20-digit unit number on the bus). Not all
+      hypervisors support larger ``target`` and ``unit`` values. It is up to
+      each hypervisor to determine the maximum value supported for the adapter.
+
+      :since:`Since 1.2.8` , the ``source`` element of a SCSI device may contain
+      the ``protocol`` attribute. When the attribute is set to "iscsi", the host
+      device XML follows the network `disk <#elementsDisks>`__ device using the
+      same ``name`` attribute and optionally using the ``auth`` element to
+      provide the authentication credentials to the iSCSI server.
+
+   ``scsi_host``
+      :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are
+      described by a ``protocol`` attribute set to "vhost" and a ``wwpn``
+      attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a prefix
+      of "naa.") established in the host configfs.
+   ``mdev``
+      Mediated devices ( :since:`Since 3.2.0` ) are described by the ``address``
+      element. The ``address`` element contains a single mandatory attribute
+      ``uuid``.
+
+``vendor``, ``product``
+   The ``vendor`` and ``product`` elements each have an ``id`` attribute that
+   specifies the USB vendor and product id. The ids can be given in decimal,
+   hexadecimal (starting with 0x) or octal (starting with 0) form.
+``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 0.8.8` for PCI
+   devices, :since:`Since 1.0.1` for USB devices.
+``rom``
+   The ``rom`` element is used to change how a PCI device's ROM is presented to
+   the guest. The optional ``bar`` attribute can be set to "on" or "off", and
+   determines whether or not the device's ROM will be visible in the guest's
+   memory map. (In PCI documentation, the "rombar" setting controls the presence
+   of the Base Address Register for the ROM). If no rom bar is specified, the
+   qemu default will be used (older versions of qemu used a default of "off",
+   while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU and KVM
+   only)` . The optional ``file`` attribute contains an absolute path to a
+   binary file to be presented to the guest as the device's ROM BIOS. This can
+   be useful, for example, to provide a PXE boot ROM for a virtual function of
+   an sr-iov capable ethernet device (which has no boot ROMs for the VFs).
+   :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled``
+   attribute can be set to ``no`` to disable PCI ROM loading completely for the
+   device; if PCI ROM loading is disabled through this attribute, attempts to
+   tweak the loading process further using the ``bar`` or ``file`` attributes
+   will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` .
+``address``
+   The ``address`` element for USB devices has a ``bus`` and ``device``
+   attribute to specify the USB bus and device number the device appears at on
+   the host. The values of these attributes can be given in decimal, hexadecimal
+   (starting with 0x) or octal (starting with 0) form. For PCI devices the
+   element carries 4 attributes allowing to designate the device as can be found
+   with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive'
+   address type must be used. For mediated devices, which are software-only
+   devices defining an allocation of resources on the physical parent device,
+   the address type used must conform to the ``model`` attribute of element
+   ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API
+   or any address type other than CCW for ``vfio-ccw`` device API will result in
+   an error. `See above <#elementsAddress>`__ for more details on the address
+   element.
+``driver``
+   PCI devices can have an optional ``driver`` subelement that specifies which
+   backend driver to use for PCI device assignment. Use the ``name`` attribute
+   to select either "vfio" (for the new VFIO device assignment backend, which is
+   compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment
+   handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU and KVM
+   only, requires kernel 3.6 or newer)` . When specified, device assignment will
+   fail if the requested method of device assignment isn't available on the
+   host. When not specified, the default is "vfio" on systems where the VFIO
+   driver is available and loaded, and "kvm" on older systems, or those where
+   the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that the
+   default was always "kvm").
+``readonly``
+   Indicates that the device is readonly, only supported by SCSI host device
+   now. :since:`Since 1.0.6 (QEMU and KVM only)`
+``shareable``
+   If present, this indicates the device is expected to be shared between
+   domains (assuming the hypervisor and OS support this). Only supported by SCSI
+   host device. :since:`Since 1.0.6`
+
+   Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did not
+   work as as expected until :since:`1.2.2` .
+
+:anchor:`<a id="elementsHostDevCaps"/>`
+
+Block / character devices
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Block / character devices from the host can be passed through to the guest using
+the ``hostdev`` element. This is only possible with container based
+virtualization. Devices are specified by a fully qualified path. :since:`since
+after 1.0.1 for LXC` :
+
+::
+
+   ...
+   <hostdev mode='capabilities' type='storage'>
+     <source>
+       <block>/dev/sdf1</block>
+     </source>
+   </hostdev>
+   ...
+
+::
+
+   ...
+   <hostdev mode='capabilities' type='misc'>
+     <source>
+       <char>/dev/input/event3</char>
+     </source>
+   </hostdev>
+   ...
+
+::
+
+   ...
+   <hostdev mode='capabilities' type='net'>
+     <source>
+       <interface>eth0</interface>
+     </source>
+   </hostdev>
+   ...
+
+``hostdev``
+   The ``hostdev`` element is the main container for describing host devices.
+   For block/character device passthrough ``mode`` is always "capabilities" and
+   ``type`` is "storage" for a block device, "misc" for a character device and
+   "net" for a host network interface.
+``source``
+   The source element describes the device as seen from the host. For block
+   devices, the path to the block device in the host OS is provided in the
+   nested "block" element, while for character devices the "char" element is
+   used. For network interfaces, the name of the interface is provided in the
+   "interface" element.
diff --git a/docs/formatdomain-devices.rst b/docs/formatdomain-devices.rst
index d704cbe05b..3a678a387d 100644
--- a/docs/formatdomain-devices.rst
+++ b/docs/formatdomain-devices.rst
@@ -45,344 +45,7 @@ following characters: ``[a-zA-Z0-9_-]``. :since:`Since 3.9.0`
 .. include:: formatdomain-devices-virtio.rst
 .. include:: formatdomain-devices-controller.rst
 .. include:: formatdomain-devices-lease.rst
-
-:anchor:`<a id="elementsHostDev"/>`
-
-Host device assignment
-~~~~~~~~~~~~~~~~~~~~~~
-
-:anchor:`<a id="elementsHostDevSubsys"/>`
-
-USB / PCI / SCSI devices
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-USB, PCI and SCSI devices attached to the host can be passed through to the
-guest using the ``hostdev`` element. :since:`since after 0.4.4 for USB, 0.6.0
-for PCI (KVM only) and 1.0.6 for SCSI (KVM only)` :
-
-::
-
-   ...
-   <devices>
-     <hostdev mode='subsystem' type='usb'>
-       <source startupPolicy='optional'>
-         <vendor id='0x1234'/>
-         <product id='0xbeef'/>
-       </source>
-       <boot order='2'/>
-     </hostdev>
-   </devices>
-   ...
-
-or:
-
-::
-
-   ...
-   <devices>
-     <hostdev mode='subsystem' type='pci' managed='yes'>
-       <source>
-         <address domain='0x0000' bus='0x06' slot='0x02' function='0x0'/>
-       </source>
-       <boot order='1'/>
-       <rom bar='on' file='/etc/fake/boot.bin'/>
-     </hostdev>
-   </devices>
-   ...
-
-or:
-
-::
-
-   ...
-   <devices>
-     <hostdev mode='subsystem' type='scsi' sgio='filtered' rawio='yes'>
-       <source>
-         <adapter name='scsi_host0'/>
-         <address bus='0' target='0' unit='0'/>
-       </source>
-       <readonly/>
-       <address type='drive' controller='0' bus='0' target='0' unit='0'/>
-     </hostdev>
-   </devices>
-   ...
-
-or:
-
-::
-
-   ...
-   <devices>
-     <hostdev mode='subsystem' type='scsi'>
-       <source protocol='iscsi' name='iqn.2014-08.com.example:iscsi-nopool/1'>
-         <host name='example.com' port='3260'/>
-         <auth username='myuser'>
-           <secret type='iscsi' usage='libvirtiscsi'/>
-         </auth>
-       </source>
-       <address type='drive' controller='0' bus='0' target='0' unit='0'/>
-     </hostdev>
-   </devices>
-   ...
-
-or:
-
-::
-
-     ...
-     <devices>
-       <hostdev mode='subsystem' type='scsi_host'>
-         <source protocol='vhost' wwpn='naa.50014057667280d8'/>
-       </hostdev>
-     </devices>
-     ...
-
-or:
-
-::
-
-     ...
-     <devices>
-       <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
-       <source>
-         <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'/>
-       </source>
-       </hostdev>
-       <hostdev mode='subsystem' type='mdev' model='vfio-ccw'>
-       <source>
-         <address uuid='9063cba3-ecef-47b6-abcf-3fef4fdcad85'/>
-       </source>
-       <address type='ccw' cssid='0xfe' ssid='0x0' devno='0x0001'/>
-       </hostdev>
-     </devices>
-     ...
-
-``hostdev``
-   The ``hostdev`` element is the main container for describing host devices.
-   For each device, the ``mode`` is always "subsystem" and the ``type`` is one
-   of the following values with additional attributes noted.
-
-   ``usb``
-      USB devices are detached from the host on guest startup and reattached
-      after the guest exits or the device is hot-unplugged.
-   ``pci``
-      For PCI devices, when ``managed`` is "yes" it is detached from the host
-      before being passed on to the guest and reattached to the host after the
-      guest exits. If ``managed`` is omitted or "no", the user is responsible to
-      call ``virNodeDeviceDetachFlags`` (or ``virsh nodedev-detach`` before
-      starting the guest or hot-plugging the device and
-      ``virNodeDeviceReAttach`` (or ``virsh nodedev-reattach``) after hot-unplug
-      or stopping the guest.
-   ``scsi``
-      For SCSI devices, user is responsible to make sure the device is not used
-      by host. If supported by the hypervisor and OS, the optional ``sgio`` (
-      :since:`since 1.0.6` ) attribute indicates whether unprivileged SG_IO
-      commands are filtered for the disk. Valid settings are "filtered" or
-      "unfiltered", where the default is "filtered". The optional ``rawio`` (
-      :since:`since 1.2.9` ) attribute indicates whether the lun needs the rawio
-      capability. Valid settings are "yes" or "no". See the rawio description
-      within the `disk <#elementsDisks>`__ section. If a disk lun in the domain
-      already has the rawio capability, then this setting not required.
-   ``scsi_host``
-      :since:`since 2.5.0` For SCSI devices, user is responsible to make sure
-      the device is not used by host. This ``type`` passes all LUNs presented by
-      a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attribute
-      can be specified further with "virtio-transitional",
-      "virtio-non-transitional", or "virtio". See `Virtio transitional
-      devices <#elementsVirtioTransitional>`__ for more details.
-   ``mdev``
-      For mediated devices ( :since:`Since 3.2.0` ) the ``model`` attribute
-      specifies the device API which determines how the host's vfio driver will
-      expose the device to the guest. Currently, ``model='vfio-pci'``,
-      ``model='vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model='vfio-ap'`` (
-      :since:`Since 4.9.0` ) is supported. `MDEV <drvnodedev.html#MDEV>`__
-      section provides more information about mediated devices as well as how to
-      create mediated devices on the host. :since:`Since 4.6.0 (QEMU 2.12)` an
-      optional ``display`` attribute may be used to enable or disable support
-      for an accelerated remote desktop backed by a mediated device (such as
-      NVIDIA vGPU or Intel GVT-g) as an alternative to emulated `video
-      devices <#elementsVideo>`__. This attribute is limited to
-      ``model='vfio-pci'`` only. Supported values are either ``on`` or ``off``
-      (default is 'off'). It is required to use a `graphical
-      framebuffer <#elementsGraphics>`__ in order to use this attribute,
-      currently only supported with VNC, Spice and egl-headless graphics
-      devices. :since:`Since version 5.10.0` , there is an optional ``ramfb``
-      attribute for devices with ``model='vfio-pci'``. Supported values are
-      either ``on`` or ``off`` (default is 'off'). When enabled, this attribute
-      provides a memory framebuffer device to the guest. This framebuffer will
-      be used as a boot display when a vgpu device is the primary display.
-
-      Note: There are also some implications on the usage of guest's address
-      type depending on the ``model`` attribute, see the ``address`` element
-      below.
-
-   Note: The ``managed`` attribute is only used with ``type='pci'`` and is
-   ignored by all the other device types, thus setting ``managed`` explicitly
-   with other than a PCI device has the same effect as omitting it. Similarly,
-   ``model`` attribute is only supported by mediated devices and ignored by all
-   other device types.
-
-``source``
-   The source element describes the device as seen from the host using the
-   following mechanism to describe:
-
-   ``usb``
-      The USB device can either be addressed by vendor / product id using the
-      ``vendor`` and ``product`` elements or by the device's address on the host
-      using the ``address`` element.
-
-      :since:`Since 1.0.0` , the ``source`` element of USB devices may contain
-      ``startupPolicy`` attribute which can be used to define policy what to do
-      if the specified host USB device is not found. The attribute accepts the
-      following values:
-
-      ========= =====================================================================
-      mandatory fail if missing for any reason (the default)
-      requisite fail if missing on boot up, drop if missing on migrate/restore/revert
-      optional  drop if missing at any start attempt
-      ========= =====================================================================
-
-   ``pci``
-      PCI devices can only be described by their ``address``.
-   ``scsi``
-      SCSI devices are described by both the ``adapter`` and ``address``
-      elements. The ``address`` element includes a ``bus`` attribute (a 2-digit
-      bus number), a ``target`` attribute (a 10-digit target number), and a
-      ``unit`` attribute (a 20-digit unit number on the bus). Not all
-      hypervisors support larger ``target`` and ``unit`` values. It is up to
-      each hypervisor to determine the maximum value supported for the adapter.
-
-      :since:`Since 1.2.8` , the ``source`` element of a SCSI device may contain
-      the ``protocol`` attribute. When the attribute is set to "iscsi", the host
-      device XML follows the network `disk <#elementsDisks>`__ device using the
-      same ``name`` attribute and optionally using the ``auth`` element to
-      provide the authentication credentials to the iSCSI server.
-
-   ``scsi_host``
-      :since:`Since 2.5.0` , multiple LUNs behind a single SCSI HBA are
-      described by a ``protocol`` attribute set to "vhost" and a ``wwpn``
-      attribute that is the vhost_scsi wwpn (16 hexadecimal digits with a prefix
-      of "naa.") established in the host configfs.
-   ``mdev``
-      Mediated devices ( :since:`Since 3.2.0` ) are described by the ``address``
-      element. The ``address`` element contains a single mandatory attribute
-      ``uuid``.
-
-``vendor``, ``product``
-   The ``vendor`` and ``product`` elements each have an ``id`` attribute that
-   specifies the USB vendor and product id. The ids can be given in decimal,
-   hexadecimal (starting with 0x) or octal (starting with 0) form.
-``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 0.8.8` for PCI
-   devices, :since:`Since 1.0.1` for USB devices.
-``rom``
-   The ``rom`` element is used to change how a PCI device's ROM is presented to
-   the guest. The optional ``bar`` attribute can be set to "on" or "off", and
-   determines whether or not the device's ROM will be visible in the guest's
-   memory map. (In PCI documentation, the "rombar" setting controls the presence
-   of the Base Address Register for the ROM). If no rom bar is specified, the
-   qemu default will be used (older versions of qemu used a default of "off",
-   while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU and KVM
-   only)` . The optional ``file`` attribute contains an absolute path to a
-   binary file to be presented to the guest as the device's ROM BIOS. This can
-   be useful, for example, to provide a PXE boot ROM for a virtual function of
-   an sr-iov capable ethernet device (which has no boot ROMs for the VFs).
-   :since:`Since 0.9.10 (QEMU and KVM only)` . The optional ``enabled``
-   attribute can be set to ``no`` to disable PCI ROM loading completely for the
-   device; if PCI ROM loading is disabled through this attribute, attempts to
-   tweak the loading process further using the ``bar`` or ``file`` attributes
-   will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)` .
-``address``
-   The ``address`` element for USB devices has a ``bus`` and ``device``
-   attribute to specify the USB bus and device number the device appears at on
-   the host. The values of these attributes can be given in decimal, hexadecimal
-   (starting with 0x) or octal (starting with 0) form. For PCI devices the
-   element carries 4 attributes allowing to designate the device as can be found
-   with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive'
-   address type must be used. For mediated devices, which are software-only
-   devices defining an allocation of resources on the physical parent device,
-   the address type used must conform to the ``model`` attribute of element
-   ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API
-   or any address type other than CCW for ``vfio-ccw`` device API will result in
-   an error. `See above <#elementsAddress>`__ for more details on the address
-   element.
-``driver``
-   PCI devices can have an optional ``driver`` subelement that specifies which
-   backend driver to use for PCI device assignment. Use the ``name`` attribute
-   to select either "vfio" (for the new VFIO device assignment backend, which is
-   compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment
-   handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU and KVM
-   only, requires kernel 3.6 or newer)` . When specified, device assignment will
-   fail if the requested method of device assignment isn't available on the
-   host. When not specified, the default is "vfio" on systems where the VFIO
-   driver is available and loaded, and "kvm" on older systems, or those where
-   the VFIO driver hasn't been loaded :since:`Since 1.1.3` (prior to that the
-   default was always "kvm").
-``readonly``
-   Indicates that the device is readonly, only supported by SCSI host device
-   now. :since:`Since 1.0.6 (QEMU and KVM only)`
-``shareable``
-   If present, this indicates the device is expected to be shared between
-   domains (assuming the hypervisor and OS support this). Only supported by SCSI
-   host device. :since:`Since 1.0.6`
-
-   Note: Although ``shareable`` was introduced :since:`in 1.0.6` , it did not
-   work as as expected until :since:`1.2.2` .
-
-:anchor:`<a id="elementsHostDevCaps"/>`
-
-Block / character devices
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Block / character devices from the host can be passed through to the guest using
-the ``hostdev`` element. This is only possible with container based
-virtualization. Devices are specified by a fully qualified path. :since:`since
-after 1.0.1 for LXC` :
-
-::
-
-   ...
-   <hostdev mode='capabilities' type='storage'>
-     <source>
-       <block>/dev/sdf1</block>
-     </source>
-   </hostdev>
-   ...
-
-::
-
-   ...
-   <hostdev mode='capabilities' type='misc'>
-     <source>
-       <char>/dev/input/event3</char>
-     </source>
-   </hostdev>
-   ...
-
-::
-
-   ...
-   <hostdev mode='capabilities' type='net'>
-     <source>
-       <interface>eth0</interface>
-     </source>
-   </hostdev>
-   ...
-
-``hostdev``
-   The ``hostdev`` element is the main container for describing host devices.
-   For block/character device passthrough ``mode`` is always "capabilities" and
-   ``type`` is "storage" for a block device, "misc" for a character device and
-   "net" for a host network interface.
-``source``
-   The source element describes the device as seen from the host. For block
-   devices, the path to the block device in the host OS is provided in the
-   nested "block" element, while for character devices the "char" element is
-   used. For network interfaces, the name of the interface is provided in the
-   "interface" element.
+.. include:: formatdomain-devices-hostdev.rst

 :anchor:`<a id="elementsRedir"/>`

diff --git a/docs/meson.build b/docs/meson.build
index 0609bfa6a8..9b65954a51 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -130,6 +130,7 @@ docs_rst_files = [
                   'formatdomain-devices-virtio.rst',
                   'formatdomain-devices-controller.rst',
                   'formatdomain-devices-lease.rst',
+                  'formatdomain-devices-hostdev.rst',
                 ]
   },
   { 'name': 'hacking' },
-- 
2.26.2




More information about the libvir-list mailing list