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