[PATCH 18/29] docs: Convert 'formatdomaincaps' to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
 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 way 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 <formatdomaincaps.html#elementsCPU>`__. 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 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 <formatdomaincaps.html#cpu-configuration>`__. 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 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 :

       ::

@@ -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 driver
    does not support the
-   `backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ (
+   `backingStoreInput <formatdomaincaps.html#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 ``backingStore``
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 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html>
-<html xmlns="http://www.w3.org/1999/xhtml";>
-  <body>
-    <h1>Domain capabilities XML format</h1>
-
-    <ul id="toc"></ul>
-
-    <h2><a id="Overview">Overview</a></h2>
-
-    <p>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
-    drivers 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.</p>
-
-    <p>The main difference between
-      <a href="/html/libvirt-libvirt-host.html#virConnectGetCapabilities">
-        <code>virConnectGetCapabilities</code>
-      </a>
-    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.</p>
-
-    <p>While the <a href="formatcaps.html">Driver Capabilities</a> provides 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.</p>
-
-    <p>The Domain Capabilities can provide information such as the correct
-    combination of devices and drivers that are supported. Knowing which host
-    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.</p>
-
-    <p>Some XML elements may be entirely omitted from the domaincapabilities
-    XML, depending on what the libvirt driver has filled in. Applications
-    should only act on what is explicitly reported in the domaincapabilities
-    XML. For example, if &lt;disk supported='yes'/&gt; is present, you can safely
-    assume the driver supports &lt;disk&gt; devices. If &lt;disk supported='no'/&gt; is
-    present, you can safely assume the driver does NOT support &lt;disk&gt;
-    devices. If the &lt;disk&gt; block is omitted entirely, the driver is not
-    indicating one way or the other whether it supports &lt;disk&gt; devices, and
-    applications should not interpret the missing block to mean any thing in
-    particular.</p>
-
-    <h2><a id="elements">Element and attribute overview</a></h2>
-
-    <p> A new query interface was added to the virConnect API's to retrieve the
-    XML listing of the set of domain capabilities (<span class="since">Since
-    1.2.7</span>):</p>
-
-<pre>
-<a href="/html/libvirt-libvirt-domain.html#virConnectGetDomainCapabilities">virConnectGetDomainCapabilities</a>
-</pre>
-
-    <p>The root element that emulator capability XML document starts with has
-    name <code>domainCapabilities</code>. It contains at least four direct
-    child elements:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  &lt;path&gt;/usr/bin/qemu-system-x86_64&lt;/path&gt;
-  &lt;domain&gt;kvm&lt;/domain&gt;
-  &lt;machine&gt;pc-i440fx-2.1&lt;/machine&gt;
-  &lt;arch&gt;x86_64&lt;/arch&gt;
-  ...
-&lt;/domainCapabilities&gt;
-</pre>
-    <dl>
-      <dt><code>path</code></dt>
-      <dd>The full path to the emulator binary.</dd>
-
-      <dt><code>domain</code></dt>
-      <dd>Describes the <a href="formatdomain.html#elements">virtualization
-          type</a> (or so called domain type).</dd>
-
-      <dt><code>machine</code></dt>
-      <dd>The domain's <a href="formatdomain.html#elementsOSBIOS">machine
-          type</a>. Since not every hypervisor has a sense of machine types
-          this element might be omitted in such drivers.</dd>
-
-      <dt><code>arch</code></dt>
-      <dd>The domain's <a href="formatdomain.html#elementsOSBIOS">
-          architecture</a>.</dd>
-
-    </dl>
-
-    <h3><a id="elementsCPUAllocation">CPU Allocation</a></h3>
-
-    <p>Before any devices capability occurs, there might be info on domain
-    wide capabilities, e.g. virtual CPUs:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;vcpu max='255'/&gt;
-  ...
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>vcpu</code></dt>
-      <dd>The maximum number of supported virtual CPUs</dd>
-    </dl>
-
-    <h3><a id="elementsOSBIOS">BIOS bootloader</a></h3>
-
-    <p>Sometimes users might want to tweak some BIOS knobs or use
-    UEFI. For cases like that, <a
-    href="formatdomain.html#elementsOSBIOS"><code>os</code></a>
-    element exposes what values can be passed to its children.</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;os supported='yes'&gt;
-    &lt;enum name='firmware'&gt;
-      &lt;value&gt;bios&lt;/value&gt;
-      &lt;value&gt;efi&lt;/value&gt;
-    &lt;/enum&gt;
-    &lt;loader supported='yes'&gt;
-      &lt;value&gt;/usr/share/OVMF/OVMF_CODE.fd&lt;/value&gt;
-      &lt;enum name='type'&gt;
-        &lt;value&gt;rom&lt;/value&gt;
-        &lt;value&gt;pflash&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='readonly'&gt;
-        &lt;value&gt;yes&lt;/value&gt;
-        &lt;value&gt;no&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='secure'&gt;
-        &lt;value&gt;yes&lt;/value&gt;
-        &lt;value&gt;no&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/loader&gt;
-  &lt;/os&gt;
-  ...
-&lt;domainCapabilities&gt;
-</pre>
-
-    <p>The <code>firmware</code> enum corresponds to the
-      <code>firmware</code> attribute of the <code>os</code> 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 <code>firmware</code> 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.
-    </p>
-
-    <p>For the <code>loader</code> element, the following can occur:</p>
-
-    <dl>
-      <dt><code>value</code></dt>
-      <dd>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.</dd>
-
-      <dt><code>type</code></dt>
-      <dd>Whether the boot loader is a typical BIOS (<code>rom</code>)
-      or a UEFI firmware (<code>pflash</code>). Each <code>value</code>
-      sub-element under the <code>type</code> enum represents a possible
-      value for the <code>type</code> attribute for the &lt;loader/&gt;
-      element in the domain XML. E.g. the presence
-      of <code>pfalsh</code> under the <code>type</code> enum means that
-      a domain XML can use UEFI firmware via: &lt;loader/&gt;
-      type="pflash" ...&gt;/path/to/the/firmware/binary/&lt;/loader&gt;.
-      </dd>
-
-      <dt><code>readonly</code></dt>
-      <dd>Options for the <code>readonly</code> attribute of the
-      &lt;loader/&gt; element in the domain XML.</dd>
-
-      <dt><code>secure</code></dt>
-      <dd>Options for the <code>secure</code> attribute of the
-      &lt;loader/&gt; element in the domain XML. Note that the
-      value <code>yes</code> 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.</dd>
-    </dl>
-
-    <h3><a id="elementsCPU">CPU configuration</a></h3>
-
-    <p>
-      The <code>cpu</code> element exposes options usable for configuring
-      <a href="formatdomain.html#elementsCPU">guest CPUs</a>.
-    </p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;cpu&gt;
-    &lt;mode name='host-passthrough' supported='yes'&gt;
-      &lt;enum name='hostPassthroughMigratable'&gt;
-        &lt;value&gt;on&lt;/value&gt;
-        &lt;value&gt;off&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/mode&gt;
-    &lt;mode name='maximum' supported='yes'&gt;
-      &lt;enum name='maximumMigratable'&gt;
-        &lt;value&gt;on&lt;/value&gt;
-        &lt;value&gt;off&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/mode&gt;
-    &lt;mode name='host-model' supported='yes'&gt;
-      &lt;model fallback='allow'&gt;Broadwell&lt;/model&gt;
-      &lt;vendor&gt;Intel&lt;/vendor&gt;
-      &lt;feature policy='disable' name='aes'/&gt;
-      &lt;feature policy='require' name='vmx'/&gt;
-    &lt;/mode&gt;
-    &lt;mode name='custom' supported='yes'&gt;
-      &lt;model usable='no' deprecated='no'&gt;Broadwell&lt;/model&gt;
-      &lt;model usable='yes' deprecated='no'&gt;Broadwell-noTSX&lt;/model&gt;
-      &lt;model usable='no' deprecated='yes'&gt;Haswell&lt;/model&gt;
-      ...
-    &lt;/mode&gt;
-  &lt;/cpu&gt;
-  ...
-&lt;domainCapabilities&gt;
-</pre>
-
-    <p>
-      Each CPU mode understood by libvirt is described with a
-      <code>mode</code> element which tells whether the particular mode
-      is supported and provides (when applicable) more details about it:
-    </p>
-
-    <dl>
-      <dt><code>host-passthrough</code></dt>
-      <dd>
-        The <code>hostPassthroughMigratable</code> enum shows possible values
-        of the <code>migratable</code> attribute for the &lt;cpu&gt; element
-        with <code>mode='host-passthrough'</code> in the domain XML.
-      </dd>
-
-      <dt><code>host-model</code></dt>
-      <dd>
-        If <code>host-model</code> is supported by the hypervisor, the
-        <code>mode</code> describes the guest CPU which will be used when
-        starting a domain with <code>host-model</code> CPU. The hypervisor
-        specifics (such as unsupported CPU models or features, machine type,
-        etc.) may be accounted for in this guest CPU specification and thus
-        the CPU can be different from the one shown in host capabilities XML.
-        This is indicated by the <code>fallback</code> attribute of the
-        <code>model</code> sub element: <code>allow</code> means not all
-        specifics were accounted for and thus the CPU a guest will see may
-        be different; <code>forbid</code> indicates that the CPU a guest will
-        see should match this CPU definition.
-      </dd>
-
-      <dt><code>custom</code></dt>
-      <dd>
-        The <code>mode</code> element contains a list of supported CPU
-        models, each described by a dedicated <code>model</code> element.
-        The <code>usable</code> attribute specifies whether the model can
-        be used directly on the host. When usable='no' the corresponding model
-        cannot be used without disabling some features that the CPU of such
-        model is expected to have. A special value <code>unknown</code>
-        indicates libvirt does not have enough information to provide the
-        usability data. The <code>deprecated</code> attribute reflects
-        the hypervisor's policy on usage of this model
-        <span class="since">(since 7.1.0)</span>.
-      </dd>
-    </dl>
-
-    <h3><a id="elementsIothreads">I/O Threads</a></h3>
-
-    <p>
-      The <code>iothread</code> elements indicates whether or not
-      <a href="formatdomain.html#elementsIOThreadsAllocation">I/O threads</a>
-      are supported.
-    </p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;iothread supported='yes'/&gt;
-  ...
-&lt;domainCapabilities&gt;
-</pre>
-
-    <h3><a id="elementsMemoryBacking">Memory Backing</a></h3>
-
-    <p>
-      The <code>memory backing</code> element indicates whether or not
-      <a href="formatdomain.html#memory-backing">memory backing</a>
-      is supported.
-    </p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;memoryBacking supported='yes'&gt;
-    &lt;enum name='sourceType'&gt;
-      &lt;value&gt;anonymous&lt;/value&gt;
-      &lt;value&gt;file&lt;/value&gt;
-      &lt;value&gt;memfd&lt;/value&gt;
-    &lt;/enum&gt;
-  &lt;/memoryBacking&gt;
-  ...
-&lt;domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>sourceType</code></dt>
-      <dd>Options for the <code>type</code> attribute of the
-      &lt;memoryBacking&gt;&lt;source&gt; element.</dd>
-    </dl>
-
-    <h3><a id="elementsDevices">Devices</a></h3>
-
-    <p>
-      Another set of XML elements describe the supported devices and their
-      capabilities. All devices occur as children of the main
-      <code>devices</code> element.
-    </p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;disk supported='yes'&gt;
-      &lt;enum name='diskDevice'&gt;
-        &lt;value&gt;disk&lt;/value&gt;
-        &lt;value&gt;cdrom&lt;/value&gt;
-        &lt;value&gt;floppy&lt;/value&gt;
-        &lt;value&gt;lun&lt;/value&gt;
-      &lt;/enum&gt;
-      ...
-    &lt;/disk&gt;
-    &lt;hostdev supported='no'/&gt;
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <p>Reported capabilities are expressed as an enumerated list of available
-    options for each of the element or attribute.  For example, the
-    &lt;disk/&gt; element has an attribute <code>device</code> which can
-    support the values <code>disk</code>, <code>cdrom</code>,
-    <code>floppy</code>, or <code>lun</code>.</p>
-
-    <h4><a id="elementsDisks">Hard drives, floppy disks, CDROMs</a></h4>
-    <p>Disk capabilities are exposed under the <code>disk</code> element. For
-    instance:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;disk supported='yes'&gt;
-      &lt;enum name='diskDevice'&gt;
-        &lt;value&gt;disk&lt;/value&gt;
-        &lt;value&gt;cdrom&lt;/value&gt;
-        &lt;value&gt;floppy&lt;/value&gt;
-        &lt;value&gt;lun&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='bus'&gt;
-        &lt;value&gt;ide&lt;/value&gt;
-        &lt;value&gt;fdc&lt;/value&gt;
-        &lt;value&gt;scsi&lt;/value&gt;
-        &lt;value&gt;virtio&lt;/value&gt;
-        &lt;value&gt;xen&lt;/value&gt;
-        &lt;value&gt;usb&lt;/value&gt;
-        &lt;value&gt;sata&lt;/value&gt;
-        &lt;value&gt;sd&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/disk&gt;
-    ...
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>diskDevice</code></dt>
-      <dd>Options for the <code>device</code> attribute of the &lt;disk/&gt;
-      element.</dd>
-
-      <dt><code>bus</code></dt>
-      <dd>Options for the <code>bus</code> attribute of the &lt;target/&gt;
-      element for a &lt;disk/&gt;.</dd>
-    </dl>
-
-
-    <h4><a id="elementsGraphics">Graphical framebuffers</a></h4>
-    <p>Graphics device capabilities are exposed under the
-    <code>graphics</code> element. For instance:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;graphics supported='yes'&gt;
-      &lt;enum name='type'&gt;
-        &lt;value&gt;sdl&lt;/value&gt;
-        &lt;value&gt;vnc&lt;/value&gt;
-        &lt;value&gt;spice&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/graphics&gt;
-    ...
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>type</code></dt>
-      <dd>Options for the <code>type</code> attribute of the &lt;graphics/&gt;
-      element.</dd>
-    </dl>
-
-
-    <h4><a id="elementsVideo">Video device</a></h4>
-    <p>Video device capabilities are exposed under the
-    <code>video</code> element. For instance:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;video supported='yes'&gt;
-      &lt;enum name='modelType'&gt;
-        &lt;value&gt;vga&lt;/value&gt;
-        &lt;value&gt;cirrus&lt;/value&gt;
-        &lt;value&gt;vmvga&lt;/value&gt;
-        &lt;value&gt;qxl&lt;/value&gt;
-        &lt;value&gt;virtio&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/video&gt;
-    ...
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>modelType</code></dt>
-      <dd>Options for the <code>type</code> attribute of the
-      &lt;video&gt;&lt;model&gt; element.</dd>
-    </dl>
-
-
-    <h4><a id="elementsHostDev">Host device assignment</a></h4>
-    <p>Some host devices can be passed through to a guest (e.g. USB, PCI and
-    SCSI). Well, only if the following is enabled:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;hostdev supported='yes'&gt;
-      &lt;enum name='mode'&gt;
-        &lt;value&gt;subsystem&lt;/value&gt;
-        &lt;value&gt;capabilities&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='startupPolicy'&gt;
-        &lt;value&gt;default&lt;/value&gt;
-        &lt;value&gt;mandatory&lt;/value&gt;
-        &lt;value&gt;requisite&lt;/value&gt;
-        &lt;value&gt;optional&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='subsysType'&gt;
-        &lt;value&gt;usb&lt;/value&gt;
-        &lt;value&gt;pci&lt;/value&gt;
-        &lt;value&gt;scsi&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='capsType'&gt;
-        &lt;value&gt;storage&lt;/value&gt;
-        &lt;value&gt;misc&lt;/value&gt;
-        &lt;value&gt;net&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='pciBackend'&gt;
-        &lt;value&gt;default&lt;/value&gt;
-        &lt;value&gt;kvm&lt;/value&gt;
-        &lt;value&gt;vfio&lt;/value&gt;
-        &lt;value&gt;xen&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/hostdev&gt;
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>mode</code></dt>
-      <dd>Options for the <code>mode</code> attribute of the &lt;hostdev/&gt;
-      element.</dd>
-
-      <dt><code>startupPolicy</code></dt>
-      <dd>Options for the <code>startupPolicy</code> attribute of the
-      &lt;hostdev/&gt; element.</dd>
-
-      <dt><code>subsysType</code></dt>
-      <dd>Options for the <code>type</code> attribute of the &lt;hostdev/&gt;
-      element in case of <code>mode="subsystem"</code>.</dd>
-
-      <dt><code>capsType</code></dt>
-      <dd>Options for the <code>type</code> attribute of the &lt;hostdev/&gt;
-      element in case of <code>mode="capabilities"</code>.</dd>
-
-      <dt><code>pciBackend</code></dt>
-      <dd>Options for the <code>name</code> attribute of the &lt;driver/&gt;
-      element.</dd>
-    </dl>
-
-
-    <h4><a id="elementsRNG">RNG device</a></h4>
-    <p>RNG device capabilities are exposed under the
-    <code>rng</code> element. For instance:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;rng supported='yes'&gt;
-      &lt;enum name='model'&gt;
-        &lt;value&gt;virtio&lt;/value&gt;
-        &lt;value&gt;virtio-transitional&lt;/value&gt;
-        &lt;value&gt;virtio-non-transitional&lt;/value&gt;
-      &lt;/enum&gt;
-      &lt;enum name='backendModel'&gt;
-        &lt;value&gt;random&lt;/value&gt;
-        &lt;value&gt;egd&lt;/value&gt;
-        &lt;value&gt;builtin&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/rng&gt;
-    ...
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>model</code></dt>
-      <dd>Options for the <code>model</code> attribute of the
-      &lt;rng&gt; element.</dd>
-      <dt><code>backendModel</code></dt>
-      <dd>Options for the <code>model</code> attribute of the
-      &lt;rng&gt;&lt;backend&gt; element.</dd>
-    </dl>
-
-
-    <h4><a id="elementsFilesystem">Filesystem device</a></h4>
-    <p>Filesystem device capabilities are exposed under the
-    <code>filesystem</code> element. For instance:</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;devices&gt;
-    &lt;filesystem supported='yes'&gt;
-      &lt;enum name='driverType'&gt;
-        &lt;value&gt;default&lt;/value&gt;
-        &lt;value&gt;path&lt;/value&gt;
-        &lt;value&gt;handle&lt;/value&gt;
-        &lt;value&gt;virtiofs&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/filesystem&gt;
-    ...
-  &lt;/devices&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <dl>
-      <dt><code>driverType</code></dt>
-      <dd>Options for the <code>type</code> attribute of the
-      &lt;filesystem&gt;&lt;driver&gt; element.</dd>
-    </dl>
-
-
-    <h3><a id="elementsFeatures">Features</a></h3>
-
-    <p>One more set of XML elements describe the supported features and
-    their capabilities. All features occur as children of the main
-    <code>features</code> element.</p>
-
-<pre>
-&lt;domainCapabilities&gt;
-  ...
-  &lt;features&gt;
-    &lt;gic supported='yes'&gt;
-      &lt;enum name='version'&gt;
-        &lt;value&gt;2&lt;/value&gt;
-        &lt;value&gt;3&lt;/value&gt;
-      &lt;/enum&gt;
-    &lt;/gic&gt;
-    &lt;vmcoreinfo supported='yes'/&gt;
-    &lt;genid supported='yes'/&gt;
-    &lt;backingStoreInput supported='yes'/&gt;
-    &lt;backup supported='yes'/&gt;
-    &lt;sev&gt;
-      &lt;cbitpos&gt;47&lt;/cbitpos&gt;
-      &lt;reduced-phys-bits&gt;1&lt;/reduced-phys-bits&gt;
-    &lt;/sev&gt;
-  &lt;/features&gt;
-&lt;/domainCapabilities&gt;
-</pre>
-
-    <p>Reported capabilities are expressed as an enumerated list of
-    possible values for each of the elements or attributes. For example, the
-    <code>gic</code> element has an attribute <code>version</code> which can
-    support the values <code>2</code> or <code>3</code>.</p>
-
-    <p>For information about the purpose of each feature, see the
-    <a href="formatdomain.html#elementsFeatures">relevant section</a> in
-    the domain XML documentation.
-    </p>
-
-    <h4><a id="elementsGIC">GIC capabilities</a></h4>
-
-    <p>GIC capabilities are exposed under the <code>gic</code> element.</p>
-
-    <dl>
-      <dt><code>version</code></dt>
-      <dd>Options for the <code>version</code> attribute of the
-      <code>gic</code> element.</dd>
-    </dl>
-
-    <h4><a id="elementsvmcoreinfo">vmcoreinfo</a></h4>
-
-    <p>Reports whether the vmcoreinfo feature can be enabled.</p>
-
-    <h4><a id="elementsgenid">genid</a></h4>
-
-    <p>Reports whether the genid feature can be used by the domain.</p>
-
-    <h4><a id="featureBackingStoreInput">backingStoreInput</a></h4>
-
-    <p>Reports whether the hypervisor will obey the &lt;backingStore&gt;
-    elements configured for a &lt;disk&gt; when booting the guest, hotplugging
-    the disk to a running guest, or similar.
-    <span class="since">(Since 5.10)</span>
-    </p>
-
-    <h4><a id="featureBackup">backup</a></h4>
-
-    <p>Reports whether the hypervisor supports the backup, checkpoint, and
-    related features. (<code>virDomainBackupBegin</code>,
-    <code>virDomainCheckpointCreateXML</code> etc). The presence of the
-    <code>backup</code> element even if <code>supported='no'</code> implies that
-    the <code>VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA</code> flag for
-    <code>virDomainUndefine</code> is supported.
-    </p>
-
-    <h4><a id="elementsS390PV">s390-pv capability</a></h4>
-
-    <p>Reports whether the hypervisor supports the Protected Virtualization.
-    In order to use Protected Virtualization with libvirt have a look at the
-    <a href="formatdomain.html#launchSecurity">launchSecurity element in the
-    domain XML</a>. For more details on the Protected Virtualization feature
-    please see <a href="kbase/s390_protected_virt.html">Protected
-    Virtualization on s390</a>.
-    </p>
-
-    <h4><a id="elementsSEV">SEV capabilities</a></h4>
-
-    <p>AMD Secure Encrypted Virtualization (SEV) capabilities are exposed under
-    the <code>sev</code> element.
-    SEV is an extension to the AMD-V architecture which supports running
-    virtual machines (VMs) under the control of a hypervisor. When supported,
-    guest owner can create a VM whose memory contents will be transparently
-    encrypted with a key unique to that VM.</p>
-
-    <p>
-      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 <a href="formatdomain.html#launchSecurity">SEV in domain XML</a>
-    </p>
-
-    <dl>
-      <dt><code>cbitpos</code></dt>
-      <dd>When memory encryption is enabled, one of the physical address bits
-      (aka the C-bit) is utilized to mark if a memory page is protected. The
-      C-bit position is Hypervisor dependent.</dd>
-      <dt><code>reducedPhysBits</code></dt>
-      <dd>When memory encryption is enabled, we lose certain bits in physical
-      address space. The number of bits we lose is hypervisor dependent.</dd>
-      <dt><code>maxGuests</code></dt>
-      <dd>The maximum number of SEV guests that can be launched on the host.
-      This value may be configurable in the firmware for some hosts.</dd>
-      <dt><code>maxESGuests</code></dt>
-      <dd>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.</dd>
-    </dl>
-
-  </body>
-</html>
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
+
+==============================
+Domain capabilities XML format
+==============================
+
+.. 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 drivers
+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 </html/libvirt-libvirt-host.html#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 <formatcaps.html>`__ provides 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 host 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 domaincapabilities XML,
+depending on what the libvirt driver has filled in. Applications should only act
+on what is explicitly reported in the domaincapabilities XML. For example, if
+<disk supported='yes'/> is present, you can safely assume the driver supports
+<disk> devices. If <disk supported='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>
+devices, 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 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:
+
+::
+
+   <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 `virtualization type <formatdomain.html#elements>`__ (or so
+   called domain type).
+``machine``
+   The domain's `machine type <formatdomain.html#elementsOSBIOS>`__. Since not
+   every hypervisor has a sense of machine types this element might be omitted
+   in such drivers.
+``arch``
+   The domain's `architecture <formatdomain.html#elementsOSBIOS>`__.
+
+CPU Allocation
+~~~~~~~~~~~~~~
+
+Before any devices capability occurs, there might be info on domain wide
+capabilities, e.g. virtual CPUs:
+
+::
+
+   <domainCapabilities>
+     ...
+     <vcpu max='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 <formatdomain.html#elementsOSBIOS>`__ element exposes what values can
+be passed to its children.
+
+::
+
+   <domainCapabilities>
+     ...
+     <os supported='yes'>
+       <enum name='firmware'>
+         <value>bios</value>
+         <value>efi</value>
+       </enum>
+       <loader supported='yes'>
+         <value>/usr/share/OVMF/OVMF_CODE.fd</value>
+         <enum name='type'>
+           <value>rom</value>
+           <value>pflash</value>
+         </enum>
+         <enum name='readonly'>
+           <value>yes</value>
+           <value>no</value>
+         </enum>
+         <enum name='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="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 <formatdomain.html#elementsCPU>`__.
+
+::
+
+   <domainCapabilities>
+     ...
+     <cpu>
+       <mode name='host-passthrough' supported='yes'>
+         <enum name='hostPassthroughMigratable'>
+           <value>on</value>
+           <value>off</value>
+         </enum>
+       </mode>
+       <mode name='maximum' supported='yes'>
+         <enum name='maximumMigratable'>
+           <value>on</value>
+           <value>off</value>
+         </enum>
+       </mode>
+       <mode name='host-model' supported='yes'>
+         <model fallback='allow'>Broadwell</model>
+         <vendor>Intel</vendor>
+         <feature policy='disable' name='aes'/>
+         <feature policy='require' name='vmx'/>
+       </mode>
+       <mode name='custom' supported='yes'>
+         <model usable='no' deprecated='no'>Broadwell</model>
+         <model usable='yes' deprecated='no'>Broadwell-noTSX</model>
+         <model usable='no' deprecated='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 values of the
+   ``migratable`` attribute for the <cpu> element with
+   ``mode='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
+   type, etc.) may be accounted for in this guest CPU specification and thus 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 will 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='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:`(since 7.1.0)` .
+
+I/O Threads
+~~~~~~~~~~~
+
+The ``iothread`` elements indicates whether or not `I/O
+threads <formatdomain.html#elementsIOThreadsAllocation>`__ are supported.
+
+::
+
+   <domainCapabilities>
+     ...
+     <iothread supported='yes'/>
+     ...
+   <domainCapabilities>
+
+Memory Backing
+~~~~~~~~~~~~~~
+
+The ``memory backing`` element indicates whether or not `memory
+backing <formatdomain.html#memory-backing>`__ is supported.
+
+::
+
+   <domainCapabilities>
+     ...
+     <memoryBacking supported='yes'>
+       <enum name='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='yes'>
+         <enum name='diskDevice'>
+           <value>disk</value>
+           <value>cdrom</value>
+           <value>floppy</value>
+           <value>lun</value>
+         </enum>
+         ...
+       </disk>
+       <hostdev supported='no'/>
+     </devices>
+   </domainCapabilities>
+
+Reported capabilities are expressed as an enumerated list of available 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='yes'>
+         <enum name='diskDevice'>
+           <value>disk</value>
+           <value>cdrom</value>
+           <value>floppy</value>
+           <value>lun</value>
+         </enum>
+         <enum name='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/> 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='yes'>
+         <enum name='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='yes'>
+         <enum name='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 and SCSI).
+Well, only if the following is enabled:
+
+::
+
+   <domainCapabilities>
+     ...
+     <devices>
+       <hostdev supported='yes'>
+         <enum name='mode'>
+           <value>subsystem</value>
+           <value>capabilities</value>
+         </enum>
+         <enum name='startupPolicy'>
+           <value>default</value>
+           <value>mandatory</value>
+           <value>requisite</value>
+           <value>optional</value>
+         </enum>
+         <enum name='subsysType'>
+           <value>usb</value>
+           <value>pci</value>
+           <value>scsi</value>
+         </enum>
+         <enum name='capsType'>
+           <value>storage</value>
+           <value>misc</value>
+           <value>net</value>
+         </enum>
+         <enum name='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/> element.
+``startupPolicy``
+   Options for the ``startupPolicy`` attribute of the <hostdev/> element.
+``subsysType``
+   Options for the ``type`` attribute of the <hostdev/> element in case of
+   ``mode="subsystem"``.
+``capsType``
+   Options for the ``type`` attribute of the <hostdev/> element in case of
+   ``mode="capabilities"``.
+``pciBackend``
+   Options for the ``name`` attribute of the <driver/> element.
+
+RNG device
+^^^^^^^^^^
+
+RNG device capabilities are exposed under the ``rng`` element. For instance:
+
+::
+
+   <domainCapabilities>
+     ...
+     <devices>
+       <rng supported='yes'>
+         <enum name='model'>
+           <value>virtio</value>
+           <value>virtio-transitional</value>
+           <value>virtio-non-transitional</value>
+         </enum>
+         <enum name='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='yes'>
+         <enum name='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='yes'>
+         <enum name='version'>
+           <value>2</value>
+           <value>3</value>
+         </enum>
+       </gic>
+       <vmcoreinfo supported='yes'/>
+       <genid supported='yes'/>
+       <backingStoreInput supported='yes'/>
+       <backup supported='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, the ``gic`` element has an
+attribute ``version`` which can support the values ``2`` or ``3``.
+
+For information about the purpose of each feature, see the `relevant
+section <formatdomain.html#elementsFeatures>`__ 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, hotplugging the disk to a running guest, or
+similar. :since:`(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='no'`` implies that the
+``VIR_DOMAIN_UNDEFINE_CHECKPOINTS_METADATA`` flag for ``virDomainUndefine`` is
+supported.
+
+s390-pv capability
+^^^^^^^^^^^^^^^^^^
+
+Reports whether the hypervisor supports the Protected Virtualization. In order
+to use Protected Virtualization with libvirt have a look at the `launchSecurity
+element in the domain XML <formatdomain.html#launchSecurity>`__. For more
+details on the Protected Virtualization feature please see `Protected
+Virtualization on s390 <kbase/s390_protected_virt.html>`__.
+
+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
+supported, 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 <formatdomain.html#launchSecurity>`__
+
+``cbitpos``
+   When memory encryption is enabled, one of the physical address bits (aka the
+   C-bit) is utilized to mark if a memory page is protected. The C-bit position
+   is Hypervisor dependent.
+``reducedPhysBits``
+   When memory encryption is enabled, we lose certain bits in physical address
+   space. The number of bits we lose is hypervisor dependent.
+``maxGuests``
+   The maximum number of SEV guests that can be launched on the host. 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/kbase/backing_chains.rst b/docs/kbase/backing_chains.rst
index 89920a61b1..38a9a2337b 100644
--- a/docs/kbase/backing_chains.rst
+++ b/docs/kbase/backing_chains.rst
@@ -97,7 +97,7 @@ specification can be used:
  </disk>

 This makes libvirt follow the settings as configured in the XML. Note that this
-is supported only when the https://libvirt.org/formatdomaincaps.html#featureBackingStoreInput
+is supported only when the https://libvirt.org/formatdomaincaps.html#backingstoreinput
 capability is present.

 An empty ``<backingStore/>`` element signals the end of the chain. Using this
diff --git a/docs/meson.build b/docs/meson.build
index 95c9babcf5..81f348398d 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
   'csharp',
   'dbus',
   'docs',
-  'formatdomaincaps',
   'formatnetwork',
   'formatnetworkport',
   'formatnode',
@@ -85,6 +84,7 @@ docs_rst_files = [
   'formatcaps',
   'formatcheckpoint',
   'formatdomain',
+  'formatdomaincaps',
   'formatsecret',
   'formatsnapshot',
   'formatstorage',
-- 
2.35.1




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux