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

[Daniel P. Berrange]

On Wed, Jun 04, 2014 at 10:04:44AM -0600, Eric Blake wrote:
> 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 at redhat.com>
> > ---
> >  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><guest/></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><capabilities>
> >    <span style="color: #E50000"><host>
> >      <cpu>
> >        <arch>x86_64</arch>
> 
> > +    <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
> > +    <power_management/> 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/msg00215.html">the
> > +        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.

Yeah, I'd kill that link, or even kill all the existing verbose description
which is rather adhoc and not well explained.


Regards,
Daniel
-- 
|: http://berrange.com      -o-    http://www.flickr.com/photos/dberrange/ :|
|: http://libvirt.org              -o-             http://virt-manager.org :|
|: http://autobuild.org       -o-         http://search.cpan.org/~danberr/ :|
|: http://entangle-photo.org       -o-       http://live.gnome.org/gtk-vnc :|