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