Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- 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
