mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 17:34:18 +03:00
docs: Convert 'formatcaps' page to rst
Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
This commit is contained in:
Peter Krempa
parent
f01f957792
commit
8b3d9314ae
@ -1,222 +0,0 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE html>
|
||||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||||
<body>
|
||||
<h1>Driver capabilities XML format</h1>
|
||||
|
||||
<ul id="toc"></ul>
|
||||
|
||||
<h2><a id="elements">Element and attribute overview</a></h2>
|
||||
|
||||
<p>As new virtualization engine support gets added to libvirt, and to
|
||||
handle cases like QEMU supporting a variety of emulations, a query
|
||||
interface has been added in 0.2.1 allowing to list the set of supported
|
||||
virtualization capabilities on the host:</p>
|
||||
|
||||
<pre>char * virConnectGetCapabilities (virConnectPtr conn);</pre>
|
||||
|
||||
<p>The value returned is an XML document listing the virtualization
|
||||
capabilities of the host and virtualization engine to which
|
||||
<code>@conn</code> is connected. One can test it using <code>virsh</code>
|
||||
command line tool command '<code>capabilities</code>', it dumps the XML
|
||||
associated to the current connection. </p>
|
||||
|
||||
<p>As can be seen in the <a href="#elementExamples">example</a>, the
|
||||
capabilities XML consists of the <code>capabilities</code> element which
|
||||
have exactly one <code>host</code> child element to report information on
|
||||
host capabilities, and zero or more <code>guest</code> element to express
|
||||
the set of architectures the host can run at the moment.</p>
|
||||
|
||||
|
||||
<h3><a id="elementHost">Host capabilities</a></h3>
|
||||
|
||||
<p>The <code><host/></code> element consists of the following child
|
||||
elements:</p>
|
||||
<dl>
|
||||
<dt><code>uuid</code></dt>
|
||||
<dd>The host UUID.</dd>
|
||||
|
||||
<dt><code>cpu</code></dt>
|
||||
<dd>The host CPU architecture and features.</dd>
|
||||
|
||||
<dt><code>power_management</code></dt>
|
||||
<dd>whether host is capable of memory suspend, disk hibernation, or
|
||||
hybrid suspend.</dd>
|
||||
|
||||
<dt><code>migration_features</code></dt>
|
||||
<dd>This element exposes information on the hypervisor's migration
|
||||
capabilities, like live migration, supported URI transports, and so
|
||||
on.</dd>
|
||||
|
||||
<dt><code>topology</code></dt>
|
||||
<dd>This element embodies the host internal topology. Management
|
||||
applications may want to learn this information when orchestrating new
|
||||
guests - e.g. due to reduce inter-NUMA node transfers. Note that the
|
||||
<code>sockets</code> value reported here is per-NUMA-node; this is in
|
||||
contrast to the value given in domain definitions, which is interpreted
|
||||
as a total number of sockets for the domain.</dd>
|
||||
|
||||
<dt><code>secmodel</code></dt>
|
||||
<dd>To find out default security labels for different security models you
|
||||
need to parse this element. In contrast with the former elements, this is
|
||||
repeated for each security model the libvirt daemon currently supports.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
<h3><a id="elementGuest">Guest capabilities</a></h3>
|
||||
|
||||
<p>While the <a href="#elementHost">previous section</a> aims at host
|
||||
capabilities, this one focuses on capabilities available to a guest
|
||||
using a given hypervisor. The <code><guest/></code> element will
|
||||
typically wrap up the following elements:</p>
|
||||
|
||||
<dl>
|
||||
<dt><code>os_type</code></dt>
|
||||
<dd>This expresses what kind of operating system the hypervisor
|
||||
is able to run. Possible values are:
|
||||
<dl>
|
||||
<dt><code>xen</code></dt>
|
||||
<dd>for XEN PV</dd>
|
||||
|
||||
<dt><code>linux</code></dt>
|
||||
<dd>legacy alias for <code>xen</code></dd>
|
||||
|
||||
<dt><code>xenpvh</code></dt>
|
||||
<dd>for XEN PVH</dd>
|
||||
|
||||
<dt><code>hvm</code></dt>
|
||||
<dd>Unmodified operating system</dd>
|
||||
|
||||
<dt><code>exe</code></dt>
|
||||
<dd>Container based virtualization</dd>
|
||||
</dl>
|
||||
</dd>
|
||||
|
||||
<dt><code>arch</code></dt>
|
||||
<dd>This element brings some information on supported guest
|
||||
architecture. Possible subelements are:
|
||||
<dl>
|
||||
<dt><code>wordsize</code></dt><dd>Size of CPU word in bits, for example 64.</dd>
|
||||
<dt><code>emulator</code></dt><dd>Emulator (device model) path, for
|
||||
use in <a href="formatdomain.html#elementEmulator">emulator</a>
|
||||
element of domain XML.</dd>
|
||||
<dt><code>loader</code></dt><dd>Loader path, for use in
|
||||
<a href="formatdomain.html#elementLoader">loader</a> element of domain
|
||||
XML.</dd>
|
||||
<dt><code>machine</code></dt><dd>Machine type, for use in
|
||||
<a href="formatdomain.html#attributeOSTypeMachine">machine</a>
|
||||
attribute of os/type element in domain XML. For example Xen
|
||||
supports <code>xenfv</code> for HVM, <code>xenpv</code> for
|
||||
PV, or <code>xenpvh</code> for PVH.</dd>
|
||||
<dt><code>domain</code></dt><dd>The <code>type</code> attribute of
|
||||
this element specifies the type of hypervisor required to run the
|
||||
domain. Use in <a href="formatdomain.html#attributeDomainType">type</a>
|
||||
attribute of the domain root element.</dd>
|
||||
</dl>
|
||||
</dd>
|
||||
|
||||
<dt><code>features</code></dt>
|
||||
<dd>This optional element encases possible features that can be used
|
||||
with a guest of described type. Possible subelements are:
|
||||
<dl>
|
||||
<dt><code>pae</code></dt><dd>If present, 32-bit guests can use PAE
|
||||
address space extensions, <span class="since">since
|
||||
0.4.1</span></dd>
|
||||
<dt><code>nonpae</code></dt><dd>If present, 32-bit guests can be run
|
||||
without requiring PAE, <span class="since">since
|
||||
0.4.1</span></dd>
|
||||
<dt><code>ia64_be</code></dt><dd>If present, IA64 guests can be run in
|
||||
big-endian mode, <span class="since">since 0.4.1</span></dd>
|
||||
<dt><code>acpi</code></dt><dd>If this element is present,
|
||||
the <code>default</code> attribute describes whether the
|
||||
hypervisor exposes ACPI to the guest by default, and
|
||||
the <code>toggle</code> attribute describes whether the
|
||||
user can override this
|
||||
default. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>apic</code></dt><dd>If this element is present,
|
||||
the <code>default</code> attribute describes whether the
|
||||
hypervisor exposes APIC to the guest by default, and
|
||||
the <code>toggle</code> attribute describes whether the
|
||||
user can override this
|
||||
default. <span class="since">Since 0.4.1</span></dd>
|
||||
<dt><code>cpuselection</code></dt><dd>If this element is present, the
|
||||
hypervisor supports the <code><cpu></code> element
|
||||
within a domain definition for fine-grained control over
|
||||
the CPU presented to the
|
||||
guest. <span class="since">Since 0.7.5</span></dd>
|
||||
<dt><code>deviceboot</code></dt><dd>If this element is present,
|
||||
the <code><boot order='...'/></code> element can
|
||||
be used inside devices, rather than the older boot
|
||||
specification by category. <span class="since">Since
|
||||
0.8.8</span></dd>
|
||||
<dt><code>disksnapshot</code></dt><dd>If this element is present,
|
||||
the <code>default</code> attribute describes whether
|
||||
external disk snapshots are supported. If absent,
|
||||
external snapshots may still be supported, but it
|
||||
requires attempting the API and checking for an error to
|
||||
find out for sure. <span class="since">Since
|
||||
1.2.3</span></dd>
|
||||
</dl>
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
<h3><a id="elementExamples">Examples</a></h3>
|
||||
|
||||
<p>For example, in the case of a 64-bit machine with hardware
|
||||
virtualization capabilities enabled in the chip and
|
||||
BIOS you will see:</p>
|
||||
|
||||
<pre><capabilities>
|
||||
<span style="color: #E50000"><host>
|
||||
<cpu>
|
||||
<arch>x86_64</arch>
|
||||
<features>
|
||||
<vmx/>
|
||||
</features>
|
||||
<model>core2duo</model>
|
||||
<vendor>Intel</vendor>
|
||||
<topology sockets="1" dies="1" cores="2" threads="1"/>
|
||||
<feature name="lahf_lm"/>
|
||||
<feature name='xtpr'/>
|
||||
...
|
||||
</cpu>
|
||||
<power_management>
|
||||
<suspend_mem/>
|
||||
<suspend_disk/>
|
||||
<suspend_hybrid/>
|
||||
</power_management>
|
||||
</host></span>
|
||||
|
||||
<!-- xen-3.0-x86_64 -->
|
||||
<span style="color: #0000E5"><guest>
|
||||
<os_type>xen</os_type>
|
||||
<arch name="x86_64">
|
||||
<wordsize>64</wordsize>
|
||||
<domain type="xen"></domain>
|
||||
<emulator>/usr/lib64/xen/bin/qemu-dm</emulator>
|
||||
</arch>
|
||||
<features>
|
||||
</features>
|
||||
</guest></span>
|
||||
|
||||
<!-- hvm-3.0-x86_32 -->
|
||||
<span style="color: #00B200"><guest>
|
||||
<os_type>hvm</os_type>
|
||||
<arch name="i686">
|
||||
<wordsize>32</wordsize>
|
||||
<domain type="xen"></domain>
|
||||
<emulator>/usr/lib/xen/bin/qemu-dm</emulator>
|
||||
<machine>pc</machine>
|
||||
<machine>isapc</machine>
|
||||
<loader>/usr/lib/xen/boot/hvmloader</loader>
|
||||
</arch>
|
||||
<features>
|
||||
<cpuselection/>
|
||||
<deviceboot/>
|
||||
</features>
|
||||
</guest></span>
|
||||
...
|
||||
</capabilities></pre>
|
||||
</body>
|
||||
</html>
|
||||
197
docs/formatcaps.rst
Normal file
197
docs/formatcaps.rst
Normal file
@ -0,0 +1,197 @@
|
||||
.. role:: since
|
||||
|
||||
==============================
|
||||
Driver capabilities XML format
|
||||
==============================
|
||||
|
||||
.. contents::
|
||||
|
||||
Element and attribute overview
|
||||
------------------------------
|
||||
|
||||
As new virtualization engine support gets added to libvirt, and to handle cases
|
||||
like QEMU supporting a variety of emulations, a query interface has been added
|
||||
in 0.2.1 allowing to list the set of supported virtualization capabilities on
|
||||
the host:
|
||||
|
||||
::
|
||||
|
||||
char * virConnectGetCapabilities (virConnectPtr conn);
|
||||
|
||||
The value returned is an XML document listing the virtualization capabilities of
|
||||
the host and virtualization engine to which ```conn`` is connected. One can test
|
||||
it using ``virsh`` command line tool command '``capabilities``', it dumps the
|
||||
XML associated to the current connection.
|
||||
|
||||
As can be seen in the `Examples`_, the capabilities XML
|
||||
consists of the ``capabilities`` element which have exactly one ``host`` child
|
||||
element to report information on host capabilities, and zero or more ``guest``
|
||||
element to express the set of architectures the host can run at the moment.
|
||||
|
||||
Host capabilities
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``<host/>`` element consists of the following child elements:
|
||||
|
||||
``uuid``
|
||||
The host UUID.
|
||||
``cpu``
|
||||
The host CPU architecture and features.
|
||||
``power_management``
|
||||
whether host is capable of memory suspend, disk hibernation, or hybrid
|
||||
suspend.
|
||||
``migration_features``
|
||||
This element exposes information on the hypervisor's migration capabilities,
|
||||
like live migration, supported URI transports, and so on.
|
||||
``topology``
|
||||
This element embodies the host internal topology. Management applications may
|
||||
want to learn this information when orchestrating new guests - e.g. due to
|
||||
reduce inter-NUMA node transfers. Note that the ``sockets`` value reported
|
||||
here is per-NUMA-node; this is in contrast to the value given in domain
|
||||
definitions, which is interpreted as a total number of sockets for the
|
||||
domain.
|
||||
``secmodel``
|
||||
To find out default security labels for different security models you need to
|
||||
parse this element. In contrast with the former elements, this is repeated
|
||||
for each security model the libvirt daemon currently supports.
|
||||
|
||||
Guest capabilities
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
While the previous section (`Host capabilities`_) aims at host capabilities,
|
||||
this one focuses on capabilities available to a guest using a given hypervisor.
|
||||
The ``<guest/>`` element will typically wrap up the following elements:
|
||||
|
||||
``os_type``
|
||||
This expresses what kind of operating system the hypervisor is able to run.
|
||||
Possible values are:
|
||||
|
||||
``xen``
|
||||
for XEN PV
|
||||
``linux``
|
||||
legacy alias for ``xen``
|
||||
``xenpvh``
|
||||
for XEN PVH
|
||||
``hvm``
|
||||
Unmodified operating system
|
||||
``exe``
|
||||
Container based virtualization
|
||||
``arch``
|
||||
This element brings some information on supported guest architecture.
|
||||
Possible subelements are:
|
||||
|
||||
``wordsize``
|
||||
Size of CPU word in bits, for example 64.
|
||||
``emulator``
|
||||
Emulator (device model) path, for use in
|
||||
`emulator <formatdomain.html#elementEmulator>`__ element of domain XML.
|
||||
``loader``
|
||||
Loader path, for use in `loader <formatdomain.html#elementLoader>`__
|
||||
element of domain XML.
|
||||
``machine``
|
||||
Machine type, for use in
|
||||
`machine <formatdomain.html#attributeOSTypeMachine>`__ attribute of
|
||||
os/type element in domain XML. For example Xen supports ``xenfv`` for HVM,
|
||||
``xenpv`` for PV, or ``xenpvh`` for PVH.
|
||||
``domain``
|
||||
The ``type`` attribute of this element specifies the type of hypervisor
|
||||
required to run the domain. Use in
|
||||
`type <formatdomain.html#attributeDomainType>`__ attribute of the domain
|
||||
root element.
|
||||
``features``
|
||||
This optional element encases possible features that can be used with a guest
|
||||
of described type. Possible subelements are:
|
||||
|
||||
``pae``
|
||||
If present, 32-bit guests can use PAE address space extensions,
|
||||
:since:`since 0.4.1`
|
||||
``nonpae``
|
||||
If present, 32-bit guests can be run without requiring PAE, :since:`since
|
||||
0.4.1`
|
||||
``ia64_be``
|
||||
If present, IA64 guests can be run in big-endian mode, :since:`since
|
||||
0.4.1`
|
||||
``acpi``
|
||||
If this element is present, the ``default`` attribute describes whether
|
||||
the hypervisor exposes ACPI to the guest by default, and the ``toggle``
|
||||
attribute describes whether the user can override this default.
|
||||
:since:`Since 0.4.1`
|
||||
``apic``
|
||||
If this element is present, the ``default`` attribute describes whether
|
||||
the hypervisor exposes APIC to the guest by default, and the ``toggle``
|
||||
attribute describes whether the user can override this default.
|
||||
:since:`Since 0.4.1`
|
||||
``cpuselection``
|
||||
If this element is present, the hypervisor supports the ``<cpu>`` element
|
||||
within a domain definition for fine-grained control over the CPU presented
|
||||
to the guest. :since:`Since 0.7.5`
|
||||
``deviceboot``
|
||||
If this element is present, the ``<boot order='...'/>`` element can be
|
||||
used inside devices, rather than the older boot specification by category.
|
||||
:since:`Since 0.8.8`
|
||||
``disksnapshot``
|
||||
If this element is present, the ``default`` attribute describes whether
|
||||
external disk snapshots are supported. If absent, external snapshots may
|
||||
still be supported, but it requires attempting the API and checking for an
|
||||
error to find out for sure. :since:`Since 1.2.3`
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
|
||||
For example, in the case of a 64-bit machine with hardware virtualization
|
||||
capabilities enabled in the chip and BIOS you will see:
|
||||
|
||||
::
|
||||
|
||||
<capabilities>
|
||||
<host>
|
||||
<cpu>
|
||||
<arch>x86_64</arch>
|
||||
<features>
|
||||
<vmx/>
|
||||
</features>
|
||||
<model>core2duo</model>
|
||||
<vendor>Intel</vendor>
|
||||
<topology sockets="1" dies="1" cores="2" threads="1"/>
|
||||
<feature name="lahf_lm"/>
|
||||
<feature name='xtpr'/>
|
||||
...
|
||||
</cpu>
|
||||
<power_management>
|
||||
<suspend_mem/>
|
||||
<suspend_disk/>
|
||||
<suspend_hybrid/>
|
||||
</power_management>
|
||||
</host>
|
||||
|
||||
<!-- xen-3.0-x86_64 -->
|
||||
<guest>
|
||||
<os_type>xen</os_type>
|
||||
<arch name="x86_64">
|
||||
<wordsize>64</wordsize>
|
||||
<domain type="xen"></domain>
|
||||
<emulator>/usr/lib64/xen/bin/qemu-dm</emulator>
|
||||
</arch>
|
||||
<features>
|
||||
</features>
|
||||
</guest>
|
||||
|
||||
<!-- hvm-3.0-x86_32 -->
|
||||
<guest>
|
||||
<os_type>hvm</os_type>
|
||||
<arch name="i686">
|
||||
<wordsize>32</wordsize>
|
||||
<domain type="xen"></domain>
|
||||
<emulator>/usr/lib/xen/bin/qemu-dm</emulator>
|
||||
<machine>pc</machine>
|
||||
<machine>isapc</machine>
|
||||
<loader>/usr/lib/xen/boot/hvmloader</loader>
|
||||
</arch>
|
||||
<features>
|
||||
<cpuselection/>
|
||||
<deviceboot/>
|
||||
</features>
|
||||
</guest>
|
||||
|
||||
...
|
||||
</capabilities>
|
||||
@ -18,7 +18,6 @@ docs_assets = [
|
||||
]
|
||||
|
||||
docs_html_in_files = [
|
||||
'formatcaps',
|
||||
'formatnetwork',
|
||||
'formatnode',
|
||||
'index',
|
||||
@ -69,6 +68,7 @@ docs_rst_files = [
|
||||
'firewall',
|
||||
'format',
|
||||
'formatbackup',
|
||||
'formatcaps',
|
||||
'formatcheckpoint',
|
||||
'formatdomain',
|
||||
'formatdomaincaps',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user