11:02 a.m.
Signed-off-by: Peter Krempa <pkrempa(a)redhat.com>
---
docs/formatcaps.html.in | 222 ----------------------------------------
docs/formatcaps.rst | 197 +++++++++++++++++++++++++++++++++++
docs/meson.build | 2 +-
3 files changed, 198 insertions(+), 223 deletions(-)
delete mode 100644 docs/formatcaps.html.in
create mode 100644 docs/formatcaps.rst
diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in
deleted file mode 100644
index a4abad5d20..0000000000
--- a/docs/formatcaps.html.in
+++ /dev/null
@@ -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>
diff --git a/docs/formatcaps.rst b/docs/formatcaps.rst
new file mode 100644
index 0000000000..abd36692e4
--- /dev/null
+++ b/docs/formatcaps.rst
@@ -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>
diff --git a/docs/meson.build b/docs/meson.build
index 0458eea683..196f49a1a0 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -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',
--
2.35.1