139a18158SMarkus Armbruster# -*- Mode: Python -*- 2f7160f32SAndrea Bolognani# vim: filetype=python 339a18158SMarkus Armbruster# 439a18158SMarkus Armbruster# Copyright (C) 2015 Red Hat, Inc. 539a18158SMarkus Armbruster# 639a18158SMarkus Armbruster# Authors: 739a18158SMarkus Armbruster# Markus Armbruster <armbru@redhat.com> 839a18158SMarkus Armbruster# 939a18158SMarkus Armbruster# This work is licensed under the terms of the GNU GPL, version 2 or later. 1039a18158SMarkus Armbruster# See the COPYING file in the top-level directory. 1139a18158SMarkus Armbruster 1239a18158SMarkus Armbruster## 13a885cd39SMarkus Armbruster# = QMP introspection 14a885cd39SMarkus Armbruster## 15a885cd39SMarkus Armbruster 16a885cd39SMarkus Armbruster## 175072f7b3SMarc-André Lureau# @query-qmp-schema: 1839a18158SMarkus Armbruster# 1939a18158SMarkus Armbruster# Command query-qmp-schema exposes the QMP wire ABI as an array of 2039a18158SMarkus Armbruster# SchemaInfo. This lets QMP clients figure out what commands and 2139a18158SMarkus Armbruster# events are available in this QEMU, and their parameters and results. 2239a18158SMarkus Armbruster# 2339a18158SMarkus Armbruster# However, the SchemaInfo can't reflect all the rules and restrictions 2439a18158SMarkus Armbruster# that apply to QMP. It's interface introspection (figuring out 2539a18158SMarkus Armbruster# what's there), not interface specification. The specification is in 2639a18158SMarkus Armbruster# the QAPI schema. 2739a18158SMarkus Armbruster# 2839a65e2cSEric Blake# Furthermore, while we strive to keep the QMP wire format 2939a65e2cSEric Blake# backwards-compatible across qemu versions, the introspection output 3039a65e2cSEric Blake# is not guaranteed to have the same stability. For example, one 3139a65e2cSEric Blake# version of qemu may list an object member as an optional 3239a65e2cSEric Blake# non-variant, while another lists the same member only through the 3339a65e2cSEric Blake# object's variants; or the type of a member may change from a generic 3439a65e2cSEric Blake# string into a specific enum or from one specific type into an 3539a65e2cSEric Blake# alternate that includes the original type alongside something else. 3639a65e2cSEric Blake# 3739a18158SMarkus Armbruster# Returns: array of @SchemaInfo, where each element describes an 3839a18158SMarkus Armbruster# entity in the ABI: command, event, type, ... 3939a18158SMarkus Armbruster# 40f5455044SEric Blake# The order of the various SchemaInfo is unspecified; however, all 41a937b6aaSMarkus Armbruster# names are guaranteed to be unique (no name will be duplicated 42a937b6aaSMarkus Armbruster# with different meta-types). 43f5455044SEric Blake# 4439a18158SMarkus Armbruster# Note: the QAPI schema is also used to help define *internal* 45a937b6aaSMarkus Armbruster# interfaces, by defining QAPI types. These are not part of the 46a937b6aaSMarkus Armbruster# QMP wire ABI, and therefore not returned by this command. 4739a18158SMarkus Armbruster# 4839a18158SMarkus Armbruster# Since: 2.5 4939a18158SMarkus Armbruster## 5039a18158SMarkus Armbruster{ 'command': 'query-qmp-schema', 5139a18158SMarkus Armbruster 'returns': [ 'SchemaInfo' ], 52624fa80cSMarkus Armbruster 'allow-preconfig': true } 5339a18158SMarkus Armbruster 5439a18158SMarkus Armbruster## 555072f7b3SMarc-André Lureau# @SchemaMetaType: 5639a18158SMarkus Armbruster# 5739a18158SMarkus Armbruster# This is a @SchemaInfo's meta type, i.e. the kind of entity it 5839a18158SMarkus Armbruster# describes. 5939a18158SMarkus Armbruster# 6039a18158SMarkus Armbruster# @builtin: a predefined type such as 'int' or 'bool'. 6139a18158SMarkus Armbruster# 6239a18158SMarkus Armbruster# @enum: an enumeration type 6339a18158SMarkus Armbruster# 6439a18158SMarkus Armbruster# @array: an array type 6539a18158SMarkus Armbruster# 6639a18158SMarkus Armbruster# @object: an object type (struct or union) 6739a18158SMarkus Armbruster# 6839a18158SMarkus Armbruster# @alternate: an alternate type 6939a18158SMarkus Armbruster# 7039a18158SMarkus Armbruster# @command: a QMP command 7139a18158SMarkus Armbruster# 7239a18158SMarkus Armbruster# @event: a QMP event 7339a18158SMarkus Armbruster# 7439a18158SMarkus Armbruster# Since: 2.5 7539a18158SMarkus Armbruster## 7639a18158SMarkus Armbruster{ 'enum': 'SchemaMetaType', 7739a18158SMarkus Armbruster 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate', 7839a18158SMarkus Armbruster 'command', 'event' ] } 7939a18158SMarkus Armbruster 8039a18158SMarkus Armbruster## 815072f7b3SMarc-André Lureau# @SchemaInfo: 8239a18158SMarkus Armbruster# 83a937b6aaSMarkus Armbruster# @name: the entity's name, inherited from @base. The SchemaInfo is 84a937b6aaSMarkus Armbruster# always referenced by this name. Commands and events have the 85a937b6aaSMarkus Armbruster# name defined in the QAPI schema. Unlike command and event 86a937b6aaSMarkus Armbruster# names, type names are not part of the wire ABI. Consequently, 87a937b6aaSMarkus Armbruster# type names are meaningless strings here, although they are still 88a937b6aaSMarkus Armbruster# guaranteed unique regardless of @meta-type. 8939a18158SMarkus Armbruster# 9039a18158SMarkus Armbruster# @meta-type: the entity's meta type, inherited from @base. 9139a18158SMarkus Armbruster# 92013b4efcSMarkus Armbruster# @features: names of features associated with the entity, in no 93a937b6aaSMarkus Armbruster# particular order. (since 4.1 for object types, 4.2 for 94a937b6aaSMarkus Armbruster# commands, 5.0 for the rest) 95013b4efcSMarkus Armbruster# 9639a18158SMarkus Armbruster# Since: 2.5 9739a18158SMarkus Armbruster## 9839a18158SMarkus Armbruster{ 'union': 'SchemaInfo', 99013b4efcSMarkus Armbruster 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType', 100013b4efcSMarkus Armbruster '*features': [ 'str' ] }, 10139a18158SMarkus Armbruster 'discriminator': 'meta-type', 10239a18158SMarkus Armbruster 'data': { 10339a18158SMarkus Armbruster 'builtin': 'SchemaInfoBuiltin', 10439a18158SMarkus Armbruster 'enum': 'SchemaInfoEnum', 10539a18158SMarkus Armbruster 'array': 'SchemaInfoArray', 10639a18158SMarkus Armbruster 'object': 'SchemaInfoObject', 10739a18158SMarkus Armbruster 'alternate': 'SchemaInfoAlternate', 10839a18158SMarkus Armbruster 'command': 'SchemaInfoCommand', 10939a18158SMarkus Armbruster 'event': 'SchemaInfoEvent' } } 11039a18158SMarkus Armbruster 11139a18158SMarkus Armbruster## 1125072f7b3SMarc-André Lureau# @SchemaInfoBuiltin: 11339a18158SMarkus Armbruster# 11439a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'builtin'. 11539a18158SMarkus Armbruster# 11639a18158SMarkus Armbruster# @json-type: the JSON type used for this type on the wire. 11739a18158SMarkus Armbruster# 11839a18158SMarkus Armbruster# Since: 2.5 11939a18158SMarkus Armbruster## 12039a18158SMarkus Armbruster{ 'struct': 'SchemaInfoBuiltin', 12139a18158SMarkus Armbruster 'data': { 'json-type': 'JSONType' } } 12239a18158SMarkus Armbruster 12339a18158SMarkus Armbruster## 1245072f7b3SMarc-André Lureau# @JSONType: 12539a18158SMarkus Armbruster# 12637aded92SMarkus Armbruster# The four primitive and two structured types according to RFC 8259 12739a18158SMarkus Armbruster# section 1, plus 'int' (split off 'number'), plus the obvious top 12839a18158SMarkus Armbruster# type 'value'. 12939a18158SMarkus Armbruster# 13039a18158SMarkus Armbruster# Since: 2.5 13139a18158SMarkus Armbruster## 13239a18158SMarkus Armbruster{ 'enum': 'JSONType', 13339a18158SMarkus Armbruster 'data': [ 'string', 'number', 'int', 'boolean', 'null', 13439a18158SMarkus Armbruster 'object', 'array', 'value' ] } 13539a18158SMarkus Armbruster 13639a18158SMarkus Armbruster## 1375072f7b3SMarc-André Lureau# @SchemaInfoEnum: 13839a18158SMarkus Armbruster# 13939a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'enum'. 14039a18158SMarkus Armbruster# 141a937b6aaSMarkus Armbruster# @members: the enum type's members, in no particular order (since 142a937b6aaSMarkus Armbruster# 6.2). 14375ecee72SMarkus Armbruster# 144a937b6aaSMarkus Armbruster# @values: the enumeration type's member names, in no particular 145a937b6aaSMarkus Armbruster# order. Redundant with @members. Just for backward 146a937b6aaSMarkus Armbruster# compatibility. 14775ecee72SMarkus Armbruster# 14875ecee72SMarkus Armbruster# Features: 149a937b6aaSMarkus Armbruster# 15075ecee72SMarkus Armbruster# @deprecated: Member @values is deprecated. Use @members instead. 15139a18158SMarkus Armbruster# 15239a18158SMarkus Armbruster# Values of this type are JSON string on the wire. 15339a18158SMarkus Armbruster# 15439a18158SMarkus Armbruster# Since: 2.5 15539a18158SMarkus Armbruster## 15639a18158SMarkus Armbruster{ 'struct': 'SchemaInfoEnum', 15775ecee72SMarkus Armbruster 'data': { 'members': [ 'SchemaInfoEnumMember' ], 15875ecee72SMarkus Armbruster 'values': { 'type': [ 'str' ], 15975ecee72SMarkus Armbruster 'features': [ 'deprecated' ] } } } 16075ecee72SMarkus Armbruster 16175ecee72SMarkus Armbruster## 16275ecee72SMarkus Armbruster# @SchemaInfoEnumMember: 16375ecee72SMarkus Armbruster# 16475ecee72SMarkus Armbruster# An object member. 16575ecee72SMarkus Armbruster# 16675ecee72SMarkus Armbruster# @name: the member's name, as defined in the QAPI schema. 16775ecee72SMarkus Armbruster# 168b6c18755SMarkus Armbruster# @features: names of features associated with the member, in no 169b6c18755SMarkus Armbruster# particular order. 170b6c18755SMarkus Armbruster# 17175ecee72SMarkus Armbruster# Since: 6.2 17275ecee72SMarkus Armbruster## 17375ecee72SMarkus Armbruster{ 'struct': 'SchemaInfoEnumMember', 174b6c18755SMarkus Armbruster 'data': { 'name': 'str', '*features': [ 'str' ] } } 17539a18158SMarkus Armbruster 17639a18158SMarkus Armbruster## 1775072f7b3SMarc-André Lureau# @SchemaInfoArray: 17839a18158SMarkus Armbruster# 17939a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'array'. 18039a18158SMarkus Armbruster# 18139a18158SMarkus Armbruster# @element-type: the array type's element type. 18239a18158SMarkus Armbruster# 18339a18158SMarkus Armbruster# Values of this type are JSON array on the wire. 18439a18158SMarkus Armbruster# 18539a18158SMarkus Armbruster# Since: 2.5 18639a18158SMarkus Armbruster## 18739a18158SMarkus Armbruster{ 'struct': 'SchemaInfoArray', 18839a18158SMarkus Armbruster 'data': { 'element-type': 'str' } } 18939a18158SMarkus Armbruster 19039a18158SMarkus Armbruster## 1915072f7b3SMarc-André Lureau# @SchemaInfoObject: 19239a18158SMarkus Armbruster# 19339a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'object'. 19439a18158SMarkus Armbruster# 195a937b6aaSMarkus Armbruster# @members: the object type's (non-variant) members, in no particular 196a937b6aaSMarkus Armbruster# order. 19739a18158SMarkus Armbruster# 198a937b6aaSMarkus Armbruster# @tag: the name of the member serving as type tag. An element of 199a937b6aaSMarkus Armbruster# @members with this name must exist. 20039a18158SMarkus Armbruster# 201a937b6aaSMarkus Armbruster# @variants: variant members, i.e. additional members that depend on 202a937b6aaSMarkus Armbruster# the type tag's value. Present exactly when @tag is present. 203a937b6aaSMarkus Armbruster# The variants are in no particular order, and may even differ 204a937b6aaSMarkus Armbruster# from the order of the values of the enum type of the @tag. 20539a18158SMarkus Armbruster# 20639a18158SMarkus Armbruster# Values of this type are JSON object on the wire. 20739a18158SMarkus Armbruster# 20839a18158SMarkus Armbruster# Since: 2.5 20939a18158SMarkus Armbruster## 21039a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObject', 21139a18158SMarkus Armbruster 'data': { 'members': [ 'SchemaInfoObjectMember' ], 21239a18158SMarkus Armbruster '*tag': 'str', 213013b4efcSMarkus Armbruster '*variants': [ 'SchemaInfoObjectVariant' ] } } 21439a18158SMarkus Armbruster 21539a18158SMarkus Armbruster## 2165072f7b3SMarc-André Lureau# @SchemaInfoObjectMember: 21739a18158SMarkus Armbruster# 21839a18158SMarkus Armbruster# An object member. 21939a18158SMarkus Armbruster# 22039a18158SMarkus Armbruster# @name: the member's name, as defined in the QAPI schema. 22139a18158SMarkus Armbruster# 22239a18158SMarkus Armbruster# @type: the name of the member's type. 22339a18158SMarkus Armbruster# 224a937b6aaSMarkus Armbruster# @default: default when used as command parameter. If absent, the 225a937b6aaSMarkus Armbruster# parameter is mandatory. If present, the value must be null. 226a937b6aaSMarkus Armbruster# The parameter is optional, and behavior when it's missing is not 227a937b6aaSMarkus Armbruster# specified here. Future extension: if present and non-null, the 228a937b6aaSMarkus Armbruster# parameter is optional, and defaults to this value. 22939a18158SMarkus Armbruster# 23084ab0086SMarkus Armbruster# @features: names of features associated with the member, in no 23184ab0086SMarkus Armbruster# particular order. (since 5.0) 23284ab0086SMarkus Armbruster# 23339a18158SMarkus Armbruster# Since: 2.5 23439a18158SMarkus Armbruster## 23539a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObjectMember', 23684ab0086SMarkus Armbruster 'data': { 'name': 'str', 'type': 'str', '*default': 'any', 23739a18158SMarkus Armbruster# @default's type must be null or match @type 23884ab0086SMarkus Armbruster '*features': [ 'str' ] } } 23939a18158SMarkus Armbruster 24039a18158SMarkus Armbruster## 2415072f7b3SMarc-André Lureau# @SchemaInfoObjectVariant: 24239a18158SMarkus Armbruster# 24339a18158SMarkus Armbruster# The variant members for a value of the type tag. 24439a18158SMarkus Armbruster# 24539a18158SMarkus Armbruster# @case: a value of the type tag. 24639a18158SMarkus Armbruster# 24739a18158SMarkus Armbruster# @type: the name of the object type that provides the variant members 24839a18158SMarkus Armbruster# when the type tag has value @case. 24939a18158SMarkus Armbruster# 25039a18158SMarkus Armbruster# Since: 2.5 25139a18158SMarkus Armbruster## 25239a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObjectVariant', 25339a18158SMarkus Armbruster 'data': { 'case': 'str', 'type': 'str' } } 25439a18158SMarkus Armbruster 25539a18158SMarkus Armbruster## 2565072f7b3SMarc-André Lureau# @SchemaInfoAlternate: 25739a18158SMarkus Armbruster# 25839a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'alternate'. 25939a18158SMarkus Armbruster# 260a937b6aaSMarkus Armbruster# @members: the alternate type's members, in no particular order. The 2617cbdabb5SMarkus Armbruster# members' wire encoding is distinct, see 2627cbdabb5SMarkus Armbruster# :doc:`/devel/qapi-code-gen` section Alternate types. 26339a18158SMarkus Armbruster# 26439a18158SMarkus Armbruster# On the wire, this can be any of the members. 26539a18158SMarkus Armbruster# 26639a18158SMarkus Armbruster# Since: 2.5 26739a18158SMarkus Armbruster## 26839a18158SMarkus Armbruster{ 'struct': 'SchemaInfoAlternate', 26939a18158SMarkus Armbruster 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } 27039a18158SMarkus Armbruster 27139a18158SMarkus Armbruster## 2725072f7b3SMarc-André Lureau# @SchemaInfoAlternateMember: 27339a18158SMarkus Armbruster# 27439a18158SMarkus Armbruster# An alternate member. 27539a18158SMarkus Armbruster# 27639a18158SMarkus Armbruster# @type: the name of the member's type. 27739a18158SMarkus Armbruster# 27839a18158SMarkus Armbruster# Since: 2.5 27939a18158SMarkus Armbruster## 28039a18158SMarkus Armbruster{ 'struct': 'SchemaInfoAlternateMember', 28139a18158SMarkus Armbruster 'data': { 'type': 'str' } } 28239a18158SMarkus Armbruster 28339a18158SMarkus Armbruster## 2845072f7b3SMarc-André Lureau# @SchemaInfoCommand: 28539a18158SMarkus Armbruster# 28639a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'command'. 28739a18158SMarkus Armbruster# 28839a18158SMarkus Armbruster# @arg-type: the name of the object type that provides the command's 28939a18158SMarkus Armbruster# parameters. 29039a18158SMarkus Armbruster# 29139a18158SMarkus Armbruster# @ret-type: the name of the command's result type. 29239a18158SMarkus Armbruster# 29325b1ef31SMarkus Armbruster# @allow-oob: whether the command allows out-of-band execution, 29425b1ef31SMarkus Armbruster# defaults to false (Since: 2.12) 295876c6751SPeter Xu# 296a937b6aaSMarkus Armbruster# TODO: @success-response (currently irrelevant, because it's QGA, not 297a937b6aaSMarkus Armbruster# QMP) 29839a18158SMarkus Armbruster# 29939a18158SMarkus Armbruster# Since: 2.5 30039a18158SMarkus Armbruster## 30139a18158SMarkus Armbruster{ 'struct': 'SchemaInfoCommand', 302876c6751SPeter Xu 'data': { 'arg-type': 'str', 'ret-type': 'str', 303013b4efcSMarkus Armbruster '*allow-oob': 'bool' } } 30439a18158SMarkus Armbruster 30539a18158SMarkus Armbruster## 3065072f7b3SMarc-André Lureau# @SchemaInfoEvent: 30739a18158SMarkus Armbruster# 30839a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'event'. 30939a18158SMarkus Armbruster# 31039a18158SMarkus Armbruster# @arg-type: the name of the object type that provides the event's 31139a18158SMarkus Armbruster# parameters. 31239a18158SMarkus Armbruster# 31339a18158SMarkus Armbruster# Since: 2.5 31439a18158SMarkus Armbruster## 31539a18158SMarkus Armbruster{ 'struct': 'SchemaInfoEvent', 31639a18158SMarkus Armbruster 'data': { 'arg-type': 'str' } } 317