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