Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
docs/formatdomain-devices-hostdev.rst.in | 337 ++++++++++++++++++++++
docs/formatdomain-devices.rst.in | 338 +----------------------
2 files changed, 338 insertions(+), 337 deletions(-)
create mode 100644 docs/formatdomain-devices-hostdev.rst.in
diff --git a/docs/formatdomain-devices-hostdev.rst.in b/docs/formatdomain-devices-hostdev.rst.in
new file mode 100644
index 0000000000..859c4b4ec5
--- /dev/null
+++ b/docs/formatdomain-devices-hostdev.rst.in
@@ -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.in b/docs/formatdomain-devices.rst.in
index c7cc190918..ad24410ecb 100644
--- a/docs/formatdomain-devices.rst.in
+++ b/docs/formatdomain-devices.rst.in
@@ -706,343 +706,7 @@ acquired.
The offset specifies where the lease is stored within the file. If the lock
manager does not require an offset, just pass 0.
-: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.in
:anchor:`<a id="elementsRedir"/>`
--
2.26.2
