mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-11-03 11:51:11 +00:00
0f358fcdca
Report domaincaps <features><genid supported='yes'/> if the guest config accepts <genid/> or <genid>$GUID</genid>. Signed-off-by: John Ferlan <jferlan@redhat.com> ACKed-by: Michal Privoznik <mprivozn@redhat.com>
472 lines
15 KiB
XML
472 lines
15 KiB
XML
<?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>
|
|
|
|
<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'>
|
|
<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>
|
|
</loader>
|
|
</os>
|
|
...
|
|
<domainCapabilities>
|
|
</pre>
|
|
|
|
<p>For the <code>loader</code> element, the following can occur:</p>
|
|
|
|
<dl>
|
|
<dt><code>value</code></dt>
|
|
<dd>List of known loader paths. Currently this is only used
|
|
to advertise known locations of OVMF binaries for qemu. Binaries
|
|
will only be listed if they actually exist on disk.</dd>
|
|
|
|
<dt><code>type</code></dt>
|
|
<dd>Whether loader is a typical BIOS (<code>rom</code>) or
|
|
an UEFI binary (<code>pflash</code>). This refers to
|
|
<code>type</code> attribute of the <loader/>
|
|
element.</dd>
|
|
|
|
<dt><code>readonly</code></dt>
|
|
<dd>Options for the <code>readonly</code> attribute of the
|
|
<loader/> element.</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'/>
|
|
<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'>Broadwell</model>
|
|
<model usable='yes'>Broadwell-noTSX</model>
|
|
<model usable='no'>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>No mode specific details are provided.</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 on the host. A special value <code>unknown</code> indicates
|
|
libvirt does not have enough information to provide the usability
|
|
data.
|
|
</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="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>uml</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>
|
|
|
|
<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'/>
|
|
</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>
|
|
|
|
</body>
|
|
</html>
|