[Qemu-devel] Libvirt debug API

[Chris Lalancette <clalance@redhat.com>]

Hello,
     In response to a lot of the talk of qemud lately on qemu-devel, the
libvirt community would like to put forward a proposal to help enable
debug/advanced options when using various hypervisors.  The goals of
this API are:

1)  To enable more rapid access to hypervisor features before proper
libvirt API's are designed around them.
2)  To facilitate debugging and access to advanced features that may
not fit into the normal libvirt world-view.

Caveats:
1)  Unlike other libvirt API's, this one will explicitly *not* be
guaranteed ABI/API compatible between libvirt updates.
2)  Again unlike other libvirt API's, access and configuration of
the debug section of a domain will be highly hypervisor dependent.
3)  Application developers will be strongly discouraged from using
this API because of the above 2 issues.  To help in this, the
API's will be in a separate library that developers will explicitly
have to link to, and it will have a different (but largely compatible)
wire protocol.
4)  We don't expect this API to solve all of the issues brought up
during the qemud discussion.  Our initial goal is just to give
ready access of the qemu command-line and monitor to developers.

With that being said, our initial proposal follows.  We expect this
to evolve over time as we get more feedback, but we think this
proposal addresses at least 2 of the major pain points qemu developers
have while trying to use libvirt.

The initial debug XML for qemu would be:

<domain type='kvm'>
  <name>myguest</name>
  ...
  <debug>
    <monitorpassthrough/>
    <commandline>
      <extra>qemu arguments</extra>
      <alter option="optname">
        <rename>newname</rename>
        <match>REGEXP</match>
        <modify>foo=on</modify>
        <extra>-bar</extra>
      </alter>
    </commandline>
  </debug>
</domain>

Raw access to the qemu monitor will be disabled by default; the
<monitorpassthrough/> tag enables the ability to send QMP (or
text, if you are using older qemu) messages straight through to the
monitor.  To do this there will be an additional API entry point
named virDomainDebugCommand() which takes an arbitrary string
and passes it to the monitor, and returns an arbitrary string as
a result.  Thus you could pass in either "info cpus" if using the
text monitor or '{ "execute": "query-cpus" }' if using QMP.

The <commandline><extra> tag does exactly what you might expect; appends
the exact string to the qemu command-line.

The <alter> tag gets more interesting.  The idea is that <alter> would
allow you to modify the libvirt-generated qemu command-line in arbitrary
ways.  How this would work is probably best explained with some examples:

<commandline>
  <alter option="-net">
    <rename>-netdev</rename>
  </alter>
</commandline>

In this example, all options named -net on the qemu command-line are
renamed to -netdev.

<commandline>
  <alter option="-net">
    <extra>-usbtablet</extra>
  </alter>
</commandline>

In this example, if (and only if) a -net option is seen, then -usbtablet is
appended to the qemu command-line.

<commandline>
  <alter option="-net">
    <match>\(.*name=hostnet0.*\)</match>
    <modify>\1,tap</modify>
  </alter>
</commandline>

This gets more complicated (but also more powerful).  In this case, any -net
option where the argument *also* matches the regex in <match> will be modified to append
the ",tap" string.  Think of it as a sed expression, s/match/modify/, against the
argument to the -net option, and it makes more sense.  

We are hoping to refine this proposal based on feedback, so comments and criticisms
are welcome!

-- 
Chris Lalancette