QMP Introspection

Short description

qemu 2.5 adds a new 'query-qmp-schema' command that allows clients to introspect what ABI elements are accepted by the QMP parser. This can be used to probe whether a given QMP feature exists in a particular qemu build, even where that build may be a downstream distro that has backported features across version numbers. Note that introspection is limited to syntax and does not tell everything about QMP; developers should still read the documentation to learn semantic constraints.

Feature authors / maintainers

Markus Armbruster
Eric Blake

Scope

[X] Changes to QEMU

[ ] Changes to guest agent

[ ] Changes to firmware (seabios, vgabios, pxe roms, etc.

[X] Affects all archs

[ ] Affects specific archs: x86, ppc, arm, s390, etc.

[ ] Affects all guests

[ ] Affects specific guests: Linux, Windows, etc.

Detailed description

The QAPI code generator underwent a number of improvements for better maintenance, including testsuite improvements to ensure backwards compatibility. With those improvements, we were finally able to expose a programmatic description of the QAPI .json files in a format suitable for machine parsing, via the new 'query-qmp-schema' QMP command.

The command returns an array of JSON objects, where each object describes a QMP entity (command, event, or type, where types include objects, builtins, arrays, and enums). Using this information, a caller can learn about the name of every JSON key accepted by a given command, and the corresponding type that must be used for the accompanying value. There is about 70k of information returned.

Since this is introspection, it follows that the 'query-qmp-schema' command itself can be introspected among the output, to gain a fuller picture of what sort of information is present. Here are some snippets of the output:

   {"arg-type": "15", "meta-type": "command", "name": "query-qmp-schema", "ret-type": "[126]"},
   {"element-type": "126", "meta-type": "array", "name": "[126]"},
   {"members": [{"name": "name", "type": "str"}, {"name": "meta-type", "type": "205"}], "meta-type": "object", "name": "126", "tag": "meta-type", "variants": [{"case": "builtin", "type": "206"}, {"case": "enum", "type": "207"}, {"case": "array", "type": "208"}, {"case": "object", "type": "209"}, "case": "alternate", "type": "210"}, {"case": "command", "type": "211"}, {"case": "event", "type": "212"}]},
   {"members": [{"name": "json-type", "type": "271"}], "meta-type": "object", "name": "206"},
   {"meta-type": "enum", "name": "271", "values": ["string", "number", "int", "boolean", "null", "object", "array", "value"]},

Benefits to QEMU and upper layers

Cleaner QAPI generator allows for easier extensions and less cruft
libvirt and other clients now have a more fine-grained way to learn about additions of optional parameters in QMP commands

Added / removed / deprecated / changed settings exposed to higher layers or users

New 'query-qmp-schema' QMP command

Update plans

QAPI cleanups still ongoing; for example, 'netdev_add' is not yet fully introspectible
May be extended in 2.6 to add a QGA 'guest-schema' command for introspecting qemu-guest-agent commands
Might be worth adding filtering to retrieve just a subset of the schema.

How to test the feature

Start a QMP connection and issue the 'query-qmp-schema' command.

Can be done under libvirt with:

virsh qemu-monitor-command $guest --pretty '{"execute":"query-qmp-schema"}'

Libvirt still needs patches to make use of the introspection data when determining qemu features.

List of commits

Lots of commits involved, but 39a181581650f4d50f4445bc6276d9716cece050 added the actual QMP command.

Dependencies

Upstream in qemu 2.5

Supporting documentation

Markus gave a presentation on the changes at KVM Forum 2015