summaryrefslogtreecommitdiff
path: root/scripts/qapi.py
AgeCommit message (Collapse)AuthorFilesLines
2018-02-05qapi: ensure stable sort ordering when checking QAPI entitiesDaniel P. Berrange1-1/+1
Some early python 3.x versions will have different default ordering when calling the 'values()' method on a dict, compared to python 2.x and later 3.x versions. Explicitly sort the items to get a stable ordering. Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20180116134217.8725-8-berrange@redhat.com> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2018-02-05qapi: Adapt to moved location of 'maketrans' function in py3Daniel P. Berrange1-1/+4
Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20180116134217.8725-6-berrange@redhat.com> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2018-02-05qapi: adapt to moved location of StringIO module in py3Daniel P. Berrange1-2/+5
Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20180116134217.8725-5-berrange@redhat.com> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2018-02-05qapi: Use OrderedDict from standard library if availableDaniel P. Berrange1-1/+4
The OrderedDict class appeared in the 'collections' module from python 2.7 onwards, so use that in preference to our local backport if available. Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20180116134217.8725-4-berrange@redhat.com> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2018-02-05qapi: use items()/values() intead of iteritems()/itervalues()Daniel P. Berrange1-6/+6
The iteritems()/itervalues() methods are gone in py3, but the items()/values() methods are still around. The latter are less efficient than the former in py2, but this has unmeasurably small impact on QEMU build time, so taking portability over efficiency is a net win. Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20180116134217.8725-3-berrange@redhat.com> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2018-02-05qapi: convert to use python print function instead of statementDaniel P. Berrange1-6/+6
Python 3 no longer supports the bare "print" statement, it must be called as a normal function with round brackets. It is possible to opt-in to this new syntax with Python 2.6 onwards by importing the "print_function" from the "__future__" module, making it easy to support Python 2 and 3 in parallel. Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Signed-off-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <20180116134217.8725-2-berrange@redhat.com> Signed-off-by: Eduardo Habkost <ehabkost@redhat.com>
2017-12-20qapi: Rename QAPIDoc.parser, .section to ._parser, ._sectionMarkus Armbruster1-26/+26
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20171002141341.24616-11-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-12-20qapi: Simplify representation of QAPIDoc section textMarkus Armbruster1-10/+6
Use a string instead of a list of strings. This makes qapi2texi.py generate additional blank lines. They're harmless, and the next commit will get rid of them again. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20171002141341.24616-9-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-12-20qapi: Unify representation of doc section without nameMarkus Armbruster1-1/+1
We have two representations of sections without a name: the main section uses name=None, the others name=''. Standardize on name=None. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20171002141341.24616-8-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-12-20qapi: Make cur_doc local to QAPISchemaParser.__init__()Markus Armbruster1-17/+17
QAPISchemaParser.cur_doc is used only by .__init__() and its helper .reject_expr_doc(). Make it local to __init__() and pass it to .reject_expr_doc() explicitly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20171002141341.24616-5-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-12-20qapi: Eliminate QAPISchemaParser.__init__()'s local fnameMarkus Armbruster1-3/+2
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20171002141341.24616-4-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-12-20qapi: Stop rejecting #optionalMarkus Armbruster1-4/+0
Commit 1d8bda1 got rid of #optional tags, and added a check to keep them from getting added back, to make sure patches then in flight don't add them back. It's been six months, time to drop that check. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20171002141341.24616-3-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-09-04qapi: drop the sentinel in enum arrayMarc-André Lureau1-3/+1
Now that all usages have been converted to user lookup helpers. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170822132255.23945-14-marcandre.lureau@redhat.com> [Rebased, superfluous local variable dropped, missing check-qom-proplist.c update added] Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503564371-26090-17-git-send-email-armbru@redhat.com>
2017-09-04qapi: Change data type of the FOO_lookup generated for enum FOOMarc-André Lureau1-5/+8
Currently, a FOO_lookup is an array of strings terminated by a NULL sentinel. A future patch will generate enums with "holes". NULL-termination will cease to work then. To prepare for that, store the length in the FOO_lookup by wrapping it in a struct and adding a member for the length. The sentinel will be dropped next. Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20170822132255.23945-13-marcandre.lureau@redhat.com> [Basically redone] Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503564371-26090-16-git-send-email-armbru@redhat.com> [Rebased]
2017-09-04qapi: Generate FOO_str() macro for QAPI enum FOOMarkus Armbruster1-0/+3
The next commit will put it to use. May look pointless now, but we're going to change the FOO_lookup's type, and then it'll help. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1503564371-26090-13-git-send-email-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2017-09-01qapi: Fix error handling code on alternate conflictEduardo Habkost1-4/+4
The conflict check added by commit c0644771 ("qapi: Reject alternates that can't work with keyval_parse()") doesn't work with the following declaration: { 'alternate': 'Alt', 'data': { 'one': 'bool', 'two': 'str' } } It crashes with: Traceback (most recent call last): File "./scripts/qapi-types.py", line 295, in <module> schema = QAPISchema(input_file) File "/home/ehabkost/rh/proj/virt/qemu/scripts/qapi.py", line 1468, in __init__ self.exprs = check_exprs(parser.exprs) File "/home/ehabkost/rh/proj/virt/qemu/scripts/qapi.py", line 958, in check_exprs check_alternate(expr, info) File "/home/ehabkost/rh/proj/virt/qemu/scripts/qapi.py", line 830, in check_alternate % (name, key, types_seen[qtype])) KeyError: 'QTYPE_QSTRING' This happens because the previously-seen conflicting member ('one') can't be found at types_seen[qtype], but at types_seen['QTYPE_BOOL']. Fix the bug by moving the error check to the same loop that adds new items to types_seen, raising an exception if types_seen[qt] is already set. Add two additional test cases that can detect the bug. Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> Message-Id: <20170717180926.14924-1-ehabkost@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2017-07-24qapi: Introduce a first class 'null' typeMarkus Armbruster1-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>
2017-07-12scripts: use build_ prefix for string not piped through cgen()Marc-André Lureau1-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>
2017-06-20qapi: merge QInt and QFloat in QNumMarc-André Lureau1-19/+17
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>
2017-05-31qapi: Reject alternates that can't work with keyval_parse()Markus Armbruster1-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>
2017-03-21qapi: Drop unused QAPIDoc member optionalMarkus Armbruster1-1/+0
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>
2017-03-16qapi: Fix a misleading parser error messageMarkus Armbruster1-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>
2017-03-16qapi: Make pylint a bit happierMarkus Armbruster1-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>
2017-03-16qapi: Drop unused .check_clash() parameter schemaMarkus Armbruster1-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>
2017-03-16qapi: union_types is a list used like a dict, make it oneMarkus Armbruster1-16/+3
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>
2017-03-16qapi: struct_types is a list used like a dict, make it oneMarkus Armbruster1-17/+4
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>
2017-03-16qapi: enum_types is a list used like a dict, make it oneMarkus Armbruster1-23/+6
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>
2017-03-16qapi: Factor add_name() calls out of the meta conditionalMarkus Armbruster1-15/+9
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>
2017-03-16qapi: Simplify what gets stored in enum_typesMarkus Armbruster1-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>
2017-03-16qapi: Drop unused variable eventsMarkus Armbruster1-3/+0
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>
2017-03-16qapi: Eliminate check_docs() and drop QAPIDoc.exprMarkus Armbruster1-17/+10
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>
2017-03-16qapi: Fix detection of bogus member documentationMarkus Armbruster1-25/+13
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>
2017-03-16qapi: Move empty doc section checking to doc parserMarkus Armbruster1-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>
2017-03-16qapi: Improve error message on @NAME: in free-form docMarkus Armbruster1-11/+6
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>
2017-03-16qapi: Move detection of doc / expression name mismatchMarkus Armbruster1-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>
2017-03-16qapi: Fix detection of doc / expression mismatchMarkus Armbruster1-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>
2017-03-16qapi2texi: Include member type in generated documentationMarkus Armbruster1-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>
2017-03-16qapi: Prefer single-quoted strings more consistentlyMarkus Armbruster1-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>
2017-03-16qapi: Use raw strings for regular expressions consistentlyMarkus Armbruster1-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>
2017-03-16qapi: The #optional tag is redundant, dropMarkus Armbruster1-19/+4
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>
2017-03-16qapi: Conjure up QAPIDoc.ArgSection for undocumented membersMarkus Armbruster1-3/+2
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>
2017-03-16qapi: Prepare for requiring more complete documentationMarkus Armbruster1-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>
2017-03-16qapi: Fix QAPISchemaEnumType.is_implicit() for 'QType'Markus Armbruster1-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>
2017-03-16qapi: Avoid unwanted blank lines in QAPIDocMarkus Armbruster1-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>
2017-03-16qapi: Fix to reject empty union base gracefullyMarkus Armbruster1-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>
2017-03-16qapi: Have each QAPI schema declare its name rule violationsMarkus Armbruster1-12/+10
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>
2017-03-16qapi: Have each QAPI schema declare its returns white-listMarkus Armbruster1-21/+9
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>
2017-03-16qapi: Make doc comments optional where we don't need themMarkus Armbruster1-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>
2017-03-16qapi: Factor QAPISchemaParser._include() out of .__init__()Markus Armbruster1-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>
2017-01-16qapi: add qapi2texi scriptMarc-André Lureau1-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>
generated by cgit v1.2.1 (git 2.18.0) at 2024-07-09 08:59:41 +0000