[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v3 30/49] docs: document schema configuration
From: |
Marc-André Lureau |
Subject: |
[Qemu-devel] [PATCH v3 30/49] docs: document schema configuration |
Date: |
Wed, 21 Mar 2018 12:51:52 +0100 |
Signed-off-by: Marc-André Lureau <address@hidden>
---
docs/devel/qapi-code-gen.txt | 38 ++++++++++++++++++++++++++++++++++++
1 file changed, 38 insertions(+)
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index a569d24745..eec52e63e5 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -728,6 +728,44 @@ Example: Red Hat, Inc. controls redhat.com, and may
therefore add a
downstream command __com.redhat_drive-mirror.
+=== Configuring the schema ===
+
+Top-level QAPI expressions and various type expressions listed below
+can take an 'if' key. The value must be a string or a list of
+string. The corresponding generated code will then guard the inclusion
+of that member in the larger struct or function with #if IFCOND
+(or several #if lines for a list), where IFCOND is the value of the
+'if' key.
+
+'struct', 'enum', 'union', 'alternate', 'command' and 'event'
+top-level QAPI expressions can take an 'if' keyword like:
+
+{ 'struct': 'IfStruct', 'data': { 'foo': 'int' },
+ 'if': 'defined(IFCOND)' }
+
+Where a member can normally be defined with a single string value as its
+type, it is also possible to supply a dictionary with both 'type' and
+'if' keys.
+
+{ 'struct': 'IfStruct', 'data':
+ { 'foo': 'int',
+ 'bar': { 'type': 'int', 'if': 'defined(IFCOND)'} } }
+
+An enum value can be replaced by a dictionary with a 'name' and a 'if'
+key:
+
+{ 'enum': 'IfEnum', 'data':
+ [ 'foo',
+ { 'name' : 'bar', 'if': 'defined(IFCOND)' } ] }
+
+Please note that you are responsible to ensure that the C code will
+compile with an arbitrary combination of conditions, since the
+generators are unable to check it at this point.
+
+The presence of 'if' keys in the schema is reflected through to the
+introspection output depending on the build configuration.
+
+
== Client JSON Protocol introspection ==
Clients of a Client JSON Protocol commonly need to figure out what
--
2.16.2.521.g9aa15f885a
- [Qemu-devel] [PATCH v3 21/49] qapi: add 'if' to enum members, (continued)
- [Qemu-devel] [PATCH v3 21/49] qapi: add 'if' to enum members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 22/49] qapi-event: add 'if' condition to implicit event enum, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 23/49] qapi: rename allow_dict to allow_implicit, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 25/49] qapi: add 'if' to implicit struct members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 24/49] qapi: add a dictionary form with 'type' key for members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 26/49] qapi: add an error in case a discriminator is conditionnal, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 27/49] qapi: add 'if' on union members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 28/49] qapi: add 'if' to alternate members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 29/49] qapi: add #if conditions to generated code members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 32/49] qapi2texi: add 'If:' condition to enum values, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 30/49] docs: document schema configuration,
Marc-André Lureau <=
- [Qemu-devel] [PATCH v3 31/49] qapi2texi: add 'If:' section to generated documentation, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 33/49] qapi2texi: add 'If:' condition to struct members, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 35/49] qapi: add conditions to VNC type/commands/events on the schema, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 34/49] qapi2texi: add condition to variants, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 36/49] qapi: add conditions to SPICE type/commands/events on the schema, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 37/49] qapi: add conditions to REPLICATION type/commands on the schema, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 38/49] build-sys: move qmp-introspect per target, Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 39/49] qapi-commands: don't initialize command list in qmp_init_marshall(), Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 40/49] RFC: qapi: learn to split schema by 'top-unit', Marc-André Lureau, 2018/03/21
- [Qemu-devel] [PATCH v3 41/49] qapi: add a top-unit 'target' schema, Marc-André Lureau, 2018/03/21