139a18158SMarkus Armbruster# -*- Mode: Python -*- 239a18158SMarkus Armbruster# 339a18158SMarkus Armbruster# QAPI/QMP introspection 439a18158SMarkus Armbruster# 539a18158SMarkus Armbruster# Copyright (C) 2015 Red Hat, Inc. 639a18158SMarkus Armbruster# 739a18158SMarkus Armbruster# Authors: 839a18158SMarkus Armbruster# Markus Armbruster <armbru@redhat.com> 939a18158SMarkus Armbruster# 1039a18158SMarkus Armbruster# This work is licensed under the terms of the GNU GPL, version 2 or later. 1139a18158SMarkus Armbruster# See the COPYING file in the top-level directory. 1239a18158SMarkus Armbruster 1339a18158SMarkus Armbruster## 145072f7b3SMarc-André Lureau# @query-qmp-schema: 1539a18158SMarkus Armbruster# 1639a18158SMarkus Armbruster# Command query-qmp-schema exposes the QMP wire ABI as an array of 1739a18158SMarkus Armbruster# SchemaInfo. This lets QMP clients figure out what commands and 1839a18158SMarkus Armbruster# events are available in this QEMU, and their parameters and results. 1939a18158SMarkus Armbruster# 2039a18158SMarkus Armbruster# However, the SchemaInfo can't reflect all the rules and restrictions 2139a18158SMarkus Armbruster# that apply to QMP. It's interface introspection (figuring out 2239a18158SMarkus Armbruster# what's there), not interface specification. The specification is in 2339a18158SMarkus Armbruster# the QAPI schema. 2439a18158SMarkus Armbruster# 2539a65e2cSEric Blake# Furthermore, while we strive to keep the QMP wire format 2639a65e2cSEric Blake# backwards-compatible across qemu versions, the introspection output 2739a65e2cSEric Blake# is not guaranteed to have the same stability. For example, one 2839a65e2cSEric Blake# version of qemu may list an object member as an optional 2939a65e2cSEric Blake# non-variant, while another lists the same member only through the 3039a65e2cSEric Blake# object's variants; or the type of a member may change from a generic 3139a65e2cSEric Blake# string into a specific enum or from one specific type into an 3239a65e2cSEric Blake# alternate that includes the original type alongside something else. 3339a65e2cSEric Blake# 3439a18158SMarkus Armbruster# Returns: array of @SchemaInfo, where each element describes an 3539a18158SMarkus Armbruster# entity in the ABI: command, event, type, ... 3639a18158SMarkus Armbruster# 37f5455044SEric Blake# The order of the various SchemaInfo is unspecified; however, all 38f5455044SEric Blake# names are guaranteed to be unique (no name will be duplicated with 39f5455044SEric Blake# different meta-types). 40f5455044SEric Blake# 4139a18158SMarkus Armbruster# Note: the QAPI schema is also used to help define *internal* 4239a18158SMarkus Armbruster# interfaces, by defining QAPI types. These are not part of the QMP 4339a18158SMarkus Armbruster# wire ABI, and therefore not returned by this command. 4439a18158SMarkus Armbruster# 4539a18158SMarkus Armbruster# Since: 2.5 4639a18158SMarkus Armbruster## 4739a18158SMarkus Armbruster{ 'command': 'query-qmp-schema', 4839a18158SMarkus Armbruster 'returns': [ 'SchemaInfo' ], 4939a18158SMarkus Armbruster 'gen': false } # just to simplify qmp_query_json() 5039a18158SMarkus Armbruster 5139a18158SMarkus Armbruster## 525072f7b3SMarc-André Lureau# @SchemaMetaType: 5339a18158SMarkus Armbruster# 5439a18158SMarkus Armbruster# This is a @SchemaInfo's meta type, i.e. the kind of entity it 5539a18158SMarkus Armbruster# describes. 5639a18158SMarkus Armbruster# 5739a18158SMarkus Armbruster# @builtin: a predefined type such as 'int' or 'bool'. 5839a18158SMarkus Armbruster# 5939a18158SMarkus Armbruster# @enum: an enumeration type 6039a18158SMarkus Armbruster# 6139a18158SMarkus Armbruster# @array: an array type 6239a18158SMarkus Armbruster# 6339a18158SMarkus Armbruster# @object: an object type (struct or union) 6439a18158SMarkus Armbruster# 6539a18158SMarkus Armbruster# @alternate: an alternate type 6639a18158SMarkus Armbruster# 6739a18158SMarkus Armbruster# @command: a QMP command 6839a18158SMarkus Armbruster# 6939a18158SMarkus Armbruster# @event: a QMP event 7039a18158SMarkus Armbruster# 7139a18158SMarkus Armbruster# Since: 2.5 7239a18158SMarkus Armbruster## 7339a18158SMarkus Armbruster{ 'enum': 'SchemaMetaType', 7439a18158SMarkus Armbruster 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate', 7539a18158SMarkus Armbruster 'command', 'event' ] } 7639a18158SMarkus Armbruster 7739a18158SMarkus Armbruster## 785072f7b3SMarc-André Lureau# @SchemaInfo: 7939a18158SMarkus Armbruster# 8039a18158SMarkus Armbruster# @name: the entity's name, inherited from @base. 815807ff88SMarc-André Lureau# The SchemaInfo is always referenced by this name. 821a9a507bSMarkus Armbruster# Commands and events have the name defined in the QAPI schema. 831a9a507bSMarkus Armbruster# Unlike command and event names, type names are not part of 841a9a507bSMarkus Armbruster# the wire ABI. Consequently, type names are meaningless 85f5455044SEric Blake# strings here, although they are still guaranteed unique 86f5455044SEric Blake# regardless of @meta-type. 8739a18158SMarkus Armbruster# 8839a18158SMarkus Armbruster# @meta-type: the entity's meta type, inherited from @base. 8939a18158SMarkus Armbruster# 9039a18158SMarkus Armbruster# Additional members depend on the value of @meta-type. 9139a18158SMarkus Armbruster# 9239a18158SMarkus Armbruster# Since: 2.5 9339a18158SMarkus Armbruster## 9439a18158SMarkus Armbruster{ 'union': 'SchemaInfo', 953666a97fSEric Blake 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' }, 9639a18158SMarkus Armbruster 'discriminator': 'meta-type', 9739a18158SMarkus Armbruster 'data': { 9839a18158SMarkus Armbruster 'builtin': 'SchemaInfoBuiltin', 9939a18158SMarkus Armbruster 'enum': 'SchemaInfoEnum', 10039a18158SMarkus Armbruster 'array': 'SchemaInfoArray', 10139a18158SMarkus Armbruster 'object': 'SchemaInfoObject', 10239a18158SMarkus Armbruster 'alternate': 'SchemaInfoAlternate', 10339a18158SMarkus Armbruster 'command': 'SchemaInfoCommand', 10439a18158SMarkus Armbruster 'event': 'SchemaInfoEvent' } } 10539a18158SMarkus Armbruster 10639a18158SMarkus Armbruster## 1075072f7b3SMarc-André Lureau# @SchemaInfoBuiltin: 10839a18158SMarkus Armbruster# 10939a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'builtin'. 11039a18158SMarkus Armbruster# 11139a18158SMarkus Armbruster# @json-type: the JSON type used for this type on the wire. 11239a18158SMarkus Armbruster# 11339a18158SMarkus Armbruster# Since: 2.5 11439a18158SMarkus Armbruster## 11539a18158SMarkus Armbruster{ 'struct': 'SchemaInfoBuiltin', 11639a18158SMarkus Armbruster 'data': { 'json-type': 'JSONType' } } 11739a18158SMarkus Armbruster 11839a18158SMarkus Armbruster## 1195072f7b3SMarc-André Lureau# @JSONType: 12039a18158SMarkus Armbruster# 12139a18158SMarkus Armbruster# The four primitive and two structured types according to RFC 7159 12239a18158SMarkus Armbruster# section 1, plus 'int' (split off 'number'), plus the obvious top 12339a18158SMarkus Armbruster# type 'value'. 12439a18158SMarkus Armbruster# 12539a18158SMarkus Armbruster# Since: 2.5 12639a18158SMarkus Armbruster## 12739a18158SMarkus Armbruster{ 'enum': 'JSONType', 12839a18158SMarkus Armbruster 'data': [ 'string', 'number', 'int', 'boolean', 'null', 12939a18158SMarkus Armbruster 'object', 'array', 'value' ] } 13039a18158SMarkus Armbruster 13139a18158SMarkus Armbruster## 1325072f7b3SMarc-André Lureau# @SchemaInfoEnum: 13339a18158SMarkus Armbruster# 13439a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'enum'. 13539a18158SMarkus Armbruster# 136f5455044SEric Blake# @values: the enumeration type's values, in no particular order. 13739a18158SMarkus Armbruster# 13839a18158SMarkus Armbruster# Values of this type are JSON string on the wire. 13939a18158SMarkus Armbruster# 14039a18158SMarkus Armbruster# Since: 2.5 14139a18158SMarkus Armbruster## 14239a18158SMarkus Armbruster{ 'struct': 'SchemaInfoEnum', 14339a18158SMarkus Armbruster 'data': { 'values': ['str'] } } 14439a18158SMarkus Armbruster 14539a18158SMarkus Armbruster## 1465072f7b3SMarc-André Lureau# @SchemaInfoArray: 14739a18158SMarkus Armbruster# 14839a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'array'. 14939a18158SMarkus Armbruster# 15039a18158SMarkus Armbruster# @element-type: the array type's element type. 15139a18158SMarkus Armbruster# 15239a18158SMarkus Armbruster# Values of this type are JSON array on the wire. 15339a18158SMarkus Armbruster# 15439a18158SMarkus Armbruster# Since: 2.5 15539a18158SMarkus Armbruster## 15639a18158SMarkus Armbruster{ 'struct': 'SchemaInfoArray', 15739a18158SMarkus Armbruster 'data': { 'element-type': 'str' } } 15839a18158SMarkus Armbruster 15939a18158SMarkus Armbruster## 1605072f7b3SMarc-André Lureau# @SchemaInfoObject: 16139a18158SMarkus Armbruster# 16239a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'object'. 16339a18158SMarkus Armbruster# 164f5455044SEric Blake# @members: the object type's (non-variant) members, in no particular order. 16539a18158SMarkus Armbruster# 166*1d8bda12SMarkus Armbruster# @tag: the name of the member serving as type tag. 16739a18158SMarkus Armbruster# An element of @members with this name must exist. 16839a18158SMarkus Armbruster# 169*1d8bda12SMarkus Armbruster# @variants: variant members, i.e. additional members that 17039a18158SMarkus Armbruster# depend on the type tag's value. Present exactly when 171f5455044SEric Blake# @tag is present. The variants are in no particular order, 172f5455044SEric Blake# and may even differ from the order of the values of the 173f5455044SEric Blake# enum type of the @tag. 17439a18158SMarkus Armbruster# 17539a18158SMarkus Armbruster# Values of this type are JSON object on the wire. 17639a18158SMarkus Armbruster# 17739a18158SMarkus Armbruster# Since: 2.5 17839a18158SMarkus Armbruster## 17939a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObject', 18039a18158SMarkus Armbruster 'data': { 'members': [ 'SchemaInfoObjectMember' ], 18139a18158SMarkus Armbruster '*tag': 'str', 18239a18158SMarkus Armbruster '*variants': [ 'SchemaInfoObjectVariant' ] } } 18339a18158SMarkus Armbruster 18439a18158SMarkus Armbruster## 1855072f7b3SMarc-André Lureau# @SchemaInfoObjectMember: 18639a18158SMarkus Armbruster# 18739a18158SMarkus Armbruster# An object member. 18839a18158SMarkus Armbruster# 18939a18158SMarkus Armbruster# @name: the member's name, as defined in the QAPI schema. 19039a18158SMarkus Armbruster# 19139a18158SMarkus Armbruster# @type: the name of the member's type. 19239a18158SMarkus Armbruster# 193*1d8bda12SMarkus Armbruster# @default: default when used as command parameter. 19439a18158SMarkus Armbruster# If absent, the parameter is mandatory. 19539a18158SMarkus Armbruster# If present, the value must be null. The parameter is 19639a18158SMarkus Armbruster# optional, and behavior when it's missing is not specified 19739a18158SMarkus Armbruster# here. 19839a18158SMarkus Armbruster# Future extension: if present and non-null, the parameter 19939a18158SMarkus Armbruster# is optional, and defaults to this value. 20039a18158SMarkus Armbruster# 20139a18158SMarkus Armbruster# Since: 2.5 20239a18158SMarkus Armbruster## 20339a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObjectMember', 20439a18158SMarkus Armbruster 'data': { 'name': 'str', 'type': 'str', '*default': 'any' } } 20539a18158SMarkus Armbruster# @default's type must be null or match @type 20639a18158SMarkus Armbruster 20739a18158SMarkus Armbruster## 2085072f7b3SMarc-André Lureau# @SchemaInfoObjectVariant: 20939a18158SMarkus Armbruster# 21039a18158SMarkus Armbruster# The variant members for a value of the type tag. 21139a18158SMarkus Armbruster# 21239a18158SMarkus Armbruster# @case: a value of the type tag. 21339a18158SMarkus Armbruster# 21439a18158SMarkus Armbruster# @type: the name of the object type that provides the variant members 21539a18158SMarkus Armbruster# when the type tag has value @case. 21639a18158SMarkus Armbruster# 21739a18158SMarkus Armbruster# Since: 2.5 21839a18158SMarkus Armbruster## 21939a18158SMarkus Armbruster{ 'struct': 'SchemaInfoObjectVariant', 22039a18158SMarkus Armbruster 'data': { 'case': 'str', 'type': 'str' } } 22139a18158SMarkus Armbruster 22239a18158SMarkus Armbruster## 2235072f7b3SMarc-André Lureau# @SchemaInfoAlternate: 22439a18158SMarkus Armbruster# 22539a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'alternate'. 22639a18158SMarkus Armbruster# 227f5455044SEric Blake# @members: the alternate type's members, in no particular order. 22839a18158SMarkus Armbruster# The members' wire encoding is distinct, see 22939a18158SMarkus Armbruster# docs/qapi-code-gen.txt section Alternate types. 23039a18158SMarkus Armbruster# 23139a18158SMarkus Armbruster# On the wire, this can be any of the members. 23239a18158SMarkus Armbruster# 23339a18158SMarkus Armbruster# Since: 2.5 23439a18158SMarkus Armbruster## 23539a18158SMarkus Armbruster{ 'struct': 'SchemaInfoAlternate', 23639a18158SMarkus Armbruster 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } 23739a18158SMarkus Armbruster 23839a18158SMarkus Armbruster## 2395072f7b3SMarc-André Lureau# @SchemaInfoAlternateMember: 24039a18158SMarkus Armbruster# 24139a18158SMarkus Armbruster# An alternate member. 24239a18158SMarkus Armbruster# 24339a18158SMarkus Armbruster# @type: the name of the member's type. 24439a18158SMarkus Armbruster# 24539a18158SMarkus Armbruster# Since: 2.5 24639a18158SMarkus Armbruster## 24739a18158SMarkus Armbruster{ 'struct': 'SchemaInfoAlternateMember', 24839a18158SMarkus Armbruster 'data': { 'type': 'str' } } 24939a18158SMarkus Armbruster 25039a18158SMarkus Armbruster## 2515072f7b3SMarc-André Lureau# @SchemaInfoCommand: 25239a18158SMarkus Armbruster# 25339a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'command'. 25439a18158SMarkus Armbruster# 25539a18158SMarkus Armbruster# @arg-type: the name of the object type that provides the command's 25639a18158SMarkus Armbruster# parameters. 25739a18158SMarkus Armbruster# 25839a18158SMarkus Armbruster# @ret-type: the name of the command's result type. 25939a18158SMarkus Armbruster# 260e22da431SMarc-André Lureau# TODO: @success-response (currently irrelevant, because it's QGA, not QMP) 26139a18158SMarkus Armbruster# 26239a18158SMarkus Armbruster# Since: 2.5 26339a18158SMarkus Armbruster## 26439a18158SMarkus Armbruster{ 'struct': 'SchemaInfoCommand', 26539a18158SMarkus Armbruster 'data': { 'arg-type': 'str', 'ret-type': 'str' } } 26639a18158SMarkus Armbruster 26739a18158SMarkus Armbruster## 2685072f7b3SMarc-André Lureau# @SchemaInfoEvent: 26939a18158SMarkus Armbruster# 27039a18158SMarkus Armbruster# Additional SchemaInfo members for meta-type 'event'. 27139a18158SMarkus Armbruster# 27239a18158SMarkus Armbruster# @arg-type: the name of the object type that provides the event's 27339a18158SMarkus Armbruster# parameters. 27439a18158SMarkus Armbruster# 27539a18158SMarkus Armbruster# Since: 2.5 27639a18158SMarkus Armbruster## 27739a18158SMarkus Armbruster{ 'struct': 'SchemaInfoEvent', 27839a18158SMarkus Armbruster 'data': { 'arg-type': 'str' } } 279