diff options
Diffstat (limited to 'docs/devel')
| -rw-r--r-- | docs/devel/qapi-code-gen.txt | 1067 |
1 files changed, 618 insertions, 449 deletions
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt index e8ec8ac1de..64d9e4c6a9 100644 --- a/docs/devel/qapi-code-gen.txt +++ b/docs/devel/qapi-code-gen.txt @@ -4,262 +4,99 @@ Copyright IBM Corp. 2011 Copyright (C) 2012-2016 Red Hat, Inc. This work is licensed under the terms of the GNU GPL, version 2 or -later. See the COPYING file in the top-level directory. +later. See the COPYING file in the top-level directory. == Introduction == QAPI is a native C API within QEMU which provides management-level -functionality to internal and external users. For external +functionality to internal and external users. For external users/processes, this interface is made available by a JSON-based wire format for the QEMU Monitor Protocol (QMP) for controlling qemu, as well as the QEMU Guest Agent (QGA) for communicating with the guest. The remainder of this document uses "Client JSON Protocol" when referring to the wire contents of a QMP or QGA connection. -To map Client JSON Protocol interfaces to the native C QAPI -implementations, a JSON-based schema is used to define types and -function signatures, and a set of scripts is used to generate types, -signatures, and marshaling/dispatch code. This document will describe -how the schemas, scripts, and resulting code are used. +To map between Client JSON Protocol interfaces and the native C API, +we generate C code from a QAPI schema. This document describes the +QAPI schema language, and how it gets mapped to the Client JSON +Protocol and to C. It additionally provides guidance on maintaining +Client JSON Protocol compatibility. -== QMP/Guest agent schema == +== The QAPI schema language == -A QAPI schema file is designed to be loosely based on JSON -(http://www.ietf.org/rfc/rfc8259.txt) with changes for quoting style -and the use of comments; a QAPI schema file is then parsed by a python -code generation program. A valid QAPI schema consists of a series of -top-level expressions, with no commas between them. Where -dictionaries (JSON objects) are used, they are parsed as python -OrderedDicts so that ordering is preserved (for predictable layout of -generated C structs and parameter lists). Ordering doesn't matter -between top-level expressions or the keys within an expression, but -does matter within dictionary values for 'data' and 'returns' members -of a single expression. QAPI schema input is written using 'single -quotes' instead of JSON's "double quotes" (in contrast, Client JSON -Protocol uses no comments, and while input accepts 'single quotes' as -an extension, output is strict JSON using only "double quotes"). As -in JSON, trailing commas are not permitted in arrays or dictionaries. -Input must be ASCII (although QMP supports full Unicode strings, the -QAPI parser does not). At present, there is no place where a QAPI -schema requires the use of JSON numbers or null. +The QAPI schema defines the Client JSON Protocol's commands and +events, as well as types used by them. Forward references are +allowed. +It is permissible for the schema to contain additional types not used +by any commands or events, for the side effect of generated C code +used internally. -=== Comments === +There are several kinds of types: simple types (a number of built-in +types, such as 'int' and 'str'; as well as enumerations), arrays, +complex types (structs and two flavors of unions), and alternate types +(a choice between other types). -Comments are allowed; anything between an unquoted # and the following -newline is ignored. -A multi-line comment that starts and ends with a '##' line is a -documentation comment. These are parsed by the documentation -generator, which recognizes certain markup detailed below. - - -==== Documentation markup ==== - -Comment text starting with '=' is a section title: - - # = Section title - -Double the '=' for a subsection title: - - # == Subsection title +=== Schema syntax === -'|' denotes examples: - - # | Text of the example, may span - # | multiple lines - -'*' starts an itemized list: +Syntax is loosely based on JSON (http://www.ietf.org/rfc/rfc8259.txt). +Differences: - # * First item, may span - # multiple lines - # * Second item +* Comments: start with a hash character (#) that is not part of a + string, and extend to the end of the line. -You can also use '-' instead of '*'. +* Strings are enclosed in 'single quotes', not "double quotes". -A decimal number followed by '.' starts a numbered list: +* Strings are restricted to printable ASCII, and escape sequences to + just '\\'. - # 1. First item, may span - # multiple lines - # 2. Second item - -The actual number doesn't matter. You could even use '*' instead of -'2.' for the second item. - -Lists can't be nested. Blank lines are currently not supported within -lists. - -Additional whitespace between the initial '#' and the comment text is -permitted. - -*foo* and _foo_ are for strong and emphasis styles respectively (they -do not work over multiple lines). @foo is used to reference a name in -the schema. - -Example: - -## -# = Section -# == Subsection -# -# Some text foo with *strong* and _emphasis_ -# 1. with a list -# 2. like that -# -# And some code: -# | $ echo foo -# | -> do this -# | <- get that -# -## - - -==== Expression documentation ==== - -Each expression that isn't an include directive may be preceded by a -documentation block. Such blocks are called expression documentation -blocks. - -When documentation is required (see pragma 'doc-required'), expression -documentation blocks are mandatory. - -The documentation block consists of a first line naming the -expression, an optional overview, a description of each argument (for -commands and events) or member (for structs, unions and alternates), -and optional tagged sections. - -FIXME: the parser accepts these things in almost any order. - -Extensions added after the expression was first released carry a -'(since x.y.z)' comment. - -A tagged section starts with one of the following words: -"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". -The section ends with the start of a new section. - -A 'Since: x.y.z' tagged section lists the release that introduced the -expression. - -For example: - -## -# @BlockStats: -# -# Statistics of a virtual block device or a block backing device. -# -# @device: If the stats are for a virtual block device, the name -# corresponding to the virtual block device. -# -# @node-name: The node name of the device. (since 2.3) -# -# ... more members ... -# -# Since: 0.14.0 -## -{ 'struct': 'BlockStats', - 'data': {'*device': 'str', '*node-name': 'str', - ... more members ... } } - -## -# @query-blockstats: -# -# Query the @BlockStats for all virtual block devices. -# -# @query-nodes: If true, the command will query all the -# block nodes ... explain, explain ... (since 2.3) -# -# Returns: A list of @BlockStats for each virtual block devices. -# -# Since: 0.14.0 -# -# Example: -# -# -> { "execute": "query-blockstats" } -# <- { -# ... lots of output ... -# } -# -## -{ 'command': 'query-blockstats', - 'data': { '*query-nodes': 'bool' }, - 'returns': ['BlockStats'] } +* Numbers and null are not supported. -==== Free-form documentation ==== - -A documentation block that isn't an expression documentation block is -a free-form documentation block. These may be used to provide -additional text and structuring content. - - -=== Schema overview === - -The schema sets up a series of types, as well as commands and events -that will use those types. Forward references are allowed: the parser -scans in two passes, where the first pass learns all type names, and -the second validates the schema and generates the code. This allows -the definition of complex structs that can have mutually recursive -types, and allows for indefinite nesting of Client JSON Protocol that -satisfies the schema. A type name should not be defined more than -once. It is permissible for the schema to contain additional types -not used by any commands or events in the Client JSON Protocol, for -the side effect of generated C code used internally. - -There are eight top-level expressions recognized by the parser: -'include', 'pragma', 'command', 'struct', 'enum', 'union', -'alternate', and 'event'. There are several groups of types: simple -types (a number of built-in types, such as 'int' and 'str'; as well as -enumerations), complex types (structs and two flavors of unions), and -alternate types (a choice between other types). The 'command' and -'event' expressions can refer to existing types by name, or list an -anonymous type as a dictionary. Listing a type name inside an array -refers to a single-dimension array of that type; multi-dimension -arrays are not directly supported (although an array of a complex -struct that contains an array member is possible). +A second layer of syntax defines the sequences of JSON texts that are +a correctly structured QAPI schema. We provide a grammar for this +syntax in an EBNF-like notation: -All names must begin with a letter, and contain only ASCII letters, -digits, hyphen, and underscore. There are two exceptions: enum values -may start with a digit, and names that are downstream extensions (see -section Downstream extensions) start with underscore. +* Production rules look like non-terminal = expression +* Concatenation: expression A B matches expression A, then B +* Alternation: expression A | B matches expression A or B +* Repetition: expression A... matches zero or more occurrences of + expression A +* Repetition: expression A, ... matches zero or more occurrences of + expression A separated by , +* Grouping: expression ( A ) matches expression A +* JSON's structural characters are terminals: { } [ ] : , +* JSON's literal names are terminals: false true +* String literals enclosed in 'single quotes' are terminal, and match + this JSON string, with a leading '*' stripped off +* When JSON object member's name starts with '*', the member is + optional. +* The symbol STRING is a terminal, and matches any JSON string +* The symbol BOOL is a terminal, and matches JSON false or true +* ALL-CAPS words other than STRING are non-terminals -Names beginning with 'q_' are reserved for the generator, which uses -them for munging QMP names that resemble C keywords or other -problematic strings. For example, a member named "default" in qapi -becomes "q_default" in the generated C code. +The order of members within JSON objects does not matter unless +explicitly noted. -Types, commands, and events share a common namespace. Therefore, -generally speaking, type definitions should always use CamelCase for -user-defined type names, while built-in types are lowercase. +A QAPI schema consists of a series of top-level expressions: -Type names ending with 'Kind' or 'List' are reserved for the -generator, which uses them for implicit union enums and array types, -respectively. + SCHEMA = TOP-LEVEL-EXPR... -Command names, and member names within a type, should be all lower -case with words separated by a hyphen. However, some existing older -commands and complex types use underscore; when extending such -expressions, consistency is preferred over blindly avoiding -underscore. +The top-level expressions are all JSON objects. Code and +documentation is generated in schema definition order. Code order +should not matter. -Event names should be ALL_CAPS with words separated by underscore. +A top-level expressions is either a directive or a definition: -Member names starting with 'has-' or 'has_' are reserved for the -generator, which uses them for tracking optional members. + TOP-LEVEL-EXPR = DIRECTIVE | DEFINITION -Any name (command, event, type, member, or enum value) beginning with -"x-" is marked experimental, and may be withdrawn or changed -incompatibly in a future release. +There are two kinds of directives and six kinds of definitions: -Pragma 'name-case-whitelist' lets you violate the rules on use of -upper and lower case. Use for new code is strongly discouraged. + DIRECTIVE = INCLUDE | PRAGMA + DEFINITION = ENUM | STRUCT | UNION | ALTERNATE | COMMAND | EVENT -In the rest of this document, usage lines are given for each -expression type, with literal strings written in lower case and -placeholders written in capitals. If a literal string includes a -prefix of '*', that key/value pair can be omitted from the expression. -For example, a usage statement that includes '*base':STRUCT-NAME -means that an expression has an optional key 'base', which if present -must have a value that forms a struct name. +These are discussed in detail below. === Built-in Types === @@ -289,16 +126,16 @@ The following types are predefined, and map to C as follows: === Include directives === -Usage: { 'include': STRING } +Syntax: + INCLUDE = { 'include': STRING } The QAPI schema definitions can be modularized using the 'include' directive: { 'include': 'path/to/file.json' } -The directive is evaluated recursively, and include paths are relative to the -file using the directive. Multiple includes of the same file are -idempotent. No other keys should appear in the expression, and the include -value should be a string. +The directive is evaluated recursively, and include paths are relative +to the file using the directive. Multiple includes of the same file +are idempotent. As a matter of style, it is a good idea to have all files be self-contained, but at the moment, nothing prevents an included file @@ -309,10 +146,12 @@ prevent incomplete include files. === Pragma directives === -Usage: { 'pragma': DICT } +Syntax: + PRAGMA = { 'pragma': { '*doc-required': BOOL, + '*returns-whitelist': [ STRING, ... ], + '*name-case-whitelist': [ STRING, ... ] } } The pragma directive lets you control optional generator behavior. -The dictionary's entries are pragma names and values. Pragma's scope is currently the complete schema. Setting the same pragma to different values in parts of the schema doesn't work. @@ -327,56 +166,97 @@ Pragma 'name-case-whitelist' takes a list of names that may violate rules on use of upper- vs. lower-case letters. Default is none. +=== Enumeration types === + +Syntax: + ENUM = { 'enum': STRING, + 'data': [ ENUM-VALUE, ... ], + '*prefix': STRING, + '*if': COND } + ENUM-VALUE = STRING + | { 'name': STRING, '*if': COND } + +Member 'enum' names the enum type. + +Each member of the 'data' array defines a value of the enumeration +type. The form STRING is shorthand for { 'name': STRING }. The +'name' values must be be distinct. + +Example: + + { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } + +Nothing prevents an empty enumeration, although it is probably not +useful. + +On the wire, an enumeration type's value is represented by its +(string) name. In C, it's represented by an enumeration constant. +These are of the form PREFIX_NAME, where PREFIX is derived from the +enumeration type's name, and NAME from the value's name. For the +example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to +VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The +optional 'prefix' member overrides PREFIX. + +The generated C enumeration constants have values 0, 1, ..., N-1 (in +QAPI schema order), where N is the number of values. There is an +additional enumeration constant PREFIX__MAX with value N. + +Do not use string or an integer type when an enumeration type can do +the job satisfactorily. + +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. + + +=== Type references and array types === + +Syntax: + TYPE-REF = STRING | ARRAY-TYPE + ARRAY-TYPE = [ STRING ] + +A string denotes the type named by the string. + +A one-element array containing a string denotes an array of the type +named by the string. Example: ['int'] denotes an array of 'int'. + + === Struct types === -Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } +Syntax: + STRUCT = { 'struct': STRING, + 'data': MEMBERS, + '*base': STRING, + '*if': COND, + '*features': FEATURES } + MEMBERS = { MEMBER, ... } + MEMBER = STRING : TYPE-REF + | STRING : { 'type': TYPE-REF, '*if': COND } + +Member 'struct' names the struct type. -A struct is a dictionary containing a single 'data' key whose value is -a dictionary; the dictionary may be empty. This corresponds to a -struct in C or an Object in JSON. Each value of the 'data' dictionary -must be the name of a type, or a one-element array containing a type -name. An example of a struct is: +Each MEMBER of the 'data' object defines a member of the struct type. + +The MEMBER's STRING name consists of an optional '*' prefix and the +struct member name. If '*' is present, the member is optional. + +The MEMBER's value defines its properties, in particular its type. +The form TYPE-REF is shorthand for { 'type': TYPE-REF }. + +Example: { 'struct': 'MyType', - 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } - -The use of '*' as a prefix to the name means the member is optional in -the corresponding JSON protocol usage. - -The default initialization value of an optional argument should not be changed -between versions of QEMU unless the new default maintains backward -compatibility to the user-visible behavior of the old default. - -With proper documentation, this policy still allows some flexibility; for -example, documenting that a default of 0 picks an optimal buffer size allows -one release to declare the optimal size at 512 while another release declares -the optimal size at 4096 - the user-visible behavior is not the bytes used by -the buffer, but the fact that the buffer was optimal size. - -On input structures (only mentioned in the 'data' side of a command), changing -from mandatory to optional is safe (older clients will supply the option, and -newer clients can benefit from the default); changing from optional to -mandatory is backwards incompatible (older clients may be omitting the option, -and must continue to work). - -On output structures (only mentioned in the 'returns' side of a command), -changing from mandatory to optional is in general unsafe (older clients may be -expecting the member, and could crash if it is missing), although it -can be done if the only way that the optional argument will be omitted -is when it is triggered by the presence of a new input flag to the -command that older clients don't know to send. Changing from optional -to mandatory is safe. - -A structure that is used in both input and output of various commands -must consider the backwards compatibility constraints of both directions -of use. - -A struct definition can specify another struct as its base. -In this case, the members of the base type are included as top-level members -of the new struct's dictionary in the Client JSON Protocol wire -format. An example definition is: - - { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } + 'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } } + +A struct type corresponds to a struct in C, and an object in JSON. +The C struct's members are generated in QAPI schema order. + +The optional 'base' member names a struct type whose members are to be +included in this type. They go first in the C struct. + +Example: + + { 'struct': 'BlockdevOptionsGenericFormat', + 'data': { 'file': 'str' } } { 'struct': 'BlockdevOptionsGenericCOWFormat', 'base': 'BlockdevOptionsGenericFormat', 'data': { '*backing': 'str' } } @@ -387,56 +267,40 @@ both members like this: { "file": "/some/place/my-image", "backing": "/some/place/my-backing-file" } +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. -=== Enumeration types === +The optional 'features' member specifies features. See "Features" +below for more on this. -Usage: { 'enum': STRING, 'data': ARRAY-OF-STRING } - { 'enum': STRING, '*prefix': STRING, 'data': ARRAY-OF-STRING } -An enumeration type is a dictionary containing a single 'data' key -whose value is a list of strings. An example enumeration is: +=== Union types === - { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } +Syntax: + UNION = { 'union': STRING, + 'data': BRANCHES, + '*if': COND } + | { 'union': STRING, + 'data': BRANCHES, + 'base': ( MEMBERS | STRING ), + 'discriminator': STRING, + '*if': COND } + BRANCHES = { BRANCH, ... } + BRANCH = STRING : TYPE-REF + | STRING : { 'type': TYPE-REF, '*if': COND } -Nothing prevents an empty enumeration, although it is probably not -useful. The list of strings should be lower case; if an enum name -represents multiple words, use '-' between words. The string 'max' is -not allowed as an enum value, and values should not be repeated. - -The enum constants will be named by using a heuristic to turn the -type name into a set of underscore separated words. For the example -above, 'MyEnum' will turn into 'MY_ENUM' giving a constant name -of 'MY_ENUM_VALUE1' for the first value. If the default heuristic -does not result in a desirable name, the optional 'prefix' member -can be used when defining the enum. - -The enumeration values are passed as strings over the Client JSON -Protocol, but are encoded as C enum integral values in generated code. -While the C code starts numbering at 0, it is better to use explicit -comparisons to enum values than implicit comparisons to 0; the C code -will also include a generated enum member ending in _MAX for tracking -the size of the enum, useful when using common functions for -converting between strings and enum values. Since the wire format -always passes by name, it is acceptable to reorder or add new -enumeration members in any location without breaking clients of Client -JSON Protocol; however, removing enum values would break -compatibility. For any struct that has a member that will only contain -a finite set of string values, using an enum type for that member is -better than open-coding the member to be type 'str'. +Member 'union' names the union type. +There are two flavors of union types: simple (no discriminator or +base), and flat (both discriminator and base). -=== Union types === +Each BRANCH of the 'data' object defines a branch of the union. A +union must have at least one branch. -Usage: { 'union': STRING, 'data': DICT } -or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME-OR-DICT, - 'discriminator': ENUM-MEMBER-OF-BASE } +The BRANCH's STRING name is the branch name. -Union types are used to let the user choose between several different -variants for an object. There are two flavors: simple (no -discriminator or base), and flat (both discriminator and base). A union -type is defined using a data dictionary as explained in the following -paragraphs. The data dictionary for either type of union must not -be empty. +The BRANCH's value defines the branch's properties, in particular its +type. The form TYPE-REF is shorthand for { 'type': TYPE-REF }. A simple union type defines a mapping from automatic discriminator values to data types like in this example: @@ -449,8 +313,8 @@ values to data types like in this example: 'data': { 'file': 'BlockdevOptionsFile', 'qcow2': 'BlockdevOptionsQcow2' } } -In the Client JSON Protocol, a simple union is represented by a -dictionary that contains the 'type' member as a discriminator, and a +In the Client JSON Protocol, a simple union is represented by an +object that contains the 'type' member as a discriminator, and a 'data' member that is of the specified data type corresponding to the discriminator value, as in these examples: @@ -458,22 +322,27 @@ discriminator value, as in these examples: { "type": "qcow2", "data": { "backing": "/some/place/my-image", "lazy-refcounts": true } } -The generated C code uses a struct containing a union. Additionally, +The generated C code uses a struct containing a union. Additionally, an implicit C enum 'NameKind' is created, corresponding to the union -'Name', for accessing the various branches of the union. No branch of -the union can be named 'max', as this would collide with the implicit -enum. The value for each branch can be of any type. - -A flat union definition avoids nesting on the wire, and specifies a -set of common members that occur in all variants of the union. The -'base' key must specify either a type name (the type must be a -struct, not a union), or a dictionary representing an anonymous type. -All branches of the union must be complex types, and the top-level -members of the union dictionary on the wire will be combination of -members from both the base type and the appropriate branch type (when -merging two dictionaries, there must be no keys in common). The -'discriminator' member must be the name of a non-optional enum-typed -member of the base struct. +'Name', for accessing the various branches of the union. The value +for each branch can be of any type. + +Flat unions permit arbitrary common members that occur in all variants +of the union, not just a discriminator. Their discriminators need not +be named 'type'. They also avoid nesting on the wire. + +The 'base' member defines the common members. If it is a MEMBERS +object, it defines common members just like a struct type's 'data' +member defines struct type members. If it is a STRING, it names a +struct type whose members are the common members. + +All flat union branches must be of struct type. + +In the Client JSON Protocol, a flat union is represented by an object +with the common members (from the base type) and the selected branch's +members. The two sets of member names must be disjoint. Member +'discriminator' must name a non-optional enum-typed member of the base +struct. The following example enhances the above simple union example by adding an optional common member 'read-only', renaming the @@ -497,12 +366,13 @@ Resulting in these JSON objects: Notice that in a flat union, the discriminator name is controlled by the user, but because it must map to a base member with enum type, the code generator ensures that branches match the existing values of the -enum. The order of the keys need not match the declaration of the enum. -The keys need not cover all possible enum values. Omitted enum values -are still valid branches that add no additional members to the data type. -In the resulting generated C data types, a flat union is -represented as a struct with the base members included directly, and -then a union of structures for each branch of the struct. +enum. The order of branches need not match the order of the enum +values. The branches need not cover all possible enum values. +Omitted enum values are still valid branches that add no additional +members to the data type. In the resulting generated C data types, a +flat union is represented as a struct with the base members in QAPI +schema order, and then a union of structures for each branch of the +struct. A simple union can always be re-written as a flat union where the base class has a single member named 'type', and where each branch of the @@ -518,32 +388,47 @@ is identical on the wire to: { 'union': 'Flat': 'base': { 'type': 'Enum' }, 'discriminator': 'type', 'data': { 'one': 'Branch1', 'two': 'Branch2' } } +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. + === Alternate types === -Usage: { 'alternate': STRING, 'data': DICT } +Syntax: + ALTERNATE = { 'alternate': STRING, + 'data': ALTERNATIVES, + '*if': COND } + ALTERNATIVES = { ALTERNATIVE, ... } + ALTERNATIVE = STRING : TYPE-REF + | STRING : { 'type': STRING, '*if': COND } + +Member 'alternate' names the alternate type. -An alternate type is one that allows a choice between two or more JSON -data types (string, integer, number, or object, but currently not -array) on the wire. The definition is similar to a simple union type, -where each branch of the union names a QAPI type. For example: +Each ALTERNATIVE of the 'data' object defines a branch of the +alternate. An alternate must have at least one branch. + +The ALTERNATIVE's STRING name is the branch name. + +The ALTERNATIVE's value defines the branch's properties, in particular +its type. The form STRING is shorthand for { 'type': STRING }. + +Example: { 'alternate': 'BlockdevRef', 'data': { 'definition': 'BlockdevOptions', 'reference': 'str' } } -Unlike a union, the discriminator string is never passed on the wire -for the Client JSON Protocol. Instead, the value's JSON type serves -as an implicit discriminator, which in turn means that an alternate -can only express a choice between types represented differently in -JSON. If a branch is typed as the 'bool' built-in, the alternate -accepts true and false; if it is typed as any of the various numeric +An alternate type is like a union type, except there is no +discriminator on the wire. Instead, the branch to use is inferred +from the value. An alternate can only express a choice between types +represented differently on the wire. + +If a branch is typed as the 'bool' built-in, the alternate accepts +true and false; if it is typed as any of the various numeric built-ins, it accepts a JSON number; if it is typed as a 'str' built-in or named enum type, it accepts a JSON string; if it is typed as the 'null' built-in, it accepts JSON null; and if it is typed as a -complex type (struct or union), it accepts a JSON object. Two -different complex types, for instance, aren't permitted, because both -are represented as a JSON object. +complex type (struct or union), it accepts a JSON object. The example alternate declaration above allows using both of the following example objects: @@ -553,43 +438,52 @@ following example objects: "read-only": false, "filename": "/tmp/mydisk.qcow2" } } +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. + === Commands === ---- General Command Layout --- - -Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, - '*returns': TYPE-NAME, '*boxed': true, - '*gen': false, '*success-response': false, - '*allow-oob': true, '*allow-preconfig': true } - -Commands are defined by using a dictionary containing several members, -where three members are most common. The 'command' member is a -mandatory string, and determines the "execute" value passed in a -Client JSON Protocol command exchange. - -The 'data' argument maps to the "arguments" dictionary passed in as -part of a Client JSON Protocol command. The 'data' member is optional -and defaults to {} (an empty dictionary). If present, it must be the -string name of a complex type, or a dictionary that declares an -anonymous type with the same semantics as a 'struct' expression. - -The 'returns' member describes what will appear in the "return" member -of a Client JSON Protocol reply on successful completion of a command. -The member is optional from the command declaration; if absent, the -"return" member will be an empty dictionary. If 'returns' is present, -it must be the string name of a complex or built-in type, a -one-element array containing the name of a complex or built-in type. -To return anything else, you have to list the command in pragma -'returns-whitelist'. If you do this, the command cannot be extended -to return additional information in the future. Use of +Syntax: + COMMAND = { 'command': STRING, + ( + '*data': ( MEMBERS | STRING ), + | + 'data': STRING, + 'boxed': true, + ) + '*returns': TYPE-REF, + '*success-response': false, + '*gen': false, + '*allow-oob': true, + '*allow-preconfig': true, + '*if': COND } + +Member 'command' names the command. + +Member 'data' defines the arguments. It defaults to an empty MEMBERS +object. + +If 'data' is a MEMBERS object, then MEMBERS defines arguments just +like a struct type's 'data' defines struct type members. + +If 'data' is a STRING, then STRING names a complex type whose members +are the arguments. A union type requires 'boxed': true. + +Member 'returns' defines the command's return type. It defaults to an +empty struct type. It must normally be a complex type or an array of +a complex type. To return anything else, the command must be listed +in pragma 'returns-whitelist'. If you do this, extending the command +to return additional information will be harder. Use of 'returns-whitelist' for new commands is strongly discouraged. -All commands in Client JSON Protocol use a dictionary to report -failure, with no way to specify that in QAPI. Where the error return -is different than the usual GenericError class in order to help the -client react differently to certain error conditions, it is worth -documenting this in the comments before the command declaration. +A command's error responses are not specified in the QAPI schema. +Error conditions should be documented in comments. + +In the Client JSON Protocol, the value of the "execute" or "exec-oob" +member is the command name. The value of the "arguments" member then +has to conform to the arguments, and the value of the success +response's "return" member will conform to the return type. Some example commands: @@ -607,23 +501,24 @@ which would validate this Client JSON Protocol transaction: => { "execute": "my-second-command" } <= { "return": [ { "value": "one" }, { } ] } -The generator emits a prototype for the user's function implementing -the command. Normally, 'data' is a dictionary for an anonymous type, -or names a struct type (possibly empty, but not a union), and its -members are passed as separate arguments to this function. If the -command definition includes a key 'boxed' with the boolean value true, -then 'data' is instead the name of any non-empty complex type -(struct, union, or alternate), and a pointer to that QAPI type is -passed as a single argument. +The generator emits a prototype for the C function implementing the +command. The function itself needs to be written by hand. See +section "Code generated for commands" for examples. + +The function returns the return type. When member 'boxed' is absent, +it takes the command arguments as arguments one by one, in QAPI schema +order. Else it takes them wrapped in the C struct generated for the +complex argument type. It takes an additional Error ** argument in +either case. The generator also emits a marshalling function that extracts arguments for the user's function out of an input QDict, calls the user's function, and if it succeeded, builds an output QObject from -its return value. +its return value. This is for use by the QMP monitor core. In rare cases, QAPI cannot express a type-safe representation of a corresponding Client JSON Protocol command. You then have to suppress -generation of a marshalling function by including a key 'gen' with +generation of a marshalling function by including a member 'gen' with boolean value false, and instead write your own function. For example: @@ -637,13 +532,12 @@ use type-safe unions. Normally, the QAPI schema is used to describe synchronous exchanges, where a response is expected. But in some cases, the action of a command is expected to change state in a way that a successful -response is not possible (although the command will still return a -normal dictionary error on failure). When a successful reply is not -possible, the command expression includes the optional key -'success-response' with boolean value false. So far, only QGA makes -use of this member. +response is not possible (although the command will still return an +error object on failure). When a successful reply is not possible, +the command definition includes the optional member 'success-response' +with boolean value false. So far, only QGA makes use of this member. -Key 'allow-oob' declares whether the command supports out-of-band +Member 'allow-oob' declares whether the command supports out-of-band (OOB) execution. It defaults to false. For example: { 'command': 'migrate_recover', @@ -676,8 +570,8 @@ other "slow" lock. When in doubt, do not implement OOB execution support. -Key 'allow-preconfig' declares whether the command is available before -the machine is built. It defaults to false. For example: +Member 'allow-preconfig' declares whether the command is available +before the machine is built. It defaults to false. For example: { 'command': 'qmp_capabilities', 'data': { '*enable': [ 'QMPCapability' ] }, @@ -686,18 +580,33 @@ the machine is built. It defaults to false. For example: QMP is available before the machine is built only when QEMU was started with --preconfig. +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. + + === Events === -Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, - '*boxed': true } +Syntax: + EVENT = { 'event': STRING, + ( + '*data': ( MEMBERS | STRING ), + | + 'data': STRING, + 'boxed': true, + ) + '*if': COND } + +Member 'event' names the event. This is the event name used in the +Client JSON Protocol. -Events are defined with the keyword 'event'. It is not allowed to -name an event 'MAX', since the generator also produces a C enumeration -of all event names with a generated _MAX value at the end. When -'data' is also specified, additional info will be included in the -event, with similar semantics to a 'struct' expression. Finally there -will be C API generated in qapi-events.h; when called by QEMU code, a -message with timestamp will be emitted on the wire. +Member 'data' defines the event-specific data. It defaults to an +empty MEMBERS object. + +If 'data' is a MEMBERS object, then MEMBERS defines event-specific +data just like a struct type's 'data' defines struct type members. + +If 'data' is a STRING, then STRING names a complex type whose members +are the event-specific data. A union type requires 'boxed': true. An example event is: @@ -710,41 +619,82 @@ Resulting in this JSON object: "data": { "b": "test string" }, "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } -The generator emits a function to send the event. Normally, 'data' is -a dictionary for an anonymous type, or names a struct type (possibly -empty, but not a union), and its members are passed as separate -arguments to this function. If the event definition includes a key -'boxed' with the boolean value true, then 'data' is instead the name of -any non-empty complex type (struct, union, or alternate), and a -pointer to that QAPI type is passed as a single argument. +The generator emits a function to send the event. When member 'boxed' +is absent, it takes event-specific data one by one, in QAPI schema +order. Else it takes them wrapped in the C struct generated for the +complex type. See section "Code generated for events" for examples. + +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. === Features === +Syntax: + FEATURES = [ FEATURE, ... ] + FEATURE = STRING + | { 'name': STRING, '*if': COND } + Sometimes, the behaviour of QEMU changes compatibly, but without a -change in the QMP syntax (usually by allowing values or operations that -previously resulted in an error). QMP clients may still need to know -whether the extension is available. +change in the QMP syntax (usually by allowing values or operations +that previously resulted in an error). QMP clients may still need to +know whether the extension is available. For this purpose, a list of features can be specified for a struct type. This is exposed to the client as a list of string, where each string signals that this build of QEMU shows a certain behaviour. -In the schema, features can be specified as simple strings, for example: +Each member of the 'features' array defines a feature. It can either +be { 'name': STRING, '*if': COND }, or STRING, which is shorthand for +{ 'name': STRING }. + +The optional 'if' member specifies a conditional. See "Configuring +the schema" below for more on this. + +Example: { 'struct': 'TestType', 'data': { 'number': 'int' }, 'features': [ 'allow-negative-numbers' ] } -Another option is to specify features as dictionaries, where the key -'name' specifies the feature string to be exposed to clients: -{ 'struct': 'TestType', - 'data': { 'number': 'int' }, - 'features': [ { 'name': 'allow-negative-numbers' } ] } +=== Naming rules and reserved names === -This expanded form is necessary if you want to make the feature -conditional (see below in "Configuring the schema"). +All names must begin with a letter, and contain only ASCII letters, +digits, hyphen, and underscore. There are two exceptions: enum values +may start with a digit, and names that are downstream extensions (see +section Downstream extensions) start with underscore. + +Names beginning with 'q_' are reserved for the generator, which uses +them for munging QMP names that resemble C keywords or other +problematic strings. For example, a member named "default" in qapi +becomes "q_default" in the generated C code. + +Types, commands, and events share a common namespace. Therefore, +generally speaking, type definitions should always use CamelCase for +user-defined type names, while built-in types are lowercase. + +Type names ending with 'Kind' or 'List' are reserved for the +generator, which uses them for implicit union enums and array types, +respectively. + +Command names, and member names within a type, should be all lower +case with words separated by a hyphen. However, some existing older +commands and complex types use underscore; when extending them, +consistency is preferred over blindly avoiding underscore. + +Event names should be ALL_CAPS with words separated by underscore. + +Member name 'u' and names starting with 'has-' or 'has_' are reserved +for the generator, which uses them for unions and for tracking +optional members. + +Any name (command, event, type, member, or enum value) beginning with +"x-" is marked experimental, and may be withdrawn or changed +incompatibly in a future release. + +Pragma 'name-case-whitelist' lets you violate the rules on use of +upper and lower case. Use for new code is strongly discouraged. === Downstream extensions === @@ -761,11 +711,14 @@ downstream command __com.redhat_drive-mirror. === Configuring the schema === -The 'struct', 'enum', 'union', 'alternate', 'command' and 'event' -top-level expressions can take an 'if' key. Its value must be a string -or a list of strings. A string is shorthand for a list containing just -that string. The code generated for the top-level expression will then -be guarded by #if COND for each COND in the list. +Syntax: + COND = STRING + | [ STRING, ... ] + +All definitions take an optional 'if' member. Its value must be a +string or a list of strings. A string is shorthand for a list +containing just that string. The code generated for the definition +will then be guarded by #if STRING for each STRING in the COND list. Example: a conditional struct @@ -780,29 +733,33 @@ gets its generated code guarded like this: #endif /* defined(HAVE_BAR) */ #endif /* defined(CONFIG_FOO) */ -Where a member can be defined with a single string value for its type, -it is also possible to supply a dictionary instead with both 'type' -and 'if' keys. +Individual members of complex types, commands arguments, and +event-specific data can also be made conditional. This requires the +longhand form of MEMBER. -Example: a conditional 'bar' member +Example: a struct type with unconditional member 'foo' and conditional +member 'bar' { 'struct': 'IfStruct', 'data': { 'foo': 'int', 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } } -An enum value can be replaced by a dictionary with a 'name' and a 'if' -key. +A union's discriminator may not be conditional. + +Likewise, individual enumeration values be conditional. This requires +the longhand form of ENUM-VALUE. -Example: a conditional 'bar' enum member. +Example: an enum type with unconditional value 'foo' and conditional +value 'bar' { 'enum': 'IfEnum', 'data': [ 'foo', { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] } -Similarly, features can be specified as a dictionary with a 'name' and -an 'if' key. +Likewise, features can be conditional. This requires the longhand +form of FEATURE. -Example: a conditional 'allow-negative-numbers' feature +Example: a struct with conditional feature 'allow-negative-numbers' { 'struct': 'TestType', 'data': { 'number': 'int' }, @@ -811,10 +768,162 @@ Example: a conditional 'allow-negative-numbers' feature Please note that you are responsible to ensure that the C code will compile with an arbitrary combination of conditions, since the -generators are unable to check it at this point. +generator is unable to check it at this point. + +The conditions apply to introspection as well, i.e. introspection +shows a conditional entity only when the condition is satisfied in +this particular build. + + +=== Documentation comments === + +A multi-line comment that starts and ends with a '##' line is a +documentation comment. + +If the documentation comment starts like + + ## + # @SYMBOL: + +it documents the definition if SYMBOL, else it's free-form +documentation. + +See below for more on definition documentation. + +Free-form documentation may be used to provide additional text and +structuring content. + + +==== Documentation markup ==== + +Comment text starting with '=' is a section title: + + # = Section title + +Double the '=' for a subsection title: + + # == Subsection title + +'|' denotes examples: + + # | Text of the example, may span + # | multiple lines + +'*' starts an itemized list: + + # * First item, may span + # multiple lines + # * Second item + +You can also use '-' instead of '*'. + +A decimal number followed by '.' starts a numbered list: + + # 1. First item, may span + # multiple lines + # 2. Second item + +The actual number doesn't matter. You could even use '*' instead of +'2.' for the second item. + +Lists can't be nested. Blank lines are currently not supported within +lists. + +Additional whitespace between the initial '#' and the comment text is +permitted. -The presence of 'if' keys in the schema is reflected through to the -introspection output depending on the build configuration. +*foo* and _foo_ are for strong and emphasis styles respectively (they +do not work over multiple lines). @foo is used to reference a name in +the schema. + +Example: + +## +# = Section +# == Subsection +# +# Some text foo with *strong* and _emphasis_ +# 1. with a list +# 2. like that +# +# And some code: +# | $ echo foo +# | -> do this +# | <- get that +# +## + + +==== Definition documentation ==== + +Definition documentation, if present, must immediately precede the +definition it documents. + +When documentation is required (see pragma 'doc-required'), every +definition must have documentation. + +Definition documentation starts with a line naming the definition, +followed by an optional overview, a description of each argument (for +commands and events), member (for structs and unions), branch (for +alternates), or value (for enums), and finally optional tagged +sections. + +FIXME: the parser accepts these things in almost any order. +FIXME: union branches should be described, too. + +Extensions added after the definition was first released carry a +'(since x.y.z)' comment. + +A tagged section starts with one of the following words: +"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:". +The section ends with the start of a new section. + +A 'Since: x.y.z' tagged section lists the release that introduced the +definition. + +For example: + +## +# @BlockStats: +# +# Statistics of a virtual block device or a block backing device. +# +# @device: If the stats are for a virtual block device, the name +# corresponding to the virtual block device. +# +# @node-name: The node name of the device. (since 2.3) +# +# ... more members ... +# +# Since: 0.14.0 +## +{ 'struct': 'BlockStats', + 'data': {'*device': 'str', '*node-name': 'str', + ... more members ... } } + +## +# @query-blockstats: +# +# Query the @BlockStats for all virtual block devices. +# +# @query-nodes: If true, the command will query all the +# block nodes ... explain, explain ... (since 2.3) +# +# Returns: A list of @BlockStats for each virtual block devices. +# +# Since: 0.14.0 +# +# Example: +# +# -> { "execute": "query-blockstats" } +# <- { +# ... lots of output ... +# } +# +## +{ 'command': 'query-blockstats', + 'data': { '*query-nodes': 'bool' }, + 'returns': ['BlockStats'] } == Client JSON Protocol introspection == @@ -901,7 +1010,7 @@ If the event carries no additional information, "arg-type" names an object type without members. The event may not have a data member on the wire then. -Each command or event defined with dictionary-valued 'data' in the +Each command or event defined with 'data' as MEMBERS object in the QAPI schema implicitly defines an object type. Example: the SchemaInfo for EVENT_C from section Events @@ -1034,6 +1143,66 @@ the names of built-in types. Clients should examine member "json-type" instead of hard-coding names of built-in types. +== Compatibility considerations == + +Maintaining backward compatibility at the Client JSON Protocol level +while evolving the schema requires some care. This section is about +syntactic compatibility, which is necessary, but not sufficient, for +actual compatibility. + +Clients send commands with argument data, and receive command +responses with return data and events with event data. + +Adding opt-in functionality to the send direction is backwards +compatible: adding commands, optional arguments, enumeration values, +union and alternate branches; turning an argument type into an +alternate of that type; making mandatory arguments optional. Clients +oblivious of the new functionality continue to work. + +Incompatible changes include removing commands, command arguments, +enumeration values, union and alternate branches, adding mandatory +command arguments, and making optional arguments mandatory. + +The specified behavior of an absent optional argument should remain +the same. With proper documentation, this policy still allows some +flexibility; for example, when an optional 'buffer-size' argument is +specified to default to a sensible buffer size, the actual default +value can still be changed. The specified default behavior is not the +exact size of the buffer, only that the default size is sensible. + +Adding functionality to the receive direction is generally backwards +compatible: adding events, adding return and event data members. +Clients are expected to ignore the ones they don't know. + +Removing "unreachable" stuff like events that can't be triggered +anymore, optional return or event data members that can't be sent +anymore, and return or event data member (enumeration) values that +can't be sent anymore makes no difference to clients, except for +introspection. The latter can conceivably confuse clients, so tread +carefully. + +Incompatible changes include removing return and event data members. + +Any change to a command definition's 'data' or one of the types used +there (recursively) needs to consider send direction compatibility. + +Any change to a command definition's 'return', an event definition's +'data', or one of the types used there (recursively) needs to consider +receive direction compatibility. + +Any change to types used in both contexts need to consider both. + +Enumeration type values and complex and alternate type members may be +reordered freely. For enumerations and alternate types, this doesn't +affect the wire encoding. For complex types, this might make the +implementation emit JSON object members in a different order, which +the Client JSON Protocol permits. + +Since type names are not visible in the Client JSON Protocol, types +may be freely renamed. Even certain refactorings are invisible, such +as splitting members from one type into a common base type. + + == Code generation == The QAPI code generator qapi-gen.py generates code and documentation |