qapi-code-gen.rst · samitouri/QOSamiQemu

Code Commits Issues Pulls Sessions CI/CD

master

rst 2,103 lines 67.8 KB

Raw

1	==================================
2	How to use the QAPI code generator
3	==================================
4
5	..
6	Copyright IBM Corp. 2011
7	Copyright (C) 2012-2016 Red Hat, Inc.
8
9	This work is licensed under the terms of the GNU GPL, version 2 or
10	later. See the COPYING file in the top-level directory.
11
12	.. _qapi:
13
14	Introduction
15	============
16
17	QAPI is a native C API within QEMU which provides management-level
18	functionality to internal and external users. For external
19	users/processes, this interface is made available by a JSON-based wire
20	format for the QEMU Monitor Protocol (QMP) for controlling qemu, as
21	well as the QEMU Guest Agent (QGA) for communicating with the guest.
22	The remainder of this document uses "Client JSON Protocol" when
23	referring to the wire contents of a QMP or QGA connection.
24
25	To map between Client JSON Protocol interfaces and the native C API,
26	we generate C code from a QAPI schema. This document describes the
27	QAPI schema language, and how it gets mapped to the Client JSON
28	Protocol and to C. It additionally provides guidance on maintaining
29	Client JSON Protocol compatibility.
30
31
32	The QAPI schema language
33	========================
34
35	The QAPI schema defines the Client JSON Protocol's commands and
36	events, as well as types used by them. Forward references are
37	allowed.
38
39	It is permissible for the schema to contain additional types not used
40	by any commands or events, for the side effect of generated C code
41	used internally.
42
43	There are several kinds of types: simple types (a number of built-in
44	types, such as ``int`` and ``str``; as well as enumerations), arrays,
45	complex types (structs and unions), and alternate types (a choice
46	between other types).
47
48
49	Schema syntax
50	-------------
51
52	Syntax is loosely based on `JSON <http://www.ietf.org/rfc/rfc8259.txt>`_.
53	Differences:
54
55	* Comments: start with a hash character (``#``) that is not part of a
56	string, and extend to the end of the line.
57
58	* Strings are enclosed in ``'single quotes'``, not ``"double quotes"``.
59
60	* Strings are restricted to printable ASCII, and escape sequences to
61	just ``\\``.
62
63	* Numbers and ``null`` are not supported.
64
65	A second layer of syntax defines the sequences of JSON texts that are
66	a correctly structured QAPI schema. We provide a grammar for this
67	syntax in an EBNF-like notation:
68
69	* Production rules look like ``non-terminal = expression``
70	* Concatenation: expression ``A B`` matches expression ``A``, then ``B``
71	* Alternation: expression ``A \| B`` matches expression ``A`` or ``B``
72	* Repetition: expression ``A...`` matches zero or more occurrences of
73	expression ``A``
74	* Repetition: expression ``A, ...`` matches zero or more occurrences of
75	expression ``A`` separated by ``,``
76	* Grouping: expression ``( A )`` matches expression ``A``
77	* JSON's structural characters are terminals: ``{ } [ ] : ,``
78	* JSON's literal names are terminals: ``false true``
79	* String literals enclosed in ``'single quotes'`` are terminal, and match
80	this JSON string, with a leading ``*`` stripped off
81	* When JSON object member's name starts with ``*``, the member is
82	optional.
83	* The symbol ``STRING`` is a terminal, and matches any JSON string
84	* The symbol ``BOOL`` is a terminal, and matches JSON ``false`` or ``true``
85	* ALL-CAPS words other than ``STRING`` are non-terminals
86
87	The order of members within JSON objects does not matter unless
88	explicitly noted.
89
90	A QAPI schema consists of a series of top-level expressions::
91
92	SCHEMA = TOP-LEVEL-EXPR...
93
94	The top-level expressions are all JSON objects. Code and
95	documentation is generated in schema definition order. Code order
96	should not matter.
97
98	A top-level expressions is either a directive or a definition::
99
100	TOP-LEVEL-EXPR = DIRECTIVE \| DEFINITION
101
102	There are two kinds of directives and six kinds of definitions::
103
104	DIRECTIVE = INCLUDE \| PRAGMA
105	DEFINITION = ENUM \| STRUCT \| UNION \| ALTERNATE \| COMMAND \| EVENT
106
107	These are discussed in detail below.
108
109
110	Built-in Types
111	--------------
112
113	The following types are predefined, and map to C as follows:
114
115	============= ============== ============================================
116	Schema C JSON
117	============= ============== ============================================
118	``str`` ``char *`` any JSON string, UTF-8
119	``number`` ``double`` any JSON number
120	``int`` ``int64_t`` a JSON number without fractional part
121	that fits into the C integer type
122	``int8`` ``int8_t`` likewise
123	``int16`` ``int16_t`` likewise
124	``int32`` ``int32_t`` likewise
125	``int64`` ``int64_t`` likewise
126	``uint8`` ``uint8_t`` likewise
127	``uint16`` ``uint16_t`` likewise
128	``uint32`` ``uint32_t`` likewise
129	``uint64`` ``uint64_t`` likewise
130	``size`` ``uint64_t`` like ``uint64_t``, except
131	``StringInputVisitor`` accepts size suffixes
132	``bool`` ``bool`` JSON ``true`` or ``false``
133	``null`` ``QNull *`` JSON ``null``
134	``any`` ``QObject *`` any JSON value
135	``QType`` ``QType`` JSON string matching enum ``QType`` values
136	============= ============== ============================================
137
138
139	Include directives
140	------------------
141
142	Syntax::
143
144	INCLUDE = { 'include': STRING }
145
146	The QAPI schema definitions can be modularized using the 'include' directive::
147
148	{ 'include': 'path/to/file.json' }
149
150	The directive is evaluated recursively, and include paths are relative
151	to the file using the directive. Multiple includes of the same file
152	are idempotent.
153
154	As a matter of style, it is a good idea to have all files be
155	self-contained, but at the moment, nothing prevents an included file
156	from making a forward reference to a type that is only introduced by
157	an outer file. The parser may be made stricter in the future to
158	prevent incomplete include files.
159
160	.. _pragma:
161
162	Pragma directives
163	-----------------
164
165	Syntax::
166
167	PRAGMA = { 'pragma': {
168	'*doc-required': BOOL,
169	'*command-name-exceptions': [ STRING, ... ],
170	'*command-returns-exceptions': [ STRING, ... ],
171	'*documentation-exceptions': [ STRING, ... ],
172	'*member-name-exceptions': [ STRING, ... ] } }
173
174	The pragma directive lets you control optional generator behavior.
175
176	Pragma's scope is currently the complete schema. Setting the same
177	pragma to different values in parts of the schema doesn't work.
178
179	Pragma 'doc-required' takes a boolean value. If true, documentation
180	is required. Default is false.
181
182	Pragma 'command-name-exceptions' takes a list of commands whose names
183	may contain ``"_"`` instead of ``"-"``. Default is none.
184
185	Pragma 'command-returns-exceptions' takes a list of commands that may
186	violate the rules on permitted return types. Default is none.
187
188	Pragma 'documentation-exceptions' takes a list of types, commands, and
189	events whose members / arguments need not be documented. Default is
190	none.
191
192	Pragma 'member-name-exceptions' takes a list of types whose member
193	names may contain uppercase letters, and ``"_"`` instead of ``"-"``.
194	Default is none.
195
196	.. _ENUM-VALUE:
197
198	Enumeration types
199	-----------------
200
201	Syntax::
202
203	ENUM = { 'enum': STRING,
204	'data': [ ENUM-VALUE, ... ],
205	'*prefix': STRING,
206	'*if': COND,
207	'*features': FEATURES }
208	ENUM-VALUE = STRING
209	\| { 'name': STRING,
210	'*if': COND,
211	'*features': FEATURES }
212
213	Member 'enum' names the enum type.
214
215	Each member of the 'data' array defines a value of the enumeration
216	type. The form STRING is shorthand for :code:`{ 'name': STRING }`. The
217	'name' values must be be distinct.
218
219	Example::
220
221	{ 'enum': 'MyEnum', 'data': [ 'value1', 'value2', 'value3' ] }
222
223	Nothing prevents an empty enumeration, although it is probably not
224	useful.
225
226	On the wire, an enumeration type's value is represented by its
227	(string) name. In C, it's represented by an enumeration constant.
228	These are of the form PREFIX_NAME, where PREFIX is derived from the
229	enumeration type's name, and NAME from the value's name. For the
230	example above, the generator maps 'MyEnum' to MY_ENUM and 'value1' to
231	VALUE1, resulting in the enumeration constant MY_ENUM_VALUE1. The
232	optional 'prefix' member overrides PREFIX. This is rarely necessary,
233	and should be used with restraint.
234
235	The generated C enumeration constants have values 0, 1, ..., N-1 (in
236	QAPI schema order), where N is the number of values. There is an
237	additional enumeration constant PREFIX__MAX with value N.
238
239	Do not use string or an integer type when an enumeration type can do
240	the job satisfactorily.
241
242	The optional 'if' member specifies a conditional. See `Configuring the
243	schema`_ below for more on this.
244
245	The optional 'features' member specifies features. See Features_
246	below for more on this.
247
248
249	.. _TYPE-REF:
250
251	Type references and array types
252	-------------------------------
253
254	Syntax::
255
256	TYPE-REF = STRING \| ARRAY-TYPE
257	ARRAY-TYPE = [ STRING ]
258
259	A string denotes the type named by the string.
260
261	A one-element array containing a string denotes an array of the type
262	named by the string. Example: ``['int']`` denotes an array of ``int``.
263
264
265	Struct types
266	------------
267
268	Syntax::
269
270	STRUCT = { 'struct': STRING,
271	'data': MEMBERS,
272	'*base': STRING,
273	'*if': COND,
274	'*features': FEATURES }
275	MEMBERS = { MEMBER, ... }
276	MEMBER = STRING : TYPE-REF
277	\| STRING : { 'type': TYPE-REF,
278	'*if': COND,
279	'*features': FEATURES }
280
281	Member 'struct' names the struct type.
282
283	Each MEMBER of the 'data' object defines a member of the struct type.
284
285	.. _MEMBERS:
286
287	The MEMBER's STRING name consists of an optional ``*`` prefix and the
288	struct member name. If ``*`` is present, the member is optional.
289
290	The MEMBER's value defines its properties, in particular its type.
291	The form TYPE-REF_ is shorthand for :code:`{ 'type': TYPE-REF }`.
292
293	Example::
294
295	{ 'struct': 'MyType',
296	'data': { 'member1': 'str', 'member2': ['int'], '*member3': 'str' } }
297
298	A struct type corresponds to a struct in C, and an object in JSON.
299	The C struct's members are generated in QAPI schema order.
300
301	The optional 'base' member names a struct type whose members are to be
302	included in this type. They go first in the C struct.
303
304	Example::
305
306	{ 'struct': 'BlockdevOptionsGenericFormat',
307	'data': { 'file': 'str' } }
308	{ 'struct': 'BlockdevOptionsGenericCOWFormat',
309	'base': 'BlockdevOptionsGenericFormat',
310	'data': { '*backing': 'str' } }
311
312	An example BlockdevOptionsGenericCOWFormat object on the wire could use
313	both members like this::
314
315	{ "file": "/some/place/my-image",
316	"backing": "/some/place/my-backing-file" }
317
318	The optional 'if' member specifies a conditional. See `Configuring
319	the schema`_ below for more on this.
320
321	The optional 'features' member specifies features. See Features_
322	below for more on this.
323
324
325	Union types
326	-----------
327
328	Syntax::
329
330	UNION = { 'union': STRING,
331	'base': ( MEMBERS \| STRING ),
332	'discriminator': STRING,
333	'data': BRANCHES,
334	'*if': COND,
335	'*features': FEATURES }
336	BRANCHES = { BRANCH, ... }
337	BRANCH = STRING : TYPE-REF
338	\| STRING : { 'type': TYPE-REF, '*if': COND }
339
340	Member 'union' names the union type.
341
342	The 'base' member defines the common members. If it is a MEMBERS_
343	object, it defines common members just like a struct type's 'data'
344	member defines struct type members. If it is a STRING, it names a
345	struct type whose members are the common members.
346
347	Member 'discriminator' must name a non-optional enum-typed member of
348	the base struct. That member's value selects a branch by its name.
349	If no such branch exists, an empty branch is assumed.
350
351	Each BRANCH of the 'data' object defines a branch of the union. A
352	union must have at least one branch.
353
354	The BRANCH's STRING name is the branch name. It must be a value of
355	the discriminator enum type.
356
357	The BRANCH's value defines the branch's properties, in particular its
358	type. The type must a struct type. The form TYPE-REF_ is shorthand
359	for :code:`{ 'type': TYPE-REF }`.
360
361	In the Client JSON Protocol, a union is represented by an object with
362	the common members (from the base type) and the selected branch's
363	members. The two sets of member names must be disjoint.
364
365	Example::
366
367	{ 'enum': 'BlockdevDriver', 'data': [ 'file', 'qcow2' ] }
368	{ 'union': 'BlockdevOptions',
369	'base': { 'driver': 'BlockdevDriver', '*read-only': 'bool' },
370	'discriminator': 'driver',
371	'data': { 'file': 'BlockdevOptionsFile',
372	'qcow2': 'BlockdevOptionsQcow2' } }
373
374	Resulting in these JSON objects::
375
376	{ "driver": "file", "read-only": true,
377	"filename": "/some/place/my-image" }
378	{ "driver": "qcow2", "read-only": false,
379	"backing": "/some/place/my-image", "lazy-refcounts": true }
380
381	The order of branches need not match the order of the enum values.
382	The branches need not cover all possible enum values. In the
383	resulting generated C data types, a union is represented as a struct
384	with the base members in QAPI schema order, and then a union of
385	structures for each branch of the struct.
386
387	The optional 'if' member specifies a conditional. See `Configuring
388	the schema`_ below for more on this.
389
390	The optional 'features' member specifies features. See Features_
391	below for more on this.
392
393
394	Alternate types
395	---------------
396
397	Syntax::
398
399	ALTERNATE = { 'alternate': STRING,
400	'data': ALTERNATIVES,
401	'*if': COND,
402	'*features': FEATURES }
403	ALTERNATIVES = { ALTERNATIVE, ... }
404	ALTERNATIVE = STRING : STRING
405	\| STRING : { 'type': STRING, '*if': COND }
406
407	Member 'alternate' names the alternate type.
408
409	Each ALTERNATIVE of the 'data' object defines a branch of the
410	alternate. An alternate must have at least one branch.
411
412	The ALTERNATIVE's STRING name is the branch name.
413
414	The ALTERNATIVE's value defines the branch's properties, in particular
415	its type. The form STRING is shorthand for :code:`{ 'type': STRING }`.
416
417	Example::
418
419	{ 'alternate': 'BlockdevRef',
420	'data': { 'definition': 'BlockdevOptions',
421	'reference': 'str' } }
422
423	An alternate type is like a union type, except there is no
424	discriminator on the wire. Instead, the branch to use is inferred
425	from the value. An alternate can only express a choice between types
426	represented differently on the wire.
427
428	If a branch is typed as the 'bool' built-in, the alternate accepts
429	true and false; if it is typed as any of the various numeric
430	built-ins, it accepts a JSON number; if it is typed as a 'str'
431	built-in or named enum type, it accepts a JSON string; if it is typed
432	as the 'null' built-in, it accepts JSON null; and if it is typed as a
433	complex type (struct or union), it accepts a JSON object.
434
435	The example alternate declaration above allows using both of the
436	following example objects::
437
438	{ "file": "my_existing_block_device_id" }
439	{ "file": { "driver": "file",
440	"read-only": false,
441	"filename": "/tmp/mydisk.qcow2" } }
442
443	The optional 'if' member specifies a conditional. See `Configuring
444	the schema`_ below for more on this.
445
446	The optional 'features' member specifies features. See Features_
447	below for more on this.
448
449
450	Commands
451	--------
452
453	Syntax::
454
455	COMMAND = { 'command': STRING,
456	(
457	'*data': ( MEMBERS \| STRING ),
458	\|
459	'data': STRING,
460	'boxed': true,
461	)
462	'*returns': TYPE-REF,
463	'*success-response': false,
464	'*gen': false,
465	'*allow-oob': true,
466	'*allow-preconfig': true,
467	'*coroutine': true,
468	'*if': COND,
469	'*features': FEATURES }
470
471	Member 'command' names the command.
472
473	Member 'data' defines the arguments. It defaults to an empty MEMBERS_
474	object.
475
476	If 'data' is a MEMBERS_ object, then MEMBERS defines arguments just
477	like a struct type's 'data' defines struct type members.
478
479	If 'data' is a STRING, then STRING names a complex type whose members
480	are the arguments. A union type requires ``'boxed': true``.
481
482	Member 'returns' defines the command's return type. It defaults to an
483	empty struct type. It must normally be a complex type or an array of
484	a complex type. To return anything else, the command must be listed
485	in pragma 'commands-returns-exceptions'. If you do this, extending
486	the command to return additional information will be harder. Use of
487	the pragma for new commands is strongly discouraged.
488
489	A command's error responses are not specified in the QAPI schema.
490	Error conditions should be documented in comments.
491
492	In the Client JSON Protocol, the value of the "execute" or "exec-oob"
493	member is the command name. The value of the "arguments" member then
494	has to conform to the arguments, and the value of the success
495	response's "return" member will conform to the return type.
496
497	Some example commands::
498
499	{ 'command': 'my-first-command',
500	'data': { 'arg1': 'str', '*arg2': 'str' } }
501	{ 'struct': 'MyType', 'data': { '*value': 'str' } }
502	{ 'command': 'my-second-command',
503	'returns': [ 'MyType' ] }
504
505	which would validate this Client JSON Protocol transaction::
506
507	=> { "execute": "my-first-command",
508	"arguments": { "arg1": "hello" } }
509	<= { "return": { } }
510	=> { "execute": "my-second-command" }
511	<= { "return": [ { "value": "one" }, { } ] }
512
513	The generator emits a prototype for the C function implementing the
514	command. The function itself needs to be written by hand. See
515	section `Code generated for commands`_ for examples.
516
517	The function returns the return type. When member 'boxed' is absent,
518	it takes the command arguments as arguments one by one, in QAPI schema
519	order. Else it takes them wrapped in the C struct generated for the
520	complex argument type. It takes an additional ``Error **`` argument in
521	either case.
522
523	The generator also emits a marshalling function that extracts
524	arguments for the user's function out of an input QDict, calls the
525	user's function, and if it succeeded, builds an output QObject from
526	its return value. This is for use by the QMP monitor core.
527
528	In rare cases, QAPI cannot express a type-safe representation of a
529	corresponding Client JSON Protocol command. You then have to suppress
530	generation of a marshalling function by including a member 'gen' with
531	boolean value false, and instead write your own function. For
532	example::
533
534	{ 'command': 'netdev_add',
535	'data': {'type': 'str', 'id': 'str'},
536	'gen': false }
537
538	Please try to avoid adding new commands that rely on this, and instead
539	use type-safe unions.
540
541	Normally, the QAPI schema is used to describe synchronous exchanges,
542	where a response is expected. But in some cases, the action of a
543	command is expected to change state in a way that a successful
544	response is not possible (although the command will still return an
545	error object on failure). When a successful reply is not possible,
546	the command definition includes the optional member 'success-response'
547	with boolean value false. So far, only QGA makes use of this member.
548
549	Member 'allow-oob' declares whether the command supports out-of-band
550	(OOB) execution. It defaults to false. For example::
551
552	{ 'command': 'migrate_recover',
553	'data': { 'uri': 'str' }, 'allow-oob': true }
554
555	See the :doc:`/interop/qmp-spec` for out-of-band execution syntax
556	and semantics.
557
558	Commands supporting out-of-band execution can still be executed
559	in-band.
560
561	When a command is executed in-band, its handler runs in the main
562	thread with the BQL held.
563
564	When a command is executed out-of-band, its handler runs in a
565	dedicated monitor I/O thread with the BQL not held.
566
567	An OOB-capable command handler must satisfy the following conditions:
568
569	- It terminates quickly.
570	- It does not invoke system calls that may block.
571	- It does not access guest RAM that may block when userfaultfd is
572	enabled for postcopy live migration.
573	- It takes only "fast" locks, i.e. all critical sections protected by
574	any lock it takes also satisfy the conditions for OOB command
575	handler code.
576
577	The restrictions on locking limit access to shared state. Such access
578	requires synchronization, but OOB commands can't take the BQL or any
579	other "slow" lock.
580
581	When in doubt, do not implement OOB execution support.
582
583	Member 'allow-preconfig' declares whether the command is available
584	before the machine is built. It defaults to false. For example::
585
586	{ 'enum': 'QMPCapability',
587	'data': [ 'oob' ] }
588	{ 'command': 'qmp_capabilities',
589	'data': { '*enable': [ 'QMPCapability' ] },
590	'allow-preconfig': true }
591
592	QMP is available before the machine is built only when QEMU was
593	started with --preconfig.
594
595	Member 'coroutine' tells the QMP dispatcher whether the command handler
596	is safe to be run in a coroutine. It defaults to false. If it is true,
597	the command handler is called from coroutine context and may yield while
598	waiting for an external event (such as I/O completion) in order to avoid
599	blocking the guest and other background operations.
600
601	Coroutine safety can be hard to prove, similar to thread safety. Common
602	pitfalls are:
603
604	- The BQL isn't held across ``qemu_coroutine_yield()``, so
605	operations that used to assume that they execute atomically may have
606	to be more careful to protect against changes in the global state.
607
608	- Nested event loops (``AIO_WAIT_WHILE()`` etc.) are problematic in
609	coroutine context and can easily lead to deadlocks. They should be
610	replaced by yielding and reentering the coroutine when the condition
611	becomes false.
612
613	Since the command handler may assume coroutine context, any callers
614	other than the QMP dispatcher must also call it in coroutine context.
615	In particular, HMP commands calling such a QMP command handler must be
616	marked ``.coroutine = true`` in hmp-commands.hx.
617
618	It is an error to specify both ``'coroutine': true`` and ``'allow-oob': true``
619	for a command. We don't currently have a use case for both together and
620	without a use case, it's not entirely clear what the semantics should
621	be.
622
623	The optional 'if' member specifies a conditional. See `Configuring
624	the schema`_ below for more on this.
625
626	The optional 'features' member specifies features. See Features_
627	below for more on this.
628
629
630	Events
631	------
632
633	Syntax::
634
635	EVENT = { 'event': STRING,
636	(
637	'*data': ( MEMBERS \| STRING ),
638	\|
639	'data': STRING,
640	'boxed': true,
641	)
642	'*if': COND,
643	'*features': FEATURES }
644
645	Member 'event' names the event. This is the event name used in the
646	Client JSON Protocol.
647
648	Member 'data' defines the event-specific data. It defaults to an
649	empty MEMBERS_ object.
650
651	If 'data' is a MEMBERS_ object, then MEMBERS defines event-specific
652	data just like a struct type's 'data' defines struct type members.
653
654	If 'data' is a STRING, then STRING names a complex type whose members
655	are the event-specific data. A union type requires ``'boxed': true``.
656
657	An example event is::
658
659	{ 'event': 'EVENT_C',
660	'data': { '*a': 'int', 'b': 'str' } }
661
662	Resulting in this JSON object::
663
664	{ "event": "EVENT_C",
665	"data": { "b": "test string" },
666	"timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
667
668	The generator emits a function to send the event. When member 'boxed'
669	is absent, it takes event-specific data one by one, in QAPI schema
670	order. Else it takes them wrapped in the C struct generated for the
671	complex type. See section `Code generated for events`_ for examples.
672
673	The optional 'if' member specifies a conditional. See `Configuring
674	the schema`_ below for more on this.
675
676	The optional 'features' member specifies features. See Features_
677	below for more on this.
678
679
680	.. _FEATURE:
681
682	Features
683	--------
684
685	Syntax::
686
687	FEATURES = [ FEATURE, ... ]
688	FEATURE = STRING
689	\| { 'name': STRING, '*if': COND }
690
691	Sometimes, the behaviour of QEMU changes compatibly, but without a
692	change in the QMP syntax (usually by allowing values or operations
693	that previously resulted in an error). QMP clients may still need to
694	know whether the extension is available.
695
696	For this purpose, a list of features can be specified for definitions,
697	enumeration values, and struct members. Each feature list member can
698	either be ``{ 'name': STRING, '*if': COND }``, or STRING, which is
699	shorthand for ``{ 'name': STRING }``.
700
701	The optional 'if' member specifies a conditional. See `Configuring
702	the schema`_ below for more on this.
703
704	Example::
705
706	{ 'struct': 'TestType',
707	'data': { 'number': 'int' },
708	'features': [ 'allow-negative-numbers' ] }
709
710	The feature strings are exposed to clients in introspection, as
711	explained in section `Client JSON Protocol introspection`_.
712
713	Intended use is to have each feature string signal that this build of
714	QEMU shows a certain behaviour.
715
716
717	Special features
718	~~~~~~~~~~~~~~~~
719
720	Feature "deprecated" marks a command, event, enum value, or struct
721	member as deprecated. It is not supported elsewhere so far.
722	Interfaces so marked may be withdrawn in future releases in accordance
723	with QEMU's deprecation policy.
724
725	Feature "unstable" marks a command, event, enum value, or struct
726	member as unstable. It is not supported elsewhere so far. Interfaces
727	so marked may be withdrawn or changed incompatibly in future releases.
728
729
730	Naming rules and reserved names
731	-------------------------------
732
733	All names must begin with a letter, and contain only ASCII letters,
734	digits, hyphen, and underscore. There are two exceptions: enum values
735	may start with a digit, and names that are downstream extensions (see
736	section `Downstream extensions`_) start with underscore.
737
738	Names beginning with ``q_`` are reserved for the generator, which uses
739	them for munging QMP names that resemble C keywords or other
740	problematic strings. For example, a member named ``default`` in qapi
741	becomes ``q_default`` in the generated C code.
742
743	Types, commands, and events share a common namespace. Therefore,
744	generally speaking, type definitions should always use CamelCase for
745	user-defined type names, while built-in types are lowercase.
746
747	Type names ending with ``List`` are reserved for the generator, which
748	uses them for array types.
749
750	Command names, member names within a type, and feature names should be
751	all lower case with words separated by a hyphen. However, some
752	existing older commands and complex types use underscore; when
753	extending them, consistency is preferred over blindly avoiding
754	underscore.
755
756	Event names should be ALL_CAPS with words separated by underscore.
757
758	Member name ``u`` and names starting with ``has-`` or ``has_`` are reserved
759	for the generator, which uses them for unions and for tracking
760	optional members.
761
762	Names beginning with ``x-`` used to signify "experimental". This
763	convention has been replaced by special feature "unstable".
764
765	Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
766	you violate naming rules. Use for new code is strongly discouraged.
767	See `Pragma directives`_ for details.
768
769
770	Downstream extensions
771	---------------------
772
773	QAPI schema names that are externally visible, say in the Client JSON
774	Protocol, need to be managed with care. Names starting with a
775	downstream prefix of the form __RFQDN_ are reserved for the downstream
776	who controls the valid, reverse fully qualified domain name RFQDN.
777	RFQDN may only contain ASCII letters, digits, hyphen and period.
778
779	Example: Red Hat, Inc. controls redhat.com, and may therefore add a
780	downstream command ``__com.redhat_drive-mirror``.
781
782
783	Configuring the schema
784	----------------------
785
786	Syntax::
787
788	COND = STRING
789	\| { 'all': [ COND, ... ] }
790	\| { 'any': [ COND, ... ] }
791	\| { 'not': COND }
792
793	All definitions take an optional 'if' member. Its value must be a
794	string, or an object with a single member 'all', 'any' or 'not'.
795
796	The C code generated for the definition will then be guarded by an #if
797	preprocessing directive with an operand generated from that condition:
798
799	* STRING will generate defined(STRING)
800	* { 'all': [COND, ...] } will generate (COND && ...)
801	* { 'any': [COND, ...] } will generate (COND \|\| ...)
802	* { 'not': COND } will generate !COND
803
804	Example: a conditional struct ::
805
806	{ 'struct': 'IfStruct', 'data': { 'foo': 'int' },
807	'if': { 'all': [ 'CONFIG_FOO', 'HAVE_BAR' ] } }
808
809	gets its generated code guarded like this::
810
811	#if defined(CONFIG_FOO) && defined(HAVE_BAR)
812	... generated code ...
813	#endif /* defined(HAVE_BAR) && defined(CONFIG_FOO) */
814
815	Individual members of complex types can also be made conditional.
816	This requires the longhand form of MEMBER.
817
818	Example: a struct type with unconditional member 'foo' and conditional
819	member 'bar' ::
820
821	{ 'struct': 'IfStruct',
822	'data': { 'foo': 'int',
823	'bar': { 'type': 'int', 'if': 'IFCOND'} } }
824
825	A union's discriminator may not be conditional.
826
827	Likewise, individual enumeration values may be conditional. This
828	requires the longhand form of ENUM-VALUE_.
829
830	Example: an enum type with unconditional value 'foo' and conditional
831	value 'bar' ::
832
833	{ 'enum': 'IfEnum',
834	'data': [ 'foo',
835	{ 'name' : 'bar', 'if': 'IFCOND' } ] }
836
837	Likewise, features can be conditional. This requires the longhand
838	form of FEATURE_.
839
840	Example: a struct with conditional feature 'allow-negative-numbers' ::
841
842	{ 'struct': 'TestType',
843	'data': { 'number': 'int' },
844	'features': [ { 'name': 'allow-negative-numbers',
845	'if': 'IFCOND' } ] }
846
847	Please note that you are responsible to ensure that the C code will
848	compile with an arbitrary combination of conditions, since the
849	generator is unable to check it at this point.
850
851	The conditions apply to introspection as well, i.e. introspection
852	shows a conditional entity only when the condition is satisfied in
853	this particular build.
854
855
856	Documentation comments
857	----------------------
858
859	A multi-line comment that starts and ends with a ``##`` line is a
860	documentation comment.
861
862	If the documentation comment starts like ::
863
864	##
865	# @SYMBOL:
866
867	it documents the definition of SYMBOL, else it's free-form
868	documentation.
869
870	See below for more on `Definition documentation`_.
871
872	Free-form documentation may be used to provide additional text and
873	structuring content.
874
875
876	Headings and subheadings
877	~~~~~~~~~~~~~~~~~~~~~~~~
878
879	Free-form documentation does not start with ``@SYMBOL`` and can contain
880	arbitrary rST markup. Headings can be marked up using the standard rST
881	syntax::
882
883	##
884	# *************************
885	# This is a level 2 heading
886	# *************************
887	#
888	# This is a free-form comment which will go under the
889	# top level heading.
890	##
891
892	##
893	# This is a third level heading
894	# ==============================
895	#
896	# Level 4
897	# _______
898	#
899	# Level 5
900	# ^^^^^^^
901	#
902	# Level 6
903	# """""""
904	##
905
906	Level 1 headings are reserved for use by the generated documentation
907	page itself, leaving level 2 as the highest level that should be used.
908
909
910	Documentation markup
911	~~~~~~~~~~~~~~~~~~~~
912
913	Documentation comments can use most rST markup. In particular,
914	a ``::`` literal block can be used for pre-formatted text::
915
916	# ::
917	#
918	# Text of the example, may span
919	# multiple lines
920
921	``*`` starts an itemized list::
922
923	# * First item, may span
924	# multiple lines
925	# * Second item
926
927	You can also use ``-`` instead of ``*``.
928
929	A decimal number followed by ``.`` starts a numbered list::
930
931	# 1. First item, may span
932	# multiple lines
933	# 2. Second item
934
935	The actual number doesn't matter.
936
937	Lists of either kind must be preceded and followed by a blank line.
938	If a list item's text spans multiple lines, then the second and
939	subsequent lines must be correctly indented to line up with the
940	first character of the first line.
941
942	The usual **strong*, \emphasized\* and ````literal```` markup
943	should be used. If you need a single literal ``*``, you will need to
944	backslash-escape it.
945
946	Use ```foo``` to reference a definition in the schema. This generates
947	a link to the definition. In the event that such a cross-reference is
948	ambiguous, you can use `QAPI cross-reference roles
949	<QAPI-domain-cross-references>` to disambiguate.
950
951	Use @foo to reference a member description within the current
952	definition. This is an rST extension. It is currently rendered the
953	same way as ````foo````, but carries additional meaning.
954
955	Example::
956
957	##
958	# Some text foo with bold and emphasis
959	#
960	# 1. with a list
961	# 2. like that
962	#
963	# And some code:
964	#
965	# ::
966	#
967	# $ echo foo
968	# -> do this
969	# <- get that
970	##
971
972	For legibility, wrap text paragraphs so every line is at most 70
973	characters long.
974
975	Separate sentences with two spaces.
976
977
978	Definition documentation
979	~~~~~~~~~~~~~~~~~~~~~~~~
980
981	Definition documentation, if present, must immediately precede the
982	definition it documents.
983
984	When documentation is required (see pragma_ 'doc-required'), every
985	definition must have documentation.
986
987	Definition documentation starts with a description naming the
988	definition with an optional indented overview, a description of each
989	argument (for commands and events), member (for structs and unions),
990	branch (for alternates), or value (for enums), a description of each
991	feature (if any), and finally optional tagged sections.
992
993	Descriptions start with '\@name:'. The description text must be
994	indented like this::
995
996	# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
997	# do eiusmod tempor incididunt ut labore et dolore magna aliqua.
998
999	.. FIXME The parser accepts these things in almost any order.
1000
1001	.. FIXME union branches should be described, too.
1002
1003	Extensions added after the definition was first released carry a
1004	"(since x.y.z)" comment.
1005
1006	The feature descriptions must be preceded by a blank line and then a
1007	line "Features:", like this::
1008
1009	#
1010	# Features:
1011	#
1012	# @feature: Description text
1013
1014	A tagged section begins with a paragraph that starts with one of the
1015	following words: "Since:", "Returns:", "Errors:", "TODO:". It ends with
1016	the start of a new section.
1017
1018	The second and subsequent lines of tagged sections must be indented
1019	like this::
1020
1021	# TODO: Ut enim ad minim veniam, quis nostrud exercitation ullamco
1022	# laboris nisi ut aliquip ex ea commodo consequat.
1023	#
1024	# Duis aute irure dolor in reprehenderit in voluptate velit esse
1025	# cillum dolore eu fugiat nulla pariatur.
1026
1027	"Returns" and "Errors" sections are only valid for commands. They
1028	document the success and the error response, respectively.
1029
1030	"Errors" sections should be formatted as an rST list, each entry
1031	detailing a relevant error condition. For example::
1032
1033	# Errors:
1034	# - If @device does not exist, DeviceNotFound
1035	# - Any other error returns a GenericError.
1036
1037	A "Since: x.y.z" tagged section lists the release that introduced the
1038	definition.
1039
1040	"TODO" sections are not rendered (they are for developers, not users of
1041	QMP). In other sections, the text is formatted, and rST markup can be
1042	used.
1043
1044	QMP Examples can be added by using the ``.. qmp-example::`` directive.
1045	In its simplest form, this can be used to contain a single QMP code
1046	block which accepts standard JSON syntax with additional server
1047	directionality indicators (``->`` and ``<-``), and elisions. An
1048	elision is commonly ``...``, but it can also be or a pair of ``...``
1049	with text in between.
1050
1051	Optionally, a plaintext title may be provided by using the ``:title:``
1052	directive option. If the title is omitted, the example title will
1053	default to "Example:".
1054
1055	A simple QMP example::
1056
1057	# .. qmp-example::
1058	#
1059	# -> { "execute": "query-name" }
1060	# <- { "return": { "name": "Fred" } }
1061
1062	More complex or multi-step examples where exposition is needed before
1063	or between QMP code blocks can be created by using the ``:annotated:``
1064	directive option. When using this option, nested QMP code blocks must
1065	be entered explicitly with rST's ``::`` syntax.
1066
1067	For example::
1068
1069	# .. qmp-example::
1070	# :annotated:
1071	# :title: A more complex demonstration
1072	#
1073	# This is a more complex example that can use
1074	# ``arbitrary rST syntax`` in its exposition::
1075	#
1076	# -> { "execute": "query-block" }
1077	# <- { "return": [
1078	# {
1079	# "device": "ide0-hd0",
1080	# ...
1081	# }
1082	# ... more ...
1083	# ] }
1084	#
1085	# Above, lengthy output has been omitted for brevity.
1086
1087	Highlighting in non-QMP languages can be accomplished by using the
1088	``.. code-block:: lang`` directive, and non-highlighted text can be
1089	achieved by omitting the language argument.
1090
1091
1092	Examples of complete definition documentation::
1093
1094	##
1095	# @BlockStats:
1096	# Statistics of a virtual block device or a block backing device.
1097	#
1098	# @device: If the stats are for a virtual block device, the name
1099	# corresponding to the virtual block device.
1100	#
1101	# @node-name: The node name of the device. (Since 2.3)
1102	#
1103	# ... more members ...
1104	#
1105	# Since: 0.14
1106	##
1107	{ 'struct': 'BlockStats',
1108	'data': {'device': 'str', 'node-name': 'str',
1109	... more members ... } }
1110
1111	##
1112	# @query-blockstats:
1113	# Query the @BlockStats for all virtual block devices.
1114	#
1115	# @query-nodes: If true, the command will query all the block nodes
1116	# ... explain, explain ...
1117	# (Since 2.3)
1118	#
1119	# Returns: A list of @BlockStats for each virtual block devices.
1120	#
1121	# Since: 0.14
1122	#
1123	# .. qmp-example::
1124	#
1125	# -> { "execute": "query-blockstats" }
1126	# <- {
1127	# ...
1128	# }
1129	##
1130	{ 'command': 'query-blockstats',
1131	'data': { '*query-nodes': 'bool' },
1132	'returns': ['BlockStats'] }
1133
1134
1135	Markup pitfalls
1136	~~~~~~~~~~~~~~~
1137
1138	A blank line is required between list items and paragraphs. Without
1139	it, the list may not be recognized, resulting in garbled output. Good
1140	example::
1141
1142	# An event's state is modified if:
1143	#
1144	# - its name matches the @name pattern, and
1145	# - if @vcpu is given, the event has the "vcpu" property.
1146
1147	Without the blank line this would be a single paragraph.
1148
1149	Indentation matters. Bad example::
1150
1151	# @none: None (no memory side cache in this proximity domain,
1152	# or cache associativity unknown)
1153	# (since 5.0)
1154
1155	The last line's de-indent is wrong. The second and subsequent lines
1156	need to line up with each other, like this::
1157
1158	# @none: None (no memory side cache in this proximity domain,
1159	# or cache associativity unknown)
1160	# (since 5.0)
1161
1162	Section tags are case-sensitive and end with a colon. They are only
1163	recognized after a blank line. Good example::
1164
1165	#
1166	# Since: 7.1
1167
1168	Bad examples (all ordinary paragraphs)::
1169
1170	# since: 7.1
1171
1172	# Since 7.1
1173
1174	# Since : 7.1
1175
1176	Likewise, member descriptions require a colon. Good example::
1177
1178	# @interface-id: Interface ID
1179
1180	Bad examples (all ordinary paragraphs)::
1181
1182	# @interface-id Interface ID
1183
1184	# @interface-id : Interface ID
1185
1186	Undocumented members are not flagged, yet. Instead, the generated
1187	documentation describes them as "Not documented". Think twice before
1188	adding more undocumented members.
1189
1190	When you change documentation comments, please check the generated
1191	documentation comes out as intended!
1192
1193
1194	Client JSON Protocol introspection
1195	==================================
1196
1197	Clients of a Client JSON Protocol commonly need to figure out what
1198	exactly the server (QEMU) supports.
1199
1200	For this purpose, QMP provides introspection via command
1201	query-qmp-schema. QGA currently doesn't support introspection.
1202
1203	While Client JSON Protocol wire compatibility should be maintained
1204	between qemu versions, we cannot make the same guarantees for
1205	introspection stability. For example, one version of qemu may provide
1206	a non-variant optional member of a struct, and a later version rework
1207	the member to instead be non-optional and associated with a variant.
1208	Likewise, one version of qemu may list a member with open-ended type
1209	'str', and a later version could convert it to a finite set of strings
1210	via an enum type; or a member may be converted from a specific type to
1211	an alternate that represents a choice between the original type and
1212	something else.
1213
1214	query-qmp-schema returns a JSON array of SchemaInfo objects. These
1215	objects together describe the wire ABI, as defined in the QAPI schema.
1216	There is no specified order to the SchemaInfo objects returned; a
1217	client must search for a particular name throughout the entire array
1218	to learn more about that name, but is at least guaranteed that there
1219	will be no collisions between type, command, and event names.
1220
1221	However, the SchemaInfo can't reflect all the rules and restrictions
1222	that apply to QMP. It's interface introspection (figuring out what's
1223	there), not interface specification. The specification is in the QAPI
1224	schema. To understand how QMP is to be used, you need to study the
1225	QAPI schema.
1226
1227	Like any other command, query-qmp-schema is itself defined in the QAPI
1228	schema, along with the SchemaInfo type. This text attempts to give an
1229	overview how things work. For details you need to consult the QAPI
1230	schema.
1231
1232	SchemaInfo objects have common members "name", "meta-type",
1233	"features", and additional variant members depending on the value of
1234	meta-type.
1235
1236	Each SchemaInfo object describes a wire ABI entity of a certain
1237	meta-type: a command, event or one of several kinds of type.
1238
1239	SchemaInfo for commands and events have the same name as in the QAPI
1240	schema.
1241
1242	Command and event names are part of the wire ABI, but type names are
1243	not. Therefore, the SchemaInfo for types have auto-generated
1244	meaningless names. For readability, the examples in this section use
1245	meaningful type names instead.
1246
1247	Optional member "features" exposes the entity's feature strings as a
1248	JSON array of strings.
1249
1250	To examine a type, start with a command or event using it, then follow
1251	references by name.
1252
1253	QAPI schema definitions not reachable that way are omitted.
1254
1255	The SchemaInfo for a command has meta-type "command", and variant
1256	members "arg-type", "ret-type" and "allow-oob". On the wire, the
1257	"arguments" member of a client's "execute" command must conform to the
1258	object type named by "arg-type". The "return" member that the server
1259	passes in a success response conforms to the type named by "ret-type".
1260	When "allow-oob" is true, it means the command supports out-of-band
1261	execution. It defaults to false.
1262
1263	If the command takes no arguments, "arg-type" names an object type
1264	without members. Likewise, if the command returns nothing, "ret-type"
1265	names an object type without members.
1266
1267	Example: the SchemaInfo for command query-qmp-schema ::
1268
1269	{ "name": "query-qmp-schema", "meta-type": "command",
1270	"arg-type": "q_empty", "ret-type": "SchemaInfoList" }
1271
1272	Type "q_empty" is an automatic object type without members, and type
1273	"SchemaInfoList" is the array of SchemaInfo type.
1274
1275	The SchemaInfo for an event has meta-type "event", and variant member
1276	"arg-type". On the wire, a "data" member that the server passes in an
1277	event conforms to the object type named by "arg-type".
1278
1279	If the event carries no additional information, "arg-type" names an
1280	object type without members. The event may not have a data member on
1281	the wire then.
1282
1283	Each command or event defined with 'data' as MEMBERS object in the
1284	QAPI schema implicitly defines an object type.
1285
1286	Example: the SchemaInfo for EVENT_C from section Events_ ::
1287
1288	{ "name": "EVENT_C", "meta-type": "event",
1289	"arg-type": "q_obj-EVENT_C-arg" }
1290
1291	Type "q_obj-EVENT_C-arg" is an implicitly defined object type with
1292	the two members from the event's definition.
1293
1294	The SchemaInfo for struct and union types has meta-type "object" and
1295	variant member "members".
1296
1297	The SchemaInfo for a union type additionally has variant members "tag"
1298	and "variants".
1299
1300	"members" is a JSON array describing the object's common members, if
1301	any. Each element is a JSON object with members "name" (the member's
1302	name), "type" (the name of its type), "features" (a JSON array of
1303	feature strings), and "default". The latter two are optional. The
1304	member is optional if "default" is present. Currently, "default" can
1305	only have value null. Other values are reserved for future
1306	extensions. The "members" array is in no particular order; clients
1307	must search the entire object when learning whether a particular
1308	member is supported.
1309
1310	Example: the SchemaInfo for MyType from section `Struct types`_ ::
1311
1312	{ "name": "MyType", "meta-type": "object",
1313	"members": [
1314	{ "name": "member1", "type": "str" },
1315	{ "name": "member2", "type": "int" },
1316	{ "name": "member3", "type": "str", "default": null } ] }
1317
1318	"features" exposes the command's feature strings as a JSON array of
1319	strings.
1320
1321	Example: the SchemaInfo for TestType from section Features_::
1322
1323	{ "name": "TestType", "meta-type": "object",
1324	"members": [
1325	{ "name": "number", "type": "int" } ],
1326	"features": ["allow-negative-numbers"] }
1327
1328	"tag" is the name of the common member serving as type tag.
1329	"variants" is a JSON array describing the object's variant members.
1330	Each element is a JSON object with members "case" (the value of type
1331	tag this element applies to) and "type" (the name of an object type
1332	that provides the variant members for this type tag value). The
1333	"variants" array is in no particular order, and is not guaranteed to
1334	list cases in the same order as the corresponding "tag" enum type.
1335
1336	Example: the SchemaInfo for union BlockdevOptions from section
1337	`Union types`_ ::
1338
1339	{ "name": "BlockdevOptions", "meta-type": "object",
1340	"members": [
1341	{ "name": "driver", "type": "BlockdevDriver" },
1342	{ "name": "read-only", "type": "bool", "default": null } ],
1343	"tag": "driver",
1344	"variants": [
1345	{ "case": "file", "type": "BlockdevOptionsFile" },
1346	{ "case": "qcow2", "type": "BlockdevOptionsQcow2" } ] }
1347
1348	Note that base types are "flattened": its members are included in the
1349	"members" array.
1350
1351	The SchemaInfo for an alternate type has meta-type "alternate", and
1352	variant member "members". "members" is a JSON array. Each element is
1353	a JSON object with member "type", which names a type. Values of the
1354	alternate type conform to exactly one of its member types. There is
1355	no guarantee on the order in which "members" will be listed.
1356
1357	Example: the SchemaInfo for BlockdevRef from section `Alternate types`_ ::
1358
1359	{ "name": "BlockdevRef", "meta-type": "alternate",
1360	"members": [
1361	{ "type": "BlockdevOptions" },
1362	{ "type": "str" } ] }
1363
1364	The SchemaInfo for an array type has meta-type "array", and variant
1365	member "element-type", which names the array's element type. Array
1366	types are implicitly defined. For convenience, the array's name may
1367	resemble the element type; however, clients should examine member
1368	"element-type" instead of making assumptions based on parsing member
1369	"name".
1370
1371	Example: the SchemaInfo for ['str'] ::
1372
1373	{ "name": "[str]", "meta-type": "array",
1374	"element-type": "str" }
1375
1376	The SchemaInfo for an enumeration type has meta-type "enum" and
1377	variant member "members".
1378
1379	"members" is a JSON array describing the enumeration values. Each
1380	element is a JSON object with member "name" (the member's name), and
1381	optionally "features" (a JSON array of feature strings). The
1382	"members" array is in no particular order; clients must search the
1383	entire array when learning whether a particular value is supported.
1384
1385	Example: the SchemaInfo for MyEnum from section `Enumeration types`_ ::
1386
1387	{ "name": "MyEnum", "meta-type": "enum",
1388	"members": [
1389	{ "name": "value1" },
1390	{ "name": "value2" },
1391	{ "name": "value3" }
1392	] }
1393
1394	The SchemaInfo for a built-in type has the same name as the type in
1395	the QAPI schema (see section `Built-in Types`_), with one exception
1396	detailed below. It has variant member "json-type" that shows how
1397	values of this type are encoded on the wire.
1398
1399	Example: the SchemaInfo for str ::
1400
1401	{ "name": "str", "meta-type": "builtin", "json-type": "string" }
1402
1403	The QAPI schema supports a number of integer types that only differ in
1404	how they map to C. They are identical as far as SchemaInfo is
1405	concerned. Therefore, they get all mapped to a single type "int" in
1406	SchemaInfo.
1407
1408	As explained above, type names are not part of the wire ABI. Not even
1409	the names of built-in types. Clients should examine member
1410	"json-type" instead of hard-coding names of built-in types.
1411
1412
1413	Compatibility considerations
1414	============================
1415
1416	Maintaining backward compatibility at the Client JSON Protocol level
1417	while evolving the schema requires some care. This section is about
1418	syntactic compatibility, which is necessary, but not sufficient, for
1419	actual compatibility.
1420
1421	Clients send commands with argument data, and receive command
1422	responses with return data and events with event data.
1423
1424	Adding opt-in functionality to the send direction is backwards
1425	compatible: adding commands, optional arguments, enumeration values,
1426	union and alternate branches; turning an argument type into an
1427	alternate of that type; making mandatory arguments optional. Clients
1428	oblivious of the new functionality continue to work.
1429
1430	Incompatible changes include removing commands, command arguments,
1431	enumeration values, union and alternate branches, adding mandatory
1432	command arguments, and making optional arguments mandatory.
1433
1434	The specified behavior of an absent optional argument should remain
1435	the same. With proper documentation, this policy still allows some
1436	flexibility; for example, when an optional 'buffer-size' argument is
1437	specified to default to a sensible buffer size, the actual default
1438	value can still be changed. The specified default behavior is not the
1439	exact size of the buffer, only that the default size is sensible.
1440
1441	Adding functionality to the receive direction is generally backwards
1442	compatible: adding events, adding return and event data members.
1443	Clients are expected to ignore the ones they don't know.
1444
1445	Removing "unreachable" stuff like events that can't be triggered
1446	anymore, optional return or event data members that can't be sent
1447	anymore, and return or event data member (enumeration) values that
1448	can't be sent anymore makes no difference to clients, except for
1449	introspection. The latter can conceivably confuse clients, so tread
1450	carefully.
1451
1452	Incompatible changes include removing return and event data members.
1453
1454	Any change to a command definition's 'data' or one of the types used
1455	there (recursively) needs to consider send direction compatibility.
1456
1457	Any change to a command definition's 'return', an event definition's
1458	'data', or one of the types used there (recursively) needs to consider
1459	receive direction compatibility.
1460
1461	Any change to types used in both contexts need to consider both.
1462
1463	Enumeration type values and complex and alternate type members may be
1464	reordered freely. For enumerations and alternate types, this doesn't
1465	affect the wire encoding. For complex types, this might make the
1466	implementation emit JSON object members in a different order, which
1467	the Client JSON Protocol permits.
1468
1469	Since type names are not visible in the Client JSON Protocol, types
1470	may be freely renamed. Even certain refactorings are invisible, such
1471	as splitting members from one type into a common base type.
1472
1473
1474	Code generation
1475	===============
1476
1477	The QAPI code generator qapi-gen.py generates code and documentation
1478	from the schema. Together with the core QAPI libraries, this code
1479	provides everything required to take JSON commands read in by a Client
1480	JSON Protocol server, unmarshal the arguments into the underlying C
1481	types, call into the corresponding C function, map the response back
1482	to a Client JSON Protocol response to be returned to the user, and
1483	introspect the commands.
1484
1485	As an example, we'll use the following schema, which describes a
1486	single complex user-defined type, along with command which takes a
1487	list of that type as a parameter, and returns a single element of that
1488	type. The user is responsible for writing the implementation of
1489	qmp_my_command(); everything else is produced by the generator.
1490
1491	::
1492
1493	$ cat example-schema.json
1494	{ 'struct': 'UserDefOne',
1495	'data': { 'integer': 'int', 'string': 'str', 'flag': 'bool' } }
1496
1497	{ 'command': 'my-command',
1498	'data': { 'arg1': ['UserDefOne'] },
1499	'returns': 'UserDefOne' }
1500
1501	{ 'event': 'MY_EVENT' }
1502
1503	We run qapi-gen.py like this::
1504
1505	$ python scripts/qapi-gen.py --output-dir="qapi-generated" \
1506	--prefix="example-" example-schema.json
1507
1508	For a more thorough look at generated code, the testsuite includes
1509	tests/qapi-schema/qapi-schema-tests.json that covers more examples of
1510	what the generator will accept, and compiles the resulting C code as
1511	part of 'make check-unit'.
1512
1513
1514	Code generated for QAPI types
1515	-----------------------------
1516
1517	The following files are created:
1518
1519	``$(prefix)qapi-types.h``
1520	C types corresponding to types defined in the schema
1521
1522	``$(prefix)qapi-types.c``
1523	Cleanup functions for the above C types
1524
1525	The $(prefix) is an optional parameter used as a namespace to keep the
1526	generated code from one schema/code-generation separated from others so code
1527	can be generated/used from multiple schemas without clobbering previously
1528	created code.
1529
1530	Example::
1531
1532	$ cat qapi-generated/example-qapi-types.h
1533	[Uninteresting stuff omitted...]
1534
1535	#ifndef EXAMPLE_QAPI_TYPES_H
1536	#define EXAMPLE_QAPI_TYPES_H
1537
1538	#include "qapi/qapi-builtin-types.h"
1539
1540	typedef struct UserDefOne UserDefOne;
1541
1542	typedef struct UserDefOneList UserDefOneList;
1543
1544	typedef struct q_obj_my_command_arg q_obj_my_command_arg;
1545
1546	struct UserDefOne {
1547	int64_t integer;
1548	char *string;
1549	bool has_flag;
1550	bool flag;
1551	};
1552
1553	void qapi_free_UserDefOne(UserDefOne *obj);
1554	G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOne, qapi_free_UserDefOne)
1555
1556	struct UserDefOneList {
1557	UserDefOneList *next;
1558	UserDefOne *value;
1559	};
1560
1561	void qapi_free_UserDefOneList(UserDefOneList *obj);
1562	G_DEFINE_AUTOPTR_CLEANUP_FUNC(UserDefOneList, qapi_free_UserDefOneList)
1563
1564	struct q_obj_my_command_arg {
1565	UserDefOneList *arg1;
1566	};
1567
1568	#endif /* EXAMPLE_QAPI_TYPES_H */
1569	$ cat qapi-generated/example-qapi-types.c
1570	[Uninteresting stuff omitted...]
1571
1572	void qapi_free_UserDefOne(UserDefOne *obj)
1573	{
1574	Visitor *v;
1575
1576	if (!obj) {
1577	return;
1578	}
1579
1580	v = qapi_dealloc_visitor_new();
1581	visit_type_UserDefOne(v, NULL, &obj, NULL);
1582	visit_free(v);
1583	}
1584
1585	void qapi_free_UserDefOneList(UserDefOneList *obj)
1586	{
1587	Visitor *v;
1588
1589	if (!obj) {
1590	return;
1591	}
1592
1593	v = qapi_dealloc_visitor_new();
1594	visit_type_UserDefOneList(v, NULL, &obj, NULL);
1595	visit_free(v);
1596	}
1597
1598	[Uninteresting stuff omitted...]
1599
1600	For a modular QAPI schema (see section `Include directives`_), code for
1601	each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1602
1603	SUBDIR/$(prefix)qapi-types-SUBMODULE.h
1604	SUBDIR/$(prefix)qapi-types-SUBMODULE.c
1605
1606	If qapi-gen.py is run with option --builtins, additional files are
1607	created:
1608
1609	``qapi-builtin-types.h``
1610	C types corresponding to built-in types
1611
1612	``qapi-builtin-types.c``
1613	Cleanup functions for the above C types
1614
1615
1616	Code generated for visiting QAPI types
1617	--------------------------------------
1618
1619	These are the visitor functions used to walk through and convert
1620	between a native QAPI C data structure and some other format (such as
1621	QObject); the generated functions are named visit_type_FOO() and
1622	visit_type_FOO_members().
1623
1624	The following files are generated:
1625
1626	``$(prefix)qapi-visit.c``
1627	Visitor function for a particular C type, used to automagically
1628	convert QObjects into the corresponding C type and vice-versa, as
1629	well as for deallocating memory for an existing C type
1630
1631	``$(prefix)qapi-visit.h``
1632	Declarations for previously mentioned visitor functions
1633
1634	Example::
1635
1636	$ cat qapi-generated/example-qapi-visit.h
1637	[Uninteresting stuff omitted...]
1638
1639	#ifndef EXAMPLE_QAPI_VISIT_H
1640	#define EXAMPLE_QAPI_VISIT_H
1641
1642	#include "qapi/qapi-builtin-visit.h"
1643	#include "example-qapi-types.h"
1644
1645
1646	bool visit_type_UserDefOne_members(Visitor v, UserDefOne obj, Error **errp);
1647
1648	bool visit_type_UserDefOne(Visitor v, const char name,
1649	UserDefOne obj, Error errp);
1650
1651	bool visit_type_UserDefOneList(Visitor v, const char name,
1652	UserDefOneList obj, Error errp);
1653
1654	bool visit_type_q_obj_my_command_arg_members(Visitor v, q_obj_my_command_arg obj, Error **errp);
1655
1656	#endif /* EXAMPLE_QAPI_VISIT_H */
1657	$ cat qapi-generated/example-qapi-visit.c
1658	[Uninteresting stuff omitted...]
1659
1660	bool visit_type_UserDefOne_members(Visitor v, UserDefOne obj, Error **errp)
1661	{
1662	bool has_string = !!obj->string;
1663
1664	if (!visit_type_int(v, "integer", &obj->integer, errp)) {
1665	return false;
1666	}
1667	if (visit_optional(v, "string", &has_string)) {
1668	if (!visit_type_str(v, "string", &obj->string, errp)) {
1669	return false;
1670	}
1671	}
1672	if (visit_optional(v, "flag", &obj->has_flag)) {
1673	if (!visit_type_bool(v, "flag", &obj->flag, errp)) {
1674	return false;
1675	}
1676	}
1677	return true;
1678	}
1679
1680	bool visit_type_UserDefOne(Visitor v, const char name,
1681	UserDefOne obj, Error errp)
1682	{
1683	bool ok = false;
1684
1685	if (!visit_start_struct(v, name, (void **)obj, sizeof(UserDefOne), errp)) {
1686	return false;
1687	}
1688	if (!*obj) {
1689	/* incomplete */
1690	assert(visit_is_dealloc(v));
1691	ok = true;
1692	goto out_obj;
1693	}
1694	if (!visit_type_UserDefOne_members(v, *obj, errp)) {
1695	goto out_obj;
1696	}
1697	ok = visit_check_struct(v, errp);
1698	out_obj:
1699	visit_end_struct(v, (void **)obj);
1700	if (!ok && visit_is_input(v)) {
1701	qapi_free_UserDefOne(*obj);
1702	*obj = NULL;
1703	}
1704	return ok;
1705	}
1706
1707	bool visit_type_UserDefOneList(Visitor v, const char name,
1708	UserDefOneList obj, Error errp)
1709	{
1710	bool ok = false;
1711	UserDefOneList *tail;
1712	size_t size = sizeof(**obj);
1713
1714	if (!visit_start_list(v, name, (GenericList **)obj, size, errp)) {
1715	return false;
1716	}
1717
1718	for (tail = *obj; tail;
1719	tail = (UserDefOneList )visit_next_list(v, (GenericList )tail, size)) {
1720	if (!visit_type_UserDefOne(v, NULL, &tail->value, errp)) {
1721	goto out_obj;
1722	}
1723	}
1724
1725	ok = visit_check_list(v, errp);
1726	out_obj:
1727	visit_end_list(v, (void **)obj);
1728	if (!ok && visit_is_input(v)) {
1729	qapi_free_UserDefOneList(*obj);
1730	*obj = NULL;
1731	}
1732	return ok;
1733	}
1734
1735	bool visit_type_q_obj_my_command_arg_members(Visitor v, q_obj_my_command_arg obj, Error **errp)
1736	{
1737	if (!visit_type_UserDefOneList(v, "arg1", &obj->arg1, errp)) {
1738	return false;
1739	}
1740	return true;
1741	}
1742
1743	[Uninteresting stuff omitted...]
1744
1745	For a modular QAPI schema (see section `Include directives`_), code for
1746	each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1747
1748	SUBDIR/$(prefix)qapi-visit-SUBMODULE.h
1749	SUBDIR/$(prefix)qapi-visit-SUBMODULE.c
1750
1751	If qapi-gen.py is run with option --builtins, additional files are
1752	created:
1753
1754	``qapi-builtin-visit.h``
1755	Visitor functions for built-in types
1756
1757	``qapi-builtin-visit.c``
1758	Declarations for these visitor functions
1759
1760
1761	Code generated for commands
1762	---------------------------
1763
1764	These are the marshaling/dispatch functions for the commands defined
1765	in the schema. The generated code provides qmp_marshal_COMMAND(), and
1766	declares qmp_COMMAND() that the user must implement.
1767
1768	The following files are generated:
1769
1770	``$(prefix)qapi-commands.c``
1771	Command marshal/dispatch functions for each QMP command defined in
1772	the schema
1773
1774	``$(prefix)qapi-commands.h``
1775	Function prototypes for the QMP commands specified in the schema
1776
1777	``$(prefix)qapi-commands.trace-events``
1778	Trace event declarations, see :ref:`tracing`.
1779
1780	``$(prefix)qapi-init-commands.h``
1781	Command initialization prototype
1782
1783	``$(prefix)qapi-init-commands.c``
1784	Command initialization code
1785
1786	Example::
1787
1788	$ cat qapi-generated/example-qapi-commands.h
1789	[Uninteresting stuff omitted...]
1790
1791	#ifndef EXAMPLE_QAPI_COMMANDS_H
1792	#define EXAMPLE_QAPI_COMMANDS_H
1793
1794	#include "example-qapi-types.h"
1795
1796	UserDefOne qmp_my_command(UserDefOneList arg1, Error **errp);
1797	void qmp_marshal_my_command(QDict args, QObject ret, Error *errp);
1798
1799	#endif /* EXAMPLE_QAPI_COMMANDS_H */
1800
1801	$ cat qapi-generated/example-qapi-commands.trace-events
1802	# AUTOMATICALLY GENERATED, DO NOT MODIFY
1803
1804	qmp_enter_my_command(const char *json) "%s"
1805	qmp_exit_my_command(const char *result, bool succeeded) "%s %d"
1806
1807	$ cat qapi-generated/example-qapi-commands.c
1808	[Uninteresting stuff omitted...]
1809
1810	void qmp_marshal_my_command(QDict args, QObject ret, Error *errp)
1811	{
1812	Error *err = NULL;
1813	bool ok = false;
1814	Visitor *v;
1815	UserDefOne *retval;
1816	Visitor *ov;
1817	q_obj_my_command_arg arg = {0};
1818
1819	v = qobject_input_visitor_new_qmp(QOBJECT(args));
1820	if (!visit_start_struct(v, NULL, NULL, 0, errp)) {
1821	goto out;
1822	}
1823	if (visit_type_q_obj_my_command_arg_members(v, &arg, errp)) {
1824	ok = visit_check_struct(v, errp);
1825	}
1826	visit_end_struct(v, NULL);
1827	if (!ok) {
1828	goto out;
1829	}
1830
1831	if (trace_event_get_state_backends(TRACE_QMP_ENTER_MY_COMMAND)) {
1832	g_autoptr(GString) req_json = qobject_to_json(QOBJECT(args));
1833
1834	trace_qmp_enter_my_command(req_json->str);
1835	}
1836
1837	retval = qmp_my_command(arg.arg1, &err);
1838	if (err) {
1839	trace_qmp_exit_my_command(error_get_pretty(err), false);
1840	error_propagate(errp, err);
1841	goto out;
1842	}
1843
1844	ov = qobject_output_visitor_new_qmp(ret);
1845	if (visit_type_UserDefOne(ov, "unused", &retval, errp)) {
1846	visit_complete(ov, ret);
1847	}
1848	visit_free(ov);
1849	ov = qapi_dealloc_visitor_new();
1850	visit_type_UserDefOne(ov, "unused", &retval, NULL);
1851	visit_free(ov);
1852
1853	if (trace_event_get_state_backends(TRACE_QMP_EXIT_MY_COMMAND)) {
1854	g_autoptr(GString) ret_json = qobject_to_json(*ret);
1855
1856	trace_qmp_exit_my_command(ret_json->str, true);
1857	}
1858
1859	out:
1860	visit_free(v);
1861	v = qapi_dealloc_visitor_new();
1862	visit_start_struct(v, NULL, NULL, 0, NULL);
1863	visit_type_q_obj_my_command_arg_members(v, &arg, NULL);
1864	visit_end_struct(v, NULL);
1865	visit_free(v);
1866	}
1867
1868	[Uninteresting stuff omitted...]
1869	$ cat qapi-generated/example-qapi-init-commands.h
1870	[Uninteresting stuff omitted...]
1871	#ifndef EXAMPLE_QAPI_INIT_COMMANDS_H
1872	#define EXAMPLE_QAPI_INIT_COMMANDS_H
1873
1874	#include "qapi/qmp-registry.h"
1875
1876	void example_qmp_init_marshal(QmpCommandList *cmds);
1877
1878	#endif /* EXAMPLE_QAPI_INIT_COMMANDS_H */
1879	$ cat qapi-generated/example-qapi-init-commands.c
1880	[Uninteresting stuff omitted...]
1881	void example_qmp_init_marshal(QmpCommandList *cmds)
1882	{
1883	QTAILQ_INIT(cmds);
1884
1885	qmp_register_command(cmds, "my-command",
1886	qmp_marshal_my_command, 0, 0);
1887	}
1888	[Uninteresting stuff omitted...]
1889
1890	For a modular QAPI schema (see section `Include directives`_), code for
1891	each sub-module SUBDIR/SUBMODULE.json is actually generated into::
1892
1893	SUBDIR/$(prefix)qapi-commands-SUBMODULE.h
1894	SUBDIR/$(prefix)qapi-commands-SUBMODULE.c
1895
1896
1897	Code generated for events
1898	-------------------------
1899
1900	This is the code related to events defined in the schema, providing
1901	qapi_event_send_EVENT().
1902
1903	The following files are created:
1904
1905	``$(prefix)qapi-events.h``
1906	Function prototypes for each event type
1907
1908	``$(prefix)qapi-events.c``
1909	Implementation of functions to send an event
1910
1911	``$(prefix)qapi-emit-events.h``
1912	Enumeration of all event names, and common event code declarations
1913
1914	``$(prefix)qapi-emit-events.c``
1915	Common event code definitions
1916
1917	Example::
1918
1919	$ cat qapi-generated/example-qapi-events.h
1920	[Uninteresting stuff omitted...]
1921
1922	#ifndef EXAMPLE_QAPI_EVENTS_H
1923	#define EXAMPLE_QAPI_EVENTS_H
1924
1925	#include "qapi/util.h"
1926	#include "example-qapi-types.h"
1927
1928	void qapi_event_send_my_event(void);
1929
1930	#endif /* EXAMPLE_QAPI_EVENTS_H */
1931	$ cat qapi-generated/example-qapi-events.c
1932	[Uninteresting stuff omitted...]
1933
1934	void qapi_event_send_my_event(void)
1935	{
1936	QDict *qmp;
1937
1938	qmp = qmp_event_build_dict("MY_EVENT");
1939
1940	example_qapi_event_emit(EXAMPLE_QAPI_EVENT_MY_EVENT, qmp);
1941
1942	qobject_unref(qmp);
1943	}
1944
1945	[Uninteresting stuff omitted...]
1946	$ cat qapi-generated/example-qapi-emit-events.h
1947	[Uninteresting stuff omitted...]
1948
1949	#ifndef EXAMPLE_QAPI_EMIT_EVENTS_H
1950	#define EXAMPLE_QAPI_EMIT_EVENTS_H
1951
1952	#include "qapi/util.h"
1953
1954	typedef enum example_QAPIEvent {
1955	EXAMPLE_QAPI_EVENT_MY_EVENT,
1956	EXAMPLE_QAPI_EVENT__MAX,
1957	} example_QAPIEvent;
1958
1959	#define example_QAPIEvent_str(val) \
1960	qapi_enum_lookup(&example_QAPIEvent_lookup, (val))
1961
1962	extern const QEnumLookup example_QAPIEvent_lookup;
1963
1964	void example_qapi_event_emit(example_QAPIEvent event, QDict *qdict);
1965
1966	#endif /* EXAMPLE_QAPI_EMIT_EVENTS_H */
1967	$ cat qapi-generated/example-qapi-emit-events.c
1968	[Uninteresting stuff omitted...]
1969
1970	const QEnumLookup example_QAPIEvent_lookup = {
1971	.array = (const char *const[]) {
1972	[EXAMPLE_QAPI_EVENT_MY_EVENT] = "MY_EVENT",
1973	},
1974	.size = EXAMPLE_QAPI_EVENT__MAX
1975	};
1976
1977	[Uninteresting stuff omitted...]
1978
1979	For a modular QAPI schema (see section `Include directives`_), code for
1980	each sub-module SUBDIR/SUBMODULE.json is actually generated into ::
1981
1982	SUBDIR/$(prefix)qapi-events-SUBMODULE.h
1983	SUBDIR/$(prefix)qapi-events-SUBMODULE.c
1984
1985
1986	Code generated for introspection
1987	--------------------------------
1988
1989	The following files are created:
1990
1991	``$(prefix)qapi-introspect.c``
1992	Defines a string holding a JSON description of the schema
1993
1994	``$(prefix)qapi-introspect.h``
1995	Declares the above string
1996
1997	Example::
1998
1999	$ cat qapi-generated/example-qapi-introspect.h
2000	[Uninteresting stuff omitted...]
2001
2002	#ifndef EXAMPLE_QAPI_INTROSPECT_H
2003	#define EXAMPLE_QAPI_INTROSPECT_H
2004
2005	#include "qobject/qlit.h"
2006
2007	extern const QLitObject example_qmp_schema_qlit;
2008
2009	#endif /* EXAMPLE_QAPI_INTROSPECT_H */
2010	$ cat qapi-generated/example-qapi-introspect.c
2011	[Uninteresting stuff omitted...]
2012
2013	const QLitObject example_qmp_schema_qlit = QLIT_QLIST(((QLitObject[]) {
2014	QLIT_QDICT(((QLitDictEntry[]) {
2015	{ "arg-type", QLIT_QSTR("0"), },
2016	{ "meta-type", QLIT_QSTR("command"), },
2017	{ "name", QLIT_QSTR("my-command"), },
2018	{ "ret-type", QLIT_QSTR("1"), },
2019	{}
2020	})),
2021	QLIT_QDICT(((QLitDictEntry[]) {
2022	{ "arg-type", QLIT_QSTR("2"), },
2023	{ "meta-type", QLIT_QSTR("event"), },
2024	{ "name", QLIT_QSTR("MY_EVENT"), },
2025	{}
2026	})),
2027	/* "0" = q_obj_my-command-arg */
2028	QLIT_QDICT(((QLitDictEntry[]) {
2029	{ "members", QLIT_QLIST(((QLitObject[]) {
2030	QLIT_QDICT(((QLitDictEntry[]) {
2031	{ "name", QLIT_QSTR("arg1"), },
2032	{ "type", QLIT_QSTR("[1]"), },
2033	{}
2034	})),
2035	{}
2036	})), },
2037	{ "meta-type", QLIT_QSTR("object"), },
2038	{ "name", QLIT_QSTR("0"), },
2039	{}
2040	})),
2041	/* "1" = UserDefOne */
2042	QLIT_QDICT(((QLitDictEntry[]) {
2043	{ "members", QLIT_QLIST(((QLitObject[]) {
2044	QLIT_QDICT(((QLitDictEntry[]) {
2045	{ "name", QLIT_QSTR("integer"), },
2046	{ "type", QLIT_QSTR("int"), },
2047	{}
2048	})),
2049	QLIT_QDICT(((QLitDictEntry[]) {
2050	{ "default", QLIT_QNULL, },
2051	{ "name", QLIT_QSTR("string"), },
2052	{ "type", QLIT_QSTR("str"), },
2053	{}
2054	})),
2055	QLIT_QDICT(((QLitDictEntry[]) {
2056	{ "default", QLIT_QNULL, },
2057	{ "name", QLIT_QSTR("flag"), },
2058	{ "type", QLIT_QSTR("bool"), },
2059	{}
2060	})),
2061	{}
2062	})), },
2063	{ "meta-type", QLIT_QSTR("object"), },
2064	{ "name", QLIT_QSTR("1"), },
2065	{}
2066	})),
2067	/* "2" = q_empty */
2068	QLIT_QDICT(((QLitDictEntry[]) {
2069	{ "members", QLIT_QLIST(((QLitObject[]) {
2070	{}
2071	})), },
2072	{ "meta-type", QLIT_QSTR("object"), },
2073	{ "name", QLIT_QSTR("2"), },
2074	{}
2075	})),
2076	QLIT_QDICT(((QLitDictEntry[]) {
2077	{ "element-type", QLIT_QSTR("1"), },
2078	{ "meta-type", QLIT_QSTR("array"), },
2079	{ "name", QLIT_QSTR("[1]"), },
2080	{}
2081	})),
2082	QLIT_QDICT(((QLitDictEntry[]) {
2083	{ "json-type", QLIT_QSTR("int"), },
2084	{ "meta-type", QLIT_QSTR("builtin"), },
2085	{ "name", QLIT_QSTR("int"), },
2086	{}
2087	})),
2088	QLIT_QDICT(((QLitDictEntry[]) {
2089	{ "json-type", QLIT_QSTR("string"), },
2090	{ "meta-type", QLIT_QSTR("builtin"), },
2091	{ "name", QLIT_QSTR("str"), },
2092	{}
2093	})),
2094	QLIT_QDICT(((QLitDictEntry[]) {
2095	{ "json-type", QLIT_QSTR("boolean"), },
2096	{ "meta-type", QLIT_QSTR("builtin"), },
2097	{ "name", QLIT_QSTR("bool"), },
2098	{}
2099	})),
2100	{}
2101	}));
2102
2103	[Uninteresting stuff omitted...]