View source for Features/QMP/Introspection

= 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 [http://events.linuxfoundation.org/sites/events/files/slides/armbru-qemu-introspection.pdf presentation] on the changes at KVM Forum 2015

[[Category:Completed feature pages]]