docs/qapi-code-gen.txt

   1 = How to use the QAPI code generator =
   2
   3 * Note: as of this writing, QMP does not use QAPI. Eventually QMP
   4 commands will be converted to use QAPI internally. The following
   5 information describes QMP/QAPI as it will exist after the
   6 conversion.
   7
   8 QAPI is a native C API within QEMU which provides management-level
   9 functionality to internal/external users. For external
  10 users/processes, this interface is made available by a JSON-based
  11 QEMU Monitor protocol that is provided by the QMP server.
  12
  13 To map QMP-defined interfaces to the native C QAPI implementations,
  14 a JSON-based schema is used to define types and function
  15 signatures, and a set of scripts is used to generate types/signatures,
  16 and marshaling/dispatch code. The QEMU Guest Agent also uses these
  17 scripts, paired with a separate schema, to generate
  18 marshaling/dispatch code for the guest agent server running in the
  19 guest.
  20
  21 This document will describe how the schemas, scripts, and resulting
  22 code is used.
  23
  24
  25 == QMP/Guest agent schema ==
  26
  27 This file defines the types, commands, and events used by QMP.  It should
  28 fully describe the interface used by QMP.
  29
  30 This file is designed to be loosely based on JSON although it's technically
  31 executable Python.  While dictionaries are used, they are parsed as
  32 OrderedDicts so that ordering is preserved.
  33
  34 There are two basic syntaxes used, type definitions and command definitions.
  35
  36 The first syntax defines a type and is represented by a dictionary.  There are
  37 three kinds of user-defined types that are supported: complex types,
  38 enumeration types and union types.
  39
  40 Generally speaking, types definitions should always use CamelCase for the type
  41 names. Command names should be all lower case with words separated by a hyphen.
  42
  43 === Complex types ===
  44
  45 A complex type is a dictionary containing a single key whose value is a
  46 dictionary.  This corresponds to a struct in C or an Object in JSON.  An
  47 example of a complex type is:
  48
  49  { 'type': 'MyType',
  50    'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } }
  51
  52 The use of '*' as a prefix to the name means the member is optional.  Optional
  53 members should always be added to the end of the dictionary to preserve
  54 backwards compatibility.
  55
  56
  57 A complex type definition can specify another complex type as its base.
  58 In this case, the fields of the base type are included as top-level fields
  59 of the new complex type's dictionary in the QMP wire format. An example
  60 definition is:
  61
  62  { 'type': 'BlockdevOptionsGenericFormat', 'data': { 'file': 'str' } }
  63  { 'type': 'BlockdevOptionsGenericCOWFormat',
  64    'base': 'BlockdevOptionsGenericFormat',
  65    'data': { '*backing': 'str' } }
  66
  67 An example BlockdevOptionsGenericCOWFormat object on the wire could use
  68 both fields like this:
  69
  70  { "file": "/some/place/my-image",
  71    "backing": "/some/place/my-backing-file" }
  72
  73 === Enumeration types ===
  74
  75 An enumeration type is a dictionary containing a single key whose value is a
  76 list of strings.  An example enumeration is:
  77
  78  { 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
  79
  80 === Union types ===
  81
  82 Union types are used to let the user choose between several different data
  83 types.  A union type is defined using a dictionary as explained in the
  84 following paragraphs.
  85
  86
  87 A simple union type defines a mapping from discriminator values to data types
  88 like in this example:
  89
  90  { 'type': 'FileOptions', 'data': { 'filename': 'str' } }
  91  { 'type': 'Qcow2Options',
  92    'data': { 'backing-file': 'str', 'lazy-refcounts': 'bool' } }
  93
  94  { 'union': 'BlockdevOptions',
  95    'data': { 'file': 'FileOptions',
  96              'qcow2': 'Qcow2Options' } }
  97
  98 In the QMP wire format, a simple union is represented by a dictionary that
  99 contains the 'type' field as a discriminator, and a 'data' field that is of the
 100 specified data type corresponding to the discriminator value:
 101
 102  { "type": "qcow2", "data" : { "backing-file": "/some/place/my-image",
 103                                "lazy-refcounts": true } }
 104
 105
 106 A union definition can specify a complex type as its base. In this case, the
 107 fields of the complex type are included as top-level fields of the union
 108 dictionary in the QMP wire format. An example definition is:
 109
 110  { 'type': 'BlockdevCommonOptions', 'data': { 'readonly': 'bool' } }
 111  { 'union': 'BlockdevOptions',
 112    'base': 'BlockdevCommonOptions',
 113    'data': { 'raw': 'RawOptions',
 114              'qcow2': 'Qcow2Options' } }
 115
 116 And it looks like this on the wire:
 117
 118  { "type": "qcow2",
 119    "readonly": false,
 120    "data" : { "backing-file": "/some/place/my-image",
 121               "lazy-refcounts": true } }
 122
 123
 124 Flat union types avoid the nesting on the wire. They are used whenever a
 125 specific field of the base type is declared as the discriminator ('type' is
 126 then no longer generated). The discriminator must be of enumeration type.
 127 The above example can then be modified as follows:
 128
 129  { 'enum': 'BlockdevDriver', 'data': [ 'raw', 'qcow2' ] }
 130  { 'type': 'BlockdevCommonOptions',
 131    'data': { 'driver': 'BlockdevDriver', 'readonly': 'bool' } }
 132  { 'union': 'BlockdevOptions',
 133    'base': 'BlockdevCommonOptions',
 134    'discriminator': 'driver',
 135    'data': { 'raw': 'RawOptions',
 136              'qcow2': 'Qcow2Options' } }
 137
 138 Resulting in this JSON object:
 139
 140  { "driver": "qcow2",
 141    "readonly": false,
 142    "backing-file": "/some/place/my-image",
 143    "lazy-refcounts": true }
 144
 145
 146 A special type of unions are anonymous unions. They don't form a dictionary in
 147 the wire format but allow the direct use of different types in their place. As
 148 they aren't structured, they don't have any explicit discriminator but use
 149 the (QObject) data type of their value as an implicit discriminator. This means
 150 that they are restricted to using only one discriminator value per QObject
 151 type. For example, you cannot have two different complex types in an anonymous
 152 union, or two different integer types.
 153
 154 Anonymous unions are declared using an empty dictionary as their discriminator.
 155 The discriminator values never appear on the wire, they are only used in the
 156 generated C code. Anonymous unions cannot have a base type.
 157
 158  { 'union': 'BlockRef',
 159    'discriminator': {},
 160    'data': { 'definition': 'BlockdevOptions',
 161              'reference': 'str' } }
 162
 163 This example allows using both of the following example objects:
 164
 165  { "file": "my_existing_block_device_id" }
 166  { "file": { "driver": "file",
 167              "readonly": false,
 168              "filename": "/tmp/mydisk.qcow2" } }
 169
 170
 171 === Commands ===
 172
 173 Commands are defined by using a list containing three members.  The first
 174 member is the command name, the second member is a dictionary containing
 175 arguments, and the third member is the return type.
 176
 177 An example command is:
 178
 179  { 'command': 'my-command',
 180    'data': { 'arg1': 'str', '*arg2': 'str' },
 181    'returns': 'str' }
 182
 183
 184 == Code generation ==
 185
 186 Schemas are fed into 3 scripts to generate all the code/files that, paired
 187 with the core QAPI libraries, comprise everything required to take JSON
 188 commands read in by a QMP/guest agent server, unmarshal the arguments into
 189 the underlying C types, call into the corresponding C function, and map the
 190 response back to a QMP/guest agent response to be returned to the user.
 191
 192 As an example, we'll use the following schema, which describes a single
 193 complex user-defined type (which will produce a C struct, along with a list
 194 node structure that can be used to chain together a list of such types in
 195 case we want to accept/return a list of this type with a command), and a
 196 command which takes that type as a parameter and returns the same type:
 197
 198     mdroth@illuin:~/w/qemu2.git$ cat example-schema.json
 199     { 'type': 'UserDefOne',
 200       'data': { 'integer': 'int', 'string': 'str' } }
 201
 202     { 'command': 'my-command',
 203       'data':    {'arg1': 'UserDefOne'},
 204       'returns': 'UserDefOne' }
 205     mdroth@illuin:~/w/qemu2.git$
 206
 207 === scripts/qapi-types.py ===
 208
 209 Used to generate the C types defined by a schema. The following files are
 210 created:
 211
 212 $(prefix)qapi-types.h - C types corresponding to types defined in
 213                         the schema you pass in
 214 $(prefix)qapi-types.c - Cleanup functions for the above C types
 215
 216 The $(prefix) is an optional parameter used as a namespace to keep the
 217 generated code from one schema/code-generation separated from others so code
 218 can be generated/used from multiple schemas without clobbering previously
 219 created code.
 220
 221 Example:
 222
 223     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \
 224       --output-dir="qapi-generated" --prefix="example-" < example-schema.json
 225     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c
 226     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
 227
 228     #include "qapi/qapi-dealloc-visitor.h"
 229     #include "example-qapi-types.h"
 230     #include "example-qapi-visit.h"
 231
 232     void qapi_free_UserDefOne(UserDefOne * obj)
 233     {
 234         QapiDeallocVisitor *md;
 235         Visitor *v;
 236
 237         if (!obj) {
 238             return;
 239         }
 240
 241         md = qapi_dealloc_visitor_new();
 242         v = qapi_dealloc_get_visitor(md);
 243         visit_type_UserDefOne(v, &obj, NULL, NULL);
 244         qapi_dealloc_visitor_cleanup(md);
 245     }
 246
 247     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h
 248     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
 249     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_TYPES
 250     #define QAPI_GENERATED_EXAMPLE_QAPI_TYPES
 251
 252     #include "qapi/qapi-types-core.h"
 253
 254     typedef struct UserDefOne UserDefOne;
 255
 256     typedef struct UserDefOneList
 257     {
 258         UserDefOne *value;
 259         struct UserDefOneList *next;
 260     } UserDefOneList;
 261
 262     struct UserDefOne
 263     {
 264         int64_t integer;
 265         char * string;
 266     };
 267
 268     void qapi_free_UserDefOne(UserDefOne * obj);
 269
 270     #endif
 271
 272
 273 === scripts/qapi-visit.py ===
 274
 275 Used to generate the visitor functions used to walk through and convert
 276 a QObject (as provided by QMP) to a native C data structure and
 277 vice-versa, as well as the visitor function used to dealloc a complex
 278 schema-defined C type.
 279
 280 The following files are generated:
 281
 282 $(prefix)qapi-visit.c: visitor function for a particular C type, used
 283                        to automagically convert QObjects into the
 284                        corresponding C type and vice-versa, as well
 285                        as for deallocating memory for an existing C
 286                        type
 287
 288 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
 289                        functions
 290
 291 Example:
 292
 293     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \
 294         --output-dir="qapi-generated" --prefix="example-" < example-schema.json
 295     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c
 296     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 297
 298     #include "example-qapi-visit.h"
 299
 300     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp)
 301     {
 302         visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), errp);
 303         visit_type_int(m, (obj && *obj) ? &(*obj)->integer : NULL, "integer", errp);
 304         visit_type_str(m, (obj && *obj) ? &(*obj)->string : NULL, "string", errp);
 305         visit_end_struct(m, errp);
 306     }
 307
 308     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp)
 309     {
 310         GenericList *i, **prev = (GenericList **)obj;
 311
 312         visit_start_list(m, name, errp);
 313
 314         for (; (i = visit_next_list(m, prev, errp)) != NULL; prev = &i) {
 315             UserDefOneList *native_i = (UserDefOneList *)i;
 316             visit_type_UserDefOne(m, &native_i->value, NULL, errp);
 317         }
 318
 319         visit_end_list(m, errp);
 320     }
 321     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h
 322     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 323
 324     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_VISIT
 325     #define QAPI_GENERATED_EXAMPLE_QAPI_VISIT
 326
 327     #include "qapi/qapi-visit-core.h"
 328     #include "example-qapi-types.h"
 329
 330     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp);
 331     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp);
 332
 333     #endif
 334     mdroth@illuin:~/w/qemu2.git$
 335
 336 (The actual structure of the visit_type_* functions is a bit more complex
 337 in order to propagate errors correctly and avoid leaking memory).
 338
 339 === scripts/qapi-commands.py ===
 340
 341 Used to generate the marshaling/dispatch functions for the commands defined
 342 in the schema. The following files are generated:
 343
 344 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
 345                         QMP command defined in the schema. Functions
 346                         generated by qapi-visit.py are used to
 347                         convert QObjects received from the wire into
 348                         function parameters, and uses the same
 349                         visitor functions to convert native C return
 350                         values to QObjects from transmission back
 351                         over the wire.
 352
 353 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
 354                          specified in the schema.
 355
 356 Example:
 357
 358     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c
 359     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 360
 361     #include "qemu-objects.h"
 362     #include "qapi/qmp-core.h"
 363     #include "qapi/qapi-visit-core.h"
 364     #include "qapi/qmp-output-visitor.h"
 365     #include "qapi/qmp-input-visitor.h"
 366     #include "qapi/qapi-dealloc-visitor.h"
 367     #include "example-qapi-types.h"
 368     #include "example-qapi-visit.h"
 369
 370     #include "example-qmp-commands.h"
 371     static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp)
 372     {
 373         QapiDeallocVisitor *md = qapi_dealloc_visitor_new();
 374         QmpOutputVisitor *mo = qmp_output_visitor_new();
 375         Visitor *v;
 376
 377         v = qmp_output_get_visitor(mo);
 378         visit_type_UserDefOne(v, &ret_in, "unused", errp);
 379         v = qapi_dealloc_get_visitor(md);
 380         visit_type_UserDefOne(v, &ret_in, "unused", errp);
 381         qapi_dealloc_visitor_cleanup(md);
 382
 383
 384         *ret_out = qmp_output_get_qobject(mo);
 385     }
 386
 387     static void qmp_marshal_input_my_command(QmpState *qmp__sess, QDict *args, QObject **ret, Error **errp)
 388     {
 389         UserDefOne * retval = NULL;
 390         QmpInputVisitor *mi;
 391         QapiDeallocVisitor *md;
 392         Visitor *v;
 393         UserDefOne * arg1 = NULL;
 394
 395         mi = qmp_input_visitor_new(QOBJECT(args));
 396         v = qmp_input_get_visitor(mi);
 397         visit_type_UserDefOne(v, &arg1, "arg1", errp);
 398
 399         if (error_is_set(errp)) {
 400             goto out;
 401         }
 402         retval = qmp_my_command(arg1, errp);
 403         qmp_marshal_output_my_command(retval, ret, errp);
 404
 405     out:
 406         md = qapi_dealloc_visitor_new();
 407         v = qapi_dealloc_get_visitor(md);
 408         visit_type_UserDefOne(v, &arg1, "arg1", errp);
 409         qapi_dealloc_visitor_cleanup(md);
 410         return;
 411     }
 412
 413     static void qmp_init_marshal(void)
 414     {
 415         qmp_register_command("my-command", qmp_marshal_input_my_command);
 416     }
 417
 418     qapi_init(qmp_init_marshal);
 419     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h
 420     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 421
 422     #ifndef QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
 423     #define QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
 424
 425     #include "example-qapi-types.h"
 426     #include "error.h"
 427
 428     UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp);
 429
 430     #endif
 431     mdroth@illuin:~/w/qemu2.git$