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