Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 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 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 14 | # @query-qmp-schema: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 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 | # |
Eric Blake | 39a65e2 | 2015-11-11 10:50:02 -0700 | [diff] [blame] | 25 | # Furthermore, while we strive to keep the QMP wire format |
| 26 | # backwards-compatible across qemu versions, the introspection output |
| 27 | # is not guaranteed to have the same stability. For example, one |
| 28 | # version of qemu may list an object member as an optional |
| 29 | # non-variant, while another lists the same member only through the |
| 30 | # object's variants; or the type of a member may change from a generic |
| 31 | # string into a specific enum or from one specific type into an |
| 32 | # alternate that includes the original type alongside something else. |
| 33 | # |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 34 | # Returns: array of @SchemaInfo, where each element describes an |
| 35 | # entity in the ABI: command, event, type, ... |
| 36 | # |
Eric Blake | f545504 | 2015-11-05 23:35:36 -0700 | [diff] [blame] | 37 | # The order of the various SchemaInfo is unspecified; however, all |
| 38 | # names are guaranteed to be unique (no name will be duplicated with |
| 39 | # different meta-types). |
| 40 | # |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 41 | # Note: the QAPI schema is also used to help define *internal* |
| 42 | # interfaces, by defining QAPI types. These are not part of the QMP |
| 43 | # wire ABI, and therefore not returned by this command. |
| 44 | # |
| 45 | # Since: 2.5 |
| 46 | ## |
| 47 | { 'command': 'query-qmp-schema', |
| 48 | 'returns': [ 'SchemaInfo' ], |
| 49 | 'gen': false } # just to simplify qmp_query_json() |
| 50 | |
| 51 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 52 | # @SchemaMetaType: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 53 | # |
| 54 | # This is a @SchemaInfo's meta type, i.e. the kind of entity it |
| 55 | # describes. |
| 56 | # |
| 57 | # @builtin: a predefined type such as 'int' or 'bool'. |
| 58 | # |
| 59 | # @enum: an enumeration type |
| 60 | # |
| 61 | # @array: an array type |
| 62 | # |
| 63 | # @object: an object type (struct or union) |
| 64 | # |
| 65 | # @alternate: an alternate type |
| 66 | # |
| 67 | # @command: a QMP command |
| 68 | # |
| 69 | # @event: a QMP event |
| 70 | # |
| 71 | # Since: 2.5 |
| 72 | ## |
| 73 | { 'enum': 'SchemaMetaType', |
| 74 | 'data': [ 'builtin', 'enum', 'array', 'object', 'alternate', |
| 75 | 'command', 'event' ] } |
| 76 | |
| 77 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 78 | # @SchemaInfo: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 79 | # |
| 80 | # @name: the entity's name, inherited from @base. |
Marc-André Lureau | 5807ff8 | 2017-01-13 15:41:21 +0100 | [diff] [blame] | 81 | # The SchemaInfo is always referenced by this name. |
Markus Armbruster | 1a9a507 | 2015-09-16 13:06:29 +0200 | [diff] [blame] | 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 |
Eric Blake | f545504 | 2015-11-05 23:35:36 -0700 | [diff] [blame] | 85 | # strings here, although they are still guaranteed unique |
| 86 | # regardless of @meta-type. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 87 | # |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 88 | # @meta-type: the entity's meta type, inherited from @base. |
| 89 | # |
| 90 | # Additional members depend on the value of @meta-type. |
| 91 | # |
| 92 | # Since: 2.5 |
| 93 | ## |
| 94 | { 'union': 'SchemaInfo', |
Eric Blake | 3666a97 | 2016-03-17 16:48:40 -0600 | [diff] [blame] | 95 | 'base': { 'name': 'str', 'meta-type': 'SchemaMetaType' }, |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 96 | 'discriminator': 'meta-type', |
| 97 | 'data': { |
| 98 | 'builtin': 'SchemaInfoBuiltin', |
| 99 | 'enum': 'SchemaInfoEnum', |
| 100 | 'array': 'SchemaInfoArray', |
| 101 | 'object': 'SchemaInfoObject', |
| 102 | 'alternate': 'SchemaInfoAlternate', |
| 103 | 'command': 'SchemaInfoCommand', |
| 104 | 'event': 'SchemaInfoEvent' } } |
| 105 | |
| 106 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 107 | # @SchemaInfoBuiltin: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 108 | # |
| 109 | # Additional SchemaInfo members for meta-type 'builtin'. |
| 110 | # |
| 111 | # @json-type: the JSON type used for this type on the wire. |
| 112 | # |
| 113 | # Since: 2.5 |
| 114 | ## |
| 115 | { 'struct': 'SchemaInfoBuiltin', |
| 116 | 'data': { 'json-type': 'JSONType' } } |
| 117 | |
| 118 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 119 | # @JSONType: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 120 | # |
| 121 | # The four primitive and two structured types according to RFC 7159 |
| 122 | # section 1, plus 'int' (split off 'number'), plus the obvious top |
| 123 | # type 'value'. |
| 124 | # |
| 125 | # Since: 2.5 |
| 126 | ## |
| 127 | { 'enum': 'JSONType', |
| 128 | 'data': [ 'string', 'number', 'int', 'boolean', 'null', |
| 129 | 'object', 'array', 'value' ] } |
| 130 | |
| 131 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 132 | # @SchemaInfoEnum: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 133 | # |
| 134 | # Additional SchemaInfo members for meta-type 'enum'. |
| 135 | # |
Eric Blake | f545504 | 2015-11-05 23:35:36 -0700 | [diff] [blame] | 136 | # @values: the enumeration type's values, in no particular order. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 137 | # |
| 138 | # Values of this type are JSON string on the wire. |
| 139 | # |
| 140 | # Since: 2.5 |
| 141 | ## |
| 142 | { 'struct': 'SchemaInfoEnum', |
| 143 | 'data': { 'values': ['str'] } } |
| 144 | |
| 145 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 146 | # @SchemaInfoArray: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 147 | # |
| 148 | # Additional SchemaInfo members for meta-type 'array'. |
| 149 | # |
| 150 | # @element-type: the array type's element type. |
| 151 | # |
| 152 | # Values of this type are JSON array on the wire. |
| 153 | # |
| 154 | # Since: 2.5 |
| 155 | ## |
| 156 | { 'struct': 'SchemaInfoArray', |
| 157 | 'data': { 'element-type': 'str' } } |
| 158 | |
| 159 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 160 | # @SchemaInfoObject: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 161 | # |
| 162 | # Additional SchemaInfo members for meta-type 'object'. |
| 163 | # |
Eric Blake | f545504 | 2015-11-05 23:35:36 -0700 | [diff] [blame] | 164 | # @members: the object type's (non-variant) members, in no particular order. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 165 | # |
Markus Armbruster | 1d8bda1 | 2017-03-15 13:57:06 +0100 | [diff] [blame] | 166 | # @tag: the name of the member serving as type tag. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 167 | # An element of @members with this name must exist. |
| 168 | # |
Markus Armbruster | 1d8bda1 | 2017-03-15 13:57:06 +0100 | [diff] [blame] | 169 | # @variants: variant members, i.e. additional members that |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 170 | # depend on the type tag's value. Present exactly when |
Eric Blake | f545504 | 2015-11-05 23:35:36 -0700 | [diff] [blame] | 171 | # @tag is present. The variants are in no particular order, |
| 172 | # and may even differ from the order of the values of the |
| 173 | # enum type of the @tag. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 174 | # |
| 175 | # Values of this type are JSON object on the wire. |
| 176 | # |
| 177 | # Since: 2.5 |
| 178 | ## |
| 179 | { 'struct': 'SchemaInfoObject', |
| 180 | 'data': { 'members': [ 'SchemaInfoObjectMember' ], |
| 181 | '*tag': 'str', |
| 182 | '*variants': [ 'SchemaInfoObjectVariant' ] } } |
| 183 | |
| 184 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 185 | # @SchemaInfoObjectMember: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 186 | # |
| 187 | # An object member. |
| 188 | # |
| 189 | # @name: the member's name, as defined in the QAPI schema. |
| 190 | # |
| 191 | # @type: the name of the member's type. |
| 192 | # |
Markus Armbruster | 1d8bda1 | 2017-03-15 13:57:06 +0100 | [diff] [blame] | 193 | # @default: default when used as command parameter. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 194 | # If absent, the parameter is mandatory. |
| 195 | # If present, the value must be null. The parameter is |
| 196 | # optional, and behavior when it's missing is not specified |
| 197 | # here. |
| 198 | # Future extension: if present and non-null, the parameter |
| 199 | # is optional, and defaults to this value. |
| 200 | # |
| 201 | # Since: 2.5 |
| 202 | ## |
| 203 | { 'struct': 'SchemaInfoObjectMember', |
| 204 | 'data': { 'name': 'str', 'type': 'str', '*default': 'any' } } |
| 205 | # @default's type must be null or match @type |
| 206 | |
| 207 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 208 | # @SchemaInfoObjectVariant: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 209 | # |
| 210 | # The variant members for a value of the type tag. |
| 211 | # |
| 212 | # @case: a value of the type tag. |
| 213 | # |
| 214 | # @type: the name of the object type that provides the variant members |
| 215 | # when the type tag has value @case. |
| 216 | # |
| 217 | # Since: 2.5 |
| 218 | ## |
| 219 | { 'struct': 'SchemaInfoObjectVariant', |
| 220 | 'data': { 'case': 'str', 'type': 'str' } } |
| 221 | |
| 222 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 223 | # @SchemaInfoAlternate: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 224 | # |
| 225 | # Additional SchemaInfo members for meta-type 'alternate'. |
| 226 | # |
Eric Blake | f545504 | 2015-11-05 23:35:36 -0700 | [diff] [blame] | 227 | # @members: the alternate type's members, in no particular order. |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 228 | # The members' wire encoding is distinct, see |
| 229 | # docs/qapi-code-gen.txt section Alternate types. |
| 230 | # |
| 231 | # On the wire, this can be any of the members. |
| 232 | # |
| 233 | # Since: 2.5 |
| 234 | ## |
| 235 | { 'struct': 'SchemaInfoAlternate', |
| 236 | 'data': { 'members': [ 'SchemaInfoAlternateMember' ] } } |
| 237 | |
| 238 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 239 | # @SchemaInfoAlternateMember: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 240 | # |
| 241 | # An alternate member. |
| 242 | # |
| 243 | # @type: the name of the member's type. |
| 244 | # |
| 245 | # Since: 2.5 |
| 246 | ## |
| 247 | { 'struct': 'SchemaInfoAlternateMember', |
| 248 | 'data': { 'type': 'str' } } |
| 249 | |
| 250 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 251 | # @SchemaInfoCommand: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 252 | # |
| 253 | # Additional SchemaInfo members for meta-type 'command'. |
| 254 | # |
| 255 | # @arg-type: the name of the object type that provides the command's |
| 256 | # parameters. |
| 257 | # |
| 258 | # @ret-type: the name of the command's result type. |
| 259 | # |
Marc-André Lureau | e22da43 | 2017-01-13 15:41:17 +0100 | [diff] [blame] | 260 | # TODO: @success-response (currently irrelevant, because it's QGA, not QMP) |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 261 | # |
| 262 | # Since: 2.5 |
| 263 | ## |
| 264 | { 'struct': 'SchemaInfoCommand', |
| 265 | 'data': { 'arg-type': 'str', 'ret-type': 'str' } } |
| 266 | |
| 267 | ## |
Marc-André Lureau | 5072f7b | 2016-11-17 19:54:55 +0400 | [diff] [blame] | 268 | # @SchemaInfoEvent: |
Markus Armbruster | 39a1815 | 2015-09-16 13:06:28 +0200 | [diff] [blame] | 269 | # |
| 270 | # Additional SchemaInfo members for meta-type 'event'. |
| 271 | # |
| 272 | # @arg-type: the name of the object type that provides the event's |
| 273 | # parameters. |
| 274 | # |
| 275 | # Since: 2.5 |
| 276 | ## |
| 277 | { 'struct': 'SchemaInfoEvent', |
| 278 | 'data': { 'arg-type': 'str' } } |