mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +00:00
docs: Convert 'formatdomaincaps' to rST
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
This commit is contained in:
Peter Krempa
parent
cc05c4e5e4
commit
9c54820eb5
@ -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
|
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
|
was designed and it is indicated by the ``fallback`` attribute set to
|
||||||
``forbid`` in the host-model CPU definition advertised in `domain
|
``forbid`` in the host-model CPU definition advertised in `domain
|
||||||
capabilities XML <formatdomaincaps.html#elementsCPU>`__. When ``fallback``
|
capabilities XML <formatdomaincaps.html#cpu-configuration>`__. When
|
||||||
attribute is set to ``allow`` in the domain capabilities XML, it is
|
``fallback`` attribute is set to ``allow`` in the domain capabilities
|
||||||
recommended to use ``custom`` mode with just the CPU model from the host
|
XML, it is recommended to use ``custom`` mode with just the CPU model
|
||||||
capabilities XML. :since:`Since 1.2.11` PowerISA allows processors to run
|
from the host capabilities XML. :since:`Since 1.2.11` PowerISA allows
|
||||||
VMs in binary compatibility mode supporting an older version of ISA.
|
processors to run VMs in binary compatibility mode supporting an older
|
||||||
Libvirt on PowerPC architecture uses the ``host-model`` to signify a guest
|
version of ISA. Libvirt on PowerPC architecture uses the ``host-model``
|
||||||
mode CPU running in binary compatibility mode. Example: When a user needs
|
to signify a guest mode CPU running in binary compatibility mode.
|
||||||
a power7 VM to run in compatibility mode on a Power8 host, this can be
|
Example: When a user needs a power7 VM to run in compatibility mode on a
|
||||||
described in XML as follows :
|
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
|
This element describes the backing store used by the disk specified by
|
||||||
sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor driver
|
sibling ``source`` element. :since:`Since 1.2.4.` If the hypervisor driver
|
||||||
does not support the
|
does not support the
|
||||||
`backingStoreInput <formatdomaincaps.html#featureBackingStoreInput>`__ (
|
`backingStoreInput <formatdomaincaps.html#backingstoreinput>`__ (
|
||||||
:since:`Since 5.10.0` ) domain feature the ``backingStore`` is ignored on
|
: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
|
input and only used for output to describe the detected backing chains of
|
||||||
running domains. If ``backingStoreInput`` is supported the ``backingStore``
|
running domains. If ``backingStoreInput`` is supported the ``backingStore``
|
||||||
|
|||||||
@ -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 <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.</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>
|
|
||||||
<domainCapabilities>
|
|
||||||
<path>/usr/bin/qemu-system-x86_64</path>
|
|
||||||
<domain>kvm</domain>
|
|
||||||
<machine>pc-i440fx-2.1</machine>
|
|
||||||
<arch>x86_64</arch>
|
|
||||||
...
|
|
||||||
</domainCapabilities>
|
|
||||||
</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>
|
|
||||||
<domainCapabilities>
|
|
||||||
...
|
|
||||||
<vcpu max='255'/>
|
|
||||||
...
|
|
||||||
</domainCapabilities>
|
|
||||||
</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>
|
|
||||||
<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>
|
|
||||||
</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 <loader/>
|
|
||||||
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: <loader/>
|
|
||||||
type="pflash" ...>/path/to/the/firmware/binary/</loader>.
|
|
||||||
</dd>
|
|
||||||
|
|
||||||
<dt><code>readonly</code></dt>
|
|
||||||
<dd>Options for the <code>readonly</code> attribute of the
|
|
||||||
<loader/> element in the domain XML.</dd>
|
|
||||||
|
|
||||||
<dt><code>secure</code></dt>
|
|
||||||
<dd>Options for the <code>secure</code> attribute of the
|
|
||||||
<loader/> 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>
|
|
||||||
<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>
|
|
||||||
</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 <cpu> 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>
|
|
||||||
<domainCapabilities>
|
|
||||||
...
|
|
||||||
<iothread supported='yes'/>
|
|
||||||
...
|
|
||||||
<domainCapabilities>
|
|
||||||
</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>
|
|
||||||
<domainCapabilities>
|
|
||||||
...
|
|
||||||
<memoryBacking supported='yes'>
|
|
||||||
<enum name='sourceType'>
|
|
||||||
<value>anonymous</value>
|
|
||||||
<value>file</value>
|
|
||||||
<value>memfd</value>
|
|
||||||
</enum>
|
|
||||||
</memoryBacking>
|
|
||||||
...
|
|
||||||
<domainCapabilities>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>sourceType</code></dt>
|
|
||||||
<dd>Options for the <code>type</code> attribute of the
|
|
||||||
<memoryBacking><source> 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>
|
|
||||||
<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>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<p>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 <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>
|
|
||||||
<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>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>diskDevice</code></dt>
|
|
||||||
<dd>Options for the <code>device</code> attribute of the <disk/>
|
|
||||||
element.</dd>
|
|
||||||
|
|
||||||
<dt><code>bus</code></dt>
|
|
||||||
<dd>Options for the <code>bus</code> attribute of the <target/>
|
|
||||||
element for a <disk/>.</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>
|
|
||||||
<domainCapabilities>
|
|
||||||
...
|
|
||||||
<devices>
|
|
||||||
<graphics supported='yes'>
|
|
||||||
<enum name='type'>
|
|
||||||
<value>sdl</value>
|
|
||||||
<value>vnc</value>
|
|
||||||
<value>spice</value>
|
|
||||||
</enum>
|
|
||||||
</graphics>
|
|
||||||
...
|
|
||||||
</devices>
|
|
||||||
</domainCapabilities>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>type</code></dt>
|
|
||||||
<dd>Options for the <code>type</code> attribute of the <graphics/>
|
|
||||||
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>
|
|
||||||
<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>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>modelType</code></dt>
|
|
||||||
<dd>Options for the <code>type</code> attribute of the
|
|
||||||
<video><model> 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>
|
|
||||||
<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>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>mode</code></dt>
|
|
||||||
<dd>Options for the <code>mode</code> attribute of the <hostdev/>
|
|
||||||
element.</dd>
|
|
||||||
|
|
||||||
<dt><code>startupPolicy</code></dt>
|
|
||||||
<dd>Options for the <code>startupPolicy</code> attribute of the
|
|
||||||
<hostdev/> element.</dd>
|
|
||||||
|
|
||||||
<dt><code>subsysType</code></dt>
|
|
||||||
<dd>Options for the <code>type</code> attribute of the <hostdev/>
|
|
||||||
element in case of <code>mode="subsystem"</code>.</dd>
|
|
||||||
|
|
||||||
<dt><code>capsType</code></dt>
|
|
||||||
<dd>Options for the <code>type</code> attribute of the <hostdev/>
|
|
||||||
element in case of <code>mode="capabilities"</code>.</dd>
|
|
||||||
|
|
||||||
<dt><code>pciBackend</code></dt>
|
|
||||||
<dd>Options for the <code>name</code> attribute of the <driver/>
|
|
||||||
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>
|
|
||||||
<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>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>model</code></dt>
|
|
||||||
<dd>Options for the <code>model</code> attribute of the
|
|
||||||
<rng> element.</dd>
|
|
||||||
<dt><code>backendModel</code></dt>
|
|
||||||
<dd>Options for the <code>model</code> attribute of the
|
|
||||||
<rng><backend> 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>
|
|
||||||
<domainCapabilities>
|
|
||||||
...
|
|
||||||
<devices>
|
|
||||||
<filesystem supported='yes'>
|
|
||||||
<enum name='driverType'>
|
|
||||||
<value>default</value>
|
|
||||||
<value>path</value>
|
|
||||||
<value>handle</value>
|
|
||||||
<value>virtiofs</value>
|
|
||||||
</enum>
|
|
||||||
</filesystem>
|
|
||||||
...
|
|
||||||
</devices>
|
|
||||||
</domainCapabilities>
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
<dl>
|
|
||||||
<dt><code>driverType</code></dt>
|
|
||||||
<dd>Options for the <code>type</code> attribute of the
|
|
||||||
<filesystem><driver> 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>
|
|
||||||
<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>
|
|
||||||
</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 <backingStore>
|
|
||||||
elements configured for a <disk> 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>
|
|
||||||
600
docs/formatdomaincaps.rst
Normal file
600
docs/formatdomaincaps.rst
Normal file
@ -0,0 +1,600 @@
|
|||||||
|
.. 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`` (`API docs <html/libvirt-libvirt-domain.html#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.
|
||||||
@ -97,7 +97,7 @@ specification can be used:
|
|||||||
</disk>
|
</disk>
|
||||||
|
|
||||||
This makes libvirt follow the settings as configured in the XML. Note that this
|
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.
|
capability is present.
|
||||||
|
|
||||||
An empty ``<backingStore/>`` element signals the end of the chain. Using this
|
An empty ``<backingStore/>`` element signals the end of the chain. Using this
|
||||||
|
|||||||
@ -21,7 +21,6 @@ docs_html_in_files = [
|
|||||||
'404',
|
'404',
|
||||||
'docs',
|
'docs',
|
||||||
'formatcaps',
|
'formatcaps',
|
||||||
'formatdomaincaps',
|
|
||||||
'formatnetwork',
|
'formatnetwork',
|
||||||
'formatnode',
|
'formatnode',
|
||||||
'formatnwfilter',
|
'formatnwfilter',
|
||||||
@ -77,6 +76,7 @@ docs_rst_files = [
|
|||||||
'formatcheckpoint',
|
'formatcheckpoint',
|
||||||
'formatdomain',
|
'formatdomain',
|
||||||
'formatnetworkport',
|
'formatnetworkport',
|
||||||
|
'formatdomaincaps',
|
||||||
'formatsecret',
|
'formatsecret',
|
||||||
'formatsnapshot',
|
'formatsnapshot',
|
||||||
'formatstorage',
|
'formatstorage',
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user