diff --git a/docs/formatcaps.html.in b/docs/formatcaps.html.in index d060a5b78b..137af258ff 100644 --- a/docs/formatcaps.html.in +++ b/docs/formatcaps.html.in @@ -4,19 +4,107 @@

Driver capabilities XML format

-

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. For example in the case of a 64 bits -machine with hardware virtualization capabilities enabled in the chip and -BIOS you will see

- 
<capabilities>
+    
+
+    
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 seen in the example, 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

+      
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 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

+
+          
linux

+          
legacy alias for xen

+
+          
hvm

+          
Unmodified operating system

+
+          
exe

+          
Container based virtualization

+
+          
uml

+          
User Mode Linux

+        

+        

+
+        
arch

+        
This element brings some information on supported guest architecture.

+
+        
features

+        
This optional element encases possible features that can be used
+        with a guest of described type.

+    

+
+    
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>
@@ -67,30 +155,5 @@ BIOS you will see

   </guest>
   ...
 </capabilities>

-        
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. 

-        
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.

-        
The third block (in green) gives similar information but
-          when running a 32 bit OS fully virtualized with Xen using
-          the hvm support.

-        
This section is likely to be updated and augmented in the
-          future,
-          see the
-          discussion which led to the capabilities format in the
-          mailing-list archives.

-