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 always be a string field.
 127 The above example can then be modified as follows:
 128
 129  { 'type': 'BlockdevCommonOptions',
 130    'data': { 'driver': 'str', 'readonly': 'bool' } }
 131  { 'union': 'BlockdevOptions',
 132    'base': 'BlockdevCommonOptions',
 133    'discriminator': 'driver',
 134    'data': { 'raw': 'RawOptions',
 135              'qcow2': 'Qcow2Options' } }
 136
 137 Resulting in this JSON object:
 138
 139  { "driver": "qcow2",
 140    "readonly": false,
 141    "backing-file": "/some/place/my-image",
 142    "lazy-refcounts": true }
 143
 144
 145 A special type of unions are anonymous unions. They don't form a dictionary in
 146 the wire format but allow the direct use of different types in their place. As
 147 they aren't structured, they don't have any explicit discriminator but use
 148 the (QObject) data type of their value as an implicit discriminator. This means
 149 that they are restricted to using only one discriminator value per QObject
 150 type. For example, you cannot have two different complex types in an anonymous
 151 union, or two different integer types.
 152
 153 Anonymous unions are declared using an empty dictionary as their discriminator.
 154 The discriminator values never appear on the wire, they are only used in the
 155 generated C code. Anonymous unions cannot have a base type.
 156
 157  { 'union': 'BlockRef',
 158    'discriminator': {},
 159    'data': { 'definition': 'BlockdevOptions',
 160              'reference': 'str' } }
 161
 162 This example allows using both of the following example objects:
 163
 164  { "file": "my_existing_block_device_id" }
 165  { "file": { "driver": "file",
 166              "readonly": false,
 167              "filename": "/tmp/mydisk.qcow2" } }
 168
 169
 170 === Commands ===
 171
 172 Commands are defined by using a list containing three members.  The first
 173 member is the command name, the second member is a dictionary containing
 174 arguments, and the third member is the return type.
 175
 176 An example command is:
 177
 178  { 'command': 'my-command',
 179    'data': { 'arg1': 'str', '*arg2': 'str' },
 180    'returns': 'str' }
 181
 182
 183 == Code generation ==
 184
 185 Schemas are fed into 3 scripts to generate all the code/files that, paired
 186 with the core QAPI libraries, comprise everything required to take JSON
 187 commands read in by a QMP/guest agent server, unmarshal the arguments into
 188 the underlying C types, call into the corresponding C function, and map the
 189 response back to a QMP/guest agent response to be returned to the user.
 190
 191 As an example, we'll use the following schema, which describes a single
 192 complex user-defined type (which will produce a C struct, along with a list
 193 node structure that can be used to chain together a list of such types in
 194 case we want to accept/return a list of this type with a command), and a
 195 command which takes that type as a parameter and returns the same type:
 196
 197     mdroth@illuin:~/w/qemu2.git$ cat example-schema.json
 198     { 'type': 'UserDefOne',
 199       'data': { 'integer': 'int', 'string': 'str' } }
 200
 201     { 'command': 'my-command',
 202       'data':    {'arg1': 'UserDefOne'},
 203       'returns': 'UserDefOne' }
 204     mdroth@illuin:~/w/qemu2.git$
 205
 206 === scripts/qapi-types.py ===
 207
 208 Used to generate the C types defined by a schema. The following files are
 209 created:
 210
 211 $(prefix)qapi-types.h - C types corresponding to types defined in
 212                         the schema you pass in
 213 $(prefix)qapi-types.c - Cleanup functions for the above C types
 214
 215 The $(prefix) is an optional parameter used as a namespace to keep the
 216 generated code from one schema/code-generation separated from others so code
 217 can be generated/used from multiple schemas without clobbering previously
 218 created code.
 219
 220 Example:
 221
 222     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-types.py \
 223       --output-dir="qapi-generated" --prefix="example-" < example-schema.json
 224     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.c
 225     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
 226
 227     #include "qapi/qapi-dealloc-visitor.h"
 228     #include "example-qapi-types.h"
 229     #include "example-qapi-visit.h"
 230
 231     void qapi_free_UserDefOne(UserDefOne * obj)
 232     {
 233         QapiDeallocVisitor *md;
 234         Visitor *v;
 235
 236         if (!obj) {
 237             return;
 238         }
 239
 240         md = qapi_dealloc_visitor_new();
 241         v = qapi_dealloc_get_visitor(md);
 242         visit_type_UserDefOne(v, &obj, NULL, NULL);
 243         qapi_dealloc_visitor_cleanup(md);
 244     }
 245
 246     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-types.h
 247     /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
 248     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_TYPES
 249     #define QAPI_GENERATED_EXAMPLE_QAPI_TYPES
 250
 251     #include "qapi/qapi-types-core.h"
 252
 253     typedef struct UserDefOne UserDefOne;
 254
 255     typedef struct UserDefOneList
 256     {
 257         UserDefOne *value;
 258         struct UserDefOneList *next;
 259     } UserDefOneList;
 260
 261     struct UserDefOne
 262     {
 263         int64_t integer;
 264         char * string;
 265     };
 266
 267     void qapi_free_UserDefOne(UserDefOne * obj);
 268
 269     #endif
 270
 271
 272 === scripts/qapi-visit.py ===
 273
 274 Used to generate the visitor functions used to walk through and convert
 275 a QObject (as provided by QMP) to a native C data structure and
 276 vice-versa, as well as the visitor function used to dealloc a complex
 277 schema-defined C type.
 278
 279 The following files are generated:
 280
 281 $(prefix)qapi-visit.c: visitor function for a particular C type, used
 282                        to automagically convert QObjects into the
 283                        corresponding C type and vice-versa, as well
 284                        as for deallocating memory for an existing C
 285                        type
 286
 287 $(prefix)qapi-visit.h: declarations for previously mentioned visitor
 288                        functions
 289
 290 Example:
 291
 292     mdroth@illuin:~/w/qemu2.git$ python scripts/qapi-visit.py \
 293         --output-dir="qapi-generated" --prefix="example-" < example-schema.json
 294     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.c
 295     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 296
 297     #include "example-qapi-visit.h"
 298
 299     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp)
 300     {
 301         visit_start_struct(m, (void **)obj, "UserDefOne", name, sizeof(UserDefOne), errp);
 302         visit_type_int(m, (obj && *obj) ? &(*obj)->integer : NULL, "integer", errp);
 303         visit_type_str(m, (obj && *obj) ? &(*obj)->string : NULL, "string", errp);
 304         visit_end_struct(m, errp);
 305     }
 306
 307     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp)
 308     {
 309         GenericList *i, **prev = (GenericList **)obj;
 310
 311         visit_start_list(m, name, errp);
 312
 313         for (; (i = visit_next_list(m, prev, errp)) != NULL; prev = &i) {
 314             UserDefOneList *native_i = (UserDefOneList *)i;
 315             visit_type_UserDefOne(m, &native_i->value, NULL, errp);
 316         }
 317
 318         visit_end_list(m, errp);
 319     }
 320     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qapi-visit.h
 321     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 322
 323     #ifndef QAPI_GENERATED_EXAMPLE_QAPI_VISIT
 324     #define QAPI_GENERATED_EXAMPLE_QAPI_VISIT
 325
 326     #include "qapi/qapi-visit-core.h"
 327     #include "example-qapi-types.h"
 328
 329     void visit_type_UserDefOne(Visitor *m, UserDefOne ** obj, const char *name, Error **errp);
 330     void visit_type_UserDefOneList(Visitor *m, UserDefOneList ** obj, const char *name, Error **errp);
 331
 332     #endif
 333     mdroth@illuin:~/w/qemu2.git$
 334
 335 (The actual structure of the visit_type_* functions is a bit more complex
 336 in order to propagate errors correctly and avoid leaking memory).
 337
 338 === scripts/qapi-commands.py ===
 339
 340 Used to generate the marshaling/dispatch functions for the commands defined
 341 in the schema. The following files are generated:
 342
 343 $(prefix)qmp-marshal.c: command marshal/dispatch functions for each
 344                         QMP command defined in the schema. Functions
 345                         generated by qapi-visit.py are used to
 346                         convert QObjects received from the wire into
 347                         function parameters, and uses the same
 348                         visitor functions to convert native C return
 349                         values to QObjects from transmission back
 350                         over the wire.
 351
 352 $(prefix)qmp-commands.h: Function prototypes for the QMP commands
 353                          specified in the schema.
 354
 355 Example:
 356
 357     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-marshal.c
 358     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 359
 360     #include "qemu-objects.h"
 361     #include "qapi/qmp-core.h"
 362     #include "qapi/qapi-visit-core.h"
 363     #include "qapi/qmp-output-visitor.h"
 364     #include "qapi/qmp-input-visitor.h"
 365     #include "qapi/qapi-dealloc-visitor.h"
 366     #include "example-qapi-types.h"
 367     #include "example-qapi-visit.h"
 368
 369     #include "example-qmp-commands.h"
 370     static void qmp_marshal_output_my_command(UserDefOne * ret_in, QObject **ret_out, Error **errp)
 371     {
 372         QapiDeallocVisitor *md = qapi_dealloc_visitor_new();
 373         QmpOutputVisitor *mo = qmp_output_visitor_new();
 374         Visitor *v;
 375
 376         v = qmp_output_get_visitor(mo);
 377         visit_type_UserDefOne(v, &ret_in, "unused", errp);
 378         v = qapi_dealloc_get_visitor(md);
 379         visit_type_UserDefOne(v, &ret_in, "unused", errp);
 380         qapi_dealloc_visitor_cleanup(md);
 381
 382
 383         *ret_out = qmp_output_get_qobject(mo);
 384     }
 385
 386     static void qmp_marshal_input_my_command(QmpState *qmp__sess, QDict *args, QObject **ret, Error **errp)
 387     {
 388         UserDefOne * retval = NULL;
 389         QmpInputVisitor *mi;
 390         QapiDeallocVisitor *md;
 391         Visitor *v;
 392         UserDefOne * arg1 = NULL;
 393
 394         mi = qmp_input_visitor_new(QOBJECT(args));
 395         v = qmp_input_get_visitor(mi);
 396         visit_type_UserDefOne(v, &arg1, "arg1", errp);
 397
 398         if (error_is_set(errp)) {
 399             goto out;
 400         }
 401         retval = qmp_my_command(arg1, errp);
 402         qmp_marshal_output_my_command(retval, ret, errp);
 403
 404     out:
 405         md = qapi_dealloc_visitor_new();
 406         v = qapi_dealloc_get_visitor(md);
 407         visit_type_UserDefOne(v, &arg1, "arg1", errp);
 408         qapi_dealloc_visitor_cleanup(md);
 409         return;
 410     }
 411
 412     static void qmp_init_marshal(void)
 413     {
 414         qmp_register_command("my-command", qmp_marshal_input_my_command);
 415     }
 416
 417     qapi_init(qmp_init_marshal);
 418     mdroth@illuin:~/w/qemu2.git$ cat qapi-generated/example-qmp-commands.h
 419     /* THIS FILE IS AUTOMATICALLY GENERATED, DO NOT MODIFY */
 420
 421     #ifndef QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
 422     #define QAPI_GENERATED_EXAMPLE_QMP_COMMANDS
 423
 424     #include "example-qapi-types.h"
 425     #include "error.h"
 426
 427     UserDefOne * qmp_my_command(UserDefOne * arg1, Error **errp);
 428
 429     #endif
 430     mdroth@illuin:~/w/qemu2.git$