From nobody Mon Feb 9 18:46:22 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 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=1648469476; cv=none; d=zohomail.com; s=zohoarc; b=GAKx11VcwB3u7T8HcR8kuco8GZNPjKb+FzwR4iuG52Uq2k3YTGJd8m1ymBPXz/6JqzhgTkfPVmbt5FBBbs7NcEzGJZLaCKGb0KEmAJVnu/ahivRMcHpNwVbTerEID1iACjGI5wC+3QLxEccWcbLUL5tCgRrRwVrwUhBhfudKgM4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1648469476; 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=xlWIGvifiOpRZmcgehZSXewVc6GrFktxyhIf6uyU70I=; b=ipBvZJoTQJ5I2XnYi0619U/0gTaQzyKPGCB+uCKhY2DRU9I8aH1ST8tJa3WzGBzWg/kA11ochaF64EVqLBqRnfF1fKPAawl9sc8P36S0V5lzhkXKDg8sxnspf7EwF4xIzgv0WJl40Yb9fA8cQ41Duy6dW9CyZatB5hKCwzWpe2k= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1648469476486221.88592125232321; Mon, 28 Mar 2022 05:11:16 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-494-6XdR0ExAPoqSfo8RQFlMCg-1; Mon, 28 Mar 2022 08:11:11 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3E98618A6581; Mon, 28 Mar 2022 12:11:08 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 26563400E10D; Mon, 28 Mar 2022 12:11:08 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 62F211940354; Mon, 28 Mar 2022 12:11:07 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id E25031940344 for ; Mon, 28 Mar 2022 12:11:04 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id B5B7F1402642; Mon, 28 Mar 2022 12:11:04 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.35]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0ADBA1400B19 for ; Mon, 28 Mar 2022 12:11:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648469475; 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=xlWIGvifiOpRZmcgehZSXewVc6GrFktxyhIf6uyU70I=; b=Y0SvojvcDTccEjNbNja0By/gDwZZ2iaVuJKcG1HRlRiOvljy1g/Lk7bFxvX4NL/8O1y8/I io41gzUxaPS5NDMtzB2mvcj0zLF5vNOWkTQkmFLTgnm2oxPpUMflFDMJSbolsixmpCVEfB tXHXjxH+ej+oDGl4sldEirlX+nC+MCk= X-MC-Unique: 6XdR0ExAPoqSfo8RQFlMCg-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH 18/29] docs: Convert 'formatdomaincaps' to rST Date: Mon, 28 Mar 2022 14:10:33 +0200 Message-Id: <469440d67190405d1f19a6064ba0702058bcad30.1648469356.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1648469478311100003 Content-Type: text/plain; charset="utf-8"; x-default="true" Signed-off-by: Peter Krempa --- docs/formatdomain.rst | 20 +- docs/formatdomaincaps.html.in | 693 ---------------------------------- docs/formatdomaincaps.rst | 602 +++++++++++++++++++++++++++++ docs/kbase/backing_chains.rst | 2 +- docs/meson.build | 2 +- 5 files changed, 614 insertions(+), 705 deletions(-) delete mode 100644 docs/formatdomaincaps.html.in create mode 100644 docs/formatdomaincaps.rst diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 95ace2677e..2dc52baa14 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -1406,15 +1406,15 @@ In case no restrictions need to be put on CPU model= and its features, a simpler expected. :since:`Since 3.2.0 and QEMU 2.9.0` this mode works the wa= y it was designed and it is indicated by the ``fallback`` attribute set to ``forbid`` in the host-model CPU definition advertised in `domain - capabilities XML `__. When ``fall= back`` - attribute is set to ``allow`` in the domain capabilities XML, it is - recommended to use ``custom`` mode with just the CPU model from the = host - capabilities XML. :since:`Since 1.2.11` PowerISA allows processors t= o run - VMs in binary compatibility mode supporting an older version of ISA. - Libvirt on PowerPC architecture uses the ``host-model`` to signify a= guest - mode CPU running in binary compatibility mode. Example: When a user = needs - a power7 VM to run in compatibility mode on a Power8 host, this can = be - described in XML as follows : + capabilities XML `__. When + ``fallback`` attribute is set to ``allow`` in the domain capabilities + XML, it is recommended to use ``custom`` mode with just the CPU model + from the host capabilities XML. :since:`Since 1.2.11` PowerISA allows + processors to run VMs in binary compatibility mode supporting an old= er + version of ISA. Libvirt on PowerPC architecture uses the ``host-mod= el`` + to signify a guest mode CPU running in binary compatibility mode. + Example: When a user needs a power7 VM to run in compatibility mode = on a + Power8 host, this can be described in XML as follows : :: @@ -2902,7 +2902,7 @@ paravirtualized driver is specified via the ``disk`` = element. This element describes the backing store used by the disk specified by sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor dri= ver does not support the - `backingStoreInput `__ ( + `backingStoreInput `__ ( :since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored = on input and only used for output to describe the detected backing chains = of running domains. If ``backingStoreInput`` is supported the ``backingSto= re`` diff --git a/docs/formatdomaincaps.html.in b/docs/formatdomaincaps.html.in deleted file mode 100644 index 35b8bf3def..0000000000 --- a/docs/formatdomaincaps.html.in +++ /dev/null @@ -1,693 +0,0 @@ - - - - -

Domain capabilities XML format

- -
    - -

    Overview

    - -

    Sometimes, when a new domain is to be created it may come handy to = know - the capabilities of the hypervisor so the correct combination of devic= es and - drivers is used. For example, when management application is consideri= ng the - mode for a host device's passthrough there are several options dependi= ng not - only on host, but on hypervisor in question too. If the hypervisor is = qemu - then it needs to be more recent to support VFIO, while legacy KVM is - achievable just fine with older qemus.

    - -

    The main difference between - - virConnectGetCapabilities - - and the emulator capabilities API is, the former one aims more on - the host capabilities (e.g. NUMA topology, security models in - effect, etc.) while the latter one specializes on the hypervisor - capabilities.

    - -

    While the Driver Capabilities provi= des the - host capabilities (e.g NUMA topology, security models in effect, etc.)= , the - Domain Capabilities provides the hypervisor specific capabilities for - Management Applications to query and make decisions regarding what to - utilize.

    - -

    The Domain Capabilities can provide information such as the correct - combination of devices and drivers that are supported. Knowing which h= ost - and hypervisor specific options are available or supported would allow= the - management application to choose an appropriate mode for a pass-through - host device as well as which adapter to utilize.

    - -

    Some XML elements may be entirely omitted from the domaincapabiliti= es - XML, depending on what the libvirt driver has filled in. Applications - should only act on what is explicitly reported in the domaincapabiliti= es - XML. For example, if <disk supported=3D'yes'/> is present, you c= an safely - assume the driver supports <disk> devices. If <disk supported= =3D'no'/> is - present, you can safely assume the driver does NOT support <disk> - devices. If the <disk> block is omitted entirely, the driver is = not - indicating one way or the other whether it supports <disk> devic= es, and - applications should not interpret the missing block to mean any thing = in - particular.

    - -

    Element and attribute overview

    - -

    A new query interface was added to the virConnect API's to retriev= e the - XML listing of the set of domain capabilities (S= ince - 1.2.7):

    - -
    -virConnectGetDomainCapabilities
-
    - -

    The root element that emulator capability XML document starts with = has - name domainCapabilities. It contains at least four direct - child elements:

    - -
    -<domainCapabilities>
-  <path>/usr/bin/qemu-system-x86_64</path>
-  <domain>kvm</domain>
-  <machine>pc-i440fx-2.1</machine>
-  <arch>x86_64</arch>
-  ...
-</domainCapabilities>
-
    -
    -
    path
    -
    The full path to the emulator binary.
    - -
    domain
    -
    Describes the virtualizat= ion - type (or so called domain type).
    - -
    machine
    -
    The domain's machine - type. Since not every hypervisor has a sense of machine types - this element might be omitted in such drivers.
    - -
    arch
    -
    The domain's - architecture.
    - -
    - -

    CPU Allocation

    - -

    Before any devices capability occurs, there might be info on domain - wide capabilities, e.g. virtual CPUs:

    - -
    -<domainCapabilities>
-  ...
-  <vcpu max=3D'255'/>
-  ...
-</domainCapabilities>
-
    - -
    -
    vcpu
    -
    The maximum number of supported virtual CPUs
    -
    - -

    BIOS bootloader

    - -

    Sometimes users might want to tweak some BIOS knobs or use - UEFI. For cases like that, os - element exposes what values can be passed to its children.

    - -
    -<domainCapabilities>
-  ...
-  <os supported=3D'yes'>
-    <enum name=3D'firmware'>
-      <value>bios</value>
-      <value>efi</value>
-    </enum>
-    <loader supported=3D'yes'>
-      <value>/usr/share/OVMF/OVMF_CODE.fd</value>
-      <enum name=3D'type'>
-        <value>rom</value>
-        <value>pflash</value>
-      </enum>
-      <enum name=3D'readonly'>
-        <value>yes</value>
-        <value>no</value>
-      </enum>
-      <enum name=3D'secure'>
-        <value>yes</value>
-        <value>no</value>
-      </enum>
-    </loader>
-  </os>
-  ...
-<domainCapabilities>
-
    - -

    The firmware enum corresponds to the - firmware attribute of the os element in - the domain XML. The presence of this enum means libvirt is capable - of the so-called firmware auto-selection feature. And the listed - firmware values represent the accepted input in the domain - XML. Note that the firmware enum reports only those - values for which a firmware "descriptor file" exists on the host. - Firmware descriptor file is a small JSON document that describes - details about a given BIOS or UEFI binary on the host, e.g. the - firmware binary path, its architecture, supported machine types, - NVRAM template, etc. This ensures that the reported values won't - cause a failure on guest boot. -

    - -

    For the loader element, the following can occur:

    - -
    -
    value
    -
    List of known firmware binary paths. Currently this is used - only to advertise the known location of OVMF binaries for - QEMU. OVMF binaries will only be listed if they actually exist on - host.
    - -
    type
    -
    Whether the boot loader is a typical BIOS (rom) - or a UEFI firmware (pflash). Each value - sub-element under the type enum represents a possible - value for the type attribute for the <loader/> - element in the domain XML. E.g. the presence - of pfalsh under the type enum means that - a domain XML can use UEFI firmware via: <loader/> - type=3D"pflash" ...>/path/to/the/firmware/binary/</loader>. -
    - -
    readonly
    -
    Options for the readonly attribute of the - <loader/> element in the domain XML.
    - -
    secure
    -
    Options for the secure attribute of the - <loader/> element in the domain XML. Note that the - value yes is listed only if libvirt detects a - firmware descriptor file that has path to an OVMF binary that - supports Secure boot, and lists its architecture and supported - machine type.
    -
    - -

    CPU configuration

    - -

    - The cpu element exposes options usable for configuring - guest CPUs. -

    - -
    -<domainCapabilities>
-  ...
-  <cpu>
-    <mode name=3D'host-passthrough' supported=3D'yes'>
-      <enum name=3D'hostPassthroughMigratable'>
-        <value>on</value>
-        <value>off</value>
-      </enum>
-    </mode>
-    <mode name=3D'maximum' supported=3D'yes'>
-      <enum name=3D'maximumMigratable'>
-        <value>on</value>
-        <value>off</value>
-      </enum>
-    </mode>
-    <mode name=3D'host-model' supported=3D'yes'>
-      <model fallback=3D'allow'>Broadwell</model>
-      <vendor>Intel</vendor>
-      <feature policy=3D'disable' name=3D'aes'/>
-      <feature policy=3D'require' name=3D'vmx'/>
-    </mode>
-    <mode name=3D'custom' supported=3D'yes'>
-      <model usable=3D'no' deprecated=3D'no'>Broadwell</model>
-      <model usable=3D'yes' deprecated=3D'no'>Broadwell-noTSX</mo=
del>
-      <model usable=3D'no' deprecated=3D'yes'>Haswell</model>
-      ...
-    </mode>
-  </cpu>
-  ...
-<domainCapabilities>
-
    - -

    - Each CPU mode understood by libvirt is described with a - mode element which tells whether the particular mode - is supported and provides (when applicable) more details about it: -

    - -
    -
    host-passthrough
    -
    - The hostPassthroughMigratable enum shows possible val= ues - of the migratable attribute for the <cpu> eleme= nt - with mode=3D'host-passthrough' in the domain XML. -
    - -
    host-model
    -
    - If host-model is supported by the hypervisor, the - mode describes the guest CPU which will be used when - starting a domain with host-model CPU. The hypervisor - specifics (such as unsupported CPU models or features, machine typ= e, - etc.) may be accounted for in this guest CPU specification and thus - the CPU can be different from the one shown in host capabilities X= ML. - This is indicated by the fallback attribute of the - model sub element: allow means not all - specifics were accounted for and thus the CPU a guest will see may - be different; forbid indicates that the CPU a guest w= ill - see should match this CPU definition. -
    - -
    custom
    -
    - The mode element contains a list of supported CPU - models, each described by a dedicated model element. - The usable attribute specifies whether the model can - be used directly on the host. When usable=3D'no' the corresponding= model - cannot be used without disabling some features that the CPU of such - model is expected to have. A special value unknown - indicates libvirt does not have enough information to provide the - usability data. The deprecated attribute reflects - the hypervisor's policy on usage of this model - (since 7.1.0). -
    -
    - -

    I/O Threads

    - -

    - The iothread elements indicates whether or not - I/O thread= s - are supported. -

    - -
    -<domainCapabilities>
-  ...
-  <iothread supported=3D'yes'/>
-  ...
-<domainCapabilities>
-
    - -

    Memory Backing

    - -

    - The memory backing element indicates whether or not - memory backing - is supported. -

    - -
    -<domainCapabilities>
-  ...
-  <memoryBacking supported=3D'yes'>
-    <enum name=3D'sourceType'>
-      <value>anonymous</value>
-      <value>file</value>
-      <value>memfd</value>
-    </enum>
-  </memoryBacking>
-  ...
-<domainCapabilities>
-
    - -
    -
    sourceType
    -
    Options for the type attribute of the - <memoryBacking><source> element.
    -
    - -

    Devices

    - -

    - Another set of XML elements describe the supported devices and their - capabilities. All devices occur as children of the main - devices element. -

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <disk supported=3D'yes'>
-      <enum name=3D'diskDevice'>
-        <value>disk</value>
-        <value>cdrom</value>
-        <value>floppy</value>
-        <value>lun</value>
-      </enum>
-      ...
-    </disk>
-    <hostdev supported=3D'no'/>
-  </devices>
-</domainCapabilities>
-
    - -

    Reported capabilities are expressed as an enumerated list of availa= ble - options for each of the element or attribute. For example, the - <disk/> element has an attribute device which can - support the values disk, cdrom, - floppy, or lun.

    - -

    Hard drives, floppy disks, CDROMs

    -

    Disk capabilities are exposed under the disk element. = For - instance:

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <disk supported=3D'yes'>
-      <enum name=3D'diskDevice'>
-        <value>disk</value>
-        <value>cdrom</value>
-        <value>floppy</value>
-        <value>lun</value>
-      </enum>
-      <enum name=3D'bus'>
-        <value>ide</value>
-        <value>fdc</value>
-        <value>scsi</value>
-        <value>virtio</value>
-        <value>xen</value>
-        <value>usb</value>
-        <value>sata</value>
-        <value>sd</value>
-      </enum>
-    </disk>
-    ...
-  </devices>
-</domainCapabilities>
-
    - -
    -
    diskDevice
    -
    Options for the device attribute of the <disk/&g= t; - element.
    - -
    bus
    -
    Options for the bus attribute of the <target/> - element for a <disk/>.
    -
    - - -

    Graphical framebuffers

    -

    Graphics device capabilities are exposed under the - graphics element. For instance:

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <graphics supported=3D'yes'>
-      <enum name=3D'type'>
-        <value>sdl</value>
-        <value>vnc</value>
-        <value>spice</value>
-      </enum>
-    </graphics>
-    ...
-  </devices>
-</domainCapabilities>
-
    - -
    -
    type
    -
    Options for the type attribute of the <graphics/= > - element.
    -
    - - -

    Video device

    -

    Video device capabilities are exposed under the - video element. For instance:

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <video supported=3D'yes'>
-      <enum name=3D'modelType'>
-        <value>vga</value>
-        <value>cirrus</value>
-        <value>vmvga</value>
-        <value>qxl</value>
-        <value>virtio</value>
-      </enum>
-    </video>
-    ...
-  </devices>
-</domainCapabilities>
-
    - -
    -
    modelType
    -
    Options for the type attribute of the - <video><model> element.
    -
    - - -

    Host device assignment

    -

    Some host devices can be passed through to a guest (e.g. USB, PCI a= nd - SCSI). Well, only if the following is enabled:

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <hostdev supported=3D'yes'>
-      <enum name=3D'mode'>
-        <value>subsystem</value>
-        <value>capabilities</value>
-      </enum>
-      <enum name=3D'startupPolicy'>
-        <value>default</value>
-        <value>mandatory</value>
-        <value>requisite</value>
-        <value>optional</value>
-      </enum>
-      <enum name=3D'subsysType'>
-        <value>usb</value>
-        <value>pci</value>
-        <value>scsi</value>
-      </enum>
-      <enum name=3D'capsType'>
-        <value>storage</value>
-        <value>misc</value>
-        <value>net</value>
-      </enum>
-      <enum name=3D'pciBackend'>
-        <value>default</value>
-        <value>kvm</value>
-        <value>vfio</value>
-        <value>xen</value>
-      </enum>
-    </hostdev>
-  </devices>
-</domainCapabilities>
-
    - -
    -
    mode
    -
    Options for the mode attribute of the <hostdev/&= gt; - element.
    - -
    startupPolicy
    -
    Options for the startupPolicy attribute of the - <hostdev/> element.
    - -
    subsysType
    -
    Options for the type attribute of the <hostdev/&= gt; - element in case of mode=3D"subsystem".
    - -
    capsType
    -
    Options for the type attribute of the <hostdev/&= gt; - element in case of mode=3D"capabilities".
    - -
    pciBackend
    -
    Options for the name attribute of the <driver/&g= t; - element.
    -
    - - -

    RNG device

    -

    RNG device capabilities are exposed under the - rng element. For instance:

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <rng supported=3D'yes'>
-      <enum name=3D'model'>
-        <value>virtio</value>
-        <value>virtio-transitional</value>
-        <value>virtio-non-transitional</value>
-      </enum>
-      <enum name=3D'backendModel'>
-        <value>random</value>
-        <value>egd</value>
-        <value>builtin</value>
-      </enum>
-    </rng>
-    ...
-  </devices>
-</domainCapabilities>
-
    - -
    -
    model
    -
    Options for the model attribute of the - <rng> element.
    -
    backendModel
    -
    Options for the model attribute of the - <rng><backend> element.
    -
    - - -

    Filesystem device

    -

    Filesystem device capabilities are exposed under the - filesystem element. For instance:

    - -
    -<domainCapabilities>
-  ...
-  <devices>
-    <filesystem supported=3D'yes'>
-      <enum name=3D'driverType'>
-        <value>default</value>
-        <value>path</value>
-        <value>handle</value>
-        <value>virtiofs</value>
-      </enum>
-    </filesystem>
-    ...
-  </devices>
-</domainCapabilities>
-
    - -
    -
    driverType
    -
    Options for the type attribute of the - <filesystem><driver> element.
    -
    - - -

    Features

    - -

    One more set of XML elements describe the supported features and - their capabilities. All features occur as children of the main - features element.

    - -
    -<domainCapabilities>
-  ...
-  <features>
-    <gic supported=3D'yes'>
-      <enum name=3D'version'>
-        <value>2</value>
-        <value>3</value>
-      </enum>
-    </gic>
-    <vmcoreinfo supported=3D'yes'/>
-    <genid supported=3D'yes'/>
-    <backingStoreInput supported=3D'yes'/>
-    <backup supported=3D'yes'/>
-    <sev>
-      <cbitpos>47</cbitpos>
-      <reduced-phys-bits>1</reduced-phys-bits>
-    </sev>
-  </features>
-</domainCapabilities>
-
    - -

    Reported capabilities are expressed as an enumerated list of - possible values for each of the elements or attributes. For example, t= he - gic element has an attribute version which c= an - support the values 2 or 3.

    - -

    For information about the purpose of each feature, see the - relevant section in - the domain XML documentation. -

    - -

    GIC capabilities

    - -

    GIC capabilities are exposed under the gic element.

    - -
    -
    version
    -
    Options for the version attribute of the - gic element.
    -
    - -

    vmcoreinfo

    - -

    Reports whether the vmcoreinfo feature can be enabled.

    - -

    genid

    - -

    Reports whether the genid feature can be used by the domain.

    - -

    backingStoreInput

    - -

    Reports whether the hypervisor will obey the <backingStore> - elements configured for a <disk> when booting the guest, hotplug= ging - the disk to a running guest, or similar. - (Since 5.10) -

    - -

    backup

    - -

    Reports whether the hypervisor supports the backup, checkpoint, and - related features. (virDomainBackupBegin, - virDomainCheckpointCreateXML etc). The presence of the - backup element even if supported=3D'no' impl= ies that - the VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA flag for - virDomainUndefine is supported. -

    - -

    s390-pv capability

    - -

    Reports whether the hypervisor supports the Protected Virtualizatio= n. - In order to use Protected Virtualization with libvirt have a look at t= he - launchSecurity element in= the - domain XML. For more details on the Protected Virtualization featu= re - please see Protected - Virtualization on s390. -

    - -

    SEV capabilities

    - -

    AMD Secure Encrypted Virtualization (SEV) capabilities are exposed = under - the sev element. - SEV is an extension to the AMD-V architecture which supports running - virtual machines (VMs) under the control of a hypervisor. When support= ed, - guest owner can create a VM whose memory contents will be transparently - encrypted with a key unique to that VM.

    - -

    - For more details on the SEV feature, please follow resources in the - AMD developer's document store. In order to use SEV with libvirt have - a look at SEV in domain= XML -

    - -
    -
    cbitpos
    -
    When memory encryption is enabled, one of the physical address b= its - (aka the C-bit) is utilized to mark if a memory page is protected. T= he - C-bit position is Hypervisor dependent.
    -
    reducedPhysBits
    -
    When memory encryption is enabled, we lose certain bits in physi= cal - address space. The number of bits we lose is hypervisor dependent. -
    maxGuests
    -
    The maximum number of SEV guests that can be launched on the hos= t. - This value may be configurable in the firmware for some hosts.
    -
    maxESGuests
    -
    The maximum number of SEV-ES guests that can be launched on the = host. - This value may be configurable in the firmware for some hosts.
    -
    - - - diff --git a/docs/formatdomaincaps.rst b/docs/formatdomaincaps.rst new file mode 100644 index 0000000000..c07c07da4b --- /dev/null +++ b/docs/formatdomaincaps.rst @@ -0,0 +1,602 @@ +.. role:: since + +=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 +Domain capabilities XML format +=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 + +.. contents:: + +Overview +-------- + +Sometimes, when a new domain is to be created it may come handy to know the +capabilities of the hypervisor so the correct combination of devices and d= rivers +is used. For example, when management application is considering the mode = for a +host device's passthrough there are several options depending not only on = host, +but on hypervisor in question too. If the hypervisor is qemu then it needs= to be +more recent to support VFIO, while legacy KVM is achievable just fine with= older +qemus. + +The main difference between +`virConnectGetCapabilities `__ +and the emulator capabilities API is, the former one aims more on the host +capabilities (e.g. NUMA topology, security models in effect, etc.) while t= he +latter one specializes on the hypervisor capabilities. + +While the `Driver Capabilities `__ provides the host +capabilities (e.g NUMA topology, security models in effect, etc.), the Dom= ain +Capabilities provides the hypervisor specific capabilities for Management +Applications to query and make decisions regarding what to utilize. + +The Domain Capabilities can provide information such as the correct combin= ation +of devices and drivers that are supported. Knowing which host and hypervis= or +specific options are available or supported would allow the management +application to choose an appropriate mode for a pass-through host device a= s well +as which adapter to utilize. + +Some XML elements may be entirely omitted from the domaincapabilities XML, +depending on what the libvirt driver has filled in. Applications should on= ly act +on what is explicitly reported in the domaincapabilities XML. For example,= if + is present, you can safely assume the driver sup= ports + devices. If is present, you can safely ass= ume the +driver does NOT support devices. If the block is omitted ent= irely, +the driver is not indicating one way or the other whether it supports +devices, and applications should not interpret the missing block to mean a= ny +thing in particular. + +Element and attribute overview +------------------------------ + +A new query interface was added to the virConnect API's to retrieve the XML +listing of the set of domain capabilities ( :since:`Since 1.2.7` ): + +:: + + virConnectGetDomainCapabilities + +The root element that emulator capability XML document starts with has name +``domainCapabilities``. It contains at least four direct child elements: + +:: + + + /usr/bin/qemu-system-x86_64 + kvm + pc-i440fx-2.1 + x86_64 + ... + + +``path`` + The full path to the emulator binary. +``domain`` + Describes the `virtualization type `__ (or = so + called domain type). +``machine`` + The domain's `machine type `__. Since= not + every hypervisor has a sense of machine types this element might be omi= tted + in such drivers. +``arch`` + The domain's `architecture `__. + +CPU Allocation +~~~~~~~~~~~~~~ + +Before any devices capability occurs, there might be info on domain wide +capabilities, e.g. virtual CPUs: + +:: + + + ... + + ... + + +``vcpu`` + The maximum number of supported virtual CPUs + +BIOS bootloader +~~~~~~~~~~~~~~~ + +Sometimes users might want to tweak some BIOS knobs or use UEFI. For cases= like +that, `os `__ element exposes what value= s can +be passed to its children. + +:: + + + ... + + + bios + efi + + + /usr/share/OVMF/OVMF_CODE.fd + + rom + pflash + + + yes + no + + + yes + no + + + + ... + + +The ``firmware`` enum corresponds to the ``firmware`` attribute of the ``o= s`` +element in the domain XML. The presence of this enum means libvirt is capa= ble of +the so-called firmware auto-selection feature. And the listed firmware val= ues +represent the accepted input in the domain XML. Note that the ``firmware``= enum +reports only those values for which a firmware "descriptor file" exists on= the +host. Firmware descriptor file is a small JSON document that describes det= ails +about a given BIOS or UEFI binary on the host, e.g. the firmware binary pa= th, +its architecture, supported machine types, NVRAM template, etc. This ensur= es +that the reported values won't cause a failure on guest boot. + +For the ``loader`` element, the following can occur: + +``value`` + List of known firmware binary paths. Currently this is used only to adv= ertise + the known location of OVMF binaries for QEMU. OVMF binaries will only be + listed if they actually exist on host. +``type`` + Whether the boot loader is a typical BIOS (``rom``) or a UEFI firmware + (``pflash``). Each ``value`` sub-element under the ``type`` enum repres= ents a + possible value for the ``type`` attribute for the element in = the + domain XML. E.g. the presence of ``pfalsh`` under the ``type`` enum mea= ns + that a domain XML can use UEFI firmware via: type=3D"pflash" + ...>/path/to/the/firmware/binary/. +``readonly`` + Options for the ``readonly`` attribute of the element in the = domain + XML. +``secure`` + Options for the ``secure`` attribute of the element in the do= main + XML. Note that the value ``yes`` is listed only if libvirt detects a fi= rmware + descriptor file that has path to an OVMF binary that supports Secure bo= ot, + and lists its architecture and supported machine type. + +CPU configuration +~~~~~~~~~~~~~~~~~ + +The ``cpu`` element exposes options usable for configuring `guest +CPUs `__. + +:: + + + ... + + + + on + off + + + + + on + off + + + + Broadwell + Intel + + + + + Broadwell + Broadwell-noTSX + Haswell + ... + + + ... + + +Each CPU mode understood by libvirt is described with a ``mode`` element w= hich +tells whether the particular mode is supported and provides (when applicab= le) +more details about it: + +``host-passthrough`` + The ``hostPassthroughMigratable`` enum shows possible values of the + ``migratable`` attribute for the element with + ``mode=3D'host-passthrough'`` in the domain XML. +``host-model`` + If ``host-model`` is supported by the hypervisor, the ``mode`` describe= s the + guest CPU which will be used when starting a domain with ``host-model``= CPU. + The hypervisor specifics (such as unsupported CPU models or features, m= achine + type, etc.) may be accounted for in this guest CPU specification and th= us the + CPU can be different from the one shown in host capabilities XML. This = is + indicated by the ``fallback`` attribute of the ``model`` sub element: + ``allow`` means not all specifics were accounted for and thus the CPU a= guest + will see may be different; ``forbid`` indicates that the CPU a guest wi= ll see + should match this CPU definition. +``custom`` + The ``mode`` element contains a list of supported CPU models, each desc= ribed + by a dedicated ``model`` element. The ``usable`` attribute specifies wh= ether + the model can be used directly on the host. When usable=3D'no' the + corresponding model cannot be used without disabling some features that= the + CPU of such model is expected to have. A special value ``unknown`` indi= cates + libvirt does not have enough information to provide the usability data.= The + ``deprecated`` attribute reflects the hypervisor's policy on usage of t= his + model :since:`(since 7.1.0)` . + +I/O Threads +~~~~~~~~~~~ + +The ``iothread`` elements indicates whether or not `I/O +threads `__ are supported. + +:: + + + ... + + ... + + +Memory Backing +~~~~~~~~~~~~~~ + +The ``memory backing`` element indicates whether or not `memory +backing `__ is supported. + +:: + + + ... + + + anonymous + file + memfd + + + ... + + +``sourceType`` + Options for the ``type`` attribute of the eleme= nt. + +Devices +~~~~~~~ + +Another set of XML elements describe the supported devices and their +capabilities. All devices occur as children of the main ``devices`` elemen= t. + +:: + + + ... + + + + disk + cdrom + floppy + lun + + ... + + + + + +Reported capabilities are expressed as an enumerated list of available opt= ions +for each of the element or attribute. For example, the element has= an +attribute ``device`` which can support the values ``disk``, ``cdrom``, +``floppy``, or ``lun``. + +Hard drives, floppy disks, CDROMs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Disk capabilities are exposed under the ``disk`` element. For instance: + +:: + + + ... + + + + disk + cdrom + floppy + lun + + + ide + fdc + scsi + virtio + xen + usb + sata + sd + + + ... + + + +``diskDevice`` + Options for the ``device`` attribute of the element. +``bus`` + Options for the ``bus`` attribute of the element for a . + +Graphical framebuffers +^^^^^^^^^^^^^^^^^^^^^^ + +Graphics device capabilities are exposed under the ``graphics`` element. F= or +instance: + +:: + + + ... + + + + sdl + vnc + spice + + + ... + + + +``type`` + Options for the ``type`` attribute of the element. + +Video device +^^^^^^^^^^^^ + +Video device capabilities are exposed under the ``video`` element. For ins= tance: + +:: + + + ... + + + ... + + + +``modelType`` + Options for the ``type`` attribute of the