summaryrefslogtreecommitdiffstats
path: root/scripts/qapi.py
Commit message (Collapse)AuthorAgeFilesLines
* qapi: Introduce a first class 'null' typeMarkus Armbruster2017-07-241-1/+4
| | | | | | | | | | I expect the 'null' type to be useful mostly for members of alternate types. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* scripts: use build_ prefix for string not piped through cgen()Marc-André Lureau2017-07-121-1/+1
| | | | | | | | | | | | | | | | The gen_ prefix is awkward. Generated C should go through cgen() exactly once (see commit 1f9a7a1). The common way to get this wrong is passing a foo=gen_foo() keyword argument to mcgen(). I'd like us to adopt a naming convention where gen_ means "something that's been piped through cgen(), and thus must not be passed to cgen() or mcgen()". Requires renaming gen_params(), gen_marshal_proto() and gen_event_send_proto(). Suggested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170601124143.10915-1-marcandre.lureau@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: merge QInt and QFloat in QNumMarc-André Lureau2017-06-201-19/+17Star
| | | | | | | | | | | | | | | We would like to use a same QObject type to represent numbers, whether they are int, uint, or floats. Getters will allow some compatibility between the various types if the number fits other representations. Add a few more tests while at it. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170607163635.17635-7-marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [parse_stats_intervals() simplified a bit, comment in test_visitor_in_int_overflow() tidied up, suppress bogus warnings] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Reject alternates that can't work with keyval_parse()Markus Armbruster2017-05-311-2/+17
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Alternates are sum types like unions, but use the JSON type on the wire / QType in QObject instead of an explicit tag. That's why we require alternate members to have distinct QTypes. The recently introduced keyval_parse() (commit d454dbe) can only produce string scalars. The qobject_input_visitor_new_keyval() input visitor mostly hides the difference, so code using a QObject input visitor doesn't have to care whether its input was parsed from JSON or KEY=VALUE,... The difference leaks for alternates, as noted in commit 0ee9ae7: a non-string, non-enum scalar alternate value can't currently be expressed. In part, this is just our insufficiently sophisticated implementation. Consider alternate type 'GuestFileWhence'. It has an integer member and a 'QGASeek' member. The latter is an enumeration with values 'set', 'cur', 'end'. The meaning of b=set, b=cur, b=end, b=0, b=1 and so forth is perfectly obvious. However, our current implementation falls apart at run time for b=0, b=1, and so forth. Fixable, but not today; add a test case and a TODO comment. Now consider an alternate type with a string and an integer member. What's the meaning of a=42? Is it the string "42" or the integer 42? Whichever meaning you pick makes the other inexpressible. This isn't just an implementation problem, it's fundamental. Our current implementation will pick string. So far, we haven't needed such alternates. To make sure we stop and think before we add one that cannot sanely work with keyval_parse(), let's require alternate members to have sufficiently distinct representation in KEY=VALUE,... syntax: * A string member clashes with any other scalar member * An enumeration member clashes with bool members when it has value 'on' or 'off'. * An enumeration member clashes with numeric members when it has a value that starts with '-', '+', or a decimal digit. This is a rather lazy approximation of the actual number syntax accepted by the visitor. Note that enumeration values starting with '-' and '+' are rejected elsewhere already, but better safe than sorry. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1495471335-23707-5-git-send-email-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
* qapi: Drop unused QAPIDoc member optionalMarkus Armbruster2017-03-211-1/+0Star
| | | | | | | | Unused since commit aa964b7 "qapi2texi: Convert to QAPISchemaVisitor" Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1490015515-25851-4-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
* qapi: Fix a misleading parser error messageMarkus Armbruster2017-03-161-1/+2
| | | | | | | | | | | | When choking on a token where an expression is expected, we report 'Expected "{", "[" or string'. Close, but no cigar. Fix it to Expected '"{", "[", string, boolean or "null"'. Missed in commit e53188a. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-48-git-send-email-armbru@redhat.com>
* qapi: Make pylint a bit happierMarkus Armbruster2017-03-161-4/+4
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-47-git-send-email-armbru@redhat.com>
* qapi: Drop unused .check_clash() parameter schemaMarkus Armbruster2017-03-161-5/+5
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-46-git-send-email-armbru@redhat.com>
* qapi: union_types is a list used like a dict, make it oneMarkus Armbruster2017-03-161-16/+3Star
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-45-git-send-email-armbru@redhat.com>
* qapi: struct_types is a list used like a dict, make it oneMarkus Armbruster2017-03-161-17/+4Star
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-44-git-send-email-armbru@redhat.com>
* qapi: enum_types is a list used like a dict, make it oneMarkus Armbruster2017-03-161-23/+6Star
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-43-git-send-email-armbru@redhat.com>
* qapi: Factor add_name() calls out of the meta conditionalMarkus Armbruster2017-03-161-15/+9Star
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-42-git-send-email-armbru@redhat.com>
* qapi: Simplify what gets stored in enum_typesMarkus Armbruster2017-03-161-14/+15
| | | | | | | | | | Don't invent a new dictionary structure just for enum_types, simply store the defining expression, like we do for struct_types and union_types. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-41-git-send-email-armbru@redhat.com>
* qapi: Drop unused variable eventsMarkus Armbruster2017-03-161-3/+0Star
| | | | | | | | Missed in commit e98859a Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-40-git-send-email-armbru@redhat.com>
* qapi: Eliminate check_docs() and drop QAPIDoc.exprMarkus Armbruster2017-03-161-17/+10Star
| | | | | | | | | | | Move what's left in check_docs() to check_expr(). Delegate the actual checking to new QAPIDoc.check_expr(). QAPIDoc.expr is now unused; drop it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-39-git-send-email-armbru@redhat.com>
* qapi: Fix detection of bogus member documentationMarkus Armbruster2017-03-161-25/+13Star
| | | | | | | | | | | | | check_definition_doc() checks for member documentation without a matching member. It laboriously second-guesses what members QAPISchema._def_exprs() will create. That's a stupid game. Move the check into QAPISchema.check(), where the members are known. Delegate the actual checking to new QAPIDoc.check(). Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-38-git-send-email-armbru@redhat.com>
* qapi: Move empty doc section checking to doc parserMarkus Armbruster2017-03-161-6/+14
| | | | | | | | | Results in a more precise error location, but the real reason is emptying out check_docs() step by step. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-35-git-send-email-armbru@redhat.com>
* qapi: Improve error message on @NAME: in free-form docMarkus Armbruster2017-03-161-11/+6Star
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-34-git-send-email-armbru@redhat.com>
* qapi: Move detection of doc / expression name mismatchMarkus Armbruster2017-03-161-10/+18
| | | | | | | | | | | | | Move the check whether the doc matches the expression name from check_definition_doc() to check_exprs(). This changes the error location from the comment to the expression. Makes sense as the message talks about the expression: "Definition of '%s' follows documentation for '%s'". It's also a step towards getting rid of check_docs(). Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-33-git-send-email-armbru@redhat.com>
* qapi: Fix detection of doc / expression mismatchMarkus Armbruster2017-03-161-13/+22
| | | | | | | | This fixes the errors uncovered by the previous commit. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-32-git-send-email-armbru@redhat.com>
* qapi2texi: Include member type in generated documentationMarkus Armbruster2017-03-161-0/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | The recent merge of docs/qmp-commands.txt and docs/qmp-events.txt into the schema lost type information. Fix this documentation regression. Example change (qemu-qmp-ref.txt): -- Struct: InputKeyEvent Keyboard input event. Members: - 'button' + 'button: InputButton' Which button this event is for. - 'down' + 'down: boolean' True for key-down and false for key-up events. Since: 2.0 Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-26-git-send-email-armbru@redhat.com>
* qapi: Prefer single-quoted strings more consistentlyMarkus Armbruster2017-03-161-48/+48
| | | | | | | | | | | | | | | | | PEP 8 advises: In Python, single-quoted strings and double-quoted strings are the same. This PEP does not make a recommendation for this. Pick a rule and stick to it. When a string contains single or double quote characters, however, use the other one to avoid backslashes in the string. It improves readability. The QAPI generators succeed at picking a rule, but fail at sticking to it. Convert a bunch of double-quoted strings to single-quoted ones. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-20-git-send-email-armbru@redhat.com>
* qapi: Use raw strings for regular expressions consistentlyMarkus Armbruster2017-03-161-4/+4
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-19-git-send-email-armbru@redhat.com>
* qapi: The #optional tag is redundant, dropMarkus Armbruster2017-03-161-19/+4Star
| | | | | | | | | | | | | | | | | | | | | | | | | We traditionally mark optional members #optional in the doc comment. Before commit 3313b61, this was entirely manual. Commit 3313b61 added some automation because its qapi2texi.py relied on #optional to determine whether a member is optional. This is no longer the case since the previous commit: the only thing qapi2texi.py still does with #optional is stripping it out. We still reject bogus qapi-schema.json and six places for qga/qapi-schema.json. Thus, you can't actually rely on #optional to see whether something is optional. Yet we still make people add it manually. That's just busy-work. Drop the code to check, fix up and strip out #optional, along with all instances of #optional. To keep it out, add code to reject it, to be dropped again once the dust settles. No change to generated documentation. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com>
* qapi: Conjure up QAPIDoc.ArgSection for undocumented membersMarkus Armbruster2017-03-161-3/+2Star
| | | | | | | | | | | | | qapi2texi.py already conjures up ArgSections for undocumented enumeration values, in texi_enum. Drop that, and conjure them up for all kinds of "arguments" (enumeration values, object and alternate type members) in qapi.py instead. Take care to keep generated documentation exactly the same for now. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-16-git-send-email-armbru@redhat.com>
* qapi: Prepare for requiring more complete documentationMarkus Armbruster2017-03-161-45/+65
| | | | | | | | | | | | | | We currently neglect to check all enumeration values, common members of object types and members of alternate types are documented. Unsurprisingly, many aren't. Add the necessary plumbing to find undocumented ones, except for variant members of object types. Don't enforce anything just yet, but connect each QAPIDoc.ArgSection to its QAPISchemaMember. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-15-git-send-email-armbru@redhat.com>
* qapi: Fix QAPISchemaEnumType.is_implicit() for 'QType'Markus Armbruster2017-03-161-2/+2
| | | | | | | | | Missed in commit 7264f5c. Harmless, because nothing checks whether an enumeration type is implicit so far. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-14-git-send-email-armbru@redhat.com>
* qapi: Avoid unwanted blank lines in QAPIDocMarkus Armbruster2017-03-161-2/+3
| | | | | | | | | | | | | | | | | We silently fix missing #optional tags for QAPIDoc by appending a line "#optional" to the section's .content. However, this interferes with .__repr__ stripping trailing blank lines from .content. Use new ArgSection instance variable .optional instead, and leave .content alone. To permit testing .optional in texi_body(), clean up texi_enum()'s hack to add empty documentation for undocumented enum values: add an ArgSection instead of ''. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <1489582656-31133-12-git-send-email-armbru@redhat.com>
* qapi: Fix to reject empty union base gracefullyMarkus Armbruster2017-03-161-1/+1
| | | | | | | | | | Common Python pitfall: 'assert base_members' fires on [] in addition to None. Correct to 'assert base_members is not None'. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1489582656-31133-10-git-send-email-armbru@redhat.com>
* qapi: Have each QAPI schema declare its name rule violationsMarkus Armbruster2017-03-161-12/+10Star
| | | | | | | | | | | qapi.py has a hardcoded white-list of type names that may violate the rule on use of upper and lower case. Add a new pragma directive 'name-case-whitelist', and use it to replace the hard-coded white-list. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1489582656-31133-7-git-send-email-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Have each QAPI schema declare its returns white-listMarkus Armbruster2017-03-161-21/+9Star
| | | | | | | | | | qapi.py has a hardcoded white-list of command names that may violate the rules on permitted return types. Add a new pragma directive 'returns-whitelist', and use it to replace the hard-coded white-list. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1489582656-31133-6-git-send-email-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Make doc comments optional where we don't need themMarkus Armbruster2017-03-161-1/+23
| | | | | | | | | | | | | | | | | | | | | | | | | | | Since we added the documentation generator in commit 3313b61, doc comments are mandatory. That's a very good idea for a schema that needs to be documented, but has proven to be annoying for testing. Make doc comments optional again, but add a new directive { 'pragma': { 'doc-required': true } } to let a QAPI schema require them. Add test cases for the new pragma directive. While there, plug a minor hole in includ directive test coverage. Require documentation in the schemas we actually want documented: qapi-schema.json and qga/qapi-schema.json. We could probably make qapi2texi.py cope with incomplete documentation, but for now, simply make it refuse to run unless the schema has 'doc-required': true. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1489582656-31133-3-git-send-email-armbru@redhat.com> [qapi-code-gen.txt wording tweaked] Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Factor QAPISchemaParser._include() out of .__init__()Markus Armbruster2017-03-161-22/+23
| | | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <1489582656-31133-2-git-send-email-armbru@redhat.com>
* qapi: add qapi2texi scriptMarc-André Lureau2017-01-161-2/+249
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: rework qapi ExceptionMarc-André Lureau2017-01-161-178/+156Star
| | | | | | | | | | Use a base class QAPIError, and QAPIParseError for parser errors and QAPISemError for semantic errors, suggested by Markus Armbruster. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20170113144135.5150-12-marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Implement boxed types for commands/eventsEric Blake2016-07-191-13/+50
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Turn on the ability to pass command and event arguments in a single boxed parameter, which must name a non-empty type (although the type can be a struct with all optional members). For structs, it makes it possible to pass a single qapi type instead of a breakout of all struct members (useful if the arguments are already in a struct or if the number of members is large); for other complex types, it is now possible to use a union or alternate as the data for a command or event. The empty type may be technically feasible if needed down the road, but it's easier to forbid it now and relax things to allow it later, than it is to allow it now and have to special case how the generated 'q_empty' type is handled (see commit 7ce106a9 for reasons why nothing is generated for the empty type). An alternate type is never considered empty, but now that a boxed type can be either an object or an alternate, we have to provide a trivial QAPISchemaAlternateType.is_empty(). The new call to arg_type.is_empty() during QAPISchemaCommand.check() requires that we first check the type in question; but there is no chance of introducing a cycle since objects do not refer back to commands. We still have a split in syntax checking between ad-hoc parsing up front (merely validates that 'boxed' has a sane value) and during .check() methods (if 'boxed' is set, then 'data' must name a non-empty user-defined type). Generated code is unchanged, as long as no client uses the new feature. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-10-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Test files renamed to *-boxed-*] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Plumb in 'boxed' to qapi generator lower levelsEric Blake2016-07-191-16/+27
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | The next patch will add support for passing a qapi union type as the 'data' of a command. But to do that, the user function for implementing the command, as called by the generated marshal command, must take the corresponding C struct as a single boxed pointer, rather than a breakdown into one parameter per member. Even without a union, being able to use a C struct rather than a list of parameters can make it much easier to handle coding with QAPI. This patch adds the internal plumbing of a 'boxed' flag associated with each command and event. In several cases, this means adding indentation, with one new dead branch and the remaining branch being the original code more deeply nested; this was done so that the new implementation in the next patch is easier to review without also being mixed with indentation changes. For this patch, no behavior or generated output changes, other than the testsuite outputting the value of the new flag (always False for now). Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-9-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Identifier box renamed to boxed in two places] Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Drop useless gen_err_check()Eric Blake2016-07-191-8/+0Star
| | | | | | | | | | | | | | Ever since commit 12f254f removed the last parameterization of gen_err_check(), it no longer makes sense to hide the three lines of generated C code behind a macro call. Just inline it into the remaining users. No change to generated code. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-7-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Add type.is_empty() helperEric Blake2016-07-191-0/+4
| | | | | | | | | | | | | | | | | | | | | | In the near future, we want to lift our artificial restriction of no variants at the top level of an event, at which point the currently open-coded check for empty members will become insufficient. Factor it out into a new helper method is_empty() now, and future-proof it by checking variants, too, along with an assert that it is not used prior to the completion of .check(). Update places that were checking for (non-)empty .members to use the new helper. All of the current callers assert that there are no variants (either directly, or by qapi.py asserting that base types have no variants), so this is not a semantic change. No change to generated code. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-6-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Hide tag_name data member of variantsEric Blake2016-07-191-4/+4
| | | | | | | | | | | | | | Clean up the only remaining external use of the tag_name field of QAPISchemaObjectTypeVariants, by explicitly listing the generated 'type' tag for all variants in the testsuite (you can still tell simple unions by the -wrapper types). Then we can mark the tag_name field as private by adding a leading underscore to prevent any further use. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-5-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Special case c_name() for empty typeEric Blake2016-07-191-0/+1
| | | | | | | | | | | | | | | | Commit 7ce106a rendered QAPISchemaObjectType.c_name() redundant, since it now does nothing more than delegate to its superclass. However, rather than deleting it, we can restore part of the assertion that was removed in that commit, to prove that we never emit the empty type directly in generated code, but rather special-case it as a built-in that makes other aspects of code generation easier to reason about. Reported-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-4-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Require all branches of flat union enum to be coveredEric Blake2016-07-191-0/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | We were previously enforcing that all flat union branches were found in the corresponding enum, but not that all enum values were covered by branches. The resulting generated code would abort() if the user passes the uncovered enum value. We don't automatically treat non-present branches in a flat union as empty types, for symmetry with simple unions (there, the enum type is generated from the list of all branches, so there is no way to omit a branch but still have it be part of the union). A later patch will add shorthand so that branches that are empty in flat unions can be declared as 'branch':{} instead of 'branch':'Empty', to avoid the need for an otherwise useless explicit empty type. [Such shorthand for simple unions is a bit harder to justify, since we would still have to generate a wrapper type that parses 'data':{}, rather than truly being an empty branch with no additional siblings to the 'type' member.] Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1468468228-27827-3-git-send-email-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Use anonymous bases in QMP flat unionsEric Blake2016-03-181-1/+1
| | | | | | | | | | | | | | | | | | | Now that the generator supports it, we might as well use an anonymous base rather than breaking out a single-use Base structure, for all three of our current QMP flat unions. Oddly enough, this change does not affect the resulting introspection output (because we already inline the members of a base type into an object, and had no independent use of the base type reachable from a command). The case_whitelist now has to list the name of an implicit type; which is not too bad (consider it a feature if it makes it harder for developers to make the whitelist grow :) Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-16-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Allow anonymous base for flat unionEric Blake2016-03-181-2/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | Rather than requiring all flat unions to explicitly create a separate base struct, we can allow the qapi schema to specify the common members via an inline dictionary. This is similar to how commands can specify an inline anonymous type for its 'data'. We already have several struct types that only exist to serve as a single flat union's base; the next commit will clean them up. In particular, this patch's change to the BlockdevOptions example in qapi-code-gen.txt will actually be done in the real QAPI schema. Now that anonymous bases are legal, we need to rework the flat-union-bad-base negative test (as previously written, it forms what is now valid QAPI; tweak it to now provide coverage of a new error message path), and add a positive test in qapi-schema-test to use an anonymous base (making the integer argument optional, for even more coverage). Note that this patch only allows anonymous bases for flat unions; simple unions are already enough syntactic sugar that we do not want to burden them further. Meanwhile, while it would be easy to also allow an anonymous base for structs, that would be quite redundant, as the members can be put right into the struct instead. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-15-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Don't special-case simple union wrappersEric Blake2016-03-181-10/+0Star
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Simple unions were carrying a special case that hid their 'data' QMP member from the resulting C struct, via the hack method QAPISchemaObjectTypeVariant.simple_union_type(). But by using the work we started by unboxing flat union and alternate branches, coupled with the ability to visit the members of an implicit type, we can now expose the simple union's implicit type in qapi-types.h: | struct q_obj_ImageInfoSpecificQCow2_wrapper { | ImageInfoSpecificQCow2 *data; | }; | | struct q_obj_ImageInfoSpecificVmdk_wrapper { | ImageInfoSpecificVmdk *data; | }; ... | struct ImageInfoSpecific { | ImageInfoSpecificKind type; | union { /* union tag is @type */ | void *data; |- ImageInfoSpecificQCow2 *qcow2; |- ImageInfoSpecificVmdk *vmdk; |+ q_obj_ImageInfoSpecificQCow2_wrapper qcow2; |+ q_obj_ImageInfoSpecificVmdk_wrapper vmdk; | } u; | }; Doing this removes asymmetry between QAPI's QMP side and its C side (both sides now expose 'data'), and means that the treatment of a simple union as sugar for a flat union is now equivalent in both languages (previously the two approaches used a different layer of dereferencing, where the simple union could be converted to a flat union with equivalent C layout but different {} on the wire, or to an equivalent QMP wire form but with different C representation). Using the implicit type also lets us get rid of the simple_union_type() hack. Of course, now all clients of simple unions have to adjust from using su->u.member to using su->u.member.data; while this touches a number of files in the tree, some earlier cleanup patches helped minimize the change to the initialization of a temporary variable rather than every single member access. The generated qapi-visit.c code is also affected by the layout change: |@@ -7393,10 +7393,10 @@ void visit_type_ImageInfoSpecific_member | } | switch (obj->type) { | case IMAGE_INFO_SPECIFIC_KIND_QCOW2: |- visit_type_ImageInfoSpecificQCow2(v, "data", &obj->u.qcow2, &err); |+ visit_type_q_obj_ImageInfoSpecificQCow2_wrapper_members(v, &obj->u.qcow2, &err); | break; | case IMAGE_INFO_SPECIFIC_KIND_VMDK: |- visit_type_ImageInfoSpecificVmdk(v, "data", &obj->u.vmdk, &err); |+ visit_type_q_obj_ImageInfoSpecificVmdk_wrapper_members(v, &obj->u.vmdk, &err); | break; | default: | abort(); Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-13-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Drop unused c_null()Eric Blake2016-03-181-29/+17Star
| | | | | | | | | | | | Now that we are always bulk-initializing a QAPI C struct to 0 (whether by g_malloc0() or by 'Type arg = {0};'), we no longer have any clients of c_null() in the generator for per-element initialization. This patch is easy enough to revert if we find a use in the future, but in the present, get rid of the dead code. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-12-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Inline gen_visit_members() into lone callerEric Blake2016-03-181-44/+2Star
| | | | | | | | | | | | | | | | | | | | | Commit 82ca8e46 noticed that we had multiple implementations of visiting every member of a struct, and consolidated it into gen_visit_fields() (now gen_visit_members()) with enough parameters to cater to slight differences between the clients. But recent exposure of implicit types has meant that we are now down to a single use of that method, so we can clean up the unused conditionals and just inline it into the remaining caller: gen_visit_object_members(). Likewise, gen_err_check() no longer needs optional parameters, as the lone use of non-defaults was via gen_visit_members(). No change to generated code. Suggested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-11-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Emit implicit structs in generated CEric Blake2016-03-181-2/+0Star
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We already have several places that want to visit all the members of an implicit object within a larger context (simple union variant, event with anonymous data, command with anonymous arguments struct); and will be adding another one soon (the ability to declare an anonymous base for a flat union). Having a C struct declared for these implicit types, along with a visit_type_FOO_members() helper function, will make for fewer special cases in our generator. We do not, however, need qapi_free_FOO() or visit_type_FOO() functions for implicit types, because they should not be used directly outside of the generated code. This is done by adding a conditional in visit_object_type() for both qapi-types.py and qapi-visit.py based on the object name. The comparison of "name.startswith('q_')" is a bit hacky (it's basically duplicating what .is_implicit() already uses), but beats changing the signature of the visit_object_type() callback to pass a new 'implicit' flag. The hack should be temporary: we are considering adding a future patch that consolidates the narrow visit_object_type(..., base, local_members, variants) and visit_object_type_flat(..., all_members, variants) [where different sets of information are already broken out, and the QAPISchemaObjectType is no longer available] into a broader visit_object_type(obj_type) [where the visitor can query the needed fields from obj_type directly]. Also, now that we WANT to output C code for implicits, we no longer need the visit_needed() filter, leaving 'q_empty' as the only object still needing a special case. Remember, 'q_empty' is the only built-in generated object, which means that without a special case it would be emitted in multiple files (the main qapi-types.h and in qga-qapi-types.h) causing compilation failure due to redefinition. But since it has no members, it's easier to just avoid an attempt to visit that particular type; since gen_object() is called recursively, we also prime the objects_seen set to cover any recursion into the empty type. The patch relies on the changed naming of implicit types in the previous patch. It is a bit unfortunate that the generated struct names and visit_type_FOO_members() don't match normal naming conventions, but it's not too bad, since they will only be used in generated code. The generated code grows substantially in size: the implicit '-wrapper' types must be emitted in qapi-types.h before any union can include an unboxed member of that type. Arguably, the '-args' types could be emitted in a private header for just qapi-visit.c and qmp-marshal.c, rather than polluting qapi-types.h; but adding complexity to the generator to split the output location according to role doesn't seem worth the maintenance costs. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-6-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Adjust names of implicit typesEric Blake2016-03-181-8/+10
| | | | | | | | | | | | | | | | | | | | | | | | | | The original choice of ':obj-' as the prefix for implicit types made it obvious that we weren't going to clash with any user-defined names, which cannot contain ':'. But now we want to create structs for implicit types, to get rid of special cases in the generators, and our use of ':' in implicit names needs a tweak to produce valid C code. We could transliterate ':' to '_', except that C99 mandates that "identifiers that begin with an underscore are always reserved for use as identifiers with file scope in both the ordinary and tag name spaces". So it's time to change our naming convention: we can instead use the 'q_' prefix that we reserved for ourselves back in commit 9fb081e0. Technically, since we aren't planning on exposing the empty type in generated code, we could keep the name ':empty', but renaming it to 'q_empty' makes the check for startswith('q_') cover all implicit types, whether or not code is generated for them. As long as we don't declare 'empty' or 'obj' ticklish, it shouldn't clash with c_name() prepending 'q_' to the user's ticklish names. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-5-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Make c_type() more OO-likeEric Blake2016-03-181-9/+30
| | | | | | | | | | | | | | | | | | | | | | | | | | QAPISchemaType.c_type() is a bit awkward: it takes two optional boolean flags is_param and is_unboxed, and they should never both be True. Add a new method for each of the flags, and drop the flags from c_type(). Most callers pass no flags; they remain unchanged. One caller passes is_param=True; call the new .c_param_type() instead. One caller passes is_unboxed=True, except for simple union types. This is actually an ugly special case that will go away soon, so until then, we now have to call either .c_type() or the new .c_unboxed_type(). Tolerable in the interim. It requires slightly more Python, but is arguably easier to read. Suggested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1458254921-17042-4-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
generated by cgit v1.2.3-55-g7522 (git 2.39.0) at 2024-12-22 21:01:05 +0100