Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-03-17' into staging

QAPI patches for 2020-03-17

# gpg: Signature made Tue 17 Mar 2020 20:50:54 GMT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* remotes/armbru/tags/pull-qapi-2020-03-17: (30 commits)
  net: Track netdevs in NetClientState rather than QemuOpt
  net: Complete qapi-fication of netdev_add
  qmp: constify QmpCommand and list
  qapi: Mark deprecated QMP parts with feature 'deprecated'
  qapi: New special feature flag "deprecated"
  qapi: Replace qmp_dispatch()'s TODO comment by an explanation
  qapi: Simplify how qmp_dispatch() gets the request ID
  qapi: Simplify how qmp_dispatch() deals with QCO_NO_SUCCESS_RESP
  qapi: Inline do_qmp_dispatch() into qmp_dispatch()
  qapi: Add feature flags to struct members
  qapi/schema: Call QAPIDoc.connect_member() in just one place
  qapi/schema: Rename QAPISchemaObjectType{Variant,Variants}
  qapi/schema: Reorder classes so related ones are together
  qapi/schema: Change _make_features() to a take feature list
  qapi/introspect: Factor out _make_tree()
  qapi/introspect: Rename *qlit* to reduce confusion
  qapi: Consistently put @features parameter right after @ifcond
  qapi: Add feature flags to remaining definitions
  qapi/schema: Clean up around QAPISchemaEntity.connect_doc()
  tests/test-qmp-event: Check event is actually emitted
  ...

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

2 files changed, 106 insertions, 23 deletions

diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 59d6973..1967adf 100644
--- a/docs/devel/qapi-code-gen.txt
+++ b/docs/devel/qapi-code-gen.txt
@@ -172,7 +172,8 @@ Syntax:
     ENUM = { 'enum': STRING,
              'data': [ ENUM-VALUE, ... ],
              '*prefix': STRING,
-             '*if': COND }
+             '*if': COND,
+             '*features': FEATURES }
     ENUM-VALUE = STRING
                | { 'name': STRING, '*if': COND }
 
@@ -207,6 +208,9 @@ the job satisfactorily.
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
 
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
 
 === Type references and array types ===
 
@@ -230,7 +234,9 @@ Syntax:
                '*features': FEATURES }
     MEMBERS = { MEMBER, ... }
     MEMBER = STRING : TYPE-REF
-           | STRING : { 'type': TYPE-REF, '*if': COND }
+           | STRING : { 'type': TYPE-REF,
+                        '*if': COND,
+                        '*features': FEATURES }
 
 Member 'struct' names the struct type.
 
@@ -279,12 +285,14 @@ below for more on this.
 Syntax:
     UNION = { 'union': STRING,
               'data': BRANCHES,
-              '*if': COND }
+              '*if': COND,
+              '*features': FEATURES }
           | { 'union': STRING,
               'data': BRANCHES,
               'base': ( MEMBERS | STRING ),
               'discriminator': STRING,
-              '*if': COND }
+              '*if': COND,
+              '*features': FEATURES }
     BRANCHES = { BRANCH, ... }
     BRANCH = STRING : TYPE-REF
            | STRING : { 'type': TYPE-REF, '*if': COND }
@@ -391,15 +399,19 @@ is identical on the wire to:
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
 
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
 
 === Alternate types ===
 
 Syntax:
     ALTERNATE = { 'alternate': STRING,
                   'data': ALTERNATIVES,
-                  '*if': COND }
+                  '*if': COND,
+                  '*features': FEATURES }
     ALTERNATIVES = { ALTERNATIVE, ... }
-    ALTERNATIVE = STRING : TYPE-REF
+    ALTERNATIVE = STRING : STRING
                 | STRING : { 'type': STRING, '*if': COND }
 
 Member 'alternate' names the alternate type.
@@ -441,6 +453,9 @@ following example objects:
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
 
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
 
 === Commands ===
 
@@ -584,6 +599,9 @@ started with --preconfig.
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
 
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
 
 === Events ===
 
@@ -595,7 +613,8 @@ Syntax:
               'data': STRING,
               'boxed': true,
               )
-              '*if': COND }
+              '*if': COND,
+              '*features': FEATURES }
 
 Member 'event' names the event.  This is the event name used in the
 Client JSON Protocol.
@@ -628,6 +647,9 @@ complex type.  See section "Code generated for events" for examples.
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
 
+The optional 'features' member specifies features.  See "Features"
+below for more on this.
+
 
 === Features ===
 
@@ -642,13 +664,8 @@ that previously resulted in an error).  QMP clients may still need to
 know whether the extension is available.
 
 For this purpose, a list of features can be specified for a command or
-struct type.  This is exposed to the client as a list of strings,
-where each string signals that this build of QEMU shows a certain
-behaviour.
-
-Each member of the 'features' array defines a feature.  It can either
-be { 'name': STRING, '*if': COND }, or STRING, which is shorthand for
-{ 'name': STRING }.
+struct type.  Each list member can either be { 'name': STRING, '*if':
+COND }, or STRING, which is shorthand for { 'name': STRING }.
 
 The optional 'if' member specifies a conditional.  See "Configuring
 the schema" below for more on this.
@@ -659,6 +676,18 @@ Example:
   'data': { 'number': 'int' },
   'features': [ 'allow-negative-numbers' ] }
 
+The feature strings are exposed to clients in introspection, as
+explained in section "Client JSON Protocol introspection".
+
+Intended use is to have each feature string signal that this build of
+QEMU shows a certain behaviour.
+
+
+==== Special features ====
+
+Feature "deprecated" marks a command, event, or struct member as
+deprecated.  It is not supported elsewhere so far.
+
 
 === Naming rules and reserved names ===
 
@@ -965,8 +994,9 @@ schema, along with the SchemaInfo type.  This text attempts to give an
 overview how things work.  For details you need to consult the QAPI
 schema.
 
-SchemaInfo objects have common members "name" and "meta-type", and
-additional variant members depending on the value of meta-type.
+SchemaInfo objects have common members "name", "meta-type",
+"features", and additional variant members depending on the value of
+meta-type.
 
 Each SchemaInfo object describes a wire ABI entity of a certain
 meta-type: a command, event or one of several kinds of type.
@@ -979,6 +1009,9 @@ not.  Therefore, the SchemaInfo for types have auto-generated
 meaningless names.  For readability, the examples in this section use
 meaningful type names instead.
 
+Optional member "features" exposes the entity's feature strings as a
+JSON array of strings.
+
 To examine a type, start with a command or event using it, then follow
 references by name.
 
@@ -988,9 +1021,9 @@ The SchemaInfo for a command has meta-type "command", and variant
 members "arg-type", "ret-type" and "allow-oob".  On the wire, the
 "arguments" member of a client's "execute" command must conform to the
 object type named by "arg-type".  The "return" member that the server
-passes in a success response conforms to the type named by
-"ret-type".  When "allow-oob" is set, it means the command supports
-out-of-band execution.
+passes in a success response conforms to the type named by "ret-type".
+When "allow-oob" is true, it means the command supports out-of-band
+execution.  It defaults to false.
 
 If the command takes no arguments, "arg-type" names an object type
 without members.  Likewise, if the command returns nothing, "ret-type"
@@ -1047,6 +1080,16 @@ Example: the SchemaInfo for MyType from section Struct types
           { "name": "member2", "type": "int" },
           { "name": "member3", "type": "str", "default": null } ] }
 
+"features" exposes the command's feature strings as a JSON array of
+strings.
+
+Example: the SchemaInfo for TestType from section Features:
+
+    { "name": "TestType", "meta-type": "object",
+      "members": [
+          { "name": "number", "type": "int" } ],
+      "features": ["allow-negative-numbers"] }
+
 "tag" is the name of the common member serving as type tag.
 "variants" is a JSON array describing the object's variant members.
 Each element is a JSON object with members "case" (the value of type
diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index 412b1b1..c633fe2 100644
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -180,27 +180,67 @@ QEMU Machine Protocol (QMP) commands
 
 Use ``blockdev-change-medium`` or ``change-vnc-password`` instead.
 
+``blockdev-open-tray``, ``blockdev-close-tray`` argument ``device`` (since 2.8.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use argument ``id`` instead.
+
+``eject`` argument ``device`` (since 2.8.0)
+'''''''''''''''''''''''''''''''''''''''''''
+
+Use argument ``id`` instead.
+
+``blockdev-change-medium`` argument ``device`` (since 2.8.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use argument ``id`` instead.
+
+``block_set_io_throttle`` argument ``device`` (since 2.8.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use argument ``id`` instead.
+
 ``migrate_set_downtime`` and ``migrate_set_speed`` (since 2.8.0)
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 Use ``migrate-set-parameters`` instead.
 
+``query-named-block-nodes`` result ``encryption_key_missing`` (since 2.10.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Always false.
+
+``query-block`` result ``inserted.encryption_key_missing`` (since 2.10.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Always false.
+
+``blockdev-add`` empty string argument ``backing`` (since 2.10.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use argument value ``null`` instead.
+
 ``migrate-set-cache-size`` and ``query-migrate-cache-size`` (since 2.11.0)
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 Use ``migrate-set-parameters`` and ``query-migrate-parameters`` instead.
 
+``block-commit`` arguments ``base`` and ``top`` (since 3.1.0)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+Use arguments ``base-node`` and ``top-node`` instead.
+
 ``object-add`` option ``props`` (since 5.0)
 '''''''''''''''''''''''''''''''''''''''''''
 
 Specify the properties for the object as top-level arguments instead.
 
-``query-block`` result field ``dirty-bitmaps[i].status`` (since 4.0)
-''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+``query-named-block-nodes`` and ``query-block`` result dirty-bitmaps[i].status (since 4.0)
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 The ``status`` field of the ``BlockDirtyInfo`` structure, returned by
-the query-block command is deprecated. Two new boolean fields,
-``recording`` and ``busy`` effectively replace it.
+these commands is deprecated. Two new boolean fields, ``recording`` and
+``busy`` effectively replace it.
 
 ``query-block`` result field ``dirty-bitmaps`` (Since 4.2)
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''