[libvirt] [PATCH] Document <cpu> elements in capabilities and domain XML

[Jiri Denemark]

Signed-off-by: Jiri Denemark <jdenemar at redhat.com>
---
 docs/formatcaps.html.in   |   13 +++++-
 docs/formatdomain.html.in |   93 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+), 3 deletions(-)

diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in
index 36718d9..525a331 100644
--- a/docs/formatcaps.html.in
+++ b/docs/formatcaps.html.in
@@ -21,6 +21,11 @@ BIOS you will see</p>
       <features>
         <vmx/>
       </features>
+      <model>core2duo</model>
+      <topology sockets="1" cores="2" threads="1"/>
+      <feature name="lahf_lm"/>
+      <feature name='xtpr'/>
+      ...
     </cpu>
   </host></span>
 
@@ -48,15 +53,17 @@ BIOS you will see</p>
       <loader>/usr/lib/xen/boot/hvmloader</loader>
     </arch>
     <features>
+      <cpuselection/>
     </features>
   </guest></span>
   ...
 </capabilities></pre>
         <p>The first block (in red) indicates the host hardware capabilities, currently
 it is limited to the CPU properties but other information may be available,
-it shows the CPU architecture, and the features of the chip (the feature
-block is similar to what you will find in a Xen fully virtualized domain
-description).</p>
+it shows the CPU architecture, topology, model name, and additional features
+which are not included in the model but the CPU provides them. Features of the
+chip are shown within the feature block (the block is similar to what you will
+find in a Xen fully virtualized domain description).</p>
         <p>The second block (in blue) indicates the paravirtualization support of the
 Xen support, you will see the os_type of xen to indicate a paravirtual
 kernel, then architecture information and potential features.</p>
diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index af31699..5030b6c 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -201,6 +201,99 @@
         CPUs allocated for the guest OS.</dd>
     </dl>
 
+    <h3><a name="elementsCPU">CPU model and topology</a></h3>
+
+    <p>
+      Requirements for CPU model, its features and topology can be specified
+      using the following collection of elements.
+      <snap class="since">Since 0.7.5</span>
+    </p>
+
+    <pre>
+        ...
+        <cpu match='exact'>
+          <model>core2duo</model>
+          <topology sockets='1' cores='2' threads='1'/>
+          <feature policy='disable' name='lahf_lm'/>
+        </cpu>
+        ...</pre>
+
+    <p>
+      In case no restrictions need to be put on CPU model and its features, a
+      simpler <code>cpu</code> element can be used.
+      <span class="since">Since 0.7.6</span>
+    </p>
+
+    <pre>
+        ...
+        <cpu>
+          <topology sockets='1' cores='2' threads='1'/>
+        </cpu>
+        ...</pre>
+
+    <dl>
+      <dt><code>cpu</code><dt>
+      <dd>The <code>cpu</code> element is the main container for describing
+        guest CPU requirements. Its <code>match</code> attribute specified how
+        strictly has the virtual CPU provided to the guest match these
+        requirements. <span class="since">Since 0.7.6</span> the
+        <code>match</code> attribute can be omitted if <code>topology</code>
+        is the only element within <code>cpu</code>. Possible values for the
+        <code>match</code> attribute are:
+
+        <dl>
+          <dt><code>minimum</code></dt>
+          <dd>The specified CPU model and features describes the minimum
+            requested CPU.</dd>
+          <dt><code>exact</code></dt>
+          <dd>The virtual CPU provided to the guest will exactly match the
+            specification</dd>
+          <dt><code>strict</code></dt>
+          <dd>The guest will not be created unless the host CPU does exactly
+            match the specification.</dd>
+        </dl>
+      </dd>
+
+      <dt><code>model</code></dt>
+      <dd>The content of the <code>model</code> element specifies CPU model
+        requested by the guest. The list of available CPU models and their
+        definition can be found in <code>cpu_map.xml</code> file installed
+        in libvirt's data directory.</dd>
+
+      <dt><code>topology</code></dt>
+      <dd>The <code>topology</code> element specifies requested topology of
+        virtual CPU provided to the guest. Three non-zero values have to be
+        given for <code>sockets</code>, <code>cores</code>, and
+        <code>threads</code>: total number of CPU sockets, number of cores per
+        socket, and number of threads per core, respectively.</dd>
+
+      <dt><code>feature</code></dt>
+      <dd>The <code>cpu</code> element can contain zero or more
+        <code>elements</code> used to fine-tune features provided by the
+        selected CPU model. The list of known feature names can be found in
+        the same file as CPU models. The meaning of each <code>feature</code>
+        element depends on its <code>policy</code> attribute, which has to be
+        set to one of the following values:
+
+        <dl>
+          <dt><code>force</code></dt>
+          <dd>The virtual CPU will claim the feature is supported regardless
+            of it being supported by host CPU.</dd>
+          <dt><code>require</code></dt>
+          <dd>Guest creation will fail unless the feature is supported by host
+            CPU.</dd>
+          <dt><code>optional</code></dt>
+          <dd>The feature will be supported by virtual CPU if and only if it
+            is supported by host CPU.</dd>
+          <dt><code>disable</code></dt>
+          <dd>The feature will not be supported by virtual CPU.</dd>
+          <dt><code>forbid</code></dt>
+          <dd>Guest creation will fail if the feature is supported by host
+            CPU.</dd>
+        </dl>
+      </dd>
+    </dl>
+
     <h3><a name="elementsLifecycle">Lifecycle control</a></h3>
 
     <p>
-- 
1.6.6