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