1# -*- Mode: Python -*- 2# 3# QAPI/QMP introspection 4# 5# Copyright (C) 2015 Red Hat, Inc. 6# 7# Authors: 8# Markus Armbruster <armbru@redhat.com> 9# 10# This work is licensed under the terms of the GNU GPL, version 2 or later. 11# See the COPYING file in the top-level directory. 12 13## 14# @query-qmp-schema 15# 16# Command query-qmp-schema exposes the QMP wire ABI as an array of 17# SchemaInfo. This lets QMP clients figure out what commands and 18# events are available in this QEMU, and their parameters and results. 19# 20# However, the SchemaInfo can't reflect all the rules and restrictions 21# that apply to QMP. It's interface introspection (figuring out 22# what's there), not interface specification. The specification is in 23# the QAPI schema. 24# 25# Returns: array of @SchemaInfo, where each element describes an 26# entity in the ABI: command, event, type, ... 27# 28# The order of the various SchemaInfo is unspecified; however, all 29# names are guaranteed to be unique (no name will be duplicated with 30# different meta-types). 31# 32# Note: the QAPI schema is also used to help define *internal* 33# interfaces, by defining QAPI types. These are not part of the QMP 34# wire ABI, and therefore not returned by this command. 35# 36# Since: 2.5 37## 38{ 'command': 'query-qmp-schema', 39 'returns': [ 'SchemaInfo' ], 40 'gen': false } # just to simplify qmp_query_json() 41 42## 43# @SchemaMetaType 44# 45# This is a @SchemaInfo's meta type, i.e. the kind of entity it 46# describes. 47# 48# @builtin: a predefined type such as 'int' or 'bool'. 49# 50# @enum: an enumeration type 51# 52# @array: an array type 53# 54# @object: an object type (struct or union) 55# 56# @alternate: an alternate type 57# 58# @command: a QMP command 59# 60# @event: a QMP event 61# 62# Since: 2.5 63## 64{ 'enum': 'SchemaMetaType', 65 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate', 66 'command', 'event' ] } 67 68## 69# @SchemaInfoBase 70# 71# Members common to any @SchemaInfo. 72# 73# Since: 2.5 74## 75{ 'struct': 'SchemaInfoBase', 76 'data': { 'name': 'str', 'meta-type': 'SchemaMetaType' } } 77 78## 79# @SchemaInfo 80# 81# @name: the entity's name, inherited from @base. 82# Commands and events have the name defined in the QAPI schema. 83# Unlike command and event names, type names are not part of 84# the wire ABI. Consequently, type names are meaningless 85# strings here, although they are still guaranteed unique 86# regardless of @meta-type. 87# 88# All references to other SchemaInfo are by name. 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': 'SchemaInfoBase', 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 7159 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: #optional the name of the member serving as type tag. 169# An element of @members with this name must exist. 170# 171# @variants: #optional 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# Values of this type are JSON object on the wire. 178# 179# Since: 2.5 180## 181{ 'struct': 'SchemaInfoObject', 182 'data': { 'members': [ 'SchemaInfoObjectMember' ], 183 '*tag': 'str', 184 '*variants': [ 'SchemaInfoObjectVariant' ] } } 185 186## 187# @SchemaInfoObjectMember 188# 189# An object member. 190# 191# @name: the member's name, as defined in the QAPI schema. 192# 193# @type: the name of the member's type. 194# 195# @default: #optional default when used as command parameter. 196# If absent, the parameter is mandatory. 197# If present, the value must be null. The parameter is 198# optional, and behavior when it's missing is not specified 199# here. 200# Future extension: if present and non-null, the parameter 201# is optional, and defaults to this value. 202# 203# Since: 2.5 204## 205{ 'struct': 'SchemaInfoObjectMember', 206 'data': { 'name': 'str', 'type': 'str', '*default': 'any' } } 207# @default's type must be null or match @type 208 209## 210# @SchemaInfoObjectVariant 211# 212# The variant members for a value of the type tag. 213# 214# @case: a value of the type tag. 215# 216# @type: the name of the object type that provides the variant members 217# when the type tag has value @case. 218# 219# Since: 2.5 220## 221{ 'struct': 'SchemaInfoObjectVariant', 222 'data': { 'case': 'str', 'type': 'str' } } 223 224## 225# @SchemaInfoAlternate 226# 227# Additional SchemaInfo members for meta-type 'alternate'. 228# 229# @members: the alternate type's members, in no particular order. 230# The members' wire encoding is distinct, see 231# docs/qapi-code-gen.txt section Alternate types. 232# 233# On the wire, this can be any of the members. 234# 235# Since: 2.5 236## 237{ 'struct': 'SchemaInfoAlternate', 238 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } 239 240## 241# @SchemaInfoAlternateMember 242# 243# An alternate member. 244# 245# @type: the name of the member's type. 246# 247# Since: 2.5 248## 249{ 'struct': 'SchemaInfoAlternateMember', 250 'data': { 'type': 'str' } } 251 252## 253# @SchemaInfoCommand 254# 255# Additional SchemaInfo members for meta-type 'command'. 256# 257# @arg-type: the name of the object type that provides the command's 258# parameters. 259# 260# @ret-type: the name of the command's result type. 261# 262# TODO @success-response (currently irrelevant, because it's QGA, not QMP) 263# 264# Since: 2.5 265## 266{ 'struct': 'SchemaInfoCommand', 267 'data': { 'arg-type': 'str', 'ret-type': 'str' } } 268 269## 270# @SchemaInfoEvent 271# 272# Additional SchemaInfo members for meta-type 'event'. 273# 274# @arg-type: the name of the object type that provides the event's 275# parameters. 276# 277# Since: 2.5 278## 279{ 'struct': 'SchemaInfoEvent', 280 'data': { 'arg-type': 'str' } } 281