| = How to use the QAPI code generator = |
| |
| Copyright IBM Corp. 2011 |
| Copyright (C) 2012-2015 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. |
| |
| == Introduction == |
| |
| QAPI is a native C API within QEMU which provides management-level |
| 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. |
| |
| |
| == QMP/Guest agent schema == |
| |
| A QAPI schema file is designed to be loosely based on JSON |
| (http://www.ietf.org/rfc/rfc7159.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. |
| |
| Comments are allowed; anything between an unquoted # and the following |
| newline is ignored. Although there is not yet a documentation |
| generator, a form of stylized comments has developed for consistently |
| documenting details about an expression and when it was added to the |
| schema. The documentation is delimited between two lines of ##, then |
| the first line names the expression, an optional overview is provided, |
| then individual documentation about each member of 'data' is provided, |
| and finally, a 'Since: x.y.z' tag lists the release that introduced |
| the expression. Optional fields are tagged with the phrase |
| '#optional', often with their default value; and extensions added |
| after the expression was first released are also given a '(since |
| x.y.z)' comment. For example: |
| |
| ## |
| # @BlockStats: |
| # |
| # Statistics of a virtual block device or a block backing device. |
| # |
| # @device: #optional If the stats are for a virtual block device, the name |
| # corresponding to the virtual block device. |
| # |
| # @stats: A @BlockDeviceStats for the device. |
| # |
| # @parent: #optional This describes the file block device if it has one. |
| # |
| # @backing: #optional This describes the backing block device if it has one. |
| # (Since 2.0) |
| # |
| # Since: 0.14.0 |
| ## |
| { 'struct': 'BlockStats', |
| 'data': {'*device': 'str', 'stats': 'BlockDeviceStats', |
| '*parent': 'BlockStats', |
| '*backing': 'BlockStats'} } |
| |
| 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 seven top-level expressions recognized by the parser: |
| 'include', '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). |
| |
| 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 |
| definitions should not end in 'Kind', as this namespace is used for |
| creating implicit C enums for visiting union types. Command names, |
| and field 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. Event |
| names should be ALL_CAPS with words separated by underscore. The |
| special string '**' appears for some commands that manually perform |
| their own type checking rather than relying on the type-safe code |
| produced by the qapi code generators. |
| |
| Any name (command, event, type, field, or enum value) beginning with |
| "x-" is marked experimental, and may be withdrawn or changed |
| incompatibly in a future release. Downstream vendors may add |
| extensions; such extensions should begin with a prefix matching |
| "__RFQDN_" (for the reverse-fully-qualified-domain-name of the |
| vendor), even if the rest of the name uses dash (example: |
| __com.redhat_drive-mirror). Other than downstream extensions (with |
| leading underscore and the use of dots), all names should begin with a |
| letter, and contain only ASCII letters, digits, dash, and underscore. |
| It is okay to reuse names that match C keywords; the generator will |
| rename a field named "default" in the QAPI to "q_default" in the |
| generated C code. |
| |
| 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. |
| |
| |
| === Built-in Types === |
| |
| The following types are built-in to the parser: |
| 'str' - arbitrary UTF-8 string |
| 'int' - 64-bit signed integer (although the C code may place further |
| restrictions on acceptable range) |
| 'number' - floating point number |
| 'bool' - JSON value of true or false |
| 'int8', 'int16', 'int32', 'int64' - like 'int', but enforce maximum |
| bit size |
| 'uint8', 'uint16', 'uint32', 'uint64' - unsigned counterparts |
| 'size' - like 'uint64', but allows scaled suffix from command line |
| visitor |
| |
| |
| === Includes === |
| |
| Usage: { '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 |
| safe. No other keys should appear in the expression, and the include |
| value should be a string. |
| |
| 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 |
| from making a forward reference to a type that is only introduced by |
| an outer file. The parser may be made stricter in the future to |
| prevent incomplete include files. |
| |
| |
| === Struct types === |
| |
| Usage: { 'struct': STRING, 'data': DICT, '*base': STRUCT-NAME } |
| |
| A struct is a dictionary containing a single 'data' key whose |
| value is a dictionary. 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: |
| |
| { '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 field, 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 fields of the base type are included as top-level fields |
| of the new struct's dictionary in the Client JSON Protocol wire |
| format. An example definition is: |
| |
| { 'struct': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } } |
| { 'struct': 'BlockdevOptionsGenericCOWFormat', |
| 'base': 'BlockdevOptionsGenericFormat', |
| 'data': { '*backing': 'str' } } |
| |
| An example BlockdevOptionsGenericCOWFormat object on the wire could use |
| both fields like this: |
| |
| { "file": "/some/place/my-image", |
| "backing": "/some/place/my-backing-file" } |
| |
| |
| === Enumeration types === |
| |
| Usage: { 'enum': 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: |
| |
| { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] } |
| |
| 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 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 field that will only contain |
| a finite set of string values, using an enum type for that field is |
| better than open-coding the field to be type 'str'. |
| |
| |
| === Union types === |
| |
| Usage: { 'union': STRING, 'data': DICT } |
| or: { 'union': STRING, 'data': DICT, 'base': STRUCT-NAME, |
| 'discriminator': ENUM-MEMBER-OF-BASE } |
| |
| 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), flat (both discriminator and base). A union |
| type is defined using a data dictionary as explained in the following |
| paragraphs. |
| |
| A simple union type defines a mapping from automatic discriminator |
| values to data types like in this example: |
| |
| { 'struct': 'FileOptions', 'data': { 'filename': 'str' } } |
| { 'struct': 'Qcow2Options', |
| 'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } } |
| |
| { 'union': 'BlockdevOptions', |
| 'data': { 'file': 'FileOptions', |
| 'qcow2': 'Qcow2Options' } } |
| |
| In the Client JSON Protocol, a simple union is represented by a |
| dictionary that contains the 'type' field as a discriminator, and a |
| 'data' field that is of the specified data type corresponding to the |
| discriminator value, as in these examples: |
| |
| { "type": "file", "data" : { "filename": "/some/place/my-image" } } |
| { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image", |
| "lazy-refcounts": true } } |
| |
| 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 specifies a struct as its base, and |
| avoids nesting on the wire. All branches of the union must be |
| complex types, and the top-level fields of the union dictionary on |
| the wire will be combination of fields from both the base type and the |
| appropriate branch type (when merging two dictionaries, there must be |
| no keys in common). The 'discriminator' field must be the name of an |
| enum-typed member of the base struct. |
| |
| The following example enhances the above simple union example by |
| adding a common field 'readonly', renaming the discriminator to |
| something more applicable, and reducing the number of {} required on |
| the wire: |
| |
| { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] } |
| { 'struct': 'BlockdevCommonOptions', |
| 'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } } |
| { 'union': 'BlockdevOptions', |
| 'base': 'BlockdevCommonOptions', |
| 'discriminator': 'driver', |
| 'data': { 'file': 'FileOptions', |
| 'qcow2': 'Qcow2Options' } } |
| |
| Resulting in these JSON objects: |
| |
| { "driver": "file", "readonly": true, |
| "filename": "/some/place/my-image" } |
| { "driver": "qcow2", "readonly": false, |
| "backing-file": "/some/place/my-image", "lazy-refcounts": true } |
| |
| 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 can ensure that branches exist for all values of the |
| enum (although the order of the keys need not match the declaration of |
| the enum). In the resulting generated C data types, a flat union is |
| represented as a struct with the base member fields included directly, |
| 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 |
| union has a struct with a single member named 'data'. That is, |
| |
| { 'union': 'Simple', 'data': { 'one': 'str', 'two': 'int' } } |
| |
| is identical on the wire to: |
| |
| { 'enum': 'Enum', 'data': ['one', 'two'] } |
| { 'struct': 'Base', 'data': { 'type': 'Enum' } } |
| { 'struct': 'Branch1', 'data': { 'data': 'str' } } |
| { 'struct': 'Branch2', 'data': { 'data': 'int' } } |
| { 'union': 'Flat': 'base': 'Base', 'discriminator': 'type', |
| 'data': { 'one': 'Branch1', 'two': 'Branch2' } } |
| |
| |
| === Alternate types === |
| |
| Usage: { 'alternate': STRING, 'data': DICT } |
| |
| 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: |
| |
| { 'alternate': 'BlockRef', |
| 'data': { 'definition': 'BlockdevOptions', |
| 'reference': 'str' } } |
| |
| Just like for a simple union, an implicit C enum 'NameKind' is created |
| to enumerate the branches for the alternate 'Name'. |
| |
| 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 |
| 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; 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. |
| |
| The example alternate declaration above allows using both of the |
| following example objects: |
| |
| { "file": "my_existing_block_device_id" } |
| { "file": { "driver": "file", |
| "readonly": false, |
| "filename": "/tmp/mydisk.qcow2" } } |
| |
| |
| === Commands === |
| |
| Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, |
| '*returns': TYPE-NAME-OR-DICT, |
| '*gen': false, '*success-response': false } |
| |
| 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, a one-element array containing the name |
| of a complex type, or a dictionary that declares an anonymous type |
| with the same semantics as a 'struct' expression, with one exception |
| noted below when 'gen' is used. |
| |
| The 'returns' member describes what will appear in the "return" field |
| of a Client JSON Protocol reply on successful completion of a command. |
| The member is optional from the command declaration; if absent, the |
| "return" field 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, |
| or a dictionary that declares an anonymous type with the same |
| semantics as a 'struct' expression, with one exception noted below |
| when 'gen' is used. Although it is permitted to have the 'returns' |
| member name a built-in type or an array of built-in types, any command |
| that does this cannot be extended to return additional information in |
| the future; thus, new commands should strongly consider returning a |
| dictionary-based type or an array of dictionaries, even if the |
| dictionary only contains one field at the present. |
| |
| 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. |
| |
| Some example commands: |
| |
| { 'command': 'my-first-command', |
| 'data': { 'arg1': 'str', '*arg2': 'str' } } |
| { 'struct': 'MyType', 'data': { '*value': 'str' } } |
| { 'command': 'my-second-command', |
| 'returns': [ 'MyType' ] } |
| |
| which would validate this Client JSON Protocol transaction: |
| |
| => { "execute": "my-first-command", |
| "arguments": { "arg1": "hello" } } |
| <= { "return": { } } |
| => { "execute": "my-second-command" } |
| <= { "return": [ { "value": "one" }, { } ] } |
| |
| In rare cases, QAPI cannot express a type-safe representation of a |
| corresponding Client JSON Protocol command. In these cases, if the |
| command expression includes the key 'gen' with boolean value false, |
| then the 'data' or 'returns' member that intends to bypass generated |
| type-safety and do its own manual validation should use an inline |
| dictionary definition, with a value of '**' rather than a valid type |
| name for the keys that the generated code will not validate. Please |
| try to avoid adding new commands that rely on this, and instead use |
| type-safe unions. For an example of bypass usage: |
| |
| { 'command': 'netdev_add', |
| 'data': {'type': 'str', 'id': 'str', '*props': '**'}, |
| 'gen': false } |
| |
| 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 should include the optional key |
| 'success-response' with boolean value false. So far, only QGA makes |
| use of this field. |
| |
| |
| === Events === |
| |
| Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT } |
| |
| 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-event.h; when called by QEMU code, a |
| message with timestamp will be emitted on the wire. |
| |
| An example event is: |
| |
| { 'event': 'EVENT_C', |
| 'data': { '*a': 'int', 'b': 'str' } } |
| |
| Resulting in this JSON object: |
| |
| { "event": "EVENT_C", |
| "data": { "b": "test string" }, |
| "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } |
| |
| |
| == Code generation == |
| |
| Schemas are fed into 3 scripts to generate all the code/files that, paired |
| with the core QAPI libraries, comprise everything required to take JSON |
| commands read in by a Client JSON Protocol server, unmarshal the arguments into |
| the underlying C types, call into the corresponding C function, and map the |
| response back to a Client JSON Protocol response to be returned to the user. |
| |
| As an example, we'll use the following schema, which describes a single |
| complex user-defined type (which will produce a C struct, along with a list |
| node structure that can be used to chain together a list of such types in |
| case we want to accept/return a list of this type with a command), and a |
| command which takes that type as a parameter and returns the same type: |
| |
| $ cat example-schema.json |
| { 'struct': 'UserDefOne', |
| 'data': { 'integer': 'int', 'string': 'str' } } |
| |
| { 'command': 'my-command', |
| 'data': {'arg1': 'UserDefOne'}, |
| 'returns': 'UserDefOne' } |
| |
| { 'event': 'MY_EVENT' } |
| |
| === scripts/qapi-types.py === |
| |
| Used to generate the C types defined by a schema. The following files are |
| created: |
| |
| $(prefix)qapi-types.h - C types corresponding to types defined in |
| the schema you pass in |
| $(prefix)qapi-types.c - Cleanup functions for the above C types |
| |
| The $(prefix) is an optional parameter used as a namespace to keep the |
| generated code from one schema/code-generation separated from others so code |
| can be generated/used from multiple schemas without clobbering previously |
| created code. |
| |
| Example: |
| |
| $ python scripts/qapi-types.py --output-dir="qapi-generated" \ |
| --prefix="example-" example-schema.json |
| $ cat qapi-generated/example-qapi-types.c |
| [Uninteresting stuff omitted...] |
| |
| void qapi_free_UserDefOneList(UserDefOneList *obj) |
| { |
| QapiDeallocVisitor *md; |
| Visitor *v; |
| |
| if (!obj) { |
| return; |
| } |
| |
| md = qapi_dealloc_visitor_new(); |
| v = qapi_dealloc_get_visitor(md); |
| visit_type_UserDefOneList(v, &obj, NULL, NULL); |
| qapi_dealloc_visitor_cleanup(md); |
| } |
| |
| void qapi_free_UserDefOne(UserDefOne *obj) |
| { |
| QapiDeallocVisitor *md; |
| Visitor *v; |
| |
| if (!obj) { |
| return; |
| } |
| |
| md = qapi_dealloc_visitor_new(); |
| v = qapi_dealloc_get_visitor(md); |
| visit_type_UserDefOne(v, &obj, NULL, NULL); |
| qapi_dealloc_visitor_cleanup(md); |
| } |
| |
| $ cat qapi-generated/example-qapi-types.h |
| [Uninteresting stuff omitted...] |
| |
| #ifndef EXAMPLE_QAPI_TYPES_H |
| #define EXAMPLE_QAPI_TYPES_H |
| |
| [Built-in types omitted...] |
| |
| typedef struct UserDefOne UserDefOne; |
| |
| typedef struct UserDefOneList |
| { |
| union { |
| UserDefOne *value; |
| uint64_t padding; |
| }; |
| struct UserDefOneList *next; |
| } UserDefOneList; |
| |
| [Functions on built-in types omitted...] |
| |
| struct UserDefOne |
| { |
| int64_t integer; |
| char *string; |
| }; |
| |
| void qapi_free_UserDefOneList(UserDefOneList *obj); |
| void qapi_free_UserDefOne(UserDefOne *obj); |
| |
| #endif |
| |
| === scripts/qapi-visit.py === |
| |
| Used to generate the visitor functions used to walk through and convert |
| a QObject (as provided by QMP) to a native C data structure and |
| vice-versa, as well as the visitor function used to dealloc a complex |
| schema-defined C type. |
| |
| The following files are generated: |
| |
| $(prefix)qapi-visit.c: visitor function for a particular C type, used |
| to automagically convert QObjects into the |
| corresponding C type and vice-versa, as well |
| as for deallocating memory for an existing C |
| type |
| |
| $(prefix)qapi-visit.h: declarations for previously mentioned visitor |
| functions |
| |
| Example: |
| |
| $ python scripts/qapi-visit.py --output-dir="qapi-generated" |
| --prefix="example-" example-schema.json |
| $ cat qapi-generated/example-qapi-visit.c |
| [Uninteresting stuff omitted...] |
| |
| static void visit_type_UserDefOne_fields(Visitor *m, UserDefOne **obj, Error **errp) |
| { |
| Error *err = NULL; |
| visit_type_int(m, &(*obj)->integer, "integer", &err); |
| if (err) { |
| goto out; |
| } |
| visit_type_str(m, &(*obj)->string, "string", &err); |
| if (err) { |
| goto out; |
| } |
| |
| out: |
| error_propagate(errp, err); |
| } |
| |
| void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp) |
| { |
| Error *err = NULL; |
| |
| visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), &err); |
| if (!err) { |
| if (*obj) { |
| visit_type_UserDefOne_fields(m, obj, errp); |
| } |
| visit_end_struct(m, &err); |
| } |
| error_propagate(errp, err); |
| } |
| |
| void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp) |
| { |
| Error *err = NULL; |
| GenericList *i, **prev; |
| |
| visit_start_list(m, name, &err); |
| if (err) { |
| goto out; |
| } |
| |
| for (prev = (GenericList **)obj; |
| !err && (i = visit_next_list(m, prev, &err)) != NULL; |
| prev = &i) { |
| UserDefOneList *native_i = (UserDefOneList *)i; |
| visit_type_UserDefOne(m, &native_i->value, NULL, &err); |
| } |
| |
| error_propagate(errp, err); |
| err = NULL; |
| visit_end_list(m, &err); |
| out: |
| error_propagate(errp, err); |
| } |
| $ cat qapi-generated/example-qapi-visit.h |
| [Uninteresting stuff omitted...] |
| |
| #ifndef EXAMPLE_QAPI_VISIT_H |
| #define EXAMPLE_QAPI_VISIT_H |
| |
| [Visitors for built-in types omitted...] |
| |
| void visit_type_UserDefOne(Visitor *m, UserDefOne **obj, const char *name, Error **errp); |
| void visit_type_UserDefOneList(Visitor *m, UserDefOneList **obj, const char *name, Error **errp); |
| |
| #endif |
| |
| === scripts/qapi-commands.py === |
| |
| Used to generate the marshaling/dispatch functions for the commands defined |
| in the schema. The following files are generated: |
| |
| $(prefix)qmp-marshal.c: command marshal/dispatch functions for each |
| QMP command defined in the schema. Functions |
| generated by qapi-visit.py are used to |
| convert QObjects received from the wire into |
| function parameters, and uses the same |
| visitor functions to convert native C return |
| values to QObjects from transmission back |
| over the wire. |
| |
| $(prefix)qmp-commands.h: Function prototypes for the QMP commands |
| specified in the schema. |
| |
| Example: |
| |
| $ python scripts/qapi-commands.py --output-dir="qapi-generated" |
| --prefix="example-" example-schema.json |
| $ cat qapi-generated/example-qmp-marshal.c |
| [Uninteresting stuff omitted...] |
| |
| static void qmp_marshal_output_my_command(UserDefOne *ret_in, QObject **ret_out, Error **errp) |
| { |
| Error *local_err = NULL; |
| QmpOutputVisitor *mo = qmp_output_visitor_new(); |
| QapiDeallocVisitor *md; |
| Visitor *v; |
| |
| v = qmp_output_get_visitor(mo); |
| visit_type_UserDefOne(v, &ret_in, "unused", &local_err); |
| if (local_err) { |
| goto out; |
| } |
| *ret_out = qmp_output_get_qobject(mo); |
| |
| out: |
| error_propagate(errp, local_err); |
| qmp_output_visitor_cleanup(mo); |
| md = qapi_dealloc_visitor_new(); |
| v = qapi_dealloc_get_visitor(md); |
| visit_type_UserDefOne(v, &ret_in, "unused", NULL); |
| qapi_dealloc_visitor_cleanup(md); |
| } |
| |
| static void qmp_marshal_input_my_command(QDict *args, QObject **ret, Error **errp) |
| { |
| Error *local_err = NULL; |
| UserDefOne *retval = NULL; |
| QmpInputVisitor *mi = qmp_input_visitor_new_strict(QOBJECT(args)); |
| QapiDeallocVisitor *md; |
| Visitor *v; |
| UserDefOne *arg1 = NULL; |
| |
| v = qmp_input_get_visitor(mi); |
| visit_type_UserDefOne(v, &arg1, "arg1", &local_err); |
| if (local_err) { |
| goto out; |
| } |
| |
| retval = qmp_my_command(arg1, &local_err); |
| if (local_err) { |
| goto out; |
| } |
| |
| qmp_marshal_output_my_command(retval, ret, &local_err); |
| |
| out: |
| error_propagate(errp, local_err); |
| qmp_input_visitor_cleanup(mi); |
| md = qapi_dealloc_visitor_new(); |
| v = qapi_dealloc_get_visitor(md); |
| visit_type_UserDefOne(v, &arg1, "arg1", NULL); |
| qapi_dealloc_visitor_cleanup(md); |
| return; |
| } |
| |
| static void qmp_init_marshal(void) |
| { |
| qmp_register_command("my-command", qmp_marshal_input_my_command, QCO_NO_OPTIONS); |
| } |
| |
| qapi_init(qmp_init_marshal); |
| $ cat qapi-generated/example-qmp-commands.h |
| [Uninteresting stuff omitted...] |
| |
| #ifndef EXAMPLE_QMP_COMMANDS_H |
| #define EXAMPLE_QMP_COMMANDS_H |
| |
| #include "example-qapi-types.h" |
| #include "qapi/qmp/qdict.h" |
| #include "qapi/error.h" |
| |
| UserDefOne *qmp_my_command(UserDefOne *arg1, Error **errp); |
| |
| #endif |
| |
| === scripts/qapi-event.py === |
| |
| Used to generate the event-related C code defined by a schema. The |
| following files are created: |
| |
| $(prefix)qapi-event.h - Function prototypes for each event type, plus an |
| enumeration of all event names |
| $(prefix)qapi-event.c - Implementation of functions to send an event |
| |
| Example: |
| |
| $ python scripts/qapi-event.py --output-dir="qapi-generated" |
| --prefix="example-" example-schema.json |
| $ cat qapi-generated/example-qapi-event.c |
| [Uninteresting stuff omitted...] |
| |
| void qapi_event_send_my_event(Error **errp) |
| { |
| QDict *qmp; |
| Error *local_err = NULL; |
| QMPEventFuncEmit emit; |
| emit = qmp_event_get_func_emit(); |
| if (!emit) { |
| return; |
| } |
| |
| qmp = qmp_event_build_dict("MY_EVENT"); |
| |
| emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp, &local_err); |
| |
| error_propagate(errp, local_err); |
| QDECREF(qmp); |
| } |
| |
| const char *EXAMPLE_QAPIEvent_lookup[] = { |
| "MY_EVENT", |
| NULL, |
| }; |
| $ cat qapi-generated/example-qapi-event.h |
| [Uninteresting stuff omitted...] |
| |
| #ifndef EXAMPLE_QAPI_EVENT_H |
| #define EXAMPLE_QAPI_EVENT_H |
| |
| #include "qapi/error.h" |
| #include "qapi/qmp/qdict.h" |
| #include "example-qapi-types.h" |
| |
| |
| void qapi_event_send_my_event(Error **errp); |
| |
| extern const char *EXAMPLE_QAPIEvent_lookup[]; |
| typedef enum EXAMPLE_QAPIEvent |
| { |
| EXAMPLE_QAPI_EVENT_MY_EVENT = 0, |
| EXAMPLE_QAPI_EVENT_MAX = 1, |
| } EXAMPLE_QAPIEvent; |
| |
| #endif |