Re: [libvirt] [PATCH 2/2] formatcaps: Rework and add stubs to document

On 06/04/2014 09:34 AM, Michal Privoznik wrote: > At the moment we are missing even basic documentation on our > capabilities XML. Without demand on completeness, I'm > reorganizing the document structure and adding very basic > documentation to two major components of the capabilities XML. > These stubs are intended to be enhanced in the future. > > Signed-off-by: Michal Privoznik <mprivozn(a)redhat.com&gt; > --- > docs/formatcaps.html.in | 158 ++++++++++++++++++++++++++++++++++++------------ > 1 file changed, 121 insertions(+), 37 deletions(-) > + > + <dt><code>migration</code></dt> > + <dd>This element expose information on hypervisor's migration s/expose/exposes/ s/on/on the/ > + 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 > + be repeated for each security model the libvirt daemon currently s/be // > + supports.</dd> > + </dl> > + > + > + <h3><a name="elementGuest">Guest capabilities</a></h3> > + > + <p>While the <a href="#elementHost">previous section</a> aims at host > + capabilities, this one focus on domain's ones. The s/focus on domain's ones/focuses on capabilities available to a guest using a given hypervisor/ > + <code>&lt;guest/&gt;</code> element will typically wrap up the following > + elements:</p> > + > + <dl> > + <dt><code>os_type</code></dt> > + <dd>This express what kind of operating system is the hypervisor able s/express/expresses/ s/is the hyperviser able/the hypervisor is able/ > + to run. Possible values are: > + > + <h3><a name="elementExamples">Examples</a></h3> > + > + <p>For example in the case of a 64 bits s/example/example,/ s/64 bits/64-bit/ > + machine with hardware virtualization capabilities enabled in the chip and > + BIOS you will see:</p> > + > + <pre>&lt;capabilities&gt; > <span style="color: #E50000">&lt;host&gt; > &lt;cpu&gt; > &lt;arch&gt;x86_64&lt;/arch&gt; > + <p>The first block (in red) indicates the host hardware capabilities, such > + as CPU properties and the power management features of the host platform. > + CPU models are shown as additional features relative to the closest base > + model, within a feature block (the block is similar to what you will find > + in a Xen fully virtualized domain description). Further, the power > + management features supported by the host are shown, such as Suspend-to-RAM > + (S3), Suspend-to-Disk (S4) and Hybrid-Suspend (a combination of S3 and S4). > + In case the host does not support any such feature, then an empty > + &lt;power_management/&gt; tag will be shown. </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> > + > + <p>The third block (in green) gives similar information but when running a > + 32 bit OS fully virtualized with Xen using the hvm support.</p> > + > + <p>This section is likely to be updated and augmented in the future, see <a > + href="https://www.redhat.com/archives/libvir-list/2007-March/msg0021... > + discussion</a> which led to the capabilities format in the mailing-list > + archives.</p> Do we still want to link to a message that old? I'd rather cover the information in the docs as a self-sufficient page instead of linking to 7-year old threads.