[libvirt] virsh capabilities vs. domcapabilities

Daniel P. Berrange berrange at redhat.com
Thu Jul 17 08:54:30 UTC 2014

On Wed, Jul 16, 2014 at 01:00:30PM -0600, Eric Blake wrote:
> 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'.

My view is that now we have dom capabilities, we shouldn't add anything
more to the old capabilities that is related to guest emulators. The
main motivation is that the old capabilities is not scalable given the
sheer volume of data we need to report per QEMU.

> 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 don't think there's really anything of value in the old capabilities
XML schema that needs preserving as-is.

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

Hmm, I'm pretty sure we agreed virt type was going to be optional and
would jsut get a sensible default. So we should fix that.

> # 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?

My original idea was that either emulator or arch would be required.
If we wanted to allow just virtype on its own, I guess we could just
default to the current host arch.

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

Yep, that's an oversight really.

> /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?
> /guest/arch/emulator vs. /domainCapabilities/path - why 3 levels vs. 2,
> and different naming?
> /guest/arch/machine at maxCpus vs. /domainCapabilities/vcpu at max - why 3
> levels vs. 2, with different naming?
> /guest/arch/machine vs. /domainCapabilities/machine - why 3 levels vs. 2?

This is just a reflection of the fact that we're doing a different
XML schema. We had the extra '/guest' level in the original XML
because we were reporting on multiple guest types. I see no reason
to make the new XML have this uneccessary extra level of nesting.

> /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?

Explicitly gone. The features element in the current capabilies is
just a dumping ground for random stuff. Initially at least the new
capabilities XML is structured around the idea of reporting valid
enum strings for elements in the domain XML schema, and is structured
to follow the domain XML schema nested.

I guess you're wondering about where to fit in the data that isn't
related to the domain XML schema, but rather API capabilities. I'd
suggest we try to come up with something formal for API information.


If the info is related to an 'unsigned int flags' parameter value
then we should perhaps using  <flag name="NNNN"/> where 'NNNN' is
the trailing suffix of the flag constant name (ie the common shared
prefix removed).

eg for virDomainBlockRebase, we might add

         <flag name="relative" supported='yes|no'/>

NB, absence of a <flag name='xxx'> entirely does not mean it is
unsupported. It just means we've declined to provide info on it.
We'd always have an explicit supported='no' attribute for stuff
that is not supported.

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

More information about the libvir-list mailing list