summaryrefslogtreecommitdiffstats
path: root/docs/qapi-code-gen.txt
Commit message (Collapse)AuthorAgeFilesLines
* qapi: Reserve 'q_*' and 'has_*' member namesEric Blake2015-11-021-4/+7
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 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>
* qapi: Reserve '*List' type names for list typesEric Blake2015-11-021-1/+2
| | | | | | | | | | | | | | | Type names ending in 'List' can clash with qapi list types in generated C. We don't currently use such names. It is easier to outlaw them now than to worry about how to resolve such a clash in the future. For precedence, see commit 4dc2e69, which did the same for names ending in 'Kind' versus implicit enum types for qapi unions. Update the testsuite to match. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1445898903-12082-5-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Consistent generated code: prefer visitor 'v'Eric Blake2015-10-121-37/+37
| | | | | | | | | | | | | | | | | We had some pointless differences in the generated code for visit, command marshalling, and events; unifying them makes it easier for future patches to consolidate to common helper functions. This is one patch of a series to clean up these differences. This patch names the local visitor variable 'v' rather than 'm'. Related objects, such as 'QapiDeallocVisitor', are also named by their initials instead of an unrelated leading m. No change in semantics to the generated code. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1443565276-4535-12-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Consistent generated code: prefer error 'err'Eric Blake2015-10-121-14/+14
| | | | | | | | | | | | | | | | We had some pointless differences in the generated code for visit, command marshalling, and events; unifying them makes it easier for future patches to consolidate to common helper functions. This is one patch of a series to clean up these differences. This patch consistently names the local error variable 'err' rather than 'local_err'. No change in semantics to the generated code. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <1443565276-4535-11-git-send-email-eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi-introspect: Hide type namesMarkus Armbruster2015-09-211-19/+17
| | | | | | | | | | | | | To eliminate the temptation for clients to look up types by name (which are not ABI), replace all type names by meaningless strings. Reduces output of query-schema by 13 out of 85KiB. As a debugging aid, provide option -u to suppress the hiding. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <1442401589-24189-27-git-send-email-armbru@redhat.com>
* qapi: New QMP command query-qmp-schema for QMP introspectionMarkus Armbruster2015-09-211-5/+232
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | qapi/introspect.json defines the introspection schema. It's designed for QMP introspection, but should do for similar uses, such as QGA. The introspection schema does not reflect all the rules and restrictions that apply to QAPI schemata. A valid QAPI schema has an introspection value conforming to the introspection schema, but the converse is not true. Introspection lowers away a number of schema details, and makes implicit things explicit: * The built-in types are declared with their JSON type. All integer types are mapped to 'int', because how many bits we use internally is an implementation detail. It could be pressed into external interface service as very approximate range information, but that's a bad idea. If we need range information, we better do it properly. * Implicit type definitions are made explicit, and given auto-generated names: - Array types, named by appending "List" to the name of their element type, like in generated C. - The enumeration types implicitly defined by simple union types, named by appending "Kind" to the name of their simple union type, like in generated C. - Types that don't occur in generated C. Their names start with ':' so they don't clash with the user's names. * All type references are by name. * The struct and union types are generalized into an object type. * Base types are flattened. * Commands take a single argument and return a single result. Dictionary argument or list result is an implicit type definition. The empty object type is used when a command takes no arguments or produces no results. The argument is always of object type, but the introspection schema doesn't reflect that. The 'gen': false directive is omitted as implementation detail. The 'success-response' directive is omitted as well for now, even though it's not an implementation detail, because it's not used by QMP. * Events carry a single data value. Implicit type definition and empty object type use, just like for commands. The value is of object type, but the introspection schema doesn't reflect that. * Types not used by commands or events are omitted. Indirect use counts as use. * Optional members have a default, which can only be null right now Instead of a mandatory "optional" flag, we have an optional default. No default means mandatory, default null means optional without default value. Non-null is available for optional with default (possible future extension). * Clients should *not* look up types by name, because type names are not ABI. Look up the command or event you're interested in, then follow the references. TODO Should we hide the type names to eliminate the temptation? New generator scripts/qapi-introspect.py computes an introspection value for its input, and generates a C variable holding it. It can generate awfully long lines. Marked TODO. A new test-qmp-input-visitor test case feeds its result for both tests/qapi-schema/qapi-schema-test.json and qapi-schema.json to a QmpInputVisitor to verify it actually conforms to the schema. New QMP command query-qmp-schema takes its return value from that variable. Its reply is some 85KiBytes for me right now. If this turns out to be too much, we have a couple of options: * We can use shorter names in the JSON. Not the QMP style. * Optionally return the sub-schema for commands and events given as arguments. Right now qmp_query_schema() sends the string literal computed by qmp-introspect.py. To compute sub-schema at run time, we'd have to duplicate parts of qapi-introspect.py in C. Unattractive. * Let clients cache the output of query-qmp-schema. It changes only on QEMU upgrades, i.e. rarely. Provide a command query-qmp-schema-hash. Clients can have a cache indexed by hash, and re-query the schema only when they don't have it cached. Even simpler: put the hash in the QMP greeting. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Pseudo-type '**' is now unused, drop itMarkus Armbruster2015-09-211-12/+6
| | | | | | | | | | 'gen': false needs to stay for now, because netdev_add is still using it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <1442401589-24189-25-git-send-email-armbru@redhat.com>
* qapi-schema: Fix up misleading specification of netdev_addMarkus Armbruster2015-09-211-1/+1
| | | | | | | | | | | | | | | | | It doesn't take a 'props' argument, let alone one in the format "NAME=VALUE,..." The bogus arguments specification doesn't matter due to 'gen': false. Clean it up to be incomplete rather than wrong, and document the incompleteness. While there, improve netdev_add usage example in the manual: add a device option to show how it's done. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <1442401589-24189-24-git-send-email-armbru@redhat.com>
* qapi: Introduce a first class 'any' typeMarkus Armbruster2015-09-211-0/+1
| | | | | | | | | | | It's first class, because unlike '**', it actually works, i.e. doesn't require 'gen': false. '**' will go away next. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com>
* qapi: Improve built-in type documentationMarkus Armbruster2015-09-211-11/+18
| | | | | | | | | | Clarify how they map to JSON. Add how they map to C. Fix the reference to StringInputVisitor. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <1442401589-24189-20-git-send-email-armbru@redhat.com>
* qapi-commands: De-duplicate output marshaling functionsMarkus Armbruster2015-09-211-2/+2
| | | | | | | | | | | | | | gen_marshal_output() uses its parameter name only for name of the generated function. Name it after the type being marshaled instead of its caller, and drop duplicates. Saves 7 copies of qmp_marshal_output_int() in qemu-ga, and one copy of qmp_marshal_output_str() in qemu-system-*. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <1442401589-24189-19-git-send-email-armbru@redhat.com>
* qapi: Rename qmp_marshal_input_FOO() to qmp_marshal_FOO()Markus Armbruster2015-09-211-2/+2
| | | | | | | | | These functions marshal both input and output. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Message-Id: <1442401589-24189-17-git-send-email-armbru@redhat.com>
* qapi: Clean up after recent conversions to QAPISchemaVisitorMarkus Armbruster2015-09-211-1/+1
| | | | | | | | | | | | | | | | | | | | | | | | Generate just 'FOO' instead of 'struct FOO' when possible. Drop helper functions that are now unused. Make pep8 and pylint reasonably happy. Rename generate_FOO() functions to gen_FOO() for consistency. Use more consistent and sensible variable names. Consistently use c_ for mapping keys when their value is a C identifier or type. Simplify gen_enum() and gen_visit_union() Consistently use single quotes for C text string literals. Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1442401589-24189-14-git-send-email-armbru@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: De-duplicate enum code generationMarkus Armbruster2015-09-211-4/+5
| | | | | | | | | | | | | | | Duplicated in commit 21cd70d. Yes, we can't import qapi-types, but that's no excuse. Move the helpers from qapi-types.py to qapi.py, and replace the duplicates in qapi-event.py. The generated event enumeration type's lookup table becomes const-correct (see commit 2e4450f), and uses explicit indexes instead of relying on order (see commit 912ae9c). Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <1442401589-24189-10-git-send-email-armbru@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi-types: Convert to QAPISchemaVisitor, fixing flat unionsMarkus Armbruster2015-09-211-15/+14
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | Fixes flat unions to get the base's base members. Test case is from commit 2fc0043, in qapi-schema-test.json: { 'union': 'UserDefFlatUnion', 'base': 'UserDefUnionBase', 'discriminator': 'enum1', 'data': { 'value1' : 'UserDefA', 'value2' : 'UserDefB', 'value3' : 'UserDefB' } } { 'struct': 'UserDefUnionBase', 'base': 'UserDefZero', 'data': { 'string': 'str', 'enum1': 'EnumOne' } } { 'struct': 'UserDefZero', 'data': { 'integer': 'int' } } Patch's effect on UserDefFlatUnion: struct UserDefFlatUnion { /* Members inherited from UserDefUnionBase: */ + int64_t integer; char *string; EnumOne enum1; /* Own members: */ union { /* union tag is @enum1 */ void *data; UserDefA *value1; UserDefB *value2; UserDefB *value3; }; }; Flat union visitors remain broken. They'll be fixed next. Code is generated in a different order now, but that doesn't matter. The two guards QAPI_TYPES_BUILTIN_STRUCT_DECL and QAPI_TYPES_BUILTIN_CLEANUP_DECL are replaced by just QAPI_TYPES_BUILTIN. Two ugly special cases for simple unions now stand out like sore thumbs: 1. The type tag is named 'type' everywhere, except in generated C, where it's 'kind'. 2. QAPISchema lowers simple unions to semantically equivalent flat unions. However, the C generated for a simple unions differs from the C generated for its equivalent flat union, and we therefore need special code to preserve that pointless difference for now. Mark both TODO. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Daniel P. Berrange <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: allow override of default enum prefix namingDaniel P. Berrange2015-09-151-0/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The camel_to_upper() method applies some heuristics to turn a mixed case type name into an all-uppercase name. This is used for example, to generate enum constant name prefixes. The heuristics don't also generate a satisfactory name though. eg { 'enum': 'QCryptoTLSCredsEndpoint', 'data': ['client', 'server']} Results in Q_CRYPTOTLS_CREDS_ENDPOINT_CLIENT. This has an undesirable _ after the initial Q and is missing an _ between the CRYPTO & TLS strings. Rather than try to add more and more heuristics to try to cope with this, simply allow the QAPI schema to specify the desired enum constant prefix explicitly. eg { 'enum': 'QCryptoTLSCredsEndpoint', 'prefix': 'QCRYPTO_TLS_CREDS_ENDPOINT', 'data': ['client', 'server']} Now gives the QCRYPTO_TLS_CREDS_ENDPOINT_CLIENT name. Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
* docs/qapi-code-gen.txt: Fix QAPI schema examplesMarkus Armbruster2015-09-041-3/+2
| | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Generated code cleanupMarkus Armbruster2015-09-041-7/+5
| | | | | | | | Clean up white-space, brace placement, and superfluous #ifdef QAPI_TYPES_BUILTIN_CLEANUP_DEF. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi-commands: Drop useless initializationMarkus Armbruster2015-09-041-1/+1
| | | | | | | | | In generated command handlers, the assignment to retval dominates its only use. Therefore, its initialization is useless. Drop it. Suggested-by: Eric Blake <eblake@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Command returning anonymous type doesn't work, outlawMarkus Armbruster2015-09-041-9/+8
| | | | | | | | | | | | | | | | | | | | | | | | | Reproducer: with { 'command': 'user_def_cmd4', 'returns': { 'a': 'int' } } added to qapi-schema-test.json, qapi-commands.py dies when it tries to generate the command handler function Traceback (most recent call last): File "/work/armbru/qemu/scripts/qapi-commands.py", line 359, in <module> ret = generate_command_decl(cmd['command'], arglist, ret_type) + "\n" File "/work/armbru/qemu/scripts/qapi-commands.py", line 29, in generate_command_decl ret_type=c_type(ret_type), name=c_name(name), File "/work/armbru/qemu/scripts/qapi.py", line 927, in c_type assert isinstance(value, str) and value != "" AssertionError because the return type doesn't exist. Simply outlaw this usage, and drop or dumb down test cases accordingly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Fix to reject union command and event argumentsMarkus Armbruster2015-09-041-4/+3
| | | | | | | | | | | | | | A command's or event's 'data' must be a struct type, given either as a dictionary, or as struct type name. Commit dd883c6 tightened the checking there, but not enough: we still accept 'union'. Fix to reject it. We may want to support union types there, but we'll have to extend qapi-commands.py and qapi-events.py for it. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi-event: Clean up how name of enum QAPIEvent is madeMarkus Armbruster2015-09-041-4/+4
| | | | | | | | | Use c_name() instead of ad hoc code. Doesn't upcase the -p prefix, which is an improvement in my book. Unbreaks prefix containing '.', but other funny characters remain broken. To be fixed next. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Clarify docs on including the same file multiple timesMarkus Armbruster2015-09-041-2/+2
| | | | | | | | | It's idempotent. While there, update examples to current code. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Drop bogus command from docsMarkus Armbruster2015-06-181-2/+0
| | | | | | | | | Commit 87a560c4 added it in the wrong place. Commit 59a2c4ce added it in the right place, but didn't remove it from the wrong place. Do that now. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Turn generators' mandatory option -i into an argumentMarkus Armbruster2015-05-141-5/+5
| | | | | | | | | Mandatory option is silly, and the error handling is missing: the programs crash when -i isn't supplied. Make it an argument, and check it properly. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Tweak doc references to QMP when QGA is also meantEric Blake2015-05-051-77/+82
| | | | | | | | | | | We have more than one qapi schema in use by more than one protocol. Add a new term 'Client JSON Protocol' for use throughout the document, to avoid confusion on whether something refers only to QMP and not QGA. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Document 'struct' metatypeEric Blake2015-05-051-29/+29
| | | | | | | | | | | | Referring to "type" as both a meta-type (built-in, enum, union, alternate, or struct) and a specific type (the name that the schema uses for declaring structs) is confusing. Now that the generator accepts 'struct' as a synonym for 'type', update all documentation to use saner wording. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Document new 'alternate' meta-typeEric Blake2015-05-051-21/+36
| | | | | | | | | | | | | | | | | | | | | | | | The next patch will quit special-casing "'union':'Foo', 'discriminator':{}" and instead use "'alternate':'Foo'". Separating docs from implementation makes it easier to focus on wording without holding up code. In particular, making alternate a separate type makes for a nice type hierarchy: /-------- meta-type ------\ / | \ simple types alternate complex types | | | | built-in enum type(struct) union | \ / / \ numeric string simple flat A later patch will then clean up 'type' vs. 'struct' confusion. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Document type-safety considerationsEric Blake2015-05-051-96/+333
| | | | | | | | | | | Go into more details about the various types of valid expressions in a qapi schema, including tweaks to document fixes being done later in the current patch series. Also fix some stale and missing documentation in the QMP specification. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Add copyright declaration on docsEric Blake2015-05-051-0/+8
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | While our top-level COPYING with its GPLv2+ license applies to any documentation file that omits explicit instructions, these days it's better to be a good example of calling out our intentions. Correct use of GPL requires the use of a copyright statement, so I'm adding notice to two QAPI documents, by attributing these files to the initial authors and major contributors. I used: $ git blame --line-porcelain $file \ | sed -n 's/^author //p' | sort | uniq -c | sort -rn to determine authorship of these two files. qmp-spec.txt blames entirely to Red Hat (easy, since my contribution falls in that category); while qapi-code-gen.txt has multiple contributors representing multiple entities. But since it was originally supplied by Michael Roth, the notice I added there copies the notice he has used in other files. As there is no intended change in license from the implicit one previously present from the top level, I have not bothered to CC other contributors; if we want to weaken things to something looser (such as LGPL) so that there is no question that someone re-implementing the spec is not forced to use GPL, that would be a different commit. CC: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
* qapi: Update docs given recent event, spacing fixesEric Blake2014-09-261-20/+80
| | | | | | | | | | | | Commit 21cd70d added event support but didn't document what the generated code looks like. Commit 05dfb26 removed some unwanted spaces in the generated code, but didn't reflect those changes into the documentation. Finally, the docs start with a big disclaimer about QMP not using QAPI yet, which feels rather stale. Signed-off-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
* qapi script: clean up in scriptsWenchao Xia2014-06-271-4/+4
| | | | | | | | | This patch improve docs and uses c_type(argentry, is_param=True) in script. Signed-off-by: Wenchao Xia <wenchaoqemu@gmail.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi script: add event supportWenchao Xia2014-06-231-0/+18
| | | | | | | | | | | | | | | | | | | | qapi-event.py will parse the schema and generate qapi-event.c, then the API in qapi-event.c can be used to handle events in qemu code. All API have prefix "qapi_event". The script mainly includes two parts: generate API for each event define, generate an enum type for all defined events. Since in some cases the real emit behavior may change, for example, qemu-img would not send a event, a callback layer is used to control the behavior. As a result, the stubs at compile time can be saved, the binding of block layer code and monitor code will become looser. Signed-off-by: Wenchao Xia <wenchaoqemu@gmail.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: skip redundant includesBenoît Canet2014-05-161-1/+1
| | | | | | | | | | | | | | | | | The purpose of this change is to help create a json file containing common definitions; each bit of generated C code must be emitted only one time. A second history global to all QAPISchema instances has been added to detect when a file is included more than one time and skip these includes. It does not act as a stack and the changes made to it by the __init__ function are propagated back to the caller so it's really a global state. Signed-off-by: Benoit Canet <benoit@irqsave.net> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Show qapi-commands.py invocation in qapi-code-gen.txtMarkus Armbruster2014-05-151-14/+13
| | | | | | | | While there, pare down the shell prompts. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Replace uncommon use of the error API by the common oneMarkus Armbruster2014-05-151-37/+50
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | We commonly use the error API like this: err = NULL; foo(..., &err); if (err) { goto out; } bar(..., &err); Every error source is checked separately. The second function is only called when the first one succeeds. Both functions are free to pass their argument to error_set(). Because error_set() asserts no error has been set, this effectively means they must not be called with an error set. The qapi-generated code uses the error API differently: // *errp was initialized to NULL somewhere up the call chain frob(..., errp); gnat(..., errp); Errors accumulate in *errp: first error wins, subsequent errors get dropped. To make this work, the second function does nothing when called with an error set. Requires non-null errp, or else the second function can't see the first one fail. This usage has also bled into visitor tests, and two device model object property getters rtc_get_date() and balloon_stats_get_all(). With the "accumulate" technique, you need fewer error checks in callers, and buy that with an error check in every callee. Can be nice. However, mixing the two techniques is confusing. You can't use the "accumulate" technique with functions designed for the "check separately" technique. You can use the "check separately" technique with functions designed for the "accumulate" technique, but then error_set() can't catch you setting an error more than once. Standardize on the "check separately" technique for now, because it's overwhelmingly prevalent. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Normalize marshalling's visitor initialization and cleanupMarkus Armbruster2014-05-151-4/+4
| | | | | | | | | | | | | | | Input and output marshalling functions do it differently. Change them to work the same: initialize the I/O visitor, use it, clean it up, initialize the dealloc visitor, use it, clean it up. This delays dealloc visitor initialization in output marshalling functions, and input visitor cleanup in input marshalling functions. No functional change, but the latter will be convenient when I change the error handling. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Update qapi-code-gen.txt example to match current codeMarkus Armbruster2014-05-151-56/+90
| | | | | | Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Document optional arguments' backwards compatibilityEric Blake2014-05-091-4/+28
| | | | | | Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Fam Zheng <famz@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Add a primitive to include other files from a QAPI schema fileLluís Vilanova2014-05-081-0/+11
| | | | | | | | | | | The primitive uses JSON syntax, and include paths are relative to the file using the directive: { 'include': 'path/to/file.json' } Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: Use an explicit input fileLluís Vilanova2014-05-081-2/+2
| | | | | | | | | | | | Use an explicit input file on the command-line instead of reading from standard input. It also outputs the proper file name when there's an error. Signed-off-by: Lluís Vilanova <vilanova@ac.upc.edu> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi script: do not allow string discriminatorWenchao Xia2014-03-111-4/+1
| | | | | | | | | | | Since enum based discriminators provide better type-safety and ensure that future qapi additions do not forget to adjust dependent unions, forbid using string as discriminator from now on. Signed-off-by: Wenchao Xia <wenchaoqemu@gmail.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi script: support enum type as discriminator in unionWenchao Xia2014-03-111-2/+6
| | | | | | | | | | | | By default, any union will automatically generate a enum type as "[UnionName]Kind" in C code, and it is duplicated when the discriminator is specified as a pre-defined enum type in schema. After this patch, the pre-defined enum type will be really used as the switch case condition in generated C code, if discriminator is an enum field. Signed-off-by: Wenchao Xia <wenchaoqemu@gmail.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
* qapi: fix documentation exampleEric Blake2013-10-261-1/+1
| | | | | | | | | The QMP wire format uses "", not '', around strings. * docs/qapi-code-gen.txt: Fix typo. Signed-off-by: Eric Blake <eblake@redhat.com> Signed-off-by: Michael Tokarev <mjt@tls.msk.ru>
* qapi-types/visit.py: Inheritance for structsKevin Wolf2013-10-111-0/+17
| | | | | | | | | | | This introduces a new 'base' key for struct definitions that refers to another struct type. On the JSON level, the fields of the base type are included directly into the same namespace as the fields of the defined type, like with unions. On the C level, a pointer to a struct of the base type is included. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Anonymous unionsKevin Wolf2013-07-261-0/+25
| | | | | | | | | | | | | | | | | | | | | The discriminator for anonymous unions is the data type. This allows to have a union type that allows both of these: { 'file': 'my_existing_block_device_id' } { 'file': { 'filename': '/tmp/mydisk.qcow2', 'read-only': true } } Unions like this are specified in the schema with an empty dict as discriminator. For this example you could take: { 'union': 'BlockRef', 'discriminator': {}, 'data': { 'definition': 'BlockOptions', 'reference': 'str' } } { 'type': 'ExampleObject', 'data: { 'file': 'BlockRef' } } Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: Flat unions with arbitrary discriminatorKevin Wolf2013-07-261-0/+22
| | | | | | | | | | | | | | | | | | | | | | Instead of the rather verbose syntax that distinguishes base and subclass fields... { "type": "file", "read-only": true, "data": { "filename": "test" } } ...we can now have both in the same namespace, allowing a more direct mapping of the command line, and moving fields between the common base and subclasses without breaking the API: { "driver": "file", "read-only": true, "filename": "test" } Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* docs: Document QAPI union typesKevin Wolf2013-07-261-7/+55
| | | | | Signed-off-by: Kevin Wolf <kwolf@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
* qapi: fix error propagationPaolo Bonzini2012-07-231-0/+2
| | | | | | | | | | | | | | | | | | | | | | Don't overwrite / leak previously set errors. Make traversal cope with missing mandatory sub-structs. Don't try to end a container that could not be started. v1->v2: - unchanged v2->v3: - instead of examining, assert that we never overwrite errors with error_set() - allow visitors to set a NULL struct pointer successfully, so traversal of incomplete objects can continue - check for a NULL "obj" before accessing "(*obj)->has_XXX" (this is not a typo, "obj != NULL" implies "*obj != NULL" here) - fix start_struct / end_struct balance for unions as well Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Laszlo Ersek <lersek@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@linux.vnet.ibm.com>
* qapi: untangle next_listPaolo Bonzini2012-03-271-2/+2
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | Right now, the semantics of next_list are complicated. The caller must: * call start_list * call next_list for each element *including the first* * on the first call to next_list, the second argument should point to NULL and the result is the head of the list. On subsequent calls, the second argument should point to the last node (last result of next_list) and next_list itself tacks the element at the tail of the list. This works for both input and output visitor, but having the visitor write memory when it is only reading the list is ugly. Plus, relying on *list to detect the first call is tricky and undocumented. We can initialize so->entry in next_list instead of start_list, leaving it NULL in start_list. This way next_list sees clearly whether it is on the first call---as a bonus, it discriminates the cases based on internal state of the visitor rather than external state. We can also pull the assignment of the list head from generated code up to next_list. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
OpenPOWER on IntegriCloud