From nobody Sun Feb 8 17:42:21 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) client-ip=205.139.110.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1594749696; cv=none; d=zohomail.com; s=zohoarc; b=PvIYvw4q6S+PYB2vud84ASVo9y3tixw1vu0TrQZyhlh2Z7gW6IXu2EJrb/i2CrAOEUMopF4lBYU3/rg7jdkdcYEsJjMqrH++UAH2Edl3mFJo6JkH+6X0aOPNszrux+misV/Ith8Y14pzErvAvziQ9Hm2gQSHbeCgjZ/VQbLEuYo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1594749696; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=/xO5QDs5XdEeeYlpp/ymvhw1R0KSvlkjLOhrWdBmTwM=; b=lCk5sTMDp4LPvNJRtOU71m0+oNvpj3t6d0fFoRJ9RkLRPPdZzI9dxM4D5a1vNZeJ2n5bhWTfu3sczFm9hc7ZbnIDXeDZZw3x+HTfqOwNdmU8pa5ZNN/4al1ydu/6DadLt8GWKrfqr9/mo+lRG9P3Als4aadwj2HNG9ag43BtE9U= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 205.139.110.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) by mx.zohomail.com with SMTPS id 1594749696489407.27395522422296; Tue, 14 Jul 2020 11:01:36 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-282-SC-FwIMYPme-UFcSB4fBMg-1; Tue, 14 Jul 2020 14:01:31 -0400 Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.phx2.redhat.com [10.5.11.22]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id D4D0E8027F9; Tue, 14 Jul 2020 18:00:36 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 7FF5E10013D7; Tue, 14 Jul 2020 18:00:36 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 4A354180954D; Tue, 14 Jul 2020 18:00:36 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 06EI0UJR024031 for ; Tue, 14 Jul 2020 14:00:30 -0400 Received: by smtp.corp.redhat.com (Postfix) id 7D0D55C679; Tue, 14 Jul 2020 18:00:30 +0000 (UTC) Received: from speedmetal.redhat.com (unknown [10.40.208.29]) by smtp.corp.redhat.com (Postfix) with ESMTP id 971735FC30 for ; Tue, 14 Jul 2020 18:00:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1594749695; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=/xO5QDs5XdEeeYlpp/ymvhw1R0KSvlkjLOhrWdBmTwM=; b=apwg6sBY0buRRsqSRiton7+9C0bw4YG9qOGXCMdOzqTIJrqRUfpfYJXVR7bKyPvDYLYhji QTKxzXmWrOBfY45yCYcTN0CJqOJD6a6MHfi1DtFIpEqP9nYhnAfM+uPyz2dCNnWM5ef/XR kpfxTK7y17IJ6N6nQS1XOJUhaQpub+Q= X-MC-Unique: SC-FwIMYPme-UFcSB4fBMg-1 From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 10/11] docs: formatdomain-devices: Split out '' into separate file Date: Tue, 14 Jul 2020 20:00:15 +0200 Message-Id: <12d94fd9461b2a43c8802a3fb1415d8d68e1b4d4.1594749375.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-loop: libvir-list@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.22 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" Signed-off-by: Peter Krempa --- 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-d= evices-hostdev.rst.in new file mode 100644 index 0000000000..859c4b4ec5 --- /dev/null +++ b/docs/formatdomain-devices-hostdev.rst.in @@ -0,0 +1,337 @@ +:anchor:`` + +Host device assignment +~~~~~~~~~~~~~~~~~~~~~~ + +:anchor:`` + +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)` : + +:: + + ... + + + + + + + + + + ... + +or: + +:: + + ... + + + +
+ + + + + + ... + +or: + +:: + + ... + + + + +
+ + +
+ + + ... + +or: + +:: + + ... + + + + + + + + +
+ + + ... + +or: + +:: + + ... + + + + + + ... + +or: + +:: + + ... + + + +
+ + + + +
+ +
+ + + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devic= es. + 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 reattach= ed + after the guest exits or the device is hot-unplugged. + ``pci`` + For PCI devices, when ``managed`` is "yes" it is detached from the h= ost + 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 responsi= ble 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 descript= ion + within the `disk <#elementsDisks>`__ section. If a disk lun in the d= omain + 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 s= ure + the device is not used by host. This ``type`` passes all LUNs presen= ted by + a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attri= bute + 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=3D'vfio-pci'``, + ``model=3D'vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model=3D'vfio-= ap'`` ( + :since:`Since 4.9.0` ) is supported. `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 supp= ort + 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=3D'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 ``ramf= b`` + attribute for devices with ``model=3D'vfio-pci'``. Supported values = are + either ``on`` or ``off`` (default is 'off'). When enabled, this attr= ibute + 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 addre= ss + type depending on the ``model`` attribute, see the ``address`` eleme= nt + below. + + Note: The ``managed`` attribute is only used with ``type=3D'pci'`` and = is + ignored by all the other device types, thus setting ``managed`` explici= tly + with other than a PCI device has the same effect as omitting it. Simila= rly, + ``model`` attribute is only supported by mediated devices and ignored b= y 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 th= e host + using the ``address`` element. + + :since:`Since 1.0.0` , the ``source`` element of USB devices may con= tain + ``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: + + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + mandatory fail if missing for any reason (the default) + requisite fail if missing on boot up, drop if missing on migrate/res= tore/revert + optional drop if missing at any start attempt + =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D + + ``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 ada= pter. + + :since:`Since 1.2.8` , the ``source`` element of a SCSI device may c= ontain + the ``protocol`` attribute. When the attribute is set to "iscsi", th= e host + device XML follows the network `disk <#elementsDisks>`__ device usin= g 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 ``add= ress`` + element. The ``address`` element contains a single mandatory attribu= te + ``uuid``. + +``vendor``, ``product`` + The ``vendor`` and ``product`` elements each have an ``id`` attribute t= hat + specifies the USB vendor and product id. The ids can be given in decima= l, + hexadecimal (starting with 0x) or octal (starting with 0) form. +``boot`` + Specifies that the device is bootable. The ``order`` attribute determin= es the + order in which devices will be tried during boot sequence. The per-devi= ce + ``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 present= ed 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 pr= esence + 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 "of= f", + while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU an= d 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 functio= n 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 fo= r the + device; if PCI ROM loading is disabled through this attribute, attempts= to + tweak the loading process further using the ``bar`` or ``file`` attribu= tes + 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 a= t on + the host. The values of these attributes can be given in decimal, hexad= ecimal + (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 devi= ce, + the address type used must conform to the ``model`` attribute of element + ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` devi= ce API + or any address type other than CCW for ``vfio-ccw`` device API will res= ult in + an error. `See above <#elementsAddress>`__ for more details on the addr= ess + element. +``driver`` + PCI devices can have an optional ``driver`` subelement that specifies w= hich + backend driver to use for PCI device assignment. Use the ``name`` attri= bute + to select either "vfio" (for the new VFIO device assignment backend, wh= ich is + compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment + handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU an= d KVM + only, requires kernel 3.6 or newer)` . When specified, device assignmen= t 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 VF= IO + driver is available and loaded, and "kvm" on older systems, or those wh= ere + 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 devi= ce + 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 b= y 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:`` + +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:`s= ince +after 1.0.1 for LXC` : + +:: + + ... + + + /dev/sdf1 + + + ... + +:: + + ... + + + /dev/input/event3 + + + ... + +:: + + ... + + + eth0 + + + ... + +``hostdev`` + The ``hostdev`` element is the main container for describing host devic= es. + 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.r= st.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:`` - -Host device assignment -~~~~~~~~~~~~~~~~~~~~~~ - -:anchor:`` - -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)` : - -:: - - ... - - - - - - - - - - ... - -or: - -:: - - ... - - - -
- - - - - - ... - -or: - -:: - - ... - - - - -
- - -
- - - ... - -or: - -:: - - ... - - - - - - - - -
- - - ... - -or: - -:: - - ... - - - - - - ... - -or: - -:: - - ... - - - -
- - - - -
- -
- - - ... - -``hostdev`` - The ``hostdev`` element is the main container for describing host devic= es. - 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 reattach= ed - after the guest exits or the device is hot-unplugged. - ``pci`` - For PCI devices, when ``managed`` is "yes" it is detached from the h= ost - 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 responsi= ble 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 descript= ion - within the `disk <#elementsDisks>`__ section. If a disk lun in the d= omain - 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 s= ure - the device is not used by host. This ``type`` passes all LUNs presen= ted by - a single HBA to the guest. :since:`Since 5.2.0,` the ``model`` attri= bute - 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=3D'vfio-pci'``, - ``model=3D'vfio-ccw'`` ( :since:`Since 4.4.0` ) and ``model=3D'vfio-= ap'`` ( - :since:`Since 4.9.0` ) is supported. `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 supp= ort - 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=3D'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 ``ramf= b`` - attribute for devices with ``model=3D'vfio-pci'``. Supported values = are - either ``on`` or ``off`` (default is 'off'). When enabled, this attr= ibute - 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 addre= ss - type depending on the ``model`` attribute, see the ``address`` eleme= nt - below. - - Note: The ``managed`` attribute is only used with ``type=3D'pci'`` and = is - ignored by all the other device types, thus setting ``managed`` explici= tly - with other than a PCI device has the same effect as omitting it. Simila= rly, - ``model`` attribute is only supported by mediated devices and ignored b= y 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 th= e host - using the ``address`` element. - - :since:`Since 1.0.0` , the ``source`` element of USB devices may con= tain - ``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: - - =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D - mandatory fail if missing for any reason (the default) - requisite fail if missing on boot up, drop if missing on migrate/res= tore/revert - optional drop if missing at any start attempt - =3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D - - ``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 ada= pter. - - :since:`Since 1.2.8` , the ``source`` element of a SCSI device may c= ontain - the ``protocol`` attribute. When the attribute is set to "iscsi", th= e host - device XML follows the network `disk <#elementsDisks>`__ device usin= g 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 ``add= ress`` - element. The ``address`` element contains a single mandatory attribu= te - ``uuid``. - -``vendor``, ``product`` - The ``vendor`` and ``product`` elements each have an ``id`` attribute t= hat - specifies the USB vendor and product id. The ids can be given in decima= l, - hexadecimal (starting with 0x) or octal (starting with 0) form. -``boot`` - Specifies that the device is bootable. The ``order`` attribute determin= es the - order in which devices will be tried during boot sequence. The per-devi= ce - ``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 present= ed 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 pr= esence - 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 "of= f", - while newer qemus have a default of "on"). :since:`Since 0.9.7 (QEMU an= d 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 functio= n 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 fo= r the - device; if PCI ROM loading is disabled through this attribute, attempts= to - tweak the loading process further using the ``bar`` or ``file`` attribu= tes - 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 a= t on - the host. The values of these attributes can be given in decimal, hexad= ecimal - (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 devi= ce, - the address type used must conform to the ``model`` attribute of element - ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` devi= ce API - or any address type other than CCW for ``vfio-ccw`` device API will res= ult in - an error. `See above <#elementsAddress>`__ for more details on the addr= ess - element. -``driver`` - PCI devices can have an optional ``driver`` subelement that specifies w= hich - backend driver to use for PCI device assignment. Use the ``name`` attri= bute - to select either "vfio" (for the new VFIO device assignment backend, wh= ich is - compatible with UEFI SecureBoot) or "kvm" (the legacy device assignment - handled directly by the KVM kernel module) :since:`Since 1.0.5 (QEMU an= d KVM - only, requires kernel 3.6 or newer)` . When specified, device assignmen= t 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 VF= IO - driver is available and loaded, and "kvm" on older systems, or those wh= ere - 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 devi= ce - 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 b= y 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:`` - -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:`s= ince -after 1.0.1 for LXC` : - -:: - - ... - - - /dev/sdf1 - - - ... - -:: - - ... - - - /dev/input/event3 - - - ... - -:: - - ... - - - eth0 - - - ... - -``hostdev`` - The ``hostdev`` element is the main container for describing host devic= es. - 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:`` --=20 2.26.2