[libvirt] virsh capabilities vs. domcapabilities

[Michal Privoznik]

On 16.07.2014 21:00, Eric Blake wrote:
> We have some inconsistencies in the node capabilities (which shows guest
> capabilities for some default binaries) and domcapabilities (which shows
> guest capabilities for a specified binary).  It might be nicer for
> client applications if the two XML components share a common schema and
> output layout, so that the same client code can be used to parse either
> (sub-tree of) XML, modulo the name of the top-most element containing
> the tree.
>
> Furthermore, I'm trying to figure out how to advertise whether a given
> domain will support active commit (and similarly, Peter's patches for
> relative backing name preservation).  Advertising the feature just
> through 'virsh capabilities' is insufficient, because that only covers
> the default binary; so it seems like the sort of thing that should also
> be in 'virsh domcapabilities'.

That depends on how's active commit accepted by libvirt. IIUC it's a 
flag to an API. (Okay, you got me there, I'm not paying much attention 
to snapshot work).

The best solution would be to introduce another section, where supported 
flags to APIs would be enumerated (same way that attribute values are). 
But this is sooo much more work than in attribute part (esp. without 
introspection) that the resulting code would be unmaintainable.

So my suggestion is to come up with yet another section and put 
arbitrary strings there to represent features like active commit. For 
instance:

<domainCapabilities>
   <path/>
   <domain/>
   ...
   <features>
     <enum name='commit'>
       <value>active-commit</value>
       <value>{some ordinary commit}</value>
     </enum>
   </features>
   <devices/>
</domainCapabilities>


>
> Since virConnectGetDomainCapabilities is brand new to 1.2.7, we still
> have time to change its XML.  But I want consensus on whether we need
> things to match, or whether we intentionally want people to rely only on
> the newer XML format of the new API call (that is, don't bloat 'virsh
> capabilities'/virConnectGetCapabilities any further, and learning
> whether active commit is supported will have to be done via 'virsh
> domcapabilities'/virConnectGetDomainCapabilities).  That is, I'm
> wondering if <domainCapabilities> should use <capabilities>/<guest> as
> its starting point, rather than completely inventing new XML.
>
> I'm also finding 'virsh domcapabilities' a bit hard to use - even though
> it allows all its arguments to be optional at the RPC level, the qemu
> implementation isn't so happy:
>
> # tools/virsh domcapabilities
> error: failed to get emulator capabilities
> error: virttype_str in qemuConnectGetDomainCapabilities must not be NULL
>
> but how am I supposed to know what --virttype strings are valid?

By reading the documentation :P
 From the virsh manpage:

The virttype option specifies the virtualization type used. The value to 
be used is either from the 'type' attribute of the <domain/> top level 
element from the domain XML or the 'type' attribute found within each 
<guest/> element from the virsh capabilities output.

I know virsh user is user unfriendly, but I think this could be solved 
by wise auto completion (if I find another student to complete it). Or 
if you have any idea meanwhile ...

>
> # tools/virsh domcapabilities --virttype kvm
> error: failed to get emulator capabilities
> error: invalid argument: at least one of emulatorbin or architecture
> fields must be present
>
> Would it be nicer to behave the same as 'virsh capabilities' and give
> the details of the default binary in this case?

Sure, but in order to get default binary we must know architecture 
(consider the case where you have both /usr/bin/qemu-system-x86_64 and 
/usr/bin/qemu-system-i686). Although, having only one qemu binary on the 
system makes it easy to find the default, doesn't it? Patch on the way.

>
>
>
> Now, for a comparison between the two XML per binary:
>
> 'virsh capabilities' gives me this segment:
>
>    <guest>
>      <os_type>hvm</os_type>
>      <arch name='alpha'>
>        <wordsize>64</wordsize>
>        <emulator>/usr/bin/qemu-system-alpha</emulator>
>        <machine maxCpus='4'>clipper</machine>
>        <domain type='qemu'>
>        </domain>
>      </arch>
>      <features>
>        <deviceboot/>
>        <disksnapshot default='on' toggle='no'/>
>      </features>
>    </guest>
>
> while 'virsh domcapabilities --emulatorbin /usr/bin/qemu-system-alpha
> --virttype kvm' gives this:
>
> <domainCapabilities>
>    <path>/usr/bin/qemu-system-alpha</path>
>    <domain>kvm</domain>
>    <machine>clipper</machine>
>    <arch>alpha</arch>
>    <vcpu max='4'/>
>    <devices>
>      <disk supported='yes'>
>        <enum name='diskDevice'>
>          <value>disk</value>
>          <value>cdrom</value>
>          <value>floppy</value>
>          <value>lun</value>
>        </enum>
>        <enum name='bus'>
>          <value>ide</value>
>          <value>fdc</value>
>          <value>scsi</value>
>          <value>virtio</value>
>          <value>usb</value>
>        </enum>
>      </disk>
>      <hostdev supported='yes'>
>        <enum name='mode'>
>          <value>subsystem</value>
>        </enum>
>        <enum name='startupPolicy'>
>          <value>default</value>
>          <value>mandatory</value>
>          <value>requisite</value>
>          <value>optional</value>
>        </enum>
>        <enum name='subsysType'>
>          <value>usb</value>
>          <value>pci</value>
>          <value>scsi</value>
>        </enum>
>        <enum name='capsType'/>
>        <enum name='pciBackend'/>
>      </hostdev>
>    </devices>
> </domainCapabilities>
>
>   I'm okay that the domcapabilites output is longer, and don't think we
> need to backport any of the new stuff to the older API.  But any
> information present in the old API should be easily retrieved using the
> new API, so that the information isn't lost, and so that a client can
> learn the same amount of detail about a non-default binary as they can
> about the defaults.
>
> Look at the difference in XPath to get to some of the same information:
>
> /guest/os_type vs. ? - where is os_type in domcapabilities?

nowhere yet.

>
> /guest/arch at name vs. /domainCapabilities/arch - why is one an attribute
> and the other an element?
>
> /guest/arch/wordsize vs. nothing - where is wordsize in domcapabilities?

Well, nowhere yet. But it's trivial to add.

>
> /guest/arch/emulator vs. /domainCapabilities/path - why 3 levels vs. 2,
> and different naming?

This is something provided by callee, so in fact it has no additional value.

>
> /guest/arch/machine at maxCpus vs. /domainCapabilities/vcpu at max - why 3
> levels vs. 2, with different naming?

Because we may want to extend <vcpu/> fom domaincaps in the future.

>
> /guest/arch/machine vs. /domainCapabilities/machine - why 3 levels vs. 2?
>
> /guest/arch/domain at type vs. /domainCapabilities/domain - why attribute
> of 3 levels vs. element at 2 levels?  And did I expose an error when I
> passed --virrtype kvm, even though qemu-system-alpha is only a qemu
> emulator on my machine (since kvm emulators is only for hardware-assit
> emulation, which is not possible when I'm doing cross architecture)?
>
> /guest/features vs. ? - where are the features in domcapabilities?
>


To sum up - I'm not hesitant to make things easier for users, but 
allowing them to use same XPath over different types of XML documents 
put much pressure on us. On the other hand, patches are welcome - as 
usual :)

Michal