Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2018-12-13-v2' into staging

QAPI patches for 2018-12-13

# gpg: Signature made Fri 14 Dec 2018 05:53:51 GMT
# gpg:                using RSA key 3870B400EB918653
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>"
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>"
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2018-12-13-v2: (32 commits)
  qapi: add conditions to REPLICATION type/commands on the schema
  qapi: add more conditions to SPICE
  qapi: add condition to variants documentation
  qapi: add 'If:' condition to struct members documentation
  qapi: add 'If:' condition to enum values documentation
  qapi: Add #if conditions to generated code members
  qapi: add 'if' to alternate members
  qapi: add 'if' to union members
  qapi: Add 'if' to implicit struct members
  qapi: add a dictionary form for TYPE
  qapi-events: add 'if' condition to implicit event enum
  qapi: add 'if' to enum members
  qapi: add a dictionary form with 'name' key for enum members
  qapi: improve reporting of unknown or missing keys
  qapi: factor out checking for keys
  tests: print enum type members more like object type members
  qapi: change enum visitor and gen_enum* to take QAPISchemaMember
  qapi: Do not define enumeration value explicitly
  qapi: break long lines at 'data' member
  qapi: rename QAPISchemaEnumType.values to .members
  ...

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 20 insertions, 1 deletions

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 53eaf01f34..43bd853e69 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -26,7 +26,7 @@ how the schemas, scripts, and resulting code are used.
 == QMP/Guest agent schema ==
 
 A QAPI schema file is designed to be loosely based on JSON
-(http://www.ietf.org/rfc/rfc7159.txt) with changes for quoting style
+(http://www.ietf.org/rfc/rfc8259.txt) with changes for quoting style
 and the use of comments; a QAPI schema file is then parsed by a python
 code generation program.  A valid QAPI schema consists of a series of
 top-level expressions, with no commas between them.  Where
@@ -752,6 +752,25 @@ gets its generated code guarded like this:
  #endif /* defined(HAVE_BAR) */
  #endif /* defined(CONFIG_FOO) */
 
+Where a member can be defined with a single string value for its type,
+it is also possible to supply a dictionary instead with both 'type'
+and 'if' keys.
+
+Example: a conditional 'bar' member
+
+{ '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.
+
+Example: a conditional 'bar' enum member.
+
+{ '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.