1# -*- Mode: Python -*- 2# 3# Copyright (C) 2015 Red Hat, Inc. 4# 5# Authors: 6# Markus Armbruster <armbru@redhat.com> 7# 8# This work is licensed under the terms of the GNU GPL, version 2 or later. 9# See the COPYING file in the top-level directory. 10 11## 12# = QMP introspection 13## 14 15## 16# @query-qmp-schema: 17# 18# Command query-qmp-schema exposes the QMP wire ABI as an array of 19# SchemaInfo. This lets QMP clients figure out what commands and 20# events are available in this QEMU, and their parameters and results. 21# 22# However, the SchemaInfo can't reflect all the rules and restrictions 23# that apply to QMP. It's interface introspection (figuring out 24# what's there), not interface specification. The specification is in 25# the QAPI schema. 26# 27# Furthermore, while we strive to keep the QMP wire format 28# backwards-compatible across qemu versions, the introspection output 29# is not guaranteed to have the same stability. For example, one 30# version of qemu may list an object member as an optional 31# non-variant, while another lists the same member only through the 32# object's variants; or the type of a member may change from a generic 33# string into a specific enum or from one specific type into an 34# alternate that includes the original type alongside something else. 35# 36# Returns: array of @SchemaInfo, where each element describes an 37# entity in the ABI: command, event, type, ... 38# 39# The order of the various SchemaInfo is unspecified; however, all 40# names are guaranteed to be unique (no name will be duplicated with 41# different meta-types). 42# 43# Note: the QAPI schema is also used to help define *internal* 44# interfaces, by defining QAPI types. These are not part of the QMP 45# wire ABI, and therefore not returned by this command. 46# 47# Since: 2.5 48## 49{ 'command': 'query-qmp-schema', 50 'returns': [ 'SchemaInfo' ], 51 'gen': false } # just to simplify qmp_query_json() 52 53## 54# @SchemaMetaType: 55# 56# This is a @SchemaInfo's meta type, i.e. the kind of entity it 57# describes. 58# 59# @builtin: a predefined type such as 'int' or 'bool'. 60# 61# @enum: an enumeration type 62# 63# @array: an array type 64# 65# @object: an object type (struct or union) 66# 67# @alternate: an alternate type 68# 69# @command: a QMP command 70# 71# @event: a QMP event 72# 73# Since: 2.5 74## 75{ 'enum': 'SchemaMetaType', 76 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate', 77 'command', 'event' ] } 78 79## 80# @SchemaInfo: 81# 82# @name: the entity's name, inherited from @base. 83# The SchemaInfo is always referenced by this name. 84# Commands and events have the name defined in the QAPI schema. 85# Unlike command and event names, type names are not part of 86# the wire ABI. Consequently, type names are meaningless 87# strings here, although they are still guaranteed unique 88# regardless of @meta-type. 89# 90# @meta-type: the entity's meta type, inherited from @base. 91# 92# Additional members depend on the value of @meta-type. 93# 94# Since: 2.5 95## 96{ 'union': 'SchemaInfo', 97 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' }, 98 'discriminator': 'meta-type', 99 'data': { 100 'builtin': 'SchemaInfoBuiltin', 101 'enum': 'SchemaInfoEnum', 102 'array': 'SchemaInfoArray', 103 'object': 'SchemaInfoObject', 104 'alternate': 'SchemaInfoAlternate', 105 'command': 'SchemaInfoCommand', 106 'event': 'SchemaInfoEvent' } } 107 108## 109# @SchemaInfoBuiltin: 110# 111# Additional SchemaInfo members for meta-type 'builtin'. 112# 113# @json-type: the JSON type used for this type on the wire. 114# 115# Since: 2.5 116## 117{ 'struct': 'SchemaInfoBuiltin', 118 'data': { 'json-type': 'JSONType' } } 119 120## 121# @JSONType: 122# 123# The four primitive and two structured types according to RFC 8259 124# section 1, plus 'int' (split off 'number'), plus the obvious top 125# type 'value'. 126# 127# Since: 2.5 128## 129{ 'enum': 'JSONType', 130 'data': [ 'string', 'number', 'int', 'boolean', 'null', 131 'object', 'array', 'value' ] } 132 133## 134# @SchemaInfoEnum: 135# 136# Additional SchemaInfo members for meta-type 'enum'. 137# 138# @values: the enumeration type's values, in no particular order. 139# 140# Values of this type are JSON string on the wire. 141# 142# Since: 2.5 143## 144{ 'struct': 'SchemaInfoEnum', 145 'data': { 'values': ['str'] } } 146 147## 148# @SchemaInfoArray: 149# 150# Additional SchemaInfo members for meta-type 'array'. 151# 152# @element-type: the array type's element type. 153# 154# Values of this type are JSON array on the wire. 155# 156# Since: 2.5 157## 158{ 'struct': 'SchemaInfoArray', 159 'data': { 'element-type': 'str' } } 160 161## 162# @SchemaInfoObject: 163# 164# Additional SchemaInfo members for meta-type 'object'. 165# 166# @members: the object type's (non-variant) members, in no particular order. 167# 168# @tag: the name of the member serving as type tag. 169# An element of @members with this name must exist. 170# 171# @variants: variant members, i.e. additional members that 172# depend on the type tag's value. Present exactly when 173# @tag is present. The variants are in no particular order, 174# and may even differ from the order of the values of the 175# enum type of the @tag. 176# 177# @features: names of features associated with the type, in no particular 178# order. (since: 4.1) 179# 180# Values of this type are JSON object on the wire. 181# 182# Since: 2.5 183## 184{ 'struct': 'SchemaInfoObject', 185 'data': { 'members': [ 'SchemaInfoObjectMember' ], 186 '*tag': 'str', 187 '*variants': [ 'SchemaInfoObjectVariant' ], 188 '*features': [ 'str' ] } } 189 190## 191# @SchemaInfoObjectMember: 192# 193# An object member. 194# 195# @name: the member's name, as defined in the QAPI schema. 196# 197# @type: the name of the member's type. 198# 199# @default: default when used as command parameter. 200# If absent, the parameter is mandatory. 201# If present, the value must be null. The parameter is 202# optional, and behavior when it's missing is not specified 203# here. 204# Future extension: if present and non-null, the parameter 205# is optional, and defaults to this value. 206# 207# Since: 2.5 208## 209{ 'struct': 'SchemaInfoObjectMember', 210 'data': { 'name': 'str', 'type': 'str', '*default': 'any' } } 211# @default's type must be null or match @type 212 213## 214# @SchemaInfoObjectVariant: 215# 216# The variant members for a value of the type tag. 217# 218# @case: a value of the type tag. 219# 220# @type: the name of the object type that provides the variant members 221# when the type tag has value @case. 222# 223# Since: 2.5 224## 225{ 'struct': 'SchemaInfoObjectVariant', 226 'data': { 'case': 'str', 'type': 'str' } } 227 228## 229# @SchemaInfoAlternate: 230# 231# Additional SchemaInfo members for meta-type 'alternate'. 232# 233# @members: the alternate type's members, in no particular order. 234# The members' wire encoding is distinct, see 235# docs/devel/qapi-code-gen.txt section Alternate types. 236# 237# On the wire, this can be any of the members. 238# 239# Since: 2.5 240## 241{ 'struct': 'SchemaInfoAlternate', 242 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } 243 244## 245# @SchemaInfoAlternateMember: 246# 247# An alternate member. 248# 249# @type: the name of the member's type. 250# 251# Since: 2.5 252## 253{ 'struct': 'SchemaInfoAlternateMember', 254 'data': { 'type': 'str' } } 255 256## 257# @SchemaInfoCommand: 258# 259# Additional SchemaInfo members for meta-type 'command'. 260# 261# @arg-type: the name of the object type that provides the command's 262# parameters. 263# 264# @ret-type: the name of the command's result type. 265# 266# @allow-oob: whether the command allows out-of-band execution, 267# defaults to false (Since: 2.12) 268# 269# TODO: @success-response (currently irrelevant, because it's QGA, not QMP) 270# 271# Since: 2.5 272## 273{ 'struct': 'SchemaInfoCommand', 274 'data': { 'arg-type': 'str', 'ret-type': 'str', 275 '*allow-oob': 'bool' } } 276 277## 278# @SchemaInfoEvent: 279# 280# Additional SchemaInfo members for meta-type 'event'. 281# 282# @arg-type: the name of the object type that provides the event's 283# parameters. 284# 285# Since: 2.5 286## 287{ 'struct': 'SchemaInfoEvent', 288 'data': { 'arg-type': 'str' } } 289