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-10-12' into staging

QAPI patches

# gpg: Signature made Mon 12 Oct 2015 18:56:35 BST using RSA key ID EB918653
# gpg: Good signature

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

QAPI patches

# gpg: Signature made Mon 12 Oct 2015 18:56:35 BST 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-10-12:
qapi: Simplify gen_visit_fields() error handling
qapi: Share gen_visit_fields()
qapi: Share gen_err_check()
qapi: Consistent generated code: minimize push_indent() usage
qapi: Consistent generated code: prefer common indentation
qapi: Consistent generated code: prefer common labels
qapi: Consistent generated code: prefer visitor 'v'
qapi: Consistent generated code: prefer error 'err'
qapi: Reuse code for flat union base validation
qapi: Test use of 'number' within alternates
qapi: Add tests for empty unions
qapi: Avoid assertion failure on union 'type' collision
qapi: Test for various name collisions
qapi: Clean up qapi.py per pep8
qapi: Invoke exception superclass initializer
qapi: Improve 'include' error message
qapi: Sort qapi-schema tests
MAINTAINERS: Specify QAPI include and test files
MAINTAINERS: Specify QObject include and test files
docs: Move files from docs/qmp/ to docs/

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

show more ...

qapi: Test for various name collisions

Expose some weaknesses in the generator: we don't always forbid
the generation of structs that contain multiple members that map
to the same C or QMP name. Th

qapi: Test for various name collisions

Expose some weaknesses in the generator: we don't always forbid
the generation of structs that contain multiple members that map
to the same C or QMP name. This has already been marked FIXME in
qapi.py in commit d90675f, but having more tests will make sure
future patches produce desired behavior; and updating existing
patches to better document things doesn't hurt, either. Some of
these collisions are already caught in the old-style parser
checks, but ultimately we want all collisions to be caught in the
new-style QAPISchema*.check() methods.

This patch focuses on C struct members, and does not consider
collisions between commands and events (affecting C function
names), or even collisions between generated C type names with
user type names (for things like automatic FOOList struct
representing array types or FOOKind for an implicit enum).

There are two types of struct collisions we want to catch:
1) Collision between two keys in a JSON object. qapi.py prevents
that within a single struct (see test duplicate-key), but it is
possible to have collisions between a type's members and its
base type's members (existing tests struct-base-clash,
struct-base-clash-deep), and its flat union variant members
(renamed test flat-union-clash-member).
2) Collision between two members of the C struct that is generated
for a given QAPI type:
a) Multiple QAPI names map to the same C name (new test
args-name-clash)
b) A QAPI name maps to a C name that is used for another purpose
(new tests flat-union-clash-branch, struct-base-clash-base,
union-clash-data). We already fixed some such cases in commit
0f61af3e and 1e6c1616, but more remain.
c) Two C names generated for other purposes clash
(updated test alternate-clash, new test union-clash-branches,
union-clash-type, flat-union-clash-type)

Ultimately, if we need to have a flat union where a tag value
clashes with a base member name, we could change the generator to
name the union (using 'foo.u.value' rather than 'foo.value') or
otherwise munge the C name corresponding to tag values. But
unless such a need arises, it will probably be easier to just
forbid these collisions.

Some of these negative tests will be deleted later, and positive
tests added to qapi-schema-test.json in their place, when the
generator code is reworked to avoid particular code generation
collisions in class 2).

[Note that viewing this patch with git rename detection enabled
may see some confusion due to renaming some tests while adding
others, but where the content is similar enough that git picks
the wrong pre- and post-patch files to associate]

Signed-off-by: Eric Blake <eblake@redhat.com>
Message-Id: <1443565276-4535-6-git-send-email-eblake@redhat.com>
[Improve commit message and comments a bit, drop an unrelated test]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

show more ...

Merge remote-tracking branch 'remotes/armbru/tags/pull-qmp-2015-05-05' into staging

drop qapi nested structs

# gpg: Signature made Tue May 5 17:40:40 2015 BST using RSA key ID EB918653
# gpg: Good

Merge remote-tracking branch 'remotes/armbru/tags/pull-qmp-2015-05-05' into staging

drop qapi nested structs

# gpg: Signature made Tue May 5 17:40:40 2015 BST 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-qmp-2015-05-05: (40 commits)
qapi: Check for member name conflicts with a base class
qapi: Support (subset of) \u escapes in strings
qapi: Tweak doc references to QMP when QGA is also meant
qapi: Drop dead visitor code related to nested structs
qapi: Drop support for inline nested types
qapi: Drop inline nested structs in query-pci
qapi: Drop inline nested struct in query-version
qapi: Drop tests for inline nested structs
qapi: Merge UserDefTwo and UserDefNested in tests
qapi: Forbid 'type' in schema
qapi: Use 'struct' instead of 'type' in schema
qapi: Document 'struct' metatype
qapi: Prefer 'struct' over 'type' in generator
qapi: More rigorous checking for type safety bypass
qapi: Whitelist commands that don't return dictionary
qapi: Require valid names
qapi: More rigourous checking of types
qapi: Add some type check tests
qapi: Unify type bypass and add tests
qapi: Allow true, false and null in schema json
...

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

show more ...

qapi: Check for member name conflicts with a base class

Our type inheritance for both 'struct' and for flat 'union' merges
key/value pairs from the base class with those from the type in
question.

qapi: Check for member name conflicts with a base class

Our type inheritance for both 'struct' and for flat 'union' merges
key/value pairs from the base class with those from the type in
question. Although the C code currently boxes things so that there
is a distinction between which member is referred to, the QMP wire
format does not allow passing a key more than once in a single
object. Besides, if we ever change the generated C code to not be
quite so boxy, we'd want to avoid duplicate member names there,
too.

Fix a testsuite entry added in an earlier patch, as well as adding
a couple more tests to ensure we have appropriate coverage. Ensure
that collisions are detected, regardless of whether there is a
difference in opinion on whether the member name is optional.

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

show more ...