11:22 a.m.
Signed-off-by: Jiri Denemark <jdenemar(a)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