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