1================================== 2How to use the QAPI code generator 3================================== 4 5.. 6 Copyright IBM Corp. 2011 7 Copyright (C) 2012-2016 Red Hat, Inc. 8 9 This work is licensed under the terms of the GNU GPL, version 2 or 10 later. See the COPYING file in the top-level directory. 11 12 13Introduction 14============ 15 16QAPI is a native C API within QEMU which provides management-level 17functionality to internal and external users. For external 18users/processes, this interface is made available by a JSON-based wire 19format for the QEMU Monitor Protocol (QMP) for controlling qemu, as 20well as the QEMU Guest Agent (QGA) for communicating with the guest. 21The remainder of this document uses "Client JSON Protocol" when 22referring to the wire contents of a QMP or QGA connection. 23 24To map between Client JSON Protocol interfaces and the native C API, 25we generate C code from a QAPI schema. This document describes the 26QAPI schema language, and how it gets mapped to the Client JSON 27Protocol and to C. It additionally provides guidance on maintaining 28Client JSON Protocol compatibility. 29 30 31The QAPI schema language 32======================== 33 34The QAPI schema defines the Client JSON Protocol's commands and 35events, as well as types used by them. Forward references are 36allowed. 37 38It is permissible for the schema to contain additional types not used 39by any commands or events, for the side effect of generated C code 40used internally. 41 42There are several kinds of types: simple types (a number of built-in 43types, such as ``int`` and ``str``; as well as enumerations), arrays, 44complex types (structs and two flavors of unions), and alternate types 45(a choice between other types). 46 47 48Schema syntax 49------------- 50 51Syntax is loosely based on `JSON <http://www.ietf.org/rfc/rfc8259.txt>`_. 52Differences: 53 54* Comments: start with a hash character (``#``) that is not part of a 55 string, and extend to the end of the line. 56 57* Strings are enclosed in ``'single quotes'``, not ``"double quotes"``. 58 59* Strings are restricted to printable ASCII, and escape sequences to 60 just ``\\``. 61 62* Numbers and ``null`` are not supported. 63 64A second layer of syntax defines the sequences of JSON texts that are 65a correctly structured QAPI schema. We provide a grammar for this 66syntax in an EBNF-like notation: 67 68* Production rules look like ``non-terminal = expression`` 69* Concatenation: expression ``A B`` matches expression ``A``, then ``B`` 70* Alternation: expression ``A | B`` matches expression ``A`` or ``B`` 71* Repetition: expression ``A...`` matches zero or more occurrences of 72 expression ``A`` 73* Repetition: expression ``A, ...`` matches zero or more occurrences of 74 expression ``A`` separated by ``,`` 75* Grouping: expression ``( A )`` matches expression ``A`` 76* JSON's structural characters are terminals: ``{ } [ ] : ,`` 77* JSON's literal names are terminals: ``false true`` 78* String literals enclosed in ``'single quotes'`` are terminal, and match 79 this JSON string, with a leading ``*`` stripped off 80* When JSON object member's name starts with ``*``, the member is 81 optional. 82* The symbol ``STRING`` is a terminal, and matches any JSON string 83* The symbol ``BOOL`` is a terminal, and matches JSON ``false`` or ``true`` 84* ALL-CAPS words other than ``STRING`` are non-terminals 85 86The order of members within JSON objects does not matter unless 87explicitly noted. 88 89A QAPI schema consists of a series of top-level expressions:: 90 91 SCHEMA = TOP-LEVEL-EXPR... 92 93The top-level expressions are all JSON objects. Code and 94documentation is generated in schema definition order. Code order 95should not matter. 96 97A top-level expressions is either a directive or a definition:: 98 99 TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION 100 101There are two kinds of directives and six kinds of definitions:: 102 103 DIRECTIVE = INCLUDE | PRAGMA 104 DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT 105 106These are discussed in detail below. 107 108 109Built-in Types 110-------------- 111 112The following types are predefined, and map to C as follows: 113 114 ============= ============== ============================================ 115 Schema C JSON 116 ============= ============== ============================================ 117 ``str`` ``char *`` any JSON string, UTF-8 118 ``number`` ``double`` any JSON number 119 ``int`` ``int64_t`` a JSON number without fractional part 120 that fits into the C integer type 121 ``int8`` ``int8_t`` likewise 122 ``int16`` ``int16_t`` likewise 123 ``int32`` ``int32_t`` likewise 124 ``int64`` ``int64_t`` likewise 125 ``uint8`` ``uint8_t`` likewise 126 ``uint16`` ``uint16_t`` likewise 127 ``uint32`` ``uint32_t`` likewise 128 ``uint64`` ``uint64_t`` likewise 129 ``size`` ``uint64_t`` like ``uint64_t``, except 130 ``StringInputVisitor`` accepts size suffixes 131 ``bool`` ``bool`` JSON ``true`` or ``false`` 132 ``null`` ``QNull *`` JSON ``null`` 133 ``any`` ``QObject *`` any JSON value 134 ``QType`` ``QType`` JSON string matching enum ``QType`` values 135 ============= ============== ============================================ 136 137 138Include directives 139------------------ 140 141Syntax:: 142 143 INCLUDE = { 'include': STRING } 144 145The QAPI schema definitions can be modularized using the 'include' directive:: 146 147 { 'include': 'path/to/file.json' } 148 149The directive is evaluated recursively, and include paths are relative 150to the file using the directive. Multiple includes of the same file 151are idempotent. 152 153As a matter of style, it is a good idea to have all files be 154self-contained, but at the moment, nothing prevents an included file 155from making a forward reference to a type that is only introduced by 156an outer file. The parser may be made stricter in the future to 157prevent incomplete include files. 158 159.. _pragma: 160 161Pragma directives 162----------------- 163 164Syntax:: 165 166 PRAGMA = { 'pragma': { 167 '*doc-required': BOOL, 168 '*command-name-exceptions': [ STRING, ... ], 169 '*command-returns-exceptions': [ STRING, ... ], 170 '*member-name-exceptions': [ STRING, ... ] } } 171 172The pragma directive lets you control optional generator behavior. 173 174Pragma's scope is currently the complete schema. Setting the same 175pragma to different values in parts of the schema doesn't work. 176 177Pragma 'doc-required' takes a boolean value. If true, documentation 178is required. Default is false. 179 180Pragma 'command-name-exceptions' takes a list of commands whose names 181may contain ``"_"`` instead of ``"-"``. Default is none. 182 183Pragma 'command-returns-exceptions' takes a list of commands that may 184violate the rules on permitted return types. Default is none. 185 186Pragma 'member-name-exceptions' takes a list of types whose member 187names may contain uppercase letters, and ``"_"`` instead of ``"-"``. 188Default is none. 189 190.. _ENUM-VALUE: 191 192Enumeration types 193----------------- 194 195Syntax:: 196 197 ENUM = { 'enum': STRING, 198 'data': [ ENUM-VALUE, ... ], 199 '*prefix': STRING, 200 '*if': COND, 201 '*features': FEATURES } 202 ENUM-VALUE = STRING 203 | { 'name': STRING, '*if': COND } 204 205Member 'enum' names the enum type. 206 207Each member of the 'data' array defines a value of the enumeration 208type. The form STRING is shorthand for :code:`{ 'name': STRING }`. The 209'name' values must be be distinct. 210 211Example:: 212 213 { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } 214 215Nothing prevents an empty enumeration, although it is probably not 216useful. 217 218On the wire, an enumeration type's value is represented by its 219(string) name. In C, it's represented by an enumeration constant. 220These are of the form PREFIX_NAME, where PREFIX is derived from the 221enumeration type's name, and NAME from the value's name. For the 222example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to 223VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The 224optional 'prefix' member overrides PREFIX. 225 226The generated C enumeration constants have values 0, 1, ..., N-1 (in 227QAPI schema order), where N is the number of values. There is an 228additional enumeration constant PREFIX__MAX with value N. 229 230Do not use string or an integer type when an enumeration type can do 231the job satisfactorily. 232 233The optional 'if' member specifies a conditional. See `Configuring the 234schema`_ below for more on this. 235 236The optional 'features' member specifies features. See Features_ 237below for more on this. 238 239 240.. _TYPE-REF: 241 242Type references and array types 243------------------------------- 244 245Syntax:: 246 247 TYPE-REF = STRING | ARRAY-TYPE 248 ARRAY-TYPE = [ STRING ] 249 250A string denotes the type named by the string. 251 252A one-element array containing a string denotes an array of the type 253named by the string. Example: ``['int']`` denotes an array of ``int``. 254 255 256Struct types 257------------ 258 259Syntax:: 260 261 STRUCT = { 'struct': STRING, 262 'data': MEMBERS, 263 '*base': STRING, 264 '*if': COND, 265 '*features': FEATURES } 266 MEMBERS = { MEMBER, ... } 267 MEMBER = STRING : TYPE-REF 268 | STRING : { 'type': TYPE-REF, 269 '*if': COND, 270 '*features': FEATURES } 271 272Member 'struct' names the struct type. 273 274Each MEMBER of the 'data' object defines a member of the struct type. 275 276.. _MEMBERS: 277 278The MEMBER's STRING name consists of an optional ``*`` prefix and the 279struct member name. If ``*`` is present, the member is optional. 280 281The MEMBER's value defines its properties, in particular its type. 282The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`. 283 284Example:: 285 286 { 'struct': 'MyType', 287 'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } } 288 289A struct type corresponds to a struct in C, and an object in JSON. 290The C struct's members are generated in QAPI schema order. 291 292The optional 'base' member names a struct type whose members are to be 293included in this type. They go first in the C struct. 294 295Example:: 296 297 { 'struct': 'BlockdevOptionsGenericFormat', 298 'data': { 'file': 'str' } } 299 { 'struct': 'BlockdevOptionsGenericCOWFormat', 300 'base': 'BlockdevOptionsGenericFormat', 301 'data': { '*backing': 'str' } } 302 303An example BlockdevOptionsGenericCOWFormat object on the wire could use 304both members like this:: 305 306 { "file": "/some/place/my-image", 307 "backing": "/some/place/my-backing-file" } 308 309The optional 'if' member specifies a conditional. See `Configuring 310the schema`_ below for more on this. 311 312The optional 'features' member specifies features. See Features_ 313below for more on this. 314 315 316Union types 317----------- 318 319Syntax:: 320 321 UNION = { 'union': STRING, 322 'data': BRANCHES, 323 '*if': COND, 324 '*features': FEATURES } 325 | { 'union': STRING, 326 'data': BRANCHES, 327 'base': ( MEMBERS | STRING ), 328 'discriminator': STRING, 329 '*if': COND, 330 '*features': FEATURES } 331 BRANCHES = { BRANCH, ... } 332 BRANCH = STRING : TYPE-REF 333 | STRING : { 'type': TYPE-REF, '*if': COND } 334 335Member 'union' names the union type. 336 337There are two flavors of union types: simple (no discriminator or 338base), and flat (both discriminator and base). 339 340Each BRANCH of the 'data' object defines a branch of the union. A 341union must have at least one branch. 342 343The BRANCH's STRING name is the branch name. 344 345The BRANCH's value defines the branch's properties, in particular its 346type. The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`. 347 348A simple union type defines a mapping from automatic discriminator 349values to data types like in this example:: 350 351 { 'struct': 'BlockdevOptionsFile', 'data': { 'filename': 'str' } } 352 { 'struct': 'BlockdevOptionsQcow2', 353 'data': { 'backing': 'str', '*lazy-refcounts': 'bool' } } 354 355 { 'union': 'BlockdevOptionsSimple', 356 'data': { 'file': 'BlockdevOptionsFile', 357 'qcow2': 'BlockdevOptionsQcow2' } } 358 359In the Client JSON Protocol, a simple union is represented by an 360object that contains the 'type' member as a discriminator, and a 361'data' member that is of the specified data type corresponding to the 362discriminator value, as in these examples:: 363 364 { "type": "file", "data": { "filename": "/some/place/my-image" } } 365 { "type": "qcow2", "data": { "backing": "/some/place/my-image", 366 "lazy-refcounts": true } } 367 368The generated C code uses a struct containing a union. Additionally, 369an implicit C enum 'NameKind' is created, corresponding to the union 370'Name', for accessing the various branches of the union. The value 371for each branch can be of any type. 372 373Flat unions permit arbitrary common members that occur in all variants 374of the union, not just a discriminator. Their discriminators need not 375be named 'type'. They also avoid nesting on the wire. 376 377The 'base' member defines the common members. If it is a MEMBERS_ 378object, it defines common members just like a struct type's 'data' 379member defines struct type members. If it is a STRING, it names a 380struct type whose members are the common members. 381 382All flat union branches must be `Struct types`_. 383 384In the Client JSON Protocol, a flat union is represented by an object 385with the common members (from the base type) and the selected branch's 386members. The two sets of member names must be disjoint. Member 387'discriminator' must name a non-optional enum-typed member of the base 388struct. 389 390The following example enhances the above simple union example by 391adding an optional common member 'read-only', renaming the 392discriminator to something more applicable than the simple union's 393default of 'type', and reducing the number of ``{}`` required on the wire:: 394 395 { 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] } 396 { 'union': 'BlockdevOptions', 397 'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' }, 398 'discriminator': 'driver', 399 'data': { 'file': 'BlockdevOptionsFile', 400 'qcow2': 'BlockdevOptionsQcow2' } } 401 402Resulting in these JSON objects:: 403 404 { "driver": "file", "read-only": true, 405 "filename": "/some/place/my-image" } 406 { "driver": "qcow2", "read-only": false, 407 "backing": "/some/place/my-image", "lazy-refcounts": true } 408 409Notice that in a flat union, the discriminator name is controlled by 410the user, but because it must map to a base member with enum type, the 411code generator ensures that branches match the existing values of the 412enum. The order of branches need not match the order of the enum 413values. The branches need not cover all possible enum values. 414Omitted enum values are still valid branches that add no additional 415members to the data type. In the resulting generated C data types, a 416flat union is represented as a struct with the base members in QAPI 417schema order, and then a union of structures for each branch of the 418struct. 419 420A simple union can always be re-written as a flat union where the base 421class has a single member named 'type', and where each branch of the 422union has a struct with a single member named 'data'. That is, :: 423 424 { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } 425 426is identical on the wire to:: 427 428 { 'enum': 'Enum', 'data': ['one', 'two'] } 429 { 'struct': 'Branch1', 'data': { 'data': 'str' } } 430 { 'struct': 'Branch2', 'data': { 'data': 'int' } } 431 { 'union': 'Flat', 'base': { 'type': 'Enum' }, 'discriminator': 'type', 432 'data': { 'one': 'Branch1', 'two': 'Branch2' } } 433 434The optional 'if' member specifies a conditional. See `Configuring 435the schema`_ below for more on this. 436 437The optional 'features' member specifies features. See Features_ 438below for more on this. 439 440 441Alternate types 442--------------- 443 444Syntax:: 445 446 ALTERNATE = { 'alternate': STRING, 447 'data': ALTERNATIVES, 448 '*if': COND, 449 '*features': FEATURES } 450 ALTERNATIVES = { ALTERNATIVE, ... } 451 ALTERNATIVE = STRING : STRING 452 | STRING : { 'type': STRING, '*if': COND } 453 454Member 'alternate' names the alternate type. 455 456Each ALTERNATIVE of the 'data' object defines a branch of the 457alternate. An alternate must have at least one branch. 458 459The ALTERNATIVE's STRING name is the branch name. 460 461The ALTERNATIVE's value defines the branch's properties, in particular 462its type. The form STRING is shorthand for :code:`{ 'type': STRING }`. 463 464Example:: 465 466 { 'alternate': 'BlockdevRef', 467 'data': { 'definition': 'BlockdevOptions', 468 'reference': 'str' } } 469 470An alternate type is like a union type, except there is no 471discriminator on the wire. Instead, the branch to use is inferred 472from the value. An alternate can only express a choice between types 473represented differently on the wire. 474 475If a branch is typed as the 'bool' built-in, the alternate accepts 476true and false; if it is typed as any of the various numeric 477built-ins, it accepts a JSON number; if it is typed as a 'str' 478built-in or named enum type, it accepts a JSON string; if it is typed 479as the 'null' built-in, it accepts JSON null; and if it is typed as a 480complex type (struct or union), it accepts a JSON object. 481 482The example alternate declaration above allows using both of the 483following example objects:: 484 485 { "file": "my_existing_block_device_id" } 486 { "file": { "driver": "file", 487 "read-only": false, 488 "filename": "/tmp/mydisk.qcow2" } } 489 490The optional 'if' member specifies a conditional. See `Configuring 491the schema`_ below for more on this. 492 493The optional 'features' member specifies features. See Features_ 494below for more on this. 495 496 497Commands 498-------- 499 500Syntax:: 501 502 COMMAND = { 'command': STRING, 503 ( 504 '*data': ( MEMBERS | STRING ), 505 | 506 'data': STRING, 507 'boxed': true, 508 ) 509 '*returns': TYPE-REF, 510 '*success-response': false, 511 '*gen': false, 512 '*allow-oob': true, 513 '*allow-preconfig': true, 514 '*coroutine': true, 515 '*if': COND, 516 '*features': FEATURES } 517 518Member 'command' names the command. 519 520Member 'data' defines the arguments. It defaults to an empty MEMBERS_ 521object. 522 523If 'data' is a MEMBERS_ object, then MEMBERS defines arguments just 524like a struct type's 'data' defines struct type members. 525 526If 'data' is a STRING, then STRING names a complex type whose members 527are the arguments. A union type requires ``'boxed': true``. 528 529Member 'returns' defines the command's return type. It defaults to an 530empty struct type. It must normally be a complex type or an array of 531a complex type. To return anything else, the command must be listed 532in pragma 'commands-returns-exceptions'. If you do this, extending 533the command to return additional information will be harder. Use of 534the pragma for new commands is strongly discouraged. 535 536A command's error responses are not specified in the QAPI schema. 537Error conditions should be documented in comments. 538 539In the Client JSON Protocol, the value of the "execute" or "exec-oob" 540member is the command name. The value of the "arguments" member then 541has to conform to the arguments, and the value of the success 542response's "return" member will conform to the return type. 543 544Some example commands:: 545 546 { 'command': 'my-first-command', 547 'data': { 'arg1': 'str', '*arg2': 'str' } } 548 { 'struct': 'MyType', 'data': { '*value': 'str' } } 549 { 'command': 'my-second-command', 550 'returns': [ 'MyType' ] } 551 552which would validate this Client JSON Protocol transaction:: 553 554 => { "execute": "my-first-command", 555 "arguments": { "arg1": "hello" } } 556 <= { "return": { } } 557 => { "execute": "my-second-command" } 558 <= { "return": [ { "value": "one" }, { } ] } 559 560The generator emits a prototype for the C function implementing the 561command. The function itself needs to be written by hand. See 562section `Code generated for commands`_ for examples. 563 564The function returns the return type. When member 'boxed' is absent, 565it takes the command arguments as arguments one by one, in QAPI schema 566order. Else it takes them wrapped in the C struct generated for the 567complex argument type. It takes an additional ``Error **`` argument in 568either case. 569 570The generator also emits a marshalling function that extracts 571arguments for the user's function out of an input QDict, calls the 572user's function, and if it succeeded, builds an output QObject from 573its return value. This is for use by the QMP monitor core. 574 575In rare cases, QAPI cannot express a type-safe representation of a 576corresponding Client JSON Protocol command. You then have to suppress 577generation of a marshalling function by including a member 'gen' with 578boolean value false, and instead write your own function. For 579example:: 580 581 { 'command': 'netdev_add', 582 'data': {'type': 'str', 'id': 'str'}, 583 'gen': false } 584 585Please try to avoid adding new commands that rely on this, and instead 586use type-safe unions. 587 588Normally, the QAPI schema is used to describe synchronous exchanges, 589where a response is expected. But in some cases, the action of a 590command is expected to change state in a way that a successful 591response is not possible (although the command will still return an 592error object on failure). When a successful reply is not possible, 593the command definition includes the optional member 'success-response' 594with boolean value false. So far, only QGA makes use of this member. 595 596Member 'allow-oob' declares whether the command supports out-of-band 597(OOB) execution. It defaults to false. For example:: 598 599 { 'command': 'migrate_recover', 600 'data': { 'uri': 'str' }, 'allow-oob': true } 601 602See qmp-spec.txt for out-of-band execution syntax and semantics. 603 604Commands supporting out-of-band execution can still be executed 605in-band. 606 607When a command is executed in-band, its handler runs in the main 608thread with the BQL held. 609 610When a command is executed out-of-band, its handler runs in a 611dedicated monitor I/O thread with the BQL *not* held. 612 613An OOB-capable command handler must satisfy the following conditions: 614 615- It terminates quickly. 616- It does not invoke system calls that may block. 617- It does not access guest RAM that may block when userfaultfd is 618 enabled for postcopy live migration. 619- It takes only "fast" locks, i.e. all critical sections protected by 620 any lock it takes also satisfy the conditions for OOB command 621 handler code. 622 623The restrictions on locking limit access to shared state. Such access 624requires synchronization, but OOB commands can't take the BQL or any 625other "slow" lock. 626 627When in doubt, do not implement OOB execution support. 628 629Member 'allow-preconfig' declares whether the command is available 630before the machine is built. It defaults to false. For example:: 631 632 { 'enum': 'QMPCapability', 633 'data': [ 'oob' ] } 634 { 'command': 'qmp_capabilities', 635 'data': { '*enable': [ 'QMPCapability' ] }, 636 'allow-preconfig': true } 637 638QMP is available before the machine is built only when QEMU was 639started with --preconfig. 640 641Member 'coroutine' tells the QMP dispatcher whether the command handler 642is safe to be run in a coroutine. It defaults to false. If it is true, 643the command handler is called from coroutine context and may yield while 644waiting for an external event (such as I/O completion) in order to avoid 645blocking the guest and other background operations. 646 647Coroutine safety can be hard to prove, similar to thread safety. Common 648pitfalls are: 649 650- The global mutex isn't held across ``qemu_coroutine_yield()``, so 651 operations that used to assume that they execute atomically may have 652 to be more careful to protect against changes in the global state. 653 654- Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in 655 coroutine context and can easily lead to deadlocks. They should be 656 replaced by yielding and reentering the coroutine when the condition 657 becomes false. 658 659Since the command handler may assume coroutine context, any callers 660other than the QMP dispatcher must also call it in coroutine context. 661In particular, HMP commands calling such a QMP command handler must be 662marked ``.coroutine = true`` in hmp-commands.hx. 663 664It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true`` 665for a command. We don't currently have a use case for both together and 666without a use case, it's not entirely clear what the semantics should 667be. 668 669The optional 'if' member specifies a conditional. See `Configuring 670the schema`_ below for more on this. 671 672The optional 'features' member specifies features. See Features_ 673below for more on this. 674 675 676Events 677------ 678 679Syntax:: 680 681 EVENT = { 'event': STRING, 682 ( 683 '*data': ( MEMBERS | STRING ), 684 | 685 'data': STRING, 686 'boxed': true, 687 ) 688 '*if': COND, 689 '*features': FEATURES } 690 691Member 'event' names the event. This is the event name used in the 692Client JSON Protocol. 693 694Member 'data' defines the event-specific data. It defaults to an 695empty MEMBERS object. 696 697If 'data' is a MEMBERS object, then MEMBERS defines event-specific 698data just like a struct type's 'data' defines struct type members. 699 700If 'data' is a STRING, then STRING names a complex type whose members 701are the event-specific data. A union type requires ``'boxed': true``. 702 703An example event is:: 704 705 { 'event': 'EVENT_C', 706 'data': { '*a': 'int', 'b': 'str' } } 707 708Resulting in this JSON object:: 709 710 { "event": "EVENT_C", 711 "data": { "b": "test string" }, 712 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } 713 714The generator emits a function to send the event. When member 'boxed' 715is absent, it takes event-specific data one by one, in QAPI schema 716order. Else it takes them wrapped in the C struct generated for the 717complex type. See section `Code generated for events`_ for examples. 718 719The optional 'if' member specifies a conditional. See `Configuring 720the schema`_ below for more on this. 721 722The optional 'features' member specifies features. See Features_ 723below for more on this. 724 725 726.. _FEATURE: 727 728Features 729-------- 730 731Syntax:: 732 733 FEATURES = [ FEATURE, ... ] 734 FEATURE = STRING 735 | { 'name': STRING, '*if': COND } 736 737Sometimes, the behaviour of QEMU changes compatibly, but without a 738change in the QMP syntax (usually by allowing values or operations 739that previously resulted in an error). QMP clients may still need to 740know whether the extension is available. 741 742For this purpose, a list of features can be specified for a command or 743struct type. Each list member can either be ``{ 'name': STRING, '*if': 744COND }``, or STRING, which is shorthand for ``{ 'name': STRING }``. 745 746The optional 'if' member specifies a conditional. See `Configuring 747the schema`_ below for more on this. 748 749Example:: 750 751 { 'struct': 'TestType', 752 'data': { 'number': 'int' }, 753 'features': [ 'allow-negative-numbers' ] } 754 755The feature strings are exposed to clients in introspection, as 756explained in section `Client JSON Protocol introspection`_. 757 758Intended use is to have each feature string signal that this build of 759QEMU shows a certain behaviour. 760 761 762Special features 763~~~~~~~~~~~~~~~~ 764 765Feature "deprecated" marks a command, event, or struct member as 766deprecated. It is not supported elsewhere so far. 767 768 769Naming rules and reserved names 770------------------------------- 771 772All names must begin with a letter, and contain only ASCII letters, 773digits, hyphen, and underscore. There are two exceptions: enum values 774may start with a digit, and names that are downstream extensions (see 775section `Downstream extensions`_) start with underscore. 776 777Names beginning with ``q_`` are reserved for the generator, which uses 778them for munging QMP names that resemble C keywords or other 779problematic strings. For example, a member named ``default`` in qapi 780becomes ``q_default`` in the generated C code. 781 782Types, commands, and events share a common namespace. Therefore, 783generally speaking, type definitions should always use CamelCase for 784user-defined type names, while built-in types are lowercase. 785 786Type names ending with ``Kind`` or ``List`` are reserved for the 787generator, which uses them for implicit union enums and array types, 788respectively. 789 790Command names, and member names within a type, should be all lower 791case with words separated by a hyphen. However, some existing older 792commands and complex types use underscore; when extending them, 793consistency is preferred over blindly avoiding underscore. 794 795Event names should be ALL_CAPS with words separated by underscore. 796 797Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved 798for the generator, which uses them for unions and for tracking 799optional members. 800 801Any name (command, event, type, member, or enum value) beginning with 802``x-`` is marked experimental, and may be withdrawn or changed 803incompatibly in a future release. 804 805Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let 806you violate naming rules. Use for new code is strongly discouraged. See 807`Pragma directives`_ for details. 808 809 810Downstream extensions 811--------------------- 812 813QAPI schema names that are externally visible, say in the Client JSON 814Protocol, need to be managed with care. Names starting with a 815downstream prefix of the form __RFQDN_ are reserved for the downstream 816who controls the valid, reverse fully qualified domain name RFQDN. 817RFQDN may only contain ASCII letters, digits, hyphen and period. 818 819Example: Red Hat, Inc. controls redhat.com, and may therefore add a 820downstream command ``__com.redhat_drive-mirror``. 821 822 823Configuring the schema 824---------------------- 825 826Syntax:: 827 828 COND = STRING 829 | [ STRING, ... ] 830 831All definitions take an optional 'if' member. Its value must be a 832string or a list of strings. A string is shorthand for a list 833containing just that string. The code generated for the definition 834will then be guarded by #if STRING for each STRING in the COND list. 835 836Example: a conditional struct :: 837 838 { 'struct': 'IfStruct', 'data': { 'foo': 'int' }, 839 'if': ['defined(CONFIG_FOO)', 'defined(HAVE_BAR)'] } 840 841gets its generated code guarded like this:: 842 843 #if defined(CONFIG_FOO) 844 #if defined(HAVE_BAR) 845 ... generated code ... 846 #endif /* defined(HAVE_BAR) */ 847 #endif /* defined(CONFIG_FOO) */ 848 849Individual members of complex types, commands arguments, and 850event-specific data can also be made conditional. This requires the 851longhand form of MEMBER. 852 853Example: a struct type with unconditional member 'foo' and conditional 854member 'bar' :: 855 856 { 'struct': 'IfStruct', 'data': 857 { 'foo': 'int', 858 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } } 859 860A union's discriminator may not be conditional. 861 862Likewise, individual enumeration values be conditional. This requires 863the longhand form of ENUM-VALUE_. 864 865Example: an enum type with unconditional value 'foo' and conditional 866value 'bar' :: 867 868 { 'enum': 'IfEnum', 'data': 869 [ 'foo', 870 { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] } 871 872Likewise, features can be conditional. This requires the longhand 873form of FEATURE_. 874 875Example: a struct with conditional feature 'allow-negative-numbers' :: 876 877 { 'struct': 'TestType', 878 'data': { 'number': 'int' }, 879 'features': [ { 'name': 'allow-negative-numbers', 880 'if': 'defined(IFCOND)' } ] } 881 882Please note that you are responsible to ensure that the C code will 883compile with an arbitrary combination of conditions, since the 884generator is unable to check it at this point. 885 886The conditions apply to introspection as well, i.e. introspection 887shows a conditional entity only when the condition is satisfied in 888this particular build. 889 890 891Documentation comments 892---------------------- 893 894A multi-line comment that starts and ends with a ``##`` line is a 895documentation comment. 896 897If the documentation comment starts like :: 898 899 ## 900 # @SYMBOL: 901 902it documents the definition of SYMBOL, else it's free-form 903documentation. 904 905See below for more on `Definition documentation`_. 906 907Free-form documentation may be used to provide additional text and 908structuring content. 909 910 911Headings and subheadings 912~~~~~~~~~~~~~~~~~~~~~~~~ 913 914A free-form documentation comment containing a line which starts with 915some ``=`` symbols and then a space defines a section heading:: 916 917 ## 918 # = This is a top level heading 919 # 920 # This is a free-form comment which will go under the 921 # top level heading. 922 ## 923 924 ## 925 # == This is a second level heading 926 ## 927 928A heading line must be the first line of the documentation 929comment block. 930 931Section headings must always be correctly nested, so you can only 932define a third-level heading inside a second-level heading, and so on. 933 934 935Documentation markup 936~~~~~~~~~~~~~~~~~~~~ 937 938Documentation comments can use most rST markup. In particular, 939a ``::`` literal block can be used for examples:: 940 941 # :: 942 # 943 # Text of the example, may span 944 # multiple lines 945 946``*`` starts an itemized list:: 947 948 # * First item, may span 949 # multiple lines 950 # * Second item 951 952You can also use ``-`` instead of ``*``. 953 954A decimal number followed by ``.`` starts a numbered list:: 955 956 # 1. First item, may span 957 # multiple lines 958 # 2. Second item 959 960The actual number doesn't matter. 961 962Lists of either kind must be preceded and followed by a blank line. 963If a list item's text spans multiple lines, then the second and 964subsequent lines must be correctly indented to line up with the 965first character of the first line. 966 967The usual ****strong****, *\*emphasized\** and ````literal```` markup 968should be used. If you need a single literal ``*``, you will need to 969backslash-escape it. As an extension beyond the usual rST syntax, you 970can also use ``@foo`` to reference a name in the schema; this is rendered 971the same way as ````foo````. 972 973Example:: 974 975 ## 976 # Some text foo with **bold** and *emphasis* 977 # 1. with a list 978 # 2. like that 979 # 980 # And some code: 981 # 982 # :: 983 # 984 # $ echo foo 985 # -> do this 986 # <- get that 987 ## 988 989 990Definition documentation 991~~~~~~~~~~~~~~~~~~~~~~~~ 992 993Definition documentation, if present, must immediately precede the 994definition it documents. 995 996When documentation is required (see pragma_ 'doc-required'), every 997definition must have documentation. 998 999Definition documentation starts with a line naming the definition, 1000followed by an optional overview, a description of each argument (for 1001commands and events), member (for structs and unions), branch (for 1002alternates), or value (for enums), and finally optional tagged 1003sections. 1004 1005Descriptions of arguments can span multiple lines. The description 1006text can start on the line following the '\@argname:', in which case it 1007must not be indented at all. It can also start on the same line as 1008the '\@argname:'. In this case if it spans multiple lines then second 1009and subsequent lines must be indented to line up with the first 1010character of the first line of the description:: 1011 1012 # @argone: 1013 # This is a two line description 1014 # in the first style. 1015 # 1016 # @argtwo: This is a two line description 1017 # in the second style. 1018 1019The number of spaces between the ':' and the text is not significant. 1020 1021.. admonition:: FIXME 1022 1023 The parser accepts these things in almost any order. 1024 1025.. admonition:: FIXME 1026 1027 union branches should be described, too. 1028 1029Extensions added after the definition was first released carry a 1030'(since x.y.z)' comment. 1031 1032A tagged section starts with one of the following words: 1033"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". 1034The section ends with the start of a new section. 1035 1036The text of a section can start on a new line, in 1037which case it must not be indented at all. It can also start 1038on the same line as the 'Note:', 'Returns:', etc tag. In this 1039case if it spans multiple lines then second and subsequent 1040lines must be indented to match the first, in the same way as 1041multiline argument descriptions. 1042 1043A 'Since: x.y.z' tagged section lists the release that introduced the 1044definition. 1045 1046The text of a section can start on a new line, in 1047which case it must not be indented at all. It can also start 1048on the same line as the 'Note:', 'Returns:', etc tag. In this 1049case if it spans multiple lines then second and subsequent 1050lines must be indented to match the first. 1051 1052An 'Example' or 'Examples' section is automatically rendered 1053entirely as literal fixed-width text. In other sections, 1054the text is formatted, and rST markup can be used. 1055 1056For example:: 1057 1058 ## 1059 # @BlockStats: 1060 # 1061 # Statistics of a virtual block device or a block backing device. 1062 # 1063 # @device: If the stats are for a virtual block device, the name 1064 # corresponding to the virtual block device. 1065 # 1066 # @node-name: The node name of the device. (since 2.3) 1067 # 1068 # ... more members ... 1069 # 1070 # Since: 0.14.0 1071 ## 1072 { 'struct': 'BlockStats', 1073 'data': {'*device': 'str', '*node-name': 'str', 1074 ... more members ... } } 1075 1076 ## 1077 # @query-blockstats: 1078 # 1079 # Query the @BlockStats for all virtual block devices. 1080 # 1081 # @query-nodes: If true, the command will query all the 1082 # block nodes ... explain, explain ... (since 2.3) 1083 # 1084 # Returns: A list of @BlockStats for each virtual block devices. 1085 # 1086 # Since: 0.14.0 1087 # 1088 # Example: 1089 # 1090 # -> { "execute": "query-blockstats" } 1091 # <- { 1092 # ... lots of output ... 1093 # } 1094 # 1095 ## 1096 { 'command': 'query-blockstats', 1097 'data': { '*query-nodes': 'bool' }, 1098 'returns': ['BlockStats'] } 1099 1100 1101Client JSON Protocol introspection 1102================================== 1103 1104Clients of a Client JSON Protocol commonly need to figure out what 1105exactly the server (QEMU) supports. 1106 1107For this purpose, QMP provides introspection via command 1108query-qmp-schema. QGA currently doesn't support introspection. 1109 1110While Client JSON Protocol wire compatibility should be maintained 1111between qemu versions, we cannot make the same guarantees for 1112introspection stability. For example, one version of qemu may provide 1113a non-variant optional member of a struct, and a later version rework 1114the member to instead be non-optional and associated with a variant. 1115Likewise, one version of qemu may list a member with open-ended type 1116'str', and a later version could convert it to a finite set of strings 1117via an enum type; or a member may be converted from a specific type to 1118an alternate that represents a choice between the original type and 1119something else. 1120 1121query-qmp-schema returns a JSON array of SchemaInfo objects. These 1122objects together describe the wire ABI, as defined in the QAPI schema. 1123There is no specified order to the SchemaInfo objects returned; a 1124client must search for a particular name throughout the entire array 1125to learn more about that name, but is at least guaranteed that there 1126will be no collisions between type, command, and event names. 1127 1128However, the SchemaInfo can't reflect all the rules and restrictions 1129that apply to QMP. It's interface introspection (figuring out what's 1130there), not interface specification. The specification is in the QAPI 1131schema. To understand how QMP is to be used, you need to study the 1132QAPI schema. 1133 1134Like any other command, query-qmp-schema is itself defined in the QAPI 1135schema, along with the SchemaInfo type. This text attempts to give an 1136overview how things work. For details you need to consult the QAPI 1137schema. 1138 1139SchemaInfo objects have common members "name", "meta-type", 1140"features", and additional variant members depending on the value of 1141meta-type. 1142 1143Each SchemaInfo object describes a wire ABI entity of a certain 1144meta-type: a command, event or one of several kinds of type. 1145 1146SchemaInfo for commands and events have the same name as in the QAPI 1147schema. 1148 1149Command and event names are part of the wire ABI, but type names are 1150not. Therefore, the SchemaInfo for types have auto-generated 1151meaningless names. For readability, the examples in this section use 1152meaningful type names instead. 1153 1154Optional member "features" exposes the entity's feature strings as a 1155JSON array of strings. 1156 1157To examine a type, start with a command or event using it, then follow 1158references by name. 1159 1160QAPI schema definitions not reachable that way are omitted. 1161 1162The SchemaInfo for a command has meta-type "command", and variant 1163members "arg-type", "ret-type" and "allow-oob". On the wire, the 1164"arguments" member of a client's "execute" command must conform to the 1165object type named by "arg-type". The "return" member that the server 1166passes in a success response conforms to the type named by "ret-type". 1167When "allow-oob" is true, it means the command supports out-of-band 1168execution. It defaults to false. 1169 1170If the command takes no arguments, "arg-type" names an object type 1171without members. Likewise, if the command returns nothing, "ret-type" 1172names an object type without members. 1173 1174Example: the SchemaInfo for command query-qmp-schema :: 1175 1176 { "name": "query-qmp-schema", "meta-type": "command", 1177 "arg-type": "q_empty", "ret-type": "SchemaInfoList" } 1178 1179 Type "q_empty" is an automatic object type without members, and type 1180 "SchemaInfoList" is the array of SchemaInfo type. 1181 1182The SchemaInfo for an event has meta-type "event", and variant member 1183"arg-type". On the wire, a "data" member that the server passes in an 1184event conforms to the object type named by "arg-type". 1185 1186If the event carries no additional information, "arg-type" names an 1187object type without members. The event may not have a data member on 1188the wire then. 1189 1190Each command or event defined with 'data' as MEMBERS object in the 1191QAPI schema implicitly defines an object type. 1192 1193Example: the SchemaInfo for EVENT_C from section Events_ :: 1194 1195 { "name": "EVENT_C", "meta-type": "event", 1196 "arg-type": "q_obj-EVENT_C-arg" } 1197 1198 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with 1199 the two members from the event's definition. 1200 1201The SchemaInfo for struct and union types has meta-type "object". 1202 1203The SchemaInfo for a struct type has variant member "members". 1204 1205The SchemaInfo for a union type additionally has variant members "tag" 1206and "variants". 1207 1208"members" is a JSON array describing the object's common members, if 1209any. Each element is a JSON object with members "name" (the member's 1210name), "type" (the name of its type), and optionally "default". The 1211member is optional if "default" is present. Currently, "default" can 1212only have value null. Other values are reserved for future 1213extensions. The "members" array is in no particular order; clients 1214must search the entire object when learning whether a particular 1215member is supported. 1216 1217Example: the SchemaInfo for MyType from section `Struct types`_ :: 1218 1219 { "name": "MyType", "meta-type": "object", 1220 "members": [ 1221 { "name": "member1", "type": "str" }, 1222 { "name": "member2", "type": "int" }, 1223 { "name": "member3", "type": "str", "default": null } ] } 1224 1225"features" exposes the command's feature strings as a JSON array of 1226strings. 1227 1228Example: the SchemaInfo for TestType from section Features_:: 1229 1230 { "name": "TestType", "meta-type": "object", 1231 "members": [ 1232 { "name": "number", "type": "int" } ], 1233 "features": ["allow-negative-numbers"] } 1234 1235"tag" is the name of the common member serving as type tag. 1236"variants" is a JSON array describing the object's variant members. 1237Each element is a JSON object with members "case" (the value of type 1238tag this element applies to) and "type" (the name of an object type 1239that provides the variant members for this type tag value). The 1240"variants" array is in no particular order, and is not guaranteed to 1241list cases in the same order as the corresponding "tag" enum type. 1242 1243Example: the SchemaInfo for flat union BlockdevOptions from section 1244`Union types`_ :: 1245 1246 { "name": "BlockdevOptions", "meta-type": "object", 1247 "members": [ 1248 { "name": "driver", "type": "BlockdevDriver" }, 1249 { "name": "read-only", "type": "bool", "default": null } ], 1250 "tag": "driver", 1251 "variants": [ 1252 { "case": "file", "type": "BlockdevOptionsFile" }, 1253 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] } 1254 1255Note that base types are "flattened": its members are included in the 1256"members" array. 1257 1258A simple union implicitly defines an enumeration type for its implicit 1259discriminator (called "type" on the wire, see section `Union types`_). 1260 1261A simple union implicitly defines an object type for each of its 1262variants. 1263 1264Example: the SchemaInfo for simple union BlockdevOptionsSimple from section 1265`Union types`_ :: 1266 1267 { "name": "BlockdevOptionsSimple", "meta-type": "object", 1268 "members": [ 1269 { "name": "type", "type": "BlockdevOptionsSimpleKind" } ], 1270 "tag": "type", 1271 "variants": [ 1272 { "case": "file", "type": "q_obj-BlockdevOptionsFile-wrapper" }, 1273 { "case": "qcow2", "type": "q_obj-BlockdevOptionsQcow2-wrapper" } ] } 1274 1275 Enumeration type "BlockdevOptionsSimpleKind" and the object types 1276 "q_obj-BlockdevOptionsFile-wrapper", "q_obj-BlockdevOptionsQcow2-wrapper" 1277 are implicitly defined. 1278 1279The SchemaInfo for an alternate type has meta-type "alternate", and 1280variant member "members". "members" is a JSON array. Each element is 1281a JSON object with member "type", which names a type. Values of the 1282alternate type conform to exactly one of its member types. There is 1283no guarantee on the order in which "members" will be listed. 1284 1285Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ :: 1286 1287 { "name": "BlockdevRef", "meta-type": "alternate", 1288 "members": [ 1289 { "type": "BlockdevOptions" }, 1290 { "type": "str" } ] } 1291 1292The SchemaInfo for an array type has meta-type "array", and variant 1293member "element-type", which names the array's element type. Array 1294types are implicitly defined. For convenience, the array's name may 1295resemble the element type; however, clients should examine member 1296"element-type" instead of making assumptions based on parsing member 1297"name". 1298 1299Example: the SchemaInfo for ['str'] :: 1300 1301 { "name": "[str]", "meta-type": "array", 1302 "element-type": "str" } 1303 1304The SchemaInfo for an enumeration type has meta-type "enum" and 1305variant member "values". The values are listed in no particular 1306order; clients must search the entire enum when learning whether a 1307particular value is supported. 1308 1309Example: the SchemaInfo for MyEnum from section `Enumeration types`_ :: 1310 1311 { "name": "MyEnum", "meta-type": "enum", 1312 "values": [ "value1", "value2", "value3" ] } 1313 1314The SchemaInfo for a built-in type has the same name as the type in 1315the QAPI schema (see section `Built-in Types`_), with one exception 1316detailed below. It has variant member "json-type" that shows how 1317values of this type are encoded on the wire. 1318 1319Example: the SchemaInfo for str :: 1320 1321 { "name": "str", "meta-type": "builtin", "json-type": "string" } 1322 1323The QAPI schema supports a number of integer types that only differ in 1324how they map to C. They are identical as far as SchemaInfo is 1325concerned. Therefore, they get all mapped to a single type "int" in 1326SchemaInfo. 1327 1328As explained above, type names are not part of the wire ABI. Not even 1329the names of built-in types. Clients should examine member 1330"json-type" instead of hard-coding names of built-in types. 1331 1332 1333Compatibility considerations 1334============================ 1335 1336Maintaining backward compatibility at the Client JSON Protocol level 1337while evolving the schema requires some care. This section is about 1338syntactic compatibility, which is necessary, but not sufficient, for 1339actual compatibility. 1340 1341Clients send commands with argument data, and receive command 1342responses with return data and events with event data. 1343 1344Adding opt-in functionality to the send direction is backwards 1345compatible: adding commands, optional arguments, enumeration values, 1346union and alternate branches; turning an argument type into an 1347alternate of that type; making mandatory arguments optional. Clients 1348oblivious of the new functionality continue to work. 1349 1350Incompatible changes include removing commands, command arguments, 1351enumeration values, union and alternate branches, adding mandatory 1352command arguments, and making optional arguments mandatory. 1353 1354The specified behavior of an absent optional argument should remain 1355the same. With proper documentation, this policy still allows some 1356flexibility; for example, when an optional 'buffer-size' argument is 1357specified to default to a sensible buffer size, the actual default 1358value can still be changed. The specified default behavior is not the 1359exact size of the buffer, only that the default size is sensible. 1360 1361Adding functionality to the receive direction is generally backwards 1362compatible: adding events, adding return and event data members. 1363Clients are expected to ignore the ones they don't know. 1364 1365Removing "unreachable" stuff like events that can't be triggered 1366anymore, optional return or event data members that can't be sent 1367anymore, and return or event data member (enumeration) values that 1368can't be sent anymore makes no difference to clients, except for 1369introspection. The latter can conceivably confuse clients, so tread 1370carefully. 1371 1372Incompatible changes include removing return and event data members. 1373 1374Any change to a command definition's 'data' or one of the types used 1375there (recursively) needs to consider send direction compatibility. 1376 1377Any change to a command definition's 'return', an event definition's 1378'data', or one of the types used there (recursively) needs to consider 1379receive direction compatibility. 1380 1381Any change to types used in both contexts need to consider both. 1382 1383Enumeration type values and complex and alternate type members may be 1384reordered freely. For enumerations and alternate types, this doesn't 1385affect the wire encoding. For complex types, this might make the 1386implementation emit JSON object members in a different order, which 1387the Client JSON Protocol permits. 1388 1389Since type names are not visible in the Client JSON Protocol, types 1390may be freely renamed. Even certain refactorings are invisible, such 1391as splitting members from one type into a common base type. 1392 1393 1394Code generation 1395=============== 1396 1397The QAPI code generator qapi-gen.py generates code and documentation 1398from the schema. Together with the core QAPI libraries, this code 1399provides everything required to take JSON commands read in by a Client 1400JSON Protocol server, unmarshal the arguments into the underlying C 1401types, call into the corresponding C function, map the response back 1402to a Client JSON Protocol response to be returned to the user, and 1403introspect the commands. 1404 1405As an example, we'll use the following schema, which describes a 1406single complex user-defined type, along with command which takes a 1407list of that type as a parameter, and returns a single element of that 1408type. The user is responsible for writing the implementation of 1409qmp_my_command(); everything else is produced by the generator. :: 1410 1411 $ cat example-schema.json 1412 { 'struct': 'UserDefOne', 1413 'data': { 'integer': 'int', '*string': 'str' } } 1414 1415 { 'command': 'my-command', 1416 'data': { 'arg1': ['UserDefOne'] }, 1417 'returns': 'UserDefOne' } 1418 1419 { 'event': 'MY_EVENT' } 1420 1421We run qapi-gen.py like this:: 1422 1423 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \ 1424 --prefix="example-" example-schema.json 1425 1426For a more thorough look at generated code, the testsuite includes 1427tests/qapi-schema/qapi-schema-tests.json that covers more examples of 1428what the generator will accept, and compiles the resulting C code as 1429part of 'make check-unit'. 1430 1431 1432Code generated for QAPI types 1433----------------------------- 1434 1435The following files are created: 1436 1437 ``$(prefix)qapi-types.h`` 1438 C types corresponding to types defined in the schema 1439 1440 ``$(prefix)qapi-types.c`` 1441 Cleanup functions for the above C types 1442 1443The $(prefix) is an optional parameter used as a namespace to keep the 1444generated code from one schema/code-generation separated from others so code 1445can be generated/used from multiple schemas without clobbering previously 1446created code. 1447 1448Example:: 1449 1450 $ cat qapi-generated/example-qapi-types.h 1451 [Uninteresting stuff omitted...] 1452 1453 #ifndef EXAMPLE_QAPI_TYPES_H 1454 #define EXAMPLE_QAPI_TYPES_H 1455 1456 #include "qapi/qapi-builtin-types.h" 1457 1458 typedef struct UserDefOne UserDefOne; 1459 1460 typedef struct UserDefOneList UserDefOneList; 1461 1462 typedef struct q_obj_my_command_arg q_obj_my_command_arg; 1463 1464 struct UserDefOne { 1465 int64_t integer; 1466 bool has_string; 1467 char *string; 1468 }; 1469 1470 void qapi_free_UserDefOne(UserDefOne *obj); 1471 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne) 1472 1473 struct UserDefOneList { 1474 UserDefOneList *next; 1475 UserDefOne *value; 1476 }; 1477 1478 void qapi_free_UserDefOneList(UserDefOneList *obj); 1479 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList) 1480 1481 struct q_obj_my_command_arg { 1482 UserDefOneList *arg1; 1483 }; 1484 1485 #endif /* EXAMPLE_QAPI_TYPES_H */ 1486 $ cat qapi-generated/example-qapi-types.c 1487 [Uninteresting stuff omitted...] 1488 1489 void qapi_free_UserDefOne(UserDefOne *obj) 1490 { 1491 Visitor *v; 1492 1493 if (!obj) { 1494 return; 1495 } 1496 1497 v = qapi_dealloc_visitor_new(); 1498 visit_type_UserDefOne(v, NULL, &obj, NULL); 1499 visit_free(v); 1500 } 1501 1502 void qapi_free_UserDefOneList(UserDefOneList *obj) 1503 { 1504 Visitor *v; 1505 1506 if (!obj) { 1507 return; 1508 } 1509 1510 v = qapi_dealloc_visitor_new(); 1511 visit_type_UserDefOneList(v, NULL, &obj, NULL); 1512 visit_free(v); 1513 } 1514 1515 [Uninteresting stuff omitted...] 1516 1517For a modular QAPI schema (see section `Include directives`_), code for 1518each sub-module SUBDIR/SUBMODULE.json is actually generated into :: 1519 1520 SUBDIR/$(prefix)qapi-types-SUBMODULE.h 1521 SUBDIR/$(prefix)qapi-types-SUBMODULE.c 1522 1523If qapi-gen.py is run with option --builtins, additional files are 1524created: 1525 1526 ``qapi-builtin-types.h`` 1527 C types corresponding to built-in types 1528 1529 ``qapi-builtin-types.c`` 1530 Cleanup functions for the above C types 1531 1532 1533Code generated for visiting QAPI types 1534-------------------------------------- 1535 1536These are the visitor functions used to walk through and convert 1537between a native QAPI C data structure and some other format (such as 1538QObject); the generated functions are named visit_type_FOO() and 1539visit_type_FOO_members(). 1540 1541The following files are generated: 1542 1543 ``$(prefix)qapi-visit.c`` 1544 Visitor function for a particular C type, used to automagically 1545 convert QObjects into the corresponding C type and vice-versa, as 1546 well as for deallocating memory for an existing C type 1547 1548 ``$(prefix)qapi-visit.h`` 1549 Declarations for previously mentioned visitor functions 1550 1551Example:: 1552 1553 $ cat qapi-generated/example-qapi-visit.h 1554 [Uninteresting stuff omitted...] 1555 1556 #ifndef EXAMPLE_QAPI_VISIT_H 1557 #define EXAMPLE_QAPI_VISIT_H 1558 1559 #include "qapi/qapi-builtin-visit.h" 1560 #include "example-qapi-types.h" 1561 1562 1563 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); 1564 1565 bool visit_type_UserDefOne(Visitor *v, const char *name, 1566 UserDefOne **obj, Error **errp); 1567 1568 bool visit_type_UserDefOneList(Visitor *v, const char *name, 1569 UserDefOneList **obj, Error **errp); 1570 1571 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp); 1572 1573 #endif /* EXAMPLE_QAPI_VISIT_H */ 1574 $ cat qapi-generated/example-qapi-visit.c 1575 [Uninteresting stuff omitted...] 1576 1577 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp) 1578 { 1579 if (!visit_type_int(v, "integer", &obj->integer, errp)) { 1580 return false; 1581 } 1582 if (visit_optional(v, "string", &obj->has_string)) { 1583 if (!visit_type_str(v, "string", &obj->string, errp)) { 1584 return false; 1585 } 1586 } 1587 return true; 1588 } 1589 1590 bool visit_type_UserDefOne(Visitor *v, const char *name, 1591 UserDefOne **obj, Error **errp) 1592 { 1593 bool ok = false; 1594 1595 if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) { 1596 return false; 1597 } 1598 if (!*obj) { 1599 /* incomplete */ 1600 assert(visit_is_dealloc(v)); 1601 ok = true; 1602 goto out_obj; 1603 } 1604 if (!visit_type_UserDefOne_members(v, *obj, errp)) { 1605 goto out_obj; 1606 } 1607 ok = visit_check_struct(v, errp); 1608 out_obj: 1609 visit_end_struct(v, (void **)obj); 1610 if (!ok && visit_is_input(v)) { 1611 qapi_free_UserDefOne(*obj); 1612 *obj = NULL; 1613 } 1614 return ok; 1615 } 1616 1617 bool visit_type_UserDefOneList(Visitor *v, const char *name, 1618 UserDefOneList **obj, Error **errp) 1619 { 1620 bool ok = false; 1621 UserDefOneList *tail; 1622 size_t size = sizeof(**obj); 1623 1624 if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) { 1625 return false; 1626 } 1627 1628 for (tail = *obj; tail; 1629 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) { 1630 if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) { 1631 goto out_obj; 1632 } 1633 } 1634 1635 ok = visit_check_list(v, errp); 1636 out_obj: 1637 visit_end_list(v, (void **)obj); 1638 if (!ok && visit_is_input(v)) { 1639 qapi_free_UserDefOneList(*obj); 1640 *obj = NULL; 1641 } 1642 return ok; 1643 } 1644 1645 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp) 1646 { 1647 if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) { 1648 return false; 1649 } 1650 return true; 1651 } 1652 1653 [Uninteresting stuff omitted...] 1654 1655For a modular QAPI schema (see section `Include directives`_), code for 1656each sub-module SUBDIR/SUBMODULE.json is actually generated into :: 1657 1658 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h 1659 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c 1660 1661If qapi-gen.py is run with option --builtins, additional files are 1662created: 1663 1664 ``qapi-builtin-visit.h`` 1665 Visitor functions for built-in types 1666 1667 ``qapi-builtin-visit.c`` 1668 Declarations for these visitor functions 1669 1670 1671Code generated for commands 1672--------------------------- 1673 1674These are the marshaling/dispatch functions for the commands defined 1675in the schema. The generated code provides qmp_marshal_COMMAND(), and 1676declares qmp_COMMAND() that the user must implement. 1677 1678The following files are generated: 1679 1680 ``$(prefix)qapi-commands.c`` 1681 Command marshal/dispatch functions for each QMP command defined in 1682 the schema 1683 1684 ``$(prefix)qapi-commands.h`` 1685 Function prototypes for the QMP commands specified in the schema 1686 1687 ``$(prefix)qapi-init-commands.h`` 1688 Command initialization prototype 1689 1690 ``$(prefix)qapi-init-commands.c`` 1691 Command initialization code 1692 1693Example:: 1694 1695 $ cat qapi-generated/example-qapi-commands.h 1696 [Uninteresting stuff omitted...] 1697 1698 #ifndef EXAMPLE_QAPI_COMMANDS_H 1699 #define EXAMPLE_QAPI_COMMANDS_H 1700 1701 #include "example-qapi-types.h" 1702 1703 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); 1704 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp); 1705 1706 #endif /* EXAMPLE_QAPI_COMMANDS_H */ 1707 $ cat qapi-generated/example-qapi-commands.c 1708 [Uninteresting stuff omitted...] 1709 1710 1711 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, 1712 QObject **ret_out, Error **errp) 1713 { 1714 Visitor *v; 1715 1716 v = qobject_output_visitor_new_qmp(ret_out); 1717 if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) { 1718 visit_complete(v, ret_out); 1719 } 1720 visit_free(v); 1721 v = qapi_dealloc_visitor_new(); 1722 visit_type_UserDefOne(v, "unused", &ret_in, NULL); 1723 visit_free(v); 1724 } 1725 1726 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) 1727 { 1728 Error *err = NULL; 1729 bool ok = false; 1730 Visitor *v; 1731 UserDefOne *retval; 1732 q_obj_my_command_arg arg = {0}; 1733 1734 v = qobject_input_visitor_new_qmp(QOBJECT(args)); 1735 if (!visit_start_struct(v, NULL, NULL, 0, errp)) { 1736 goto out; 1737 } 1738 if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) { 1739 ok = visit_check_struct(v, errp); 1740 } 1741 visit_end_struct(v, NULL); 1742 if (!ok) { 1743 goto out; 1744 } 1745 1746 retval = qmp_my_command(arg.arg1, &err); 1747 error_propagate(errp, err); 1748 if (err) { 1749 goto out; 1750 } 1751 1752 qmp_marshal_output_UserDefOne(retval, ret, errp); 1753 1754 out: 1755 visit_free(v); 1756 v = qapi_dealloc_visitor_new(); 1757 visit_start_struct(v, NULL, NULL, 0, NULL); 1758 visit_type_q_obj_my_command_arg_members(v, &arg, NULL); 1759 visit_end_struct(v, NULL); 1760 visit_free(v); 1761 } 1762 1763 [Uninteresting stuff omitted...] 1764 $ cat qapi-generated/example-qapi-init-commands.h 1765 [Uninteresting stuff omitted...] 1766 #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H 1767 #define EXAMPLE_QAPI_INIT_COMMANDS_H 1768 1769 #include "qapi/qmp/dispatch.h" 1770 1771 void example_qmp_init_marshal(QmpCommandList *cmds); 1772 1773 #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */ 1774 $ cat qapi-generated/example-qapi-init-commands.c 1775 [Uninteresting stuff omitted...] 1776 void example_qmp_init_marshal(QmpCommandList *cmds) 1777 { 1778 QTAILQ_INIT(cmds); 1779 1780 qmp_register_command(cmds, "my-command", 1781 qmp_marshal_my_command, QCO_NO_OPTIONS); 1782 } 1783 [Uninteresting stuff omitted...] 1784 1785For a modular QAPI schema (see section `Include directives`_), code for 1786each sub-module SUBDIR/SUBMODULE.json is actually generated into:: 1787 1788 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h 1789 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c 1790 1791 1792Code generated for events 1793------------------------- 1794 1795This is the code related to events defined in the schema, providing 1796qapi_event_send_EVENT(). 1797 1798The following files are created: 1799 1800 ``$(prefix)qapi-events.h`` 1801 Function prototypes for each event type 1802 1803 ``$(prefix)qapi-events.c`` 1804 Implementation of functions to send an event 1805 1806 ``$(prefix)qapi-emit-events.h`` 1807 Enumeration of all event names, and common event code declarations 1808 1809 ``$(prefix)qapi-emit-events.c`` 1810 Common event code definitions 1811 1812Example:: 1813 1814 $ cat qapi-generated/example-qapi-events.h 1815 [Uninteresting stuff omitted...] 1816 1817 #ifndef EXAMPLE_QAPI_EVENTS_H 1818 #define EXAMPLE_QAPI_EVENTS_H 1819 1820 #include "qapi/util.h" 1821 #include "example-qapi-types.h" 1822 1823 void qapi_event_send_my_event(void); 1824 1825 #endif /* EXAMPLE_QAPI_EVENTS_H */ 1826 $ cat qapi-generated/example-qapi-events.c 1827 [Uninteresting stuff omitted...] 1828 1829 void qapi_event_send_my_event(void) 1830 { 1831 QDict *qmp; 1832 1833 qmp = qmp_event_build_dict("MY_EVENT"); 1834 1835 example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp); 1836 1837 qobject_unref(qmp); 1838 } 1839 1840 [Uninteresting stuff omitted...] 1841 $ cat qapi-generated/example-qapi-emit-events.h 1842 [Uninteresting stuff omitted...] 1843 1844 #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H 1845 #define EXAMPLE_QAPI_EMIT_EVENTS_H 1846 1847 #include "qapi/util.h" 1848 1849 typedef enum example_QAPIEvent { 1850 EXAMPLE_QAPI_EVENT_MY_EVENT, 1851 EXAMPLE_QAPI_EVENT__MAX, 1852 } example_QAPIEvent; 1853 1854 #define example_QAPIEvent_str(val) \ 1855 qapi_enum_lookup(&example_QAPIEvent_lookup, (val)) 1856 1857 extern const QEnumLookup example_QAPIEvent_lookup; 1858 1859 void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict); 1860 1861 #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */ 1862 $ cat qapi-generated/example-qapi-emit-events.c 1863 [Uninteresting stuff omitted...] 1864 1865 const QEnumLookup example_QAPIEvent_lookup = { 1866 .array = (const char *const[]) { 1867 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", 1868 }, 1869 .size = EXAMPLE_QAPI_EVENT__MAX 1870 }; 1871 1872 [Uninteresting stuff omitted...] 1873 1874For a modular QAPI schema (see section `Include directives`_), code for 1875each sub-module SUBDIR/SUBMODULE.json is actually generated into :: 1876 1877 SUBDIR/$(prefix)qapi-events-SUBMODULE.h 1878 SUBDIR/$(prefix)qapi-events-SUBMODULE.c 1879 1880 1881Code generated for introspection 1882-------------------------------- 1883 1884The following files are created: 1885 1886 ``$(prefix)qapi-introspect.c`` 1887 Defines a string holding a JSON description of the schema 1888 1889 ``$(prefix)qapi-introspect.h`` 1890 Declares the above string 1891 1892Example:: 1893 1894 $ cat qapi-generated/example-qapi-introspect.h 1895 [Uninteresting stuff omitted...] 1896 1897 #ifndef EXAMPLE_QAPI_INTROSPECT_H 1898 #define EXAMPLE_QAPI_INTROSPECT_H 1899 1900 #include "qapi/qmp/qlit.h" 1901 1902 extern const QLitObject example_qmp_schema_qlit; 1903 1904 #endif /* EXAMPLE_QAPI_INTROSPECT_H */ 1905 $ cat qapi-generated/example-qapi-introspect.c 1906 [Uninteresting stuff omitted...] 1907 1908 const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) { 1909 QLIT_QDICT(((QLitDictEntry[]) { 1910 { "arg-type", QLIT_QSTR("0"), }, 1911 { "meta-type", QLIT_QSTR("command"), }, 1912 { "name", QLIT_QSTR("my-command"), }, 1913 { "ret-type", QLIT_QSTR("1"), }, 1914 {} 1915 })), 1916 QLIT_QDICT(((QLitDictEntry[]) { 1917 { "arg-type", QLIT_QSTR("2"), }, 1918 { "meta-type", QLIT_QSTR("event"), }, 1919 { "name", QLIT_QSTR("MY_EVENT"), }, 1920 {} 1921 })), 1922 /* "0" = q_obj_my-command-arg */ 1923 QLIT_QDICT(((QLitDictEntry[]) { 1924 { "members", QLIT_QLIST(((QLitObject[]) { 1925 QLIT_QDICT(((QLitDictEntry[]) { 1926 { "name", QLIT_QSTR("arg1"), }, 1927 { "type", QLIT_QSTR("[1]"), }, 1928 {} 1929 })), 1930 {} 1931 })), }, 1932 { "meta-type", QLIT_QSTR("object"), }, 1933 { "name", QLIT_QSTR("0"), }, 1934 {} 1935 })), 1936 /* "1" = UserDefOne */ 1937 QLIT_QDICT(((QLitDictEntry[]) { 1938 { "members", QLIT_QLIST(((QLitObject[]) { 1939 QLIT_QDICT(((QLitDictEntry[]) { 1940 { "name", QLIT_QSTR("integer"), }, 1941 { "type", QLIT_QSTR("int"), }, 1942 {} 1943 })), 1944 QLIT_QDICT(((QLitDictEntry[]) { 1945 { "default", QLIT_QNULL, }, 1946 { "name", QLIT_QSTR("string"), }, 1947 { "type", QLIT_QSTR("str"), }, 1948 {} 1949 })), 1950 {} 1951 })), }, 1952 { "meta-type", QLIT_QSTR("object"), }, 1953 { "name", QLIT_QSTR("1"), }, 1954 {} 1955 })), 1956 /* "2" = q_empty */ 1957 QLIT_QDICT(((QLitDictEntry[]) { 1958 { "members", QLIT_QLIST(((QLitObject[]) { 1959 {} 1960 })), }, 1961 { "meta-type", QLIT_QSTR("object"), }, 1962 { "name", QLIT_QSTR("2"), }, 1963 {} 1964 })), 1965 QLIT_QDICT(((QLitDictEntry[]) { 1966 { "element-type", QLIT_QSTR("1"), }, 1967 { "meta-type", QLIT_QSTR("array"), }, 1968 { "name", QLIT_QSTR("[1]"), }, 1969 {} 1970 })), 1971 QLIT_QDICT(((QLitDictEntry[]) { 1972 { "json-type", QLIT_QSTR("int"), }, 1973 { "meta-type", QLIT_QSTR("builtin"), }, 1974 { "name", QLIT_QSTR("int"), }, 1975 {} 1976 })), 1977 QLIT_QDICT(((QLitDictEntry[]) { 1978 { "json-type", QLIT_QSTR("string"), }, 1979 { "meta-type", QLIT_QSTR("builtin"), }, 1980 { "name", QLIT_QSTR("str"), }, 1981 {} 1982 })), 1983 {} 1984 })); 1985 1986 [Uninteresting stuff omitted...] 1987