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

Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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