Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2015-11-10' into staging

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

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

"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

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

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

 * Handle an error without reporting it (just for completeness):

 *     error_free(err);

 *

 * Assert that an expected error occurred, but clean it up without

 * reporting it (primarily useful in testsuites):

 *     error_free_or_abort(&err);

 *

 * Pass an existing error to the caller:

 *     error_propagate(errp, err);

 * where Error **errp is a parameter, by convention the last one.

 */

void error_free(Error *err);

/*

 * Convenience function to assert that *@errp is set, then silently free it.

 */

void error_free_or_abort(Error **errp);

/*

 * Convenience function to error_report() and free @err.

 */

 */

static inline void qobject_decref(QObject *obj)

{

    assert(!obj || obj->refcnt);

    if (obj && --obj->refcnt == 0) {

        assert(obj->type != NULL);

        assert(obj->type->destroy != NULL);

# Returns: array of @SchemaInfo, where each element describes an

# entity in the ABI: command, event, type, ...

#

# The order of the various SchemaInfo is unspecified; however, all

# names are guaranteed to be unique (no name will be duplicated with

# different meta-types).

#

# Note: the QAPI schema is also used to help define *internal*

# interfaces, by defining QAPI types.  These are not part of the QMP

# wire ABI, and therefore not returned by this command.

#        Commands and events have the name defined in the QAPI schema.

#        Unlike command and event names, type names are not part of

#        the wire ABI.  Consequently, type names are meaningless

#        strings here.

#        strings here, although they are still guaranteed unique

#        regardless of @meta-type.

#

# All references to other SchemaInfo are by name.

#

#

# Additional SchemaInfo members for meta-type 'enum'.

#

# @values: the enumeration type's values.

# @values: the enumeration type's values, in no particular order.

#

# Values of this type are JSON string on the wire.

#

#

# Additional SchemaInfo members for meta-type 'object'.

#

# @members: the object type's (non-variant) members.

# @members: the object type's (non-variant) members, in no particular order.

#

# @tag: #optional the name of the member serving as type tag.

#       An element of @members with this name must exist.

#

# @variants: #optional variant members, i.e. additional members that

#            depend on the type tag's value.  Present exactly when

#            @tag is present.

#            @tag is present.  The variants are in no particular order,

#            and may even differ from the order of the values of the

#            enum type of the @tag.

#

# Values of this type are JSON object on the wire.

#

#

# Additional SchemaInfo members for meta-type 'alternate'.

#

# @members: the alternate type's members.

# @members: the alternate type's members, in no particular order.

#           The members' wire encoding is distinct, see

#           docs/qapi-code-gen.txt section Alternate types.

#

        # characters.

        if isinstance(typ, QAPISchemaBuiltinType):

            return typ.name

        if isinstance(typ, QAPISchemaArrayType):

            return '[' + self._use_type(typ.element_type) + ']'

        return self._name(typ.name)

    def _gen_json(self, name, mtype, obj):

        if mtype != 'command' and mtype != 'event' and mtype != 'builtin':

        if mtype not in ('command', 'event', 'builtin', 'array'):

            name = self._name(name)

        obj['name'] = name

        obj['meta-type'] = mtype

        self._gen_json(name, 'enum', {'values': values})

    def visit_array_type(self, name, info, element_type):

        self._gen_json(name, 'array',

                       {'element-type': self._use_type(element_type)})

        element = self._use_type(element_type)

        self._gen_json('[' + element + ']', 'array', {'element-type': element})

    def visit_object_type_flat(self, name, info, members, variants):

        obj = {'members': [self._gen_member(m) for m in members]}