aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2015-11-10 09:39:24 +0000
committerPeter Maydell <peter.maydell@linaro.org>2015-11-10 09:39:24 +0000
commita8b4f9585a0bf5186fca793ce2c5d754cd8ec49a (patch)
treed9e1c80de4fdeb4d89b4e22743c0be83d486eb5a /docs
parentce278618b088afd10b91a05311eaeb6401bb5004 (diff)
parentf5455044201747fd72531f5e8c1b1e9c56573d9c (diff)
downloadqemu-a8b4f9585a0bf5186fca793ce2c5d754cd8ec49a.zip
qemu-a8b4f9585a0bf5186fca793ce2c5d754cd8ec49a.tar.gz
qemu-a8b4f9585a0bf5186fca793ce2c5d754cd8ec49a.tar.bz2
Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2015-11-10' into staging
QAPI patches # gpg: Signature made Tue 10 Nov 2015 07:12:25 GMT using RSA key ID EB918653 # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" * remotes/armbru/tags/pull-qapi-2015-11-10: qapi-introspect: Document lack of sorting qapi: Provide nicer array names in introspection qapi: More tests of input arrays qapi: Test failure in middle of array parse qapi: More tests of alternate output qapi: Simplify error cleanup in test-qmp-* qapi: Simplify non-error testing in test-qmp-* qapi: Plug leaks in test-qmp-* qapi: Share test_init code in test-qmp-input* qobject: Protect against use-after-free in qobject_decref() qapi: Strengthen test of TestStructList qapi: Use generated TestStruct machinery in tests Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Diffstat (limited to 'docs')
-rw-r--r--docs/qapi-code-gen.txt26
1 files changed, 20 insertions, 6 deletions
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 4d8c2fc..f9fa6f3 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -516,6 +516,10 @@ query-qmp-schema. QGA currently doesn't support introspection.
query-qmp-schema returns a JSON array of SchemaInfo objects. These
objects together describe the wire ABI, as defined in the QAPI schema.
+There is no specified order to the SchemaInfo objects returned; a
+client must search for a particular name throughout the entire array
+to learn more about that name, but is at least guaranteed that there
+will be no collisions between type, command, and event names.
However, the SchemaInfo can't reflect all the rules and restrictions
that apply to QMP. It's interface introspection (figuring out what's
@@ -596,7 +600,9 @@ any. Each element is a JSON object with members "name" (the member's
name), "type" (the name of its type), and optionally "default". The
member is optional if "default" is present. Currently, "default" can
only have value null. Other values are reserved for future
-extensions.
+extensions. The "members" array is in no particular order; clients
+must search the entire object when learning whether a particular
+member is supported.
Example: the SchemaInfo for MyType from section Struct types
@@ -610,7 +616,9 @@ Example: the SchemaInfo for MyType from section Struct types
"variants" is a JSON array describing the object's variant members.
Each element is a JSON object with members "case" (the value of type
tag this element applies to) and "type" (the name of an object type
-that provides the variant members for this type tag value).
+that provides the variant members for this type tag value). The
+"variants" array is in no particular order, and is not guaranteed to
+list cases in the same order as the corresponding "tag" enum type.
Example: the SchemaInfo for flat union BlockdevOptions from section
Union types
@@ -651,7 +659,8 @@ Union types
The SchemaInfo for an alternate type has meta-type "alternate", and
variant member "members". "members" is a JSON array. Each element is
a JSON object with member "type", which names a type. Values of the
-alternate type conform to exactly one of its member types.
+alternate type conform to exactly one of its member types. There is
+no guarantee on the order in which "members" will be listed.
Example: the SchemaInfo for BlockRef from section Alternate types
@@ -662,15 +671,20 @@ Example: the SchemaInfo for BlockRef from section Alternate types
The SchemaInfo for an array type has meta-type "array", and variant
member "element-type", which names the array's element type. Array
-types are implicitly defined.
+types are implicitly defined. For convenience, the array's name may
+resemble the element type; however, clients should examine member
+"element-type" instead of making assumptions based on parsing member
+"name".
Example: the SchemaInfo for ['str']
- { "name": "strList", "meta-type": "array",
+ { "name": "[str]", "meta-type": "array",
"element-type": "str" }
The SchemaInfo for an enumeration type has meta-type "enum" and
-variant member "values".
+variant member "values". The values are listed in no particular
+order; clients must search the entire enum when learning whether a
+particular value is supported.
Example: the SchemaInfo for MyEnum from section Enumeration types