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. "TODO" sections are not rendered at all 1011(they are for developers, not users of QMP). In other sections, the 1012text is formatted, and rST markup can be used. 1013 1014For example:: 1015 1016 ## 1017 # @BlockStats: 1018 # 1019 # Statistics of a virtual block device or a block backing device. 1020 # 1021 # @device: If the stats are for a virtual block device, the name 1022 # corresponding to the virtual block device. 1023 # 1024 # @node-name: The node name of the device. (since 2.3) 1025 # 1026 # ... more members ... 1027 # 1028 # Since: 0.14.0 1029 ## 1030 { 'struct': 'BlockStats', 1031 'data': {'*device': 'str', '*node-name': 'str', 1032 ... more members ... } } 1033 1034 ## 1035 # @query-blockstats: 1036 # 1037 # Query the @BlockStats for all virtual block devices. 1038 # 1039 # @query-nodes: If true, the command will query all the 1040 # block nodes ... explain, explain ... (since 2.3) 1041 # 1042 # Returns: A list of @BlockStats for each virtual block devices. 1043 # 1044 # Since: 0.14.0 1045 # 1046 # Example: 1047 # 1048 # -> { "execute": "query-blockstats" } 1049 # <- { 1050 # ... lots of output ... 1051 # } 1052 # 1053 ## 1054 { 'command': 'query-blockstats', 1055 'data': { '*query-nodes': 'bool' }, 1056 'returns': ['BlockStats'] } 1057 1058 1059Markup pitfalls 1060~~~~~~~~~~~~~~~ 1061 1062A blank line is required between list items and paragraphs. Without 1063it, the list may not be recognized, resulting in garbled output. Good 1064example:: 1065 1066 # An event's state is modified if: 1067 # 1068 # - its name matches the @name pattern, and 1069 # - if @vcpu is given, the event has the "vcpu" property. 1070 1071Without the blank line this would be a single paragraph. 1072 1073Indentation matters. Bad example:: 1074 1075 # @none: None (no memory side cache in this proximity domain, 1076 # or cache associativity unknown) 1077 1078The description is parsed as a definition list with term "None (no 1079memory side cache in this proximity domain," and definition "or cache 1080associativity unknown)". 1081 1082Section tags are case-sensitive and end with a colon. Good example:: 1083 1084 # Since: 7.1 1085 1086Bad examples (all ordinary paragraphs):: 1087 1088 # since: 7.1 1089 1090 # Since 7.1 1091 1092 # Since : 7.1 1093 1094Likewise, member descriptions require a colon. Good example:: 1095 1096 # @interface-id: Interface ID 1097 1098Bad examples (all ordinary paragraphs):: 1099 1100 # @interface-id Interface ID 1101 1102 # @interface-id : Interface ID 1103 1104Undocumented members are not flagged, yet. Instead, the generated 1105documentation describes them as "Not documented". Think twice before 1106adding more undocumented members. 1107 1108When you change documentation comments, please check the generated 1109documentation comes out as intended! 1110 1111 1112Client JSON Protocol introspection 1113================================== 1114 1115Clients of a Client JSON Protocol commonly need to figure out what 1116exactly the server (QEMU) supports. 1117 1118For this purpose, QMP provides introspection via command 1119query-qmp-schema. QGA currently doesn't support introspection. 1120 1121While Client JSON Protocol wire compatibility should be maintained 1122between qemu versions, we cannot make the same guarantees for 1123introspection stability. For example, one version of qemu may provide 1124a non-variant optional member of a struct, and a later version rework 1125the member to instead be non-optional and associated with a variant. 1126Likewise, one version of qemu may list a member with open-ended type 1127'str', and a later version could convert it to a finite set of strings 1128via an enum type; or a member may be converted from a specific type to 1129an alternate that represents a choice between the original type and 1130something else. 1131 1132query-qmp-schema returns a JSON array of SchemaInfo objects. These 1133objects together describe the wire ABI, as defined in the QAPI schema. 1134There is no specified order to the SchemaInfo objects returned; a 1135client must search for a particular name throughout the entire array 1136to learn more about that name, but is at least guaranteed that there 1137will be no collisions between type, command, and event names. 1138 1139However, the SchemaInfo can't reflect all the rules and restrictions 1140that apply to QMP. It's interface introspection (figuring out what's 1141there), not interface specification. The specification is in the QAPI 1142schema. To understand how QMP is to be used, you need to study the 1143QAPI schema. 1144 1145Like any other command, query-qmp-schema is itself defined in the QAPI 1146schema, along with the SchemaInfo type. This text attempts to give an 1147overview how things work. For details you need to consult the QAPI 1148schema. 1149 1150SchemaInfo objects have common members "name", "meta-type", 1151"features", and additional variant members depending on the value of 1152meta-type. 1153 1154Each SchemaInfo object describes a wire ABI entity of a certain 1155meta-type: a command, event or one of several kinds of type. 1156 1157SchemaInfo for commands and events have the same name as in the QAPI 1158schema. 1159 1160Command and event names are part of the wire ABI, but type names are 1161not. Therefore, the SchemaInfo for types have auto-generated 1162meaningless names. For readability, the examples in this section use 1163meaningful type names instead. 1164 1165Optional member "features" exposes the entity's feature strings as a 1166JSON array of strings. 1167 1168To examine a type, start with a command or event using it, then follow 1169references by name. 1170 1171QAPI schema definitions not reachable that way are omitted. 1172 1173The SchemaInfo for a command has meta-type "command", and variant 1174members "arg-type", "ret-type" and "allow-oob". On the wire, the 1175"arguments" member of a client's "execute" command must conform to the 1176object type named by "arg-type". The "return" member that the server 1177passes in a success response conforms to the type named by "ret-type". 1178When "allow-oob" is true, it means the command supports out-of-band 1179execution. It defaults to false. 1180 1181If the command takes no arguments, "arg-type" names an object type 1182without members. Likewise, if the command returns nothing, "ret-type" 1183names an object type without members. 1184 1185Example: the SchemaInfo for command query-qmp-schema :: 1186 1187 { "name": "query-qmp-schema", "meta-type": "command", 1188 "arg-type": "q_empty", "ret-type": "SchemaInfoList" } 1189 1190 Type "q_empty" is an automatic object type without members, and type 1191 "SchemaInfoList" is the array of SchemaInfo type. 1192 1193The SchemaInfo for an event has meta-type "event", and variant member 1194"arg-type". On the wire, a "data" member that the server passes in an 1195event conforms to the object type named by "arg-type". 1196 1197If the event carries no additional information, "arg-type" names an 1198object type without members. The event may not have a data member on 1199the wire then. 1200 1201Each command or event defined with 'data' as MEMBERS object in the 1202QAPI schema implicitly defines an object type. 1203 1204Example: the SchemaInfo for EVENT_C from section Events_ :: 1205 1206 { "name": "EVENT_C", "meta-type": "event", 1207 "arg-type": "q_obj-EVENT_C-arg" } 1208 1209 Type "q_obj-EVENT_C-arg" is an implicitly defined object type with 1210 the two members from the event's definition. 1211 1212The SchemaInfo for struct and union types has meta-type "object" and 1213variant member "members". 1214 1215The SchemaInfo for a union type additionally has variant members "tag" 1216and "variants". 1217 1218"members" is a JSON array describing the object's common members, if 1219any. Each element is a JSON object with members "name" (the member's 1220name), "type" (the name of its type), "features" (a JSON array of 1221feature strings), and "default". The latter two are optional. The 1222member is optional if "default" is present. Currently, "default" can 1223only have value null. Other values are reserved for future 1224extensions. The "members" array is in no particular order; clients 1225must search the entire object when learning whether a particular 1226member is supported. 1227 1228Example: the SchemaInfo for MyType from section `Struct types`_ :: 1229 1230 { "name": "MyType", "meta-type": "object", 1231 "members": [ 1232 { "name": "member1", "type": "str" }, 1233 { "name": "member2", "type": "int" }, 1234 { "name": "member3", "type": "str", "default": null } ] } 1235 1236"features" exposes the command's feature strings as a JSON array of 1237strings. 1238 1239Example: the SchemaInfo for TestType from section Features_:: 1240 1241 { "name": "TestType", "meta-type": "object", 1242 "members": [ 1243 { "name": "number", "type": "int" } ], 1244 "features": ["allow-negative-numbers"] } 1245 1246"tag" is the name of the common member serving as type tag. 1247"variants" is a JSON array describing the object's variant members. 1248Each element is a JSON object with members "case" (the value of type 1249tag this element applies to) and "type" (the name of an object type 1250that provides the variant members for this type tag value). The 1251"variants" array is in no particular order, and is not guaranteed to 1252list cases in the same order as the corresponding "tag" enum type. 1253 1254Example: the SchemaInfo for union BlockdevOptions from section 1255`Union types`_ :: 1256 1257 { "name": "BlockdevOptions", "meta-type": "object", 1258 "members": [ 1259 { "name": "driver", "type": "BlockdevDriver" }, 1260 { "name": "read-only", "type": "bool", "default": null } ], 1261 "tag": "driver", 1262 "variants": [ 1263 { "case": "file", "type": "BlockdevOptionsFile" }, 1264 { "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] } 1265 1266Note that base types are "flattened": its members are included in the 1267"members" array. 1268 1269The SchemaInfo for an alternate type has meta-type "alternate", and 1270variant member "members". "members" is a JSON array. Each element is 1271a JSON object with member "type", which names a type. Values of the 1272alternate type conform to exactly one of its member types. There is 1273no guarantee on the order in which "members" will be listed. 1274 1275Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ :: 1276 1277 { "name": "BlockdevRef", "meta-type": "alternate", 1278 "members": [ 1279 { "type": "BlockdevOptions" }, 1280 { "type": "str" } ] } 1281 1282The SchemaInfo for an array type has meta-type "array", and variant 1283member "element-type", which names the array's element type. Array 1284types are implicitly defined. For convenience, the array's name may 1285resemble the element type; however, clients should examine member 1286"element-type" instead of making assumptions based on parsing member 1287"name". 1288 1289Example: the SchemaInfo for ['str'] :: 1290 1291 { "name": "[str]", "meta-type": "array", 1292 "element-type": "str" } 1293 1294The SchemaInfo for an enumeration type has meta-type "enum" and 1295variant member "members". 1296 1297"members" is a JSON array describing the enumeration values. Each 1298element is a JSON object with member "name" (the member's name), and 1299optionally "features" (a JSON array of feature strings). The 1300"members" array is in no particular order; clients must search the 1301entire array when learning whether a particular value is supported. 1302 1303Example: the SchemaInfo for MyEnum from section `Enumeration types`_ :: 1304 1305 { "name": "MyEnum", "meta-type": "enum", 1306 "members": [ 1307 { "name": "value1" }, 1308 { "name": "value2" }, 1309 { "name": "value3" } 1310 ] } 1311 1312The SchemaInfo for a built-in type has the same name as the type in 1313the QAPI schema (see section `Built-in Types`_), with one exception 1314detailed below. It has variant member "json-type" that shows how 1315values of this type are encoded on the wire. 1316 1317Example: the SchemaInfo for str :: 1318 1319 { "name": "str", "meta-type": "builtin", "json-type": "string" } 1320 1321The QAPI schema supports a number of integer types that only differ in 1322how they map to C. They are identical as far as SchemaInfo is 1323concerned. Therefore, they get all mapped to a single type "int" in 1324SchemaInfo. 1325 1326As explained above, type names are not part of the wire ABI. Not even 1327the names of built-in types. Clients should examine member 1328"json-type" instead of hard-coding names of built-in types. 1329 1330 1331Compatibility considerations 1332============================ 1333 1334Maintaining backward compatibility at the Client JSON Protocol level 1335while evolving the schema requires some care. This section is about 1336syntactic compatibility, which is necessary, but not sufficient, for 1337actual compatibility. 1338 1339Clients send commands with argument data, and receive command 1340responses with return data and events with event data. 1341 1342Adding opt-in functionality to the send direction is backwards 1343compatible: adding commands, optional arguments, enumeration values, 1344union and alternate branches; turning an argument type into an 1345alternate of that type; making mandatory arguments optional. Clients 1346oblivious of the new functionality continue to work. 1347 1348Incompatible changes include removing commands, command arguments, 1349enumeration values, union and alternate branches, adding mandatory 1350command arguments, and making optional arguments mandatory. 1351 1352The specified behavior of an absent optional argument should remain 1353the same. With proper documentation, this policy still allows some 1354flexibility; for example, when an optional 'buffer-size' argument is 1355specified to default to a sensible buffer size, the actual default 1356value can still be changed. The specified default behavior is not the 1357exact size of the buffer, only that the default size is sensible. 1358 1359Adding functionality to the receive direction is generally backwards 1360compatible: adding events, adding return and event data members. 1361Clients are expected to ignore the ones they don't know. 1362 1363Removing "unreachable" stuff like events that can't be triggered 1364anymore, optional return or event data members that can't be sent 1365anymore, and return or event data member (enumeration) values that 1366can't be sent anymore makes no difference to clients, except for 1367introspection. The latter can conceivably confuse clients, so tread 1368carefully. 1369 1370Incompatible changes include removing return and event data members. 1371 1372Any change to a command definition's 'data' or one of the types used 1373there (recursively) needs to consider send direction compatibility. 1374 1375Any change to a command definition's 'return', an event definition's 1376'data', or one of the types used there (recursively) needs to consider 1377receive direction compatibility. 1378 1379Any change to types used in both contexts need to consider both. 1380 1381Enumeration type values and complex and alternate type members may be 1382reordered freely. For enumerations and alternate types, this doesn't 1383affect the wire encoding. For complex types, this might make the 1384implementation emit JSON object members in a different order, which 1385the Client JSON Protocol permits. 1386 1387Since type names are not visible in the Client JSON Protocol, types 1388may be freely renamed. Even certain refactorings are invisible, such 1389as splitting members from one type into a common base type. 1390 1391 1392Code generation 1393=============== 1394 1395The QAPI code generator qapi-gen.py generates code and documentation 1396from the schema. Together with the core QAPI libraries, this code 1397provides everything required to take JSON commands read in by a Client 1398JSON Protocol server, unmarshal the arguments into the underlying C 1399types, call into the corresponding C function, map the response back 1400to a Client JSON Protocol response to be returned to the user, and 1401introspect the commands. 1402 1403As an example, we'll use the following schema, which describes a 1404single complex user-defined type, along with command which takes a 1405list of that type as a parameter, and returns a single element of that 1406type. The user is responsible for writing the implementation of 1407qmp_my_command(); everything else is produced by the generator. :: 1408 1409 $ cat example-schema.json 1410 { 'struct': 'UserDefOne', 1411 'data': { 'integer': 'int', '*string': 'str', '*flag': 'bool' } } 1412 1413 { 'command': 'my-command', 1414 'data': { 'arg1': ['UserDefOne'] }, 1415 'returns': 'UserDefOne' } 1416 1417 { 'event': 'MY_EVENT' } 1418 1419We run qapi-gen.py like this:: 1420 1421 $ python scripts/qapi-gen.py --output-dir="qapi-generated" \ 1422 --prefix="example-" example-schema.json 1423 1424For a more thorough look at generated code, the testsuite includes 1425tests/qapi-schema/qapi-schema-tests.json that covers more examples of 1426what the generator will accept, and compiles the resulting C code as 1427part of 'make check-unit'. 1428 1429 1430Code generated for QAPI types 1431----------------------------- 1432 1433The following files are created: 1434 1435 ``$(prefix)qapi-types.h`` 1436 C types corresponding to types defined in the schema 1437 1438 ``$(prefix)qapi-types.c`` 1439 Cleanup functions for the above C types 1440 1441The $(prefix) is an optional parameter used as a namespace to keep the 1442generated code from one schema/code-generation separated from others so code 1443can be generated/used from multiple schemas without clobbering previously 1444created code. 1445 1446Example:: 1447 1448 $ cat qapi-generated/example-qapi-types.h 1449 [Uninteresting stuff omitted...] 1450 1451 #ifndef EXAMPLE_QAPI_TYPES_H 1452 #define EXAMPLE_QAPI_TYPES_H 1453 1454 #include "qapi/qapi-builtin-types.h" 1455 1456 typedef struct UserDefOne UserDefOne; 1457 1458 typedef struct UserDefOneList UserDefOneList; 1459 1460 typedef struct q_obj_my_command_arg q_obj_my_command_arg; 1461 1462 struct UserDefOne { 1463 int64_t integer; 1464 char *string; 1465 bool has_flag; 1466 bool flag; 1467 }; 1468 1469 void qapi_free_UserDefOne(UserDefOne *obj); 1470 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne) 1471 1472 struct UserDefOneList { 1473 UserDefOneList *next; 1474 UserDefOne *value; 1475 }; 1476 1477 void qapi_free_UserDefOneList(UserDefOneList *obj); 1478 G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList) 1479 1480 struct q_obj_my_command_arg { 1481 UserDefOneList *arg1; 1482 }; 1483 1484 #endif /* EXAMPLE_QAPI_TYPES_H */ 1485 $ cat qapi-generated/example-qapi-types.c 1486 [Uninteresting stuff omitted...] 1487 1488 void qapi_free_UserDefOne(UserDefOne *obj) 1489 { 1490 Visitor *v; 1491 1492 if (!obj) { 1493 return; 1494 } 1495 1496 v = qapi_dealloc_visitor_new(); 1497 visit_type_UserDefOne(v, NULL, &obj, NULL); 1498 visit_free(v); 1499 } 1500 1501 void qapi_free_UserDefOneList(UserDefOneList *obj) 1502 { 1503 Visitor *v; 1504 1505 if (!obj) { 1506 return; 1507 } 1508 1509 v = qapi_dealloc_visitor_new(); 1510 visit_type_UserDefOneList(v, NULL, &obj, NULL); 1511 visit_free(v); 1512 } 1513 1514 [Uninteresting stuff omitted...] 1515 1516For a modular QAPI schema (see section `Include directives`_), code for 1517each sub-module SUBDIR/SUBMODULE.json is actually generated into :: 1518 1519 SUBDIR/$(prefix)qapi-types-SUBMODULE.h 1520 SUBDIR/$(prefix)qapi-types-SUBMODULE.c 1521 1522If qapi-gen.py is run with option --builtins, additional files are 1523created: 1524 1525 ``qapi-builtin-types.h`` 1526 C types corresponding to built-in types 1527 1528 ``qapi-builtin-types.c`` 1529 Cleanup functions for the above C types 1530 1531 1532Code generated for visiting QAPI types 1533-------------------------------------- 1534 1535These are the visitor functions used to walk through and convert 1536between a native QAPI C data structure and some other format (such as 1537QObject); the generated functions are named visit_type_FOO() and 1538visit_type_FOO_members(). 1539 1540The following files are generated: 1541 1542 ``$(prefix)qapi-visit.c`` 1543 Visitor function for a particular C type, used to automagically 1544 convert QObjects into the corresponding C type and vice-versa, as 1545 well as for deallocating memory for an existing C type 1546 1547 ``$(prefix)qapi-visit.h`` 1548 Declarations for previously mentioned visitor functions 1549 1550Example:: 1551 1552 $ cat qapi-generated/example-qapi-visit.h 1553 [Uninteresting stuff omitted...] 1554 1555 #ifndef EXAMPLE_QAPI_VISIT_H 1556 #define EXAMPLE_QAPI_VISIT_H 1557 1558 #include "qapi/qapi-builtin-visit.h" 1559 #include "example-qapi-types.h" 1560 1561 1562 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp); 1563 1564 bool visit_type_UserDefOne(Visitor *v, const char *name, 1565 UserDefOne **obj, Error **errp); 1566 1567 bool visit_type_UserDefOneList(Visitor *v, const char *name, 1568 UserDefOneList **obj, Error **errp); 1569 1570 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp); 1571 1572 #endif /* EXAMPLE_QAPI_VISIT_H */ 1573 $ cat qapi-generated/example-qapi-visit.c 1574 [Uninteresting stuff omitted...] 1575 1576 bool visit_type_UserDefOne_members(Visitor *v, UserDefOne *obj, Error **errp) 1577 { 1578 bool has_string = !!obj->string; 1579 1580 if (!visit_type_int(v, "integer", &obj->integer, errp)) { 1581 return false; 1582 } 1583 if (visit_optional(v, "string", &has_string)) { 1584 if (!visit_type_str(v, "string", &obj->string, errp)) { 1585 return false; 1586 } 1587 } 1588 if (visit_optional(v, "flag", &obj->has_flag)) { 1589 if (!visit_type_bool(v, "flag", &obj->flag, errp)) { 1590 return false; 1591 } 1592 } 1593 return true; 1594 } 1595 1596 bool visit_type_UserDefOne(Visitor *v, const char *name, 1597 UserDefOne **obj, Error **errp) 1598 { 1599 bool ok = false; 1600 1601 if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) { 1602 return false; 1603 } 1604 if (!*obj) { 1605 /* incomplete */ 1606 assert(visit_is_dealloc(v)); 1607 ok = true; 1608 goto out_obj; 1609 } 1610 if (!visit_type_UserDefOne_members(v, *obj, errp)) { 1611 goto out_obj; 1612 } 1613 ok = visit_check_struct(v, errp); 1614 out_obj: 1615 visit_end_struct(v, (void **)obj); 1616 if (!ok && visit_is_input(v)) { 1617 qapi_free_UserDefOne(*obj); 1618 *obj = NULL; 1619 } 1620 return ok; 1621 } 1622 1623 bool visit_type_UserDefOneList(Visitor *v, const char *name, 1624 UserDefOneList **obj, Error **errp) 1625 { 1626 bool ok = false; 1627 UserDefOneList *tail; 1628 size_t size = sizeof(**obj); 1629 1630 if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) { 1631 return false; 1632 } 1633 1634 for (tail = *obj; tail; 1635 tail = (UserDefOneList *)visit_next_list(v, (GenericList *)tail, size)) { 1636 if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) { 1637 goto out_obj; 1638 } 1639 } 1640 1641 ok = visit_check_list(v, errp); 1642 out_obj: 1643 visit_end_list(v, (void **)obj); 1644 if (!ok && visit_is_input(v)) { 1645 qapi_free_UserDefOneList(*obj); 1646 *obj = NULL; 1647 } 1648 return ok; 1649 } 1650 1651 bool visit_type_q_obj_my_command_arg_members(Visitor *v, q_obj_my_command_arg *obj, Error **errp) 1652 { 1653 if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) { 1654 return false; 1655 } 1656 return true; 1657 } 1658 1659 [Uninteresting stuff omitted...] 1660 1661For a modular QAPI schema (see section `Include directives`_), code for 1662each sub-module SUBDIR/SUBMODULE.json is actually generated into :: 1663 1664 SUBDIR/$(prefix)qapi-visit-SUBMODULE.h 1665 SUBDIR/$(prefix)qapi-visit-SUBMODULE.c 1666 1667If qapi-gen.py is run with option --builtins, additional files are 1668created: 1669 1670 ``qapi-builtin-visit.h`` 1671 Visitor functions for built-in types 1672 1673 ``qapi-builtin-visit.c`` 1674 Declarations for these visitor functions 1675 1676 1677Code generated for commands 1678--------------------------- 1679 1680These are the marshaling/dispatch functions for the commands defined 1681in the schema. The generated code provides qmp_marshal_COMMAND(), and 1682declares qmp_COMMAND() that the user must implement. 1683 1684The following files are generated: 1685 1686 ``$(prefix)qapi-commands.c`` 1687 Command marshal/dispatch functions for each QMP command defined in 1688 the schema 1689 1690 ``$(prefix)qapi-commands.h`` 1691 Function prototypes for the QMP commands specified in the schema 1692 1693 ``$(prefix)qapi-commands.trace-events`` 1694 Trace event declarations, see :ref:`tracing`. 1695 1696 ``$(prefix)qapi-init-commands.h`` 1697 Command initialization prototype 1698 1699 ``$(prefix)qapi-init-commands.c`` 1700 Command initialization code 1701 1702Example:: 1703 1704 $ cat qapi-generated/example-qapi-commands.h 1705 [Uninteresting stuff omitted...] 1706 1707 #ifndef EXAMPLE_QAPI_COMMANDS_H 1708 #define EXAMPLE_QAPI_COMMANDS_H 1709 1710 #include "example-qapi-types.h" 1711 1712 UserDefOne *qmp_my_command(UserDefOneList *arg1, Error **errp); 1713 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp); 1714 1715 #endif /* EXAMPLE_QAPI_COMMANDS_H */ 1716 1717 $ cat qapi-generated/example-qapi-commands.trace-events 1718 # AUTOMATICALLY GENERATED, DO NOT MODIFY 1719 1720 qmp_enter_my_command(const char *json) "%s" 1721 qmp_exit_my_command(const char *result, bool succeeded) "%s %d" 1722 1723 $ cat qapi-generated/example-qapi-commands.c 1724 [Uninteresting stuff omitted...] 1725 1726 static void qmp_marshal_output_UserDefOne(UserDefOne *ret_in, 1727 QObject **ret_out, Error **errp) 1728 { 1729 Visitor *v; 1730 1731 v = qobject_output_visitor_new_qmp(ret_out); 1732 if (visit_type_UserDefOne(v, "unused", &ret_in, errp)) { 1733 visit_complete(v, ret_out); 1734 } 1735 visit_free(v); 1736 v = qapi_dealloc_visitor_new(); 1737 visit_type_UserDefOne(v, "unused", &ret_in, NULL); 1738 visit_free(v); 1739 } 1740 1741 void qmp_marshal_my_command(QDict *args, QObject **ret, Error **errp) 1742 { 1743 Error *err = NULL; 1744 bool ok = false; 1745 Visitor *v; 1746 UserDefOne *retval; 1747 q_obj_my_command_arg arg = {0}; 1748 1749 v = qobject_input_visitor_new_qmp(QOBJECT(args)); 1750 if (!visit_start_struct(v, NULL, NULL, 0, errp)) { 1751 goto out; 1752 } 1753 if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) { 1754 ok = visit_check_struct(v, errp); 1755 } 1756 visit_end_struct(v, NULL); 1757 if (!ok) { 1758 goto out; 1759 } 1760 1761 if (trace_event_get_state_backends(TRACE_QMP_ENTER_MY_COMMAND)) { 1762 g_autoptr(GString) req_json = qobject_to_json(QOBJECT(args)); 1763 1764 trace_qmp_enter_my_command(req_json->str); 1765 } 1766 1767 retval = qmp_my_command(arg.arg1, &err); 1768 if (err) { 1769 trace_qmp_exit_my_command(error_get_pretty(err), false); 1770 error_propagate(errp, err); 1771 goto out; 1772 } 1773 1774 qmp_marshal_output_UserDefOne(retval, ret, errp); 1775 1776 if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) { 1777 g_autoptr(GString) ret_json = qobject_to_json(*ret); 1778 1779 trace_qmp_exit_my_command(ret_json->str, true); 1780 } 1781 1782 out: 1783 visit_free(v); 1784 v = qapi_dealloc_visitor_new(); 1785 visit_start_struct(v, NULL, NULL, 0, NULL); 1786 visit_type_q_obj_my_command_arg_members(v, &arg, NULL); 1787 visit_end_struct(v, NULL); 1788 visit_free(v); 1789 } 1790 1791 [Uninteresting stuff omitted...] 1792 $ cat qapi-generated/example-qapi-init-commands.h 1793 [Uninteresting stuff omitted...] 1794 #ifndef EXAMPLE_QAPI_INIT_COMMANDS_H 1795 #define EXAMPLE_QAPI_INIT_COMMANDS_H 1796 1797 #include "qapi/qmp/dispatch.h" 1798 1799 void example_qmp_init_marshal(QmpCommandList *cmds); 1800 1801 #endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */ 1802 $ cat qapi-generated/example-qapi-init-commands.c 1803 [Uninteresting stuff omitted...] 1804 void example_qmp_init_marshal(QmpCommandList *cmds) 1805 { 1806 QTAILQ_INIT(cmds); 1807 1808 qmp_register_command(cmds, "my-command", 1809 qmp_marshal_my_command, 0, 0); 1810 } 1811 [Uninteresting stuff omitted...] 1812 1813For a modular QAPI schema (see section `Include directives`_), code for 1814each sub-module SUBDIR/SUBMODULE.json is actually generated into:: 1815 1816 SUBDIR/$(prefix)qapi-commands-SUBMODULE.h 1817 SUBDIR/$(prefix)qapi-commands-SUBMODULE.c 1818 1819 1820Code generated for events 1821------------------------- 1822 1823This is the code related to events defined in the schema, providing 1824qapi_event_send_EVENT(). 1825 1826The following files are created: 1827 1828 ``$(prefix)qapi-events.h`` 1829 Function prototypes for each event type 1830 1831 ``$(prefix)qapi-events.c`` 1832 Implementation of functions to send an event 1833 1834 ``$(prefix)qapi-emit-events.h`` 1835 Enumeration of all event names, and common event code declarations 1836 1837 ``$(prefix)qapi-emit-events.c`` 1838 Common event code definitions 1839 1840Example:: 1841 1842 $ cat qapi-generated/example-qapi-events.h 1843 [Uninteresting stuff omitted...] 1844 1845 #ifndef EXAMPLE_QAPI_EVENTS_H 1846 #define EXAMPLE_QAPI_EVENTS_H 1847 1848 #include "qapi/util.h" 1849 #include "example-qapi-types.h" 1850 1851 void qapi_event_send_my_event(void); 1852 1853 #endif /* EXAMPLE_QAPI_EVENTS_H */ 1854 $ cat qapi-generated/example-qapi-events.c 1855 [Uninteresting stuff omitted...] 1856 1857 void qapi_event_send_my_event(void) 1858 { 1859 QDict *qmp; 1860 1861 qmp = qmp_event_build_dict("MY_EVENT"); 1862 1863 example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp); 1864 1865 qobject_unref(qmp); 1866 } 1867 1868 [Uninteresting stuff omitted...] 1869 $ cat qapi-generated/example-qapi-emit-events.h 1870 [Uninteresting stuff omitted...] 1871 1872 #ifndef EXAMPLE_QAPI_EMIT_EVENTS_H 1873 #define EXAMPLE_QAPI_EMIT_EVENTS_H 1874 1875 #include "qapi/util.h" 1876 1877 typedef enum example_QAPIEvent { 1878 EXAMPLE_QAPI_EVENT_MY_EVENT, 1879 EXAMPLE_QAPI_EVENT__MAX, 1880 } example_QAPIEvent; 1881 1882 #define example_QAPIEvent_str(val) \ 1883 qapi_enum_lookup(&example_QAPIEvent_lookup, (val)) 1884 1885 extern const QEnumLookup example_QAPIEvent_lookup; 1886 1887 void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict); 1888 1889 #endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */ 1890 $ cat qapi-generated/example-qapi-emit-events.c 1891 [Uninteresting stuff omitted...] 1892 1893 const QEnumLookup example_QAPIEvent_lookup = { 1894 .array = (const char *const[]) { 1895 [EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT", 1896 }, 1897 .size = EXAMPLE_QAPI_EVENT__MAX 1898 }; 1899 1900 [Uninteresting stuff omitted...] 1901 1902For a modular QAPI schema (see section `Include directives`_), code for 1903each sub-module SUBDIR/SUBMODULE.json is actually generated into :: 1904 1905 SUBDIR/$(prefix)qapi-events-SUBMODULE.h 1906 SUBDIR/$(prefix)qapi-events-SUBMODULE.c 1907 1908 1909Code generated for introspection 1910-------------------------------- 1911 1912The following files are created: 1913 1914 ``$(prefix)qapi-introspect.c`` 1915 Defines a string holding a JSON description of the schema 1916 1917 ``$(prefix)qapi-introspect.h`` 1918 Declares the above string 1919 1920Example:: 1921 1922 $ cat qapi-generated/example-qapi-introspect.h 1923 [Uninteresting stuff omitted...] 1924 1925 #ifndef EXAMPLE_QAPI_INTROSPECT_H 1926 #define EXAMPLE_QAPI_INTROSPECT_H 1927 1928 #include "qapi/qmp/qlit.h" 1929 1930 extern const QLitObject example_qmp_schema_qlit; 1931 1932 #endif /* EXAMPLE_QAPI_INTROSPECT_H */ 1933 $ cat qapi-generated/example-qapi-introspect.c 1934 [Uninteresting stuff omitted...] 1935 1936 const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) { 1937 QLIT_QDICT(((QLitDictEntry[]) { 1938 { "arg-type", QLIT_QSTR("0"), }, 1939 { "meta-type", QLIT_QSTR("command"), }, 1940 { "name", QLIT_QSTR("my-command"), }, 1941 { "ret-type", QLIT_QSTR("1"), }, 1942 {} 1943 })), 1944 QLIT_QDICT(((QLitDictEntry[]) { 1945 { "arg-type", QLIT_QSTR("2"), }, 1946 { "meta-type", QLIT_QSTR("event"), }, 1947 { "name", QLIT_QSTR("MY_EVENT"), }, 1948 {} 1949 })), 1950 /* "0" = q_obj_my-command-arg */ 1951 QLIT_QDICT(((QLitDictEntry[]) { 1952 { "members", QLIT_QLIST(((QLitObject[]) { 1953 QLIT_QDICT(((QLitDictEntry[]) { 1954 { "name", QLIT_QSTR("arg1"), }, 1955 { "type", QLIT_QSTR("[1]"), }, 1956 {} 1957 })), 1958 {} 1959 })), }, 1960 { "meta-type", QLIT_QSTR("object"), }, 1961 { "name", QLIT_QSTR("0"), }, 1962 {} 1963 })), 1964 /* "1" = UserDefOne */ 1965 QLIT_QDICT(((QLitDictEntry[]) { 1966 { "members", QLIT_QLIST(((QLitObject[]) { 1967 QLIT_QDICT(((QLitDictEntry[]) { 1968 { "name", QLIT_QSTR("integer"), }, 1969 { "type", QLIT_QSTR("int"), }, 1970 {} 1971 })), 1972 QLIT_QDICT(((QLitDictEntry[]) { 1973 { "default", QLIT_QNULL, }, 1974 { "name", QLIT_QSTR("string"), }, 1975 { "type", QLIT_QSTR("str"), }, 1976 {} 1977 })), 1978 QLIT_QDICT(((QLitDictEntry[]) { 1979 { "default", QLIT_QNULL, }, 1980 { "name", QLIT_QSTR("flag"), }, 1981 { "type", QLIT_QSTR("bool"), }, 1982 {} 1983 })), 1984 {} 1985 })), }, 1986 { "meta-type", QLIT_QSTR("object"), }, 1987 { "name", QLIT_QSTR("1"), }, 1988 {} 1989 })), 1990 /* "2" = q_empty */ 1991 QLIT_QDICT(((QLitDictEntry[]) { 1992 { "members", QLIT_QLIST(((QLitObject[]) { 1993 {} 1994 })), }, 1995 { "meta-type", QLIT_QSTR("object"), }, 1996 { "name", QLIT_QSTR("2"), }, 1997 {} 1998 })), 1999 QLIT_QDICT(((QLitDictEntry[]) { 2000 { "element-type", QLIT_QSTR("1"), }, 2001 { "meta-type", QLIT_QSTR("array"), }, 2002 { "name", QLIT_QSTR("[1]"), }, 2003 {} 2004 })), 2005 QLIT_QDICT(((QLitDictEntry[]) { 2006 { "json-type", QLIT_QSTR("int"), }, 2007 { "meta-type", QLIT_QSTR("builtin"), }, 2008 { "name", QLIT_QSTR("int"), }, 2009 {} 2010 })), 2011 QLIT_QDICT(((QLitDictEntry[]) { 2012 { "json-type", QLIT_QSTR("string"), }, 2013 { "meta-type", QLIT_QSTR("builtin"), }, 2014 { "name", QLIT_QSTR("str"), }, 2015 {} 2016 })), 2017 QLIT_QDICT(((QLitDictEntry[]) { 2018 { "json-type", QLIT_QSTR("boolean"), }, 2019 { "meta-type", QLIT_QSTR("builtin"), }, 2020 { "name", QLIT_QSTR("bool"), }, 2021 {} 2022 })), 2023 {} 2024 })); 2025 2026 [Uninteresting stuff omitted...] 2027