[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v2 40/54] docs: document schema configuration
From: |
Marc-André Lureau |
Subject: |
[Qemu-devel] [PATCH v2 40/54] docs: document schema configuration |
Date: |
Tue, 22 Aug 2017 15:22:41 +0200 |
Signed-off-by: Marc-André Lureau <address@hidden>
---
docs/devel/qapi-code-gen.txt | 47 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 47 insertions(+)
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index b653e86bff..94555c01eb 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -682,6 +682,53 @@ Example: Red Hat, Inc. controls redhat.com, and may
therefore add a
downstream command __com.redhat_drive-mirror.
+=== Configuring the schema ===
+
+'struct', 'enum', 'union', 'alternate', 'command' and 'event'
+top-level QAPI expressions can take a 'if' keyword like:
+
+{ 'struct': 'IfStruct', 'data': { 'foo': 'int' },
+ 'if': 'defined(IF_STRUCT) && defined(FOO)' }
+
+Members can be exploded as dictionnary with 'type' & 'if' keys:
+
+{ 'struct': 'IfStruct', 'data':
+ { 'foo': 'int',
+ 'bar': { 'type': 'int', 'if': 'defined(IF_STRUCT_BAR)'} } }
+
+Enum values can be exploded as dictionnary with 'name' & 'if' keys:
+
+{ 'enum': 'IfEnum', 'data':
+ [ 'foo',
+ { 'name' : 'bar', 'if': 'defined(IF_ENUM_BAR)' } ] }
+
+The C code generators will wrap the corresponding lines with #if / #endif
+pre-processor conditions for a given 'if' value.
+
+Example for enum values:
+
+enum IfEnum {
+ IF_ENUM_FOO,
+#if defined(IF_ENUM_BAR)
+ IF_ENUM_BAR,
+#endif /* defined(IF_ENUM_BAR) */
+ IF_ENUM__MAX
+}
+
+Please note that you are responsbile 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.
+
+Poisoined symbols like TARGET_I386 can be wrapped around a preliminary
+NEED_CPU_H condition, using a list value, like so:
+
+{ ..., 'if': ['defined(NEED_CPU_H)', 'defined(TARGET_I386)'] }
+
+This will generate two consecutive #if lines to silence the C error
+when compiling common code. FIXME: split the schema in various units
+instead.
+
+
== Client JSON Protocol introspection ==
Clients of a Client JSON Protocol commonly need to figure out what
--
2.14.1.146.gd35faa819
- Re: [Qemu-devel] [PATCH v2 06/54] qapi: introduce qapi_enum_lookup(), (continued)
- [Qemu-devel] [PATCH v2 27/54] qapi-types: add #if conditions to types, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 49/54] build-sys: make qemu qapi objects per-target, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 23/54] qapi-commands: add #if conditions to commands, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 40/54] docs: document schema configuration,
Marc-André Lureau <=
- [Qemu-devel] [PATCH v2 46/54] qapi: add conditions to SPICE type/commands/events on the schema, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 41/54] qapi2texi: add 'If:' section to generated documentation, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 44/54] qapi2texi: add condition to variants, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 47/54] qapi: add conditions to REPLICATION type/commands on the schema, Marc-André Lureau, 2017/08/22
- [Qemu-devel] [PATCH v2 52/54] qapi: make query-gic-capabilities depend on TARGET_ARM, Marc-André Lureau, 2017/08/22
- Re: [Qemu-devel] [PATCH v2 00/54] qapi: add #if pre-processor conditions to generated code, no-reply, 2017/08/22
- Re: [Qemu-devel] [PATCH v2 00/54] qapi: add #if pre-processor conditions to generated code, Markus Armbruster, 2017/08/23