riscv/qemu - qemu - Gitea: Git with a cup of tea

Author	SHA1	Message	Date
Markus Armbruster	87c16dceca	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>	9 years ago
Marc-André Lureau	3313b6124b	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>	9 years ago
Eric Blake	59a92feedc	qapi: Tighten the regex on valid names We already documented that qapi names should match specific patterns (such as starting with a letter unless it was an enum value or a downstream extension). Tighten that from a suggestion into a hard requirement, which frees up names beginning with a single underscore for qapi internal usage. The tighter regex doesn't forbid everything insane that a user could provide (for example, a user could name a type 'Foo-lookup' to collide with the generated 'Foo_lookup[]' for an enum 'Foo'), but does a good job at protecting the most obvious uses, and also happens to reserve single leading underscore for later use. The handling of enum values starting with a digit is tricky: commit `9fb081e` introduced a subtle bug by using c_name() on a munged value, which would allow an enum to include the member 'q-int' in spite of our reservation. Furthermore, munging with a leading '_' would fail our tighter regex. So fix it by only munging for leading digits (which are never ticklish in c_name()) and by using a different prefix (I picked 'D', although any letter should do). Add new tests, reserved-member-underscore and reserved-enum-q, to demonstrate the tighter checking. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1447836791-369-22-git-send-email-eblake@redhat.com> Message-Id: <1447883135-18020-1-git-send-email-eblake@redhat.com> [Eric's fixup squashed in] Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago
Eric Blake	9fb081e0b9	qapi: Reserve 'q_' and 'has_' member names c_name() produces names starting with 'q_' when protecting a dictionary member name that would fail to directly compile, but in doing so can cause clashes with any member name already beginning with 'q-' or 'q_'. Likewise, we create a C name 'has_' for any optional member that can clash with any member name beginning with 'has-' or 'has_'. Technically, rather than blindly reserving the namespace, we could try to complain about user names only when an actual collision occurs, or even teach c_name() how to munge names to avoid collisions. But it is not trivial, especially when collisions can occur across multiple types (such as via inheritance or flat unions). Besides, no existing .json files are trying to use these names. So it's easier to just outright forbid the potential for collision. We can always relax things in the future if a real need arises for QMP to express member names that have been forbidden here. 'has_' only has to be reserved for struct/union member names, while 'q_' is reserved everywhere (matching the fact that only members can be optional, while we use c_name() for munging both members and entities). Note that we could relax 'q_' restrictions on entities independently from member names; for example, c_name('qmp_' + 'unix') would result in a different function name than our current 'qmp_' + c_name('unix'). Update and add tests to cover the new error messages. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1445898903-12082-6-git-send-email-eblake@redhat.com> [Consistently pass protect=False to c_name(); commit message tweaked slightly] Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago
Eric Blake	1976708321	tests/qapi-schema: Test for reserved names, empty struct Add some testsuite coverage to ensure future patches are on the right track: Our current C representation of qapi arrays is done by appending 'List' to the element name; but we are not preventing the creation of an object type with the same name. Add reserved-type-list.json to test this. Then rename enum-union-clash.json to reserved-type-kind.json to cover the reservation that we DO detect, and shorten it to match the fact that the name is reserved even if there is no clash. We are failing to detect a collision between a dictionary member and the implicit 'has_*' flag for another optional member. The easiest fix would be for a future patch to reserve the entire "has[-_]" namespace for member names (the collision is also possible for branch names within flat unions, but only as long as branch names can collide with (non-variant) members; however, since future patches are about to remove that, it is not worth testing here). Add reserved-member-has.json to test this. A similar collision exists between a dictionary member where c_name() munges what might otherwise be a reserved name to start with 'q_', and another member explicitly starts with "q[-_]". Again, the easiest solution for a future patch will be reserving the entire namespace, but here for commands as well as members. Add reserved-member-q.json and reserved-command-q.json to test this; separate tests since arguably our munging of command 'unix' to 'qmp_q_unix()' could be done without a q_, which is different than the munging of a member 'unix' to 'foo.q_unix'. Finally, our testsuite does not have any compilation coverage of struct inheritance with empty qapi structs. Update qapi-schema-test.json to test this. Note that there is currently no technical reason to forbid type name patterns from member names, or member name patterns from types, since the two are not in the same namespace in C and won't collide; but it's not worth adding positive tests of these corner cases at this time, especially while there is other churn pending in patches that rearrange which collisions actually happen. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1445898903-12082-2-git-send-email-eblake@redhat.com> [Commit message tweaked slightly] Signed-off-by: Markus Armbruster <armbru@redhat.com>	11 years ago