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