[PATCH 17/29] docs: Convert 'formatcaps' page to rST

Peter Krempa pkrempa at redhat.com
Mon Mar 28 12:10:32 UTC 2022


Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/formatcaps.html.in | 219 ----------------------------------------
 docs/formatcaps.rst     | 196 +++++++++++++++++++++++++++++++++++
 docs/meson.build        |   2 +-
 3 files changed, 197 insertions(+), 220 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 09662f78c8..0000000000
--- a/docs/formatcaps.html.in
+++ /dev/null
@@ -1,219 +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.</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..1ba847cea1
--- /dev/null
+++ b/docs/formatcaps.rst
@@ -0,0 +1,196 @@
+.. 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 `example <#elementExamples>`__, 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.
+``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 <#elementHost>`__ 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 acc455c7c7..95c9babcf5 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -22,7 +22,6 @@ docs_html_in_files = [
   'csharp',
   'dbus',
   'docs',
-  'formatcaps',
   'formatdomaincaps',
   'formatnetwork',
   'formatnetworkport',
@@ -83,6 +82,7 @@ docs_rst_files = [
   'firewall',
   'format',
   'formatbackup',
+  'formatcaps',
   'formatcheckpoint',
   'formatdomain',
   'formatsecret',
-- 
2.35.1



More information about the libvir-list mailing list