1= How to use the QAPI code generator = 2 3Copyright IBM Corp. 2011 4Copyright (C) 2012-2016 Red Hat, Inc. 5 6This work is licensed under the terms of the GNU GPL, version 2 or 7later. See the COPYING file in the top-level directory. 8 9== Introduction == 10 11QAPI is a native C API within QEMU which provides management-level 12functionality to internal and external users. For external 13users/processes, this interface is made available by a JSON-based wire 14format for the QEMU Monitor Protocol (QMP) for controlling qemu, as 15well as the QEMU Guest Agent (QGA) for communicating with the guest. 16The remainder of this document uses "Client JSON Protocol" when 17referring to the wire contents of a QMP or QGA connection. 18 19To map Client JSON Protocol interfaces to the native C QAPI 20implementations, a JSON-based schema is used to define types and 21function signatures, and a set of scripts is used to generate types, 22signatures, and marshaling/dispatch code. This document will describe 23how the schemas, scripts, and resulting code are used. 24 25 26== QMP/Guest agent schema == 27 28A QAPI schema file is designed to be loosely based on JSON 29(http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style 30and the use of comments; a QAPI schema file is then parsed by a python 31code generation program. A valid QAPI schema consists of a series of 32top-level expressions, with no commas between them. Where 33dictionaries (JSON objects) are used, they are parsed as python 34OrderedDicts so that ordering is preserved (for predictable layout of 35generated C structs and parameter lists). Ordering doesn't matter 36between top-level expressions or the keys within an expression, but 37does matter within dictionary values for 'data' and 'returns' members 38of a single expression. QAPI schema input is written using 'single 39quotes' instead of JSON's "double quotes" (in contrast, Client JSON 40Protocol uses no comments, and while input accepts 'single quotes' as 41an extension, output is strict JSON using only "double quotes"). As 42in JSON, trailing commas are not permitted in arrays or dictionaries. 43Input must be ASCII (although QMP supports full Unicode strings, the 44QAPI parser does not). At present, there is no place where a QAPI 45schema requires the use of JSON numbers or null. 46 47Comments are allowed; anything between an unquoted # and the following 48newline is ignored. Although there is not yet a documentation 49generator, a form of stylized comments has developed for consistently 50documenting details about an expression and when it was added to the 51schema. The documentation is delimited between two lines of ##, then 52the first line names the expression, an optional overview is provided, 53then individual documentation about each member of 'data' is provided, 54and finally, a 'Since: x.y.z' tag lists the release that introduced 55the expression. Optional members are tagged with the phrase 56'#optional', often with their default value; and extensions added 57after the expression was first released are also given a '(since 58x.y.z)' comment. For example: 59 60 ## 61 # @BlockStats: 62 # 63 # Statistics of a virtual block device or a block backing device. 64 # 65 # @device: #optional If the stats are for a virtual block device, the name 66 # corresponding to the virtual block device. 67 # 68 # @stats: A @BlockDeviceStats for the device. 69 # 70 # @parent: #optional This describes the file block device if it has one. 71 # 72 # @backing: #optional This describes the backing block device if it has one. 73 # (Since 2.0) 74 # 75 # Since: 0.14.0 76 ## 77 { 'struct': 'BlockStats', 78 'data': {'*device': 'str', 'stats': 'BlockDeviceStats', 79 '*parent': 'BlockStats', 80 '*backing': 'BlockStats'} } 81 82The schema sets up a series of types, as well as commands and events 83that will use those types. Forward references are allowed: the parser 84scans in two passes, where the first pass learns all type names, and 85the second validates the schema and generates the code. This allows 86the definition of complex structs that can have mutually recursive 87types, and allows for indefinite nesting of Client JSON Protocol that 88satisfies the schema. A type name should not be defined more than 89once. It is permissible for the schema to contain additional types 90not used by any commands or events in the Client JSON Protocol, for 91the side effect of generated C code used internally. 92 93There are seven top-level expressions recognized by the parser: 94'include', 'command', 'struct', 'enum', 'union', 'alternate', and 95'event'. There are several groups of types: simple types (a number of 96built-in types, such as 'int' and 'str'; as well as enumerations), 97complex types (structs and two flavors of unions), and alternate types 98(a choice between other types). The 'command' and 'event' expressions 99can refer to existing types by name, or list an anonymous type as a 100dictionary. Listing a type name inside an array refers to a 101single-dimension array of that type; multi-dimension arrays are not 102directly supported (although an array of a complex struct that 103contains an array member is possible). 104 105Types, commands, and events share a common namespace. Therefore, 106generally speaking, type definitions should always use CamelCase for 107user-defined type names, while built-in types are lowercase. Type 108definitions should not end in 'Kind', as this namespace is used for 109creating implicit C enums for visiting union types, or in 'List', as 110this namespace is used for creating array types. Command names, 111and member names within a type, should be all lower case with words 112separated by a hyphen. However, some existing older commands and 113complex types use underscore; when extending such expressions, 114consistency is preferred over blindly avoiding underscore. Event 115names should be ALL_CAPS with words separated by underscore. Member 116names cannot start with 'has-' or 'has_', as this is reserved for 117tracking optional members. 118 119Any name (command, event, type, member, or enum value) beginning with 120"x-" is marked experimental, and may be withdrawn or changed 121incompatibly in a future release. All names must begin with a letter, 122and contain only ASCII letters, digits, dash, and underscore. There 123are two exceptions: enum values may start with a digit, and any 124extensions added by downstream vendors should start with a prefix 125matching "__RFQDN_" (for the reverse-fully-qualified-domain-name of 126the vendor), even if the rest of the name uses dash (example: 127__com.redhat_drive-mirror). Names beginning with 'q_' are reserved 128for the generator: QMP names that resemble C keywords or other 129problematic strings will be munged in C to use this prefix. For 130example, a member named "default" in qapi becomes "q_default" in the 131generated C code. 132 133In the rest of this document, usage lines are given for each 134expression type, with literal strings written in lower case and 135placeholders written in capitals. If a literal string includes a 136prefix of '*', that key/value pair can be omitted from the expression. 137For example, a usage statement that includes '*base':STRUCT-NAME 138means that an expression has an optional key 'base', which if present 139must have a value that forms a struct name. 140 141 142=== Built-in Types === 143 144The following types are predefined, and map to C as follows: 145 146 Schema C JSON 147 str char * any JSON string, UTF-8 148 number double any JSON number 149 int int64_t a JSON number without fractional part 150 that fits into the C integer type 151 int8 int8_t likewise 152 int16 int16_t likewise 153 int32 int32_t likewise 154 int64 int64_t likewise 155 uint8 uint8_t likewise 156 uint16 uint16_t likewise 157 uint32 uint32_t likewise 158 uint64 uint64_t likewise 159 size uint64_t like uint64_t, except StringInputVisitor 160 accepts size suffixes 161 bool bool JSON true or false 162 any QObject * any JSON value 163 QType QType JSON string matching enum QType values 164 165 166=== Includes === 167 168Usage: { 'include': STRING } 169 170The QAPI schema definitions can be modularized using the 'include' directive: 171 172 { 'include': 'path/to/file.json' } 173 174The directive is evaluated recursively, and include paths are relative to the 175file using the directive. Multiple includes of the same file are 176idempotent. No other keys should appear in the expression, and the include 177value should be a string. 178 179As a matter of style, it is a good idea to have all files be 180self-contained, but at the moment, nothing prevents an included file 181from making a forward reference to a type that is only introduced by 182an outer file. The parser may be made stricter in the future to 183prevent incomplete include files. 184 185 186=== Struct types === 187 188Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } 189 190A struct is a dictionary containing a single 'data' key whose value is 191a dictionary; the dictionary may be empty. This corresponds to a 192struct in C or an Object in JSON. Each value of the 'data' dictionary 193must be the name of a type, or a one-element array containing a type 194name. An example of a struct is: 195 196 { 'struct': 'MyType', 197 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } 198 199The use of '*' as a prefix to the name means the member is optional in 200the corresponding JSON protocol usage. 201 202The default initialization value of an optional argument should not be changed 203between versions of QEMU unless the new default maintains backward 204compatibility to the user-visible behavior of the old default. 205 206With proper documentation, this policy still allows some flexibility; for 207example, documenting that a default of 0 picks an optimal buffer size allows 208one release to declare the optimal size at 512 while another release declares 209the optimal size at 4096 - the user-visible behavior is not the bytes used by 210the buffer, but the fact that the buffer was optimal size. 211 212On input structures (only mentioned in the 'data' side of a command), changing 213from mandatory to optional is safe (older clients will supply the option, and 214newer clients can benefit from the default); changing from optional to 215mandatory is backwards incompatible (older clients may be omitting the option, 216and must continue to work). 217 218On output structures (only mentioned in the 'returns' side of a command), 219changing from mandatory to optional is in general unsafe (older clients may be 220expecting the member, and could crash if it is missing), although it 221can be done if the only way that the optional argument will be omitted 222is when it is triggered by the presence of a new input flag to the 223command that older clients don't know to send. Changing from optional 224to mandatory is safe. 225 226A structure that is used in both input and output of various commands 227must consider the backwards compatibility constraints of both directions 228of use. 229 230A struct definition can specify another struct as its base. 231In this case, the members of the base type are included as top-level members 232of the new struct's dictionary in the Client JSON Protocol wire 233format. An example definition is: 234 235 { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } 236 { 'struct': 'BlockdevOptionsGenericCOWFormat', 237 'base': 'BlockdevOptionsGenericFormat', 238 'data': { '*backing': 'str' } } 239 240An example BlockdevOptionsGenericCOWFormat object on the wire could use 241both members like this: 242 243 { "file": "/some/place/my-image", 244 "backing": "/some/place/my-backing-file" } 245 246 247=== Enumeration types === 248 249Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING } 250 { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING } 251 252An enumeration type is a dictionary containing a single 'data' key 253whose value is a list of strings. An example enumeration is: 254 255 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } 256 257Nothing prevents an empty enumeration, although it is probably not 258useful. The list of strings should be lower case; if an enum name 259represents multiple words, use '-' between words. The string 'max' is 260not allowed as an enum value, and values should not be repeated. 261 262The enum constants will be named by using a heuristic to turn the 263type name into a set of underscore separated words. For the example 264above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name 265of 'MY_ENUM_VALUE1' for the first value. If the default heuristic 266does not result in a desirable name, the optional 'prefix' member 267can be used when defining the enum. 268 269The enumeration values are passed as strings over the Client JSON 270Protocol, but are encoded as C enum integral values in generated code. 271While the C code starts numbering at 0, it is better to use explicit 272comparisons to enum values than implicit comparisons to 0; the C code 273will also include a generated enum member ending in _MAX for tracking 274the size of the enum, useful when using common functions for 275converting between strings and enum values. Since the wire format 276always passes by name, it is acceptable to reorder or add new 277enumeration members in any location without breaking clients of Client 278JSON Protocol; however, removing enum values would break 279compatibility. For any struct that has a member that will only contain 280a finite set of string values, using an enum type for that member is 281better than open-coding the member to be type 'str'. 282 283 284=== Union types === 285 286Usage: { 'union': STRING, 'data': DICT } 287or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT, 288 'discriminator': ENUM-MEMBER-OF-BASE } 289 290Union types are used to let the user choose between several different 291variants for an object. There are two flavors: simple (no 292discriminator or base), and flat (both discriminator and base). A union 293type is defined using a data dictionary as explained in the following 294paragraphs. The data dictionary for either type of union must not 295be empty. 296 297A simple union type defines a mapping from automatic discriminator 298values to data types like in this example: 299 300 { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } } 301 { 'struct': 'BlockdevOptionsQcow2', 302 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } } 303 304 { 'union': 'BlockdevOptionsSimple', 305 'data': { 'file': 'BlockdevOptionsFile', 306 'qcow2': 'BlockdevOptionsQcow2' } } 307 308In the Client JSON Protocol, a simple union is represented by a 309dictionary that contains the 'type' member as a discriminator, and a 310'data' member that is of the specified data type corresponding to the 311discriminator value, as in these examples: 312 313 { "type": "file", "data": { "filename": "/some/place/my-image" } } 314 { "type": "qcow2", "data": { "backing": "/some/place/my-image", 315 "lazy-refcounts": true } } 316 317The generated C code uses a struct containing a union. Additionally, 318an implicit C enum 'NameKind' is created, corresponding to the union 319'Name', for accessing the various branches of the union. No branch of 320the union can be named 'max', as this would collide with the implicit 321enum. The value for each branch can be of any type. 322 323A flat union definition avoids nesting on the wire, and specifies a 324set of common members that occur in all variants of the union. The 325'base' key must specifiy either a type name (the type must be a 326struct, not a union), or a dictionary representing an anonymous type. 327All branches of the union must be complex types, and the top-level 328members of the union dictionary on the wire will be combination of 329members from both the base type and the appropriate branch type (when 330merging two dictionaries, there must be no keys in common). The 331'discriminator' member must be the name of a non-optional enum-typed 332member of the base struct. 333 334The following example enhances the above simple union example by 335adding an optional common member 'read-only', renaming the 336discriminator to something more applicable than the simple union's 337default of 'type', and reducing the number of {} required on the wire: 338 339 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } 340 { 'union': 'BlockdevOptions', 341 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' }, 342 'discriminator': 'driver', 343 'data': { 'file': 'BlockdevOptionsFile', 344 'qcow2': 'BlockdevOptionsQcow2' } } 345 346Resulting in these JSON objects: 347 348 { "driver": "file", "read-only": true, 349 "filename": "/some/place/my-image" } 350 { "driver": "qcow2", "read-only": false, 351 "backing": "/some/place/my-image", "lazy-refcounts": true } 352 353Notice that in a flat union, the discriminator name is controlled by 354the user, but because it must map to a base member with enum type, the 355code generator can ensure that branches exist for all values of the 356enum (although the order of the keys need not match the declaration of 357the enum). In the resulting generated C data types, a flat union is 358represented as a struct with the base members included directly, and 359then a union of structures for each branch of the struct. 360 361A simple union can always be re-written as a flat union where the base 362class has a single member named 'type', and where each branch of the 363union has a struct with a single member named 'data'. That is, 364 365 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } 366 367is identical on the wire to: 368 369 { 'enum': 'Enum', 'data': ['one', 'two'] } 370 { 'struct': 'Branch1', 'data': { 'data': 'str' } } 371 { 'struct': 'Branch2', 'data': { 'data': 'int' } } 372 { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type', 373 'data': { 'one': 'Branch1', 'two': 'Branch2' } } 374 375 376=== Alternate types === 377 378Usage: { 'alternate': STRING, 'data': DICT } 379 380An alternate type is one that allows a choice between two or more JSON 381data types (string, integer, number, or object, but currently not 382array) on the wire. The definition is similar to a simple union type, 383where each branch of the union names a QAPI type. For example: 384 385 { 'alternate': 'BlockdevRef', 386 'data': { 'definition': 'BlockdevOptions', 387 'reference': 'str' } } 388 389Unlike a union, the discriminator string is never passed on the wire 390for the Client JSON Protocol. Instead, the value's JSON type serves 391as an implicit discriminator, which in turn means that an alternate 392can only express a choice between types represented differently in 393JSON. If a branch is typed as the 'bool' built-in, the alternate 394accepts true and false; if it is typed as any of the various numeric 395built-ins, it accepts a JSON number; if it is typed as a 'str' 396built-in or named enum type, it accepts a JSON string; and if it is 397typed as a complex type (struct or union), it accepts a JSON object. 398Two different complex types, for instance, aren't permitted, because 399both are represented as a JSON object. 400 401The example alternate declaration above allows using both of the 402following example objects: 403 404 { "file": "my_existing_block_device_id" } 405 { "file": { "driver": "file", 406 "read-only": false, 407 "filename": "/tmp/mydisk.qcow2" } } 408 409 410=== Commands === 411 412Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, 413 '*returns': TYPE-NAME, 414 '*gen': false, '*success-response': false } 415 416Commands are defined by using a dictionary containing several members, 417where three members are most common. The 'command' member is a 418mandatory string, and determines the "execute" value passed in a 419Client JSON Protocol command exchange. 420 421The 'data' argument maps to the "arguments" dictionary passed in as 422part of a Client JSON Protocol command. The 'data' member is optional 423and defaults to {} (an empty dictionary). If present, it must be the 424string name of a complex type, or a dictionary that declares an 425anonymous type with the same semantics as a 'struct' expression, with 426one exception noted below when 'gen' is used. 427 428The 'returns' member describes what will appear in the "return" member 429of a Client JSON Protocol reply on successful completion of a command. 430The member is optional from the command declaration; if absent, the 431"return" member will be an empty dictionary. If 'returns' is present, 432it must be the string name of a complex or built-in type, a 433one-element array containing the name of a complex or built-in type, 434with one exception noted below when 'gen' is used. Although it is 435permitted to have the 'returns' member name a built-in type or an 436array of built-in types, any command that does this cannot be extended 437to return additional information in the future; thus, new commands 438should strongly consider returning a dictionary-based type or an array 439of dictionaries, even if the dictionary only contains one member at the 440present. 441 442All commands in Client JSON Protocol use a dictionary to report 443failure, with no way to specify that in QAPI. Where the error return 444is different than the usual GenericError class in order to help the 445client react differently to certain error conditions, it is worth 446documenting this in the comments before the command declaration. 447 448Some example commands: 449 450 { 'command': 'my-first-command', 451 'data': { 'arg1': 'str', '*arg2': 'str' } } 452 { 'struct': 'MyType', 'data': { '*value': 'str' } } 453 { 'command': 'my-second-command', 454 'returns': [ 'MyType' ] } 455 456which would validate this Client JSON Protocol transaction: 457 458 => { "execute": "my-first-command", 459 "arguments": { "arg1": "hello" } } 460 <= { "return": { } } 461 => { "execute": "my-second-command" } 462 <= { "return": [ { "value": "one" }, { } ] } 463 464In rare cases, QAPI cannot express a type-safe representation of a 465corresponding Client JSON Protocol command. You then have to suppress 466generation of a marshalling function by including a key 'gen' with 467boolean value false, and instead write your own function. Please try 468to avoid adding new commands that rely on this, and instead use 469type-safe unions. For an example of this usage: 470 471 { 'command': 'netdev_add', 472 'data': {'type': 'str', 'id': 'str'}, 473 'gen': false } 474 475Normally, the QAPI schema is used to describe synchronous exchanges, 476where a response is expected. But in some cases, the action of a 477command is expected to change state in a way that a successful 478response is not possible (although the command will still return a 479normal dictionary error on failure). When a successful reply is not 480possible, the command expression should include the optional key 481'success-response' with boolean value false. So far, only QGA makes 482use of this member. 483 484 485=== Events === 486 487Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT } 488 489Events are defined with the keyword 'event'. It is not allowed to 490name an event 'MAX', since the generator also produces a C enumeration 491of all event names with a generated _MAX value at the end. When 492'data' is also specified, additional info will be included in the 493event, with similar semantics to a 'struct' expression. Finally there 494will be C API generated in qapi-event.h; when called by QEMU code, a 495message with timestamp will be emitted on the wire. 496 497An example event is: 498 499{ 'event': 'EVENT_C', 500 'data': { '*a': 'int', 'b': 'str' } } 501 502Resulting in this JSON object: 503 504{ "event": "EVENT_C", 505 "data": { "b": "test string" }, 506 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } 507 508 509== Client JSON Protocol introspection == 510 511Clients of a Client JSON Protocol commonly need to figure out what 512exactly the server (QEMU) supports. 513 514For this purpose, QMP provides introspection via command 515query-qmp-schema. QGA currently doesn't support introspection. 516 517While Client JSON Protocol wire compatibility should be maintained 518between qemu versions, we cannot make the same guarantees for 519introspection stability. For example, one version of qemu may provide 520a non-variant optional member of a struct, and a later version rework 521the member to instead be non-optional and associated with a variant. 522Likewise, one version of qemu may list a member with open-ended type 523'str', and a later version could convert it to a finite set of strings 524via an enum type; or a member may be converted from a specific type to 525an alternate that represents a choice between the original type and 526something else. 527 528query-qmp-schema returns a JSON array of SchemaInfo objects. These 529objects together describe the wire ABI, as defined in the QAPI schema. 530There is no specified order to the SchemaInfo objects returned; a 531client must search for a particular name throughout the entire array 532to learn more about that name, but is at least guaranteed that there 533will be no collisions between type, command, and event names. 534 535However, the SchemaInfo can't reflect all the rules and restrictions 536that apply to QMP. It's interface introspection (figuring out what's 537there), not interface specification. The specification is in the QAPI 538schema. To understand how QMP is to be used, you need to study the 539QAPI schema. 540 541Like any other command, query-qmp-schema is itself defined in the QAPI 542schema, along with the SchemaInfo type. This text attempts to give an 543overview how things work. For details you need to consult the QAPI 544schema. 545 546SchemaInfo objects have common members "name" and "meta-type", and 547additional variant members depending on the value of meta-type. 548 549Each SchemaInfo object describes a wire ABI entity of a certain 550meta-type: a command, event or one of several kinds of type. 551 552SchemaInfo for commands and events have the same name as in the QAPI 553schema. 554 555Command and event names are part of the wire ABI, but type names are 556not. Therefore, the SchemaInfo for types have auto-generated 557meaningless names. For readability, the examples in this section use 558meaningful type names instead. 559 560To examine a type, start with a command or event using it, then follow 561references by name. 562 563QAPI schema definitions not reachable that way are omitted. 564 565The SchemaInfo for a command has meta-type "command", and variant 566members "arg-type" and "ret-type". On the wire, the "arguments" 567member of a client's "execute" command must conform to the object type 568named by "arg-type". The "return" member that the server passes in a 569success response conforms to the type named by "ret-type". 570 571If the command takes no arguments, "arg-type" names an object type 572without members. Likewise, if the command returns nothing, "ret-type" 573names an object type without members. 574 575Example: the SchemaInfo for command query-qmp-schema 576 577 { "name": "query-qmp-schema", "meta-type": "command", 578 "arg-type": "q_empty", "ret-type": "SchemaInfoList" } 579 580 Type "q_empty" is an automatic object type without members, and type 581 "SchemaInfoList" is the array of SchemaInfo type. 582 583The SchemaInfo for an event has meta-type "event", and variant member 584"arg-type". On the wire, a "data" member that the server passes in an 585event conforms to the object type named by "arg-type". 586 587If the event carries no additional information, "arg-type" names an 588object type without members. The event may not have a data member on 589the wire then. 590 591Each command or event defined with dictionary-valued 'data' in the 592QAPI schema implicitly defines an object type. 593 594Example: the SchemaInfo for EVENT_C from section Events 595 596 { "name": "EVENT_C", "meta-type": "event", 597 "arg-type": "q_obj-EVENT_C-arg" } 598 599 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with 600 the two members from the event's definition. 601 602The SchemaInfo for struct and union types has meta-type "object". 603 604The SchemaInfo for a struct type has variant member "members". 605 606The SchemaInfo for a union type additionally has variant members "tag" 607and "variants". 608 609"members" is a JSON array describing the object's common members, if 610any. Each element is a JSON object with members "name" (the member's 611name), "type" (the name of its type), and optionally "default". The 612member is optional if "default" is present. Currently, "default" can 613only have value null. Other values are reserved for future 614extensions. The "members" array is in no particular order; clients 615must search the entire object when learning whether a particular 616member is supported. 617 618Example: the SchemaInfo for MyType from section Struct types 619 620 { "name": "MyType", "meta-type": "object", 621 "members": [ 622 { "name": "member1", "type": "str" }, 623 { "name": "member2", "type": "int" }, 624 { "name": "member3", "type": "str", "default": null } ] } 625 626"tag" is the name of the common member serving as type tag. 627"variants" is a JSON array describing the object's variant members. 628Each element is a JSON object with members "case" (the value of type 629tag this element applies to) and "type" (the name of an object type 630that provides the variant members for this type tag value). The 631"variants" array is in no particular order, and is not guaranteed to 632list cases in the same order as the corresponding "tag" enum type. 633 634Example: the SchemaInfo for flat union BlockdevOptions from section 635Union types 636 637 { "name": "BlockdevOptions", "meta-type": "object", 638 "members": [ 639 { "name": "driver", "type": "BlockdevDriver" }, 640 { "name": "read-only", "type": "bool", "default": null } ], 641 "tag": "driver", 642 "variants": [ 643 { "case": "file", "type": "BlockdevOptionsFile" }, 644 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] } 645 646Note that base types are "flattened": its members are included in the 647"members" array. 648 649A simple union implicitly defines an enumeration type for its implicit 650discriminator (called "type" on the wire, see section Union types). 651 652A simple union implicitly defines an object type for each of its 653variants. 654 655Example: the SchemaInfo for simple union BlockdevOptionsSimple from section 656Union types 657 658 { "name": "BlockdevOptionsSimple", "meta-type": "object", 659 "members": [ 660 { "name": "type", "type": "BlockdevOptionsSimpleKind" } ], 661 "tag": "type", 662 "variants": [ 663 { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" }, 664 { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] } 665 666 Enumeration type "BlockdevOptionsSimpleKind" and the object types 667 "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper" 668 are implicitly defined. 669 670The SchemaInfo for an alternate type has meta-type "alternate", and 671variant member "members". "members" is a JSON array. Each element is 672a JSON object with member "type", which names a type. Values of the 673alternate type conform to exactly one of its member types. There is 674no guarantee on the order in which "members" will be listed. 675 676Example: the SchemaInfo for BlockdevRef from section Alternate types 677 678 { "name": "BlockdevRef", "meta-type": "alternate", 679 "members": [ 680 { "type": "BlockdevOptions" }, 681 { "type": "str" } ] } 682 683The SchemaInfo for an array type has meta-type "array", and variant 684member "element-type", which names the array's element type. Array 685types are implicitly defined. For convenience, the array's name may 686resemble the element type; however, clients should examine member 687"element-type" instead of making assumptions based on parsing member 688"name". 689 690Example: the SchemaInfo for ['str'] 691 692 { "name": "[str]", "meta-type": "array", 693 "element-type": "str" } 694 695The SchemaInfo for an enumeration type has meta-type "enum" and 696variant member "values". The values are listed in no particular 697order; clients must search the entire enum when learning whether a 698particular value is supported. 699 700Example: the SchemaInfo for MyEnum from section Enumeration types 701 702 { "name": "MyEnum", "meta-type": "enum", 703 "values": [ "value1", "value2", "value3" ] } 704 705The SchemaInfo for a built-in type has the same name as the type in 706the QAPI schema (see section Built-in Types), with one exception 707detailed below. It has variant member "json-type" that shows how 708values of this type are encoded on the wire. 709 710Example: the SchemaInfo for str 711 712 { "name": "str", "meta-type": "builtin", "json-type": "string" } 713 714The QAPI schema supports a number of integer types that only differ in 715how they map to C. They are identical as far as SchemaInfo is 716concerned. Therefore, they get all mapped to a single type "int" in 717SchemaInfo. 718 719As explained above, type names are not part of the wire ABI. Not even 720the names of built-in types. Clients should examine member 721"json-type" instead of hard-coding names of built-in types. 722 723 724== Code generation == 725 726Schemas are fed into five scripts to generate all the code/files that, 727paired with the core QAPI libraries, comprise everything required to 728take JSON commands read in by a Client JSON Protocol server, unmarshal 729the arguments into the underlying C types, call into the corresponding 730C function, map the response back to a Client JSON Protocol response 731to be returned to the user, and introspect the commands. 732 733As an example, we'll use the following schema, which describes a 734single complex user-defined type, along with command which takes a 735list of that type as a parameter, and returns a single element of that 736type. The user is responsible for writing the implementation of 737qmp_my_command(); everything else is produced by the generator. 738 739 $ cat example-schema.json 740 { 'struct': 'UserDefOne', 741 'data': { 'integer': 'int', '*string': 'str' } } 742 743 { 'command': 'my-command', 744 'data': { 'arg1': ['UserDefOne'] }, 745 'returns': 'UserDefOne' } 746 747 { 'event': 'MY_EVENT' } 748 749For a more thorough look at generated code, the testsuite includes 750tests/qapi-schema/qapi-schema-tests.json that covers more examples of 751what the generator will accept, and compiles the resulting C code as 752part of 'make check-unit'. 753 754=== scripts/qapi-types.py === 755 756Used to generate the C types defined by a schema, along with 757supporting code. The following files are created: 758 759$(prefix)qapi-types.h - C types corresponding to types defined in 760 the schema you pass in 761$(prefix)qapi-types.c - Cleanup functions for the above C types 762 763The $(prefix) is an optional parameter used as a namespace to keep the 764generated code from one schema/code-generation separated from others so code 765can be generated/used from multiple schemas without clobbering previously 766created code. 767 768Example: 769 770 $ python scripts/qapi-types.py --output-dir="qapi-generated" \ 771 --prefix="example-" example-schema.json 772 $ cat qapi-generated/example-qapi-types.h 773[Uninteresting stuff omitted...] 774 775 #ifndef EXAMPLE_QAPI_TYPES_H 776 #define EXAMPLE_QAPI_TYPES_H 777 778[Built-in types omitted...] 779 780 typedef struct UserDefOne UserDefOne; 781 782 typedef struct UserDefOneList UserDefOneList; 783 784 struct UserDefOne { 785 int64_t integer; 786 bool has_string; 787 char *string; 788 }; 789 790 void qapi_free_UserDefOne(UserDefOne *obj); 791 792 struct UserDefOneList { 793 UserDefOneList *next; 794 UserDefOne *value; 795 }; 796 797 void qapi_free_UserDefOneList(UserDefOneList *obj); 798 799 #endif 800 $ cat qapi-generated/example-qapi-types.c 801[Uninteresting stuff omitted...] 802 803 void qapi_free_UserDefOne(UserDefOne *obj) 804 { 805 QapiDeallocVisitor *qdv; 806 Visitor *v; 807 808 if (!obj) { 809 return; 810 } 811 812 qdv = qapi_dealloc_visitor_new(); 813 v = qapi_dealloc_get_visitor(qdv); 814 visit_type_UserDefOne(v, NULL, &obj, NULL); 815 qapi_dealloc_visitor_cleanup(qdv); 816 } 817 818 void qapi_free_UserDefOneList(UserDefOneList *obj) 819 { 820 QapiDeallocVisitor *qdv; 821 Visitor *v; 822 823 if (!obj) { 824 return; 825 } 826 827 qdv = qapi_dealloc_visitor_new(); 828 v = qapi_dealloc_get_visitor(qdv); 829 visit_type_UserDefOneList(v, NULL, &obj, NULL); 830 qapi_dealloc_visitor_cleanup(qdv); 831 } 832 833=== scripts/qapi-visit.py === 834 835Used to generate the visitor functions used to walk through and 836convert between a native QAPI C data structure and some other format 837(such as QObject); the generated functions are named visit_type_FOO() 838and visit_type_FOO_members(). 839 840The following files are generated: 841 842$(prefix)qapi-visit.c: visitor function for a particular C type, used 843 to automagically convert QObjects into the 844 corresponding C type and vice-versa, as well 845 as for deallocating memory for an existing C 846 type 847 848$(prefix)qapi-visit.h: declarations for previously mentioned visitor 849 functions 850 851Example: 852 853 $ python scripts/qapi-visit.py --output-dir="qapi-generated" 854 --prefix="example-" example-schema.json 855 $ cat qapi-generated/example-qapi-visit.h 856[Uninteresting stuff omitted...] 857 858 #ifndef EXAMPLE_QAPI_VISIT_H 859 #define EXAMPLE_QAPI_VISIT_H 860 861[Visitors for built-in types omitted...] 862 863 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); 864 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp); 865 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp); 866 867 #endif 868 $ cat qapi-generated/example-qapi-visit.c 869[Uninteresting stuff omitted...] 870 871 void visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp) 872 { 873 Error *err = NULL; 874 875 visit_type_int(v, "integer", &obj->integer, &err); 876 if (err) { 877 goto out; 878 } 879 if (visit_optional(v, "string", &obj->has_string)) { 880 visit_type_str(v, "string", &obj->string, &err); 881 if (err) { 882 goto out; 883 } 884 } 885 886 out: 887 error_propagate(errp, err); 888 } 889 890 void visit_type_UserDefOne(Visitor *v, const char *name, UserDefOne **obj, Error **errp) 891 { 892 Error *err = NULL; 893 894 visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), &err); 895 if (err) { 896 goto out; 897 } 898 if (!*obj) { 899 goto out_obj; 900 } 901 visit_type_UserDefOne_members(v, *obj, &err); 902 error_propagate(errp, err); 903 err = NULL; 904 out_obj: 905 visit_end_struct(v, &err); 906 out: 907 error_propagate(errp, err); 908 } 909 910 void visit_type_UserDefOneList(Visitor *v, const char *name, UserDefOneList **obj, Error **errp) 911 { 912 Error *err = NULL; 913 GenericList *i, **prev; 914 915 visit_start_list(v, name, &err); 916 if (err) { 917 goto out; 918 } 919 920 for (prev = (GenericList **)obj; 921 !err && (i = visit_next_list(v, prev, sizeof(**obj))) != NULL; 922 prev = &i) { 923 UserDefOneList *native_i = (UserDefOneList *)i; 924 visit_type_UserDefOne(v, NULL, &native_i->value, &err); 925 } 926 927 visit_end_list(v); 928 out: 929 error_propagate(errp, err); 930 } 931 932=== scripts/qapi-commands.py === 933 934Used to generate the marshaling/dispatch functions for the commands 935defined in the schema. The generated code implements 936qmp_marshal_COMMAND() (mentioned in qmp-commands.hx, and registered 937automatically), and declares qmp_COMMAND() that the user must 938implement. The following files are generated: 939 940$(prefix)qmp-marshal.c: command marshal/dispatch functions for each 941 QMP command defined in the schema. Functions 942 generated by qapi-visit.py are used to 943 convert QObjects received from the wire into 944 function parameters, and uses the same 945 visitor functions to convert native C return 946 values to QObjects from transmission back 947 over the wire. 948 949$(prefix)qmp-commands.h: Function prototypes for the QMP commands 950 specified in the schema. 951 952Example: 953 954 $ python scripts/qapi-commands.py --output-dir="qapi-generated" 955 --prefix="example-" example-schema.json 956 $ cat qapi-generated/example-qmp-commands.h 957[Uninteresting stuff omitted...] 958 959 #ifndef EXAMPLE_QMP_COMMANDS_H 960 #define EXAMPLE_QMP_COMMANDS_H 961 962 #include "example-qapi-types.h" 963 #include "qapi/qmp/qdict.h" 964 #include "qapi/error.h" 965 966 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); 967 968 #endif 969 $ cat qapi-generated/example-qmp-marshal.c 970[Uninteresting stuff omitted...] 971 972 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, QObject **ret_out, Error **errp) 973 { 974 Error *err = NULL; 975 QmpOutputVisitor *qov = qmp_output_visitor_new(); 976 QapiDeallocVisitor *qdv; 977 Visitor *v; 978 979 v = qmp_output_get_visitor(qov); 980 visit_type_UserDefOne(v, "unused", &ret_in, &err); 981 if (err) { 982 goto out; 983 } 984 *ret_out = qmp_output_get_qobject(qov); 985 986 out: 987 error_propagate(errp, err); 988 qmp_output_visitor_cleanup(qov); 989 qdv = qapi_dealloc_visitor_new(); 990 v = qapi_dealloc_get_visitor(qdv); 991 visit_type_UserDefOne(v, "unused", &ret_in, NULL); 992 qapi_dealloc_visitor_cleanup(qdv); 993 } 994 995 static void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) 996 { 997 Error *err = NULL; 998 UserDefOne *retval; 999 QmpInputVisitor *qiv = qmp_input_visitor_new_strict(QOBJECT(args)); 1000 QapiDeallocVisitor *qdv;
1001 Visitor *v; 1002 UserDefOneList *arg1 = NULL; 1003 1004 v = qmp_input_get_visitor(qiv); 1005 visit_type_UserDefOneList(v, "arg1", &arg1, &err); 1006 if (err) { 1007 goto out; 1008 } 1009 1010 retval = qmp_my_command(arg1, &err); 1011 if (err) { 1012 goto out; 1013 } 1014 1015 qmp_marshal_output_UserDefOne(retval, ret, &err); 1016 1017 out: 1018 error_propagate(errp, err); 1019 qmp_input_visitor_cleanup(qiv); 1020 qdv = qapi_dealloc_visitor_new(); 1021 v = qapi_dealloc_get_visitor(qdv); 1022 visit_type_UserDefOneList(v, "arg1", &arg1, NULL); 1023 qapi_dealloc_visitor_cleanup(qdv); 1024 } 1025 1026 static void qmp_init_marshal(void) 1027 { 1028 qmp_register_command("my-command", qmp_marshal_my_command, QCO_NO_OPTIONS); 1029 } 1030 1031 qapi_init(qmp_init_marshal); 1032 1033=== scripts/qapi-event.py === 1034 1035Used to generate the event-related C code defined by a schema, with 1036implementations for qapi_event_send_FOO(). The following files are 1037created: 1038 1039$(prefix)qapi-event.h - Function prototypes for each event type, plus an 1040 enumeration of all event names 1041$(prefix)qapi-event.c - Implementation of functions to send an event 1042 1043Example: 1044 1045 $ python scripts/qapi-event.py --output-dir="qapi-generated" 1046 --prefix="example-" example-schema.json 1047 $ cat qapi-generated/example-qapi-event.h 1048[Uninteresting stuff omitted...] 1049 1050 #ifndef EXAMPLE_QAPI_EVENT_H 1051 #define EXAMPLE_QAPI_EVENT_H 1052 1053 #include "qapi/error.h" 1054 #include "qapi/qmp/qdict.h" 1055 #include "example-qapi-types.h" 1056 1057 1058 void qapi_event_send_my_event(Error **errp); 1059 1060 typedef enum example_QAPIEvent { 1061 EXAMPLE_QAPI_EVENT_MY_EVENT = 0, 1062 EXAMPLE_QAPI_EVENT__MAX = 1, 1063 } example_QAPIEvent; 1064 1065 extern const char *const example_QAPIEvent_lookup[]; 1066 1067 #endif 1068 $ cat qapi-generated/example-qapi-event.c 1069[Uninteresting stuff omitted...] 1070 1071 void qapi_event_send_my_event(Error **errp) 1072 { 1073 QDict *qmp; 1074 Error *err = NULL; 1075 QMPEventFuncEmit emit; 1076 emit = qmp_event_get_func_emit(); 1077 if (!emit) { 1078 return; 1079 } 1080 1081 qmp = qmp_event_build_dict("MY_EVENT"); 1082 1083 emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &err); 1084 1085 error_propagate(errp, err); 1086 QDECREF(qmp); 1087 } 1088 1089 const char *const example_QAPIEvent_lookup[] = { 1090 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", 1091 [EXAMPLE_QAPI_EVENT__MAX] = NULL, 1092 }; 1093 1094=== scripts/qapi-introspect.py === 1095 1096Used to generate the introspection C code for a schema. The following 1097files are created: 1098 1099$(prefix)qmp-introspect.c - Defines a string holding a JSON 1100 description of the schema. 1101$(prefix)qmp-introspect.h - Declares the above string. 1102 1103Example: 1104 1105 $ python scripts/qapi-introspect.py --output-dir="qapi-generated" 1106 --prefix="example-" example-schema.json 1107 $ cat qapi-generated/example-qmp-introspect.h 1108[Uninteresting stuff omitted...] 1109 1110 #ifndef EXAMPLE_QMP_INTROSPECT_H 1111 #define EXAMPLE_QMP_INTROSPECT_H 1112 1113 extern const char example_qmp_schema_json[]; 1114 1115 #endif 1116 $ cat qapi-generated/example-qmp-introspect.c 1117[Uninteresting stuff omitted...] 1118 1119 const char example_qmp_schema_json[] = "[" 1120 "{\"arg-type\": \"0\", \"meta-type\": \"event\", \"name\": \"MY_EVENT\"}, " 1121 "{\"arg-type\": \"1\", \"meta-type\": \"command\", \"name\": \"my-command\", \"ret-type\": \"2\"}, " 1122 "{\"members\": [], \"meta-type\": \"object\", \"name\": \"0\"}, " 1123 "{\"members\": [{\"name\": \"arg1\", \"type\": \"[2]\"}], \"meta-type\": \"object\", \"name\": \"1\"}, " 1124 "{\"members\": [{\"name\": \"integer\", \"type\": \"int\"}, {\"default\": null, \"name\": \"string\", \"type\": \"str\"}], \"meta-type\": \"object\", \"name\": \"2\"}, " 1125 "{\"element-type\": \"2\", \"meta-type\": \"array\", \"name\": \"[2]\"}, " 1126 "{\"json-type\": \"int\", \"meta-type\": \"builtin\", \"name\": \"int\"}, " 1127 "{\"json-type\": \"string\", \"meta-type\": \"builtin\", \"name\": \"str\"}]"; 1128