[libvirt] [RFC 3/6] schema: Validate GIC capabilities

[Andrea Bolognani]

On Wed, 2016-03-30 at 15:36 -0400, John Ferlan wrote:
> On 03/21/2016 01:28 PM, Andrea Bolognani wrote:
> > 
> > We need to expose GIC capabilities in the domain capabilities
> > XML: update the schema to validate documents that contain the
> > new information.
> > ---
> >  docs/schemas/domaincaps.rng | 18 ++++++++++++++++++
> >  1 file changed, 18 insertions(+)
>
> I think patches 3 and 4 should be combined and 5 is not too far behind!

I usually try to keep patches as small and self-contained
as possible, provided doing so doesn't break the check and
syntax-check targets and the changes represent some sort
of meaningful unit.

The balance is of course very hard to get right, so I fully
expect other people to disagree with the way I've orgainzed
them :)

If you feel like squashing a bunch of commits together will
help you during review, then I'll definitely do that.

> "features" is fairly generic for something so specific, but I'm not sure
> I have other great suggestions for a "domain capabilities" section that
> has path, domain, machine, arch, vcpu, os, and devices already. It is a
> cpu interrupt controller - so maybe it's an "interrupt" device.

In the domain XML, the <gic> element will be a child of the
<features> element, so this name seemed like a natural choice.

The documentation[1] claims

  The available features can be found by asking for the
  capabilities XML

so it will have to be updated, because in this case the
information would be in the *domain* capabilities and not in
the *host* capabilities. At least the name of the containing
element will be the same.

> When the XML is created what is it going to look like?
> 
>  <features>
>    <gic supported='yes'/>
>      <enum name='version'>
>        <value>2</value>
>        <value>3</value>
>      </enum>
>    </gic>
>  </features>

Yes, it's going to look exactly like that. As you mentioned
later on, the documentation will have to contain examples.

> Is putting it after "<devices>" a back compat thing? I guess I would
> think it was more logical after the <arch> or even more radical as part
> of it:
> 
>   <arch gic_version='%s' gic_emulated='%s' git_kernel='%s'>armv7l</arch>

Users should not be relying on the order of elements anyway,
so if we want it to appear right after <arch> I guess there's
nothing stopping us from doing so.

Merging this into <arch> would not work, because you have to
report information about more than a single version...

As for the other attributes, the reason why this is in domain
capabilities in the first place is because that way the user
doesn't need to worry about the difference between 'kernel'
and 'emulated': in the capabilities for a kvm domain we will
only report the GIC versions that are implemented in kernel,
whereas for a qemu domain we will only report those that can
be emulated. The user only needs to look at the XML and pick
one of the versions listed.

> Additionally, docs/formatdomaincaps.html.in will need an update to
> describe this...

Absolutely.

> And then there's virsh.pod - not sure if it needs an update...

Don't think so.

Cheers.


[1] https://libvirt.org/formatdomain.html#elementsFeatures
-- 
Andrea Bolognani
Software Engineer - Virtualization Team