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