Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2019-09-28' into staging

QAPI patches for 2019-09-28

# gpg: Signature made Sat 28 Sep 2019 16:18:13 BST
# gpg: using RSA k

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2019-09-28' into staging

QAPI patches for 2019-09-28

# gpg: Signature made Sat 28 Sep 2019 16:18:13 BST
# 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-2019-09-28: (27 commits)
qapi: Improve source file read error handling
qapi: Improve reporting of redefinition
qapi: Improve reporting of missing documentation comment
qapi: Eliminate check_keys(), rename check_known_keys()
qapi: Improve reporting of invalid 'if' further
qapi: Avoid redundant definition references in error messages
qapi: Improve reporting of missing / unknown definition keys
qapi: Improve reporting of invalid flags
qapi: Improve reporting of invalid 'if' errors
qapi: Move context-free checking to the proper place
qapi: Move context-sensitive checking to the proper place
qapi: Inline check_name() into check_union()
qapi: Plumb info to the QAPISchemaMember
qapi: Make check_type()'s array case a bit more obvious
qapi: Move check for reserved names out of add_name()
qapi: Report invalid '*' prefix like any other invalid name
qapi: Use check_name_str() where it suffices
qapi: Improve reporting of invalid name errors
qapi: Reorder check_FOO() parameters for consistency
qapi: Improve reporting of member name clashes
...

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

show more ...

qapi: Clean up member name case checking

QAPISchemaMember.check_clash() checks for member names that map to the
same c_name(). Takes care of rejecting duplicate names.

It also checks a naming rule

qapi: Clean up member name case checking

QAPISchemaMember.check_clash() checks for member names that map to the
same c_name(). Takes care of rejecting duplicate names.

It also checks a naming rule: no uppercase in member names. That's a
rather odd place to do it. Enforcing naming rules is
check_name_str()'s job.

qapi-code-gen.txt specifies the name case rule applies to the name as
it appears in the schema. check_clash() checks c_name(name) instead.
No difference, as c_name() leaves alone case, but unclean.

Move the name case check into check_name_str(), less the c_name().
New argument @permit_upper suppresses it. Pass permit_upper=True for
definitions (which are not members), and when the member's owner is
whitelisted with pragma name-case-whitelist.

Bonus: name-case-whitelist now applies to a union's inline base, too.
Update qapi/qapi-schema.json pragma to whitelist union CpuInfo instead
of CpuInfo's implicit base type's name q_obj_CpuInfo-base.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20190927134639.4284-6-armbru@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-03-16' into staging

QAPI patches for 2017-03-16

# gpg: Signature made Thu 16 Mar 2017 06:18:38 GMT
# gpg: using RSA k

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-03-16' into staging

QAPI patches for 2017-03-16

# gpg: Signature made Thu 16 Mar 2017 06:18:38 GMT
# gpg: using RSA key 0x3870B400EB918653
# 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-2017-03-16: (49 commits)
qapi: Fix a misleading parser error message
qapi: Make pylint a bit happier
qapi: Drop unused .check_clash() parameter schema
qapi: union_types is a list used like a dict, make it one
qapi: struct_types is a list used like a dict, make it one
qapi: enum_types is a list used like a dict, make it one
qapi: Factor add_name() calls out of the meta conditional
qapi: Simplify what gets stored in enum_types
qapi: Drop unused variable events
qapi: Eliminate check_docs() and drop QAPIDoc.expr
qapi: Fix detection of bogus member documentation
tests/qapi-schema: Improve coverage of bogus member docs
tests/qapi-schema: Rename doc-bad-args to doc-bad-command-arg
qapi: Move empty doc section checking to doc parser
qapi: Improve error message on @NAME: in free-form doc
qapi: Move detection of doc / expression name mismatch
qapi: Fix detection of doc / expression mismatch
tests/qapi-schema: Improve doc / expression mismatch coverage
qapi2texi: Use category "Object" for all object types
qapi2texi: Generate descriptions for simple union tags
...

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

show more ...

qapi: Back out doc comments added just to please qapi.py

This reverts commit 3313b61's changes to tests/qapi-schema/, except
for tests/qapi-schema/doc-*.

We could keep some of these doc comments to

qapi: Back out doc comments added just to please qapi.py

This reverts commit 3313b61's changes to tests/qapi-schema/, except
for tests/qapi-schema/doc-*.

We could keep some of these doc comments to serve as positive test
cases. However, they don't actually add to what we get from doc
comment use in actual schemas, as we we don't test output matches
expectations, and don't systematically cover doc comment features.
Proper positive test coverage would be nice.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-4-git-send-email-armbru@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-01-16' into staging

QAPI patches for 2017-01-16

# gpg: Signature made Mon 16 Jan 2017 09:26:49 GMT
# gpg: using RSA k

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2017-01-16' into staging

QAPI patches for 2017-01-16

# gpg: Signature made Mon 16 Jan 2017 09:26:49 GMT
# gpg: using RSA key 0x3870B400EB918653
# 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-2017-01-16: (180 commits)
build-sys: add qapi doc generation targets
build-sys: add txt documentation rules
build-sys: use a generic TEXI2MAN rule
build-sys: remove dvi doc generation
build-sys: use --no-split for info
docs: add qemu logo to pdf
qapi: add qapi2texi script
qmp-events: move 'MIGRATION_PASS' doc to schema
qmp-events: move 'DUMP_COMPLETED' doc to schema
qmp-events: move 'MEM_UNPLUG_ERROR' doc to schema
qmp-events: move 'VSERPORT_CHANGE' doc to schema
qmp-events: move 'QUORUM_REPORT_BAD' doc to schema
qmp-events: move 'QUORUM_FAILURE' doc to schema
qmp-events: move 'GUEST_PANICKED' doc to schema
qmp-events: move 'BALLOON_CHANGE' doc to schema
qmp-events: move 'ACPI_DEVICE_OST' doc to schema
qmp-events: move 'MIGRATION' doc to schema
qmp-events: move 'SPICE_MIGRATE_COMPLETED' doc to schema
qmp-events: move 'SPICE_DISCONNECTED' doc to schema
qmp-events: move 'SPICE_INITIALIZED' doc to schema
...

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

show more ...

qapi: add qapi2texi script

As the name suggests, the qapi2texi script converts JSON QAPI
description into a texi file suitable for different target
formats (info/man/txt/pdf/html...).

It parses the

qapi: add qapi2texi script

As the name suggests, the qapi2texi script converts JSON QAPI
description into a texi file suitable for different target
formats (info/man/txt/pdf/html...).

It parses the following kind of blocks:

Free-form:

##
# = Section
# == Subsection
#
# Some text foo with *emphasis*
# 1. with a list
# 2. like that
#
# And some code:
# | $ echo foo
# | -> do this
# | <- get that
#
##

Symbol description:

##
# @symbol:
#
# Symbol body ditto ergo sum. Foo bar
# baz ding.
#
# @param1: the frob to frobnicate
# @param2: #optional how hard to frobnicate
#
# Returns: the frobnicated frob.
# If frob isn't frobnicatable, GenericError.
#
# Since: version
# Notes: notes, comments can have
# - itemized list
# - like this
#
# Example:
#
# -> { "execute": "quit" }
# <- { "return": {} }
#
##

That's roughly following the following EBNF grammar:

api_comment = "##\n" comment "##\n"
comment = freeform_comment | symbol_comment
freeform_comment = { "# " text "\n" | "#\n" }
symbol_comment = "# @" name ":\n" { member | tag_section | freeform_comment }
member = "# @" name ':' [ text ] "\n" freeform_comment
tag_section = "# " ( "Returns:", "Since:", "Note:", "Notes:", "Example:", "Examples:" ) [ text ] "\n" freeform_comment
text = free text with markup

Note that the grammar is ambiguous: a line "# @foo:\n" can be parsed
both as freeform_comment and as symbol_comment. The actual parser
recognizes symbol_comment.

See docs/qapi-code-gen.txt for more details.

Deficiencies and limitations:
- the generated QMP documentation includes internal types
- union type support is lacking
- type information is lacking in generated documentation
- doc comment error message positions are imprecise, they point
to the beginning of the comment.
- a few minor issues, all marked TODO/FIXME in the code

Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20170113144135.5150-16-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[test-qapi.py tweaked to avoid trailing empty lines in .out]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2015-12-17' into staging

QAPI patches for 2015-12-17

# gpg: Signature made Thu 17 Dec 2015 07:33:41 GMT using RSA key ID EB918653
# gpg:

Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2015-12-17' into staging

QAPI patches for 2015-12-17

# gpg: Signature made Thu 17 Dec 2015 07:33:41 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-12-17: (40 commits)
qapi: Detect base class loops
qapi: Move duplicate collision checks to schema check()
qapi: Enforce (or whitelist) case conventions on qapi members
qapi: Track enum values by QAPISchemaMember, not string
qapi: Prepare new QAPISchemaMember base class
qapi: Shorter visits of optional fields
qapi: Simplify visits of optional fields
qapi: Fix alternates that accept 'number' but not 'int'
qapi: Inline _make_implicit_tag()
qapi-types: Drop unnedeed ._fwdefn
qapi: Simplify visiting of alternate types
qapi: Convert QType into QAPI built-in enum type
qobject: Rename qtype_code to QType
qobject: Simplify QObject
qapi: Change munging of CamelCase enum values
qapi: Add alias for ErrorClass
cpu: Convert CpuInfo into flat union
qapi: Remove obsolete tests for MAX collision
qapi: Don't let implicit enum MAX member collide
qapi: Tighten the regex on valid names
...

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

show more ...

qapi: Enforce (or whitelist) case conventions on qapi members

We document that members of enums and objects should be
'lower-case', although we were not enforcing it. We have to
whitelist a few pre

qapi: Enforce (or whitelist) case conventions on qapi members

We document that members of enums and objects should be
'lower-case', although we were not enforcing it. We have to
whitelist a few pre-existing entities that violate the norms.
Add three new tests to expose the new error message, each of
which first uses the whitelisted name 'UuidInfo' to prove the
whitelist works, then triggers the failure (this is the same
pattern used in the existing returns-whitelist.json test).

Note that by adding this check, we have effectively forbidden
an entity with a case-insensitive clash of member names, for
any entity that is not on the whitelist (although there is
still the possibility to clash via '-' vs. '_').

Not done here: a future patch should also add naming convention
support and whitelist exceptions for command, event, and type
names.

The additions to QAPISchemaMember.check_clash() check whether
info['name'] is in the whitelist (the top-most entity name at
the point 'info' tracks), rather than self.owner (the type,
possibly implicit, that directly owns the member), because it
is easier to maintain the whitelist by the names actually in
the user's .json file, rather than worrying about the names
of implicit types.

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <1449033659-25497-14-git-send-email-eblake@redhat.com>
[Simplified a bit as per discussion with Eric]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...