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. Generated code is unchanged, as long as no client uses the new feature. Signed-off-by: Eric Blake <ebl...@redhat.com> --- v8: forbid empty type, allow alternates, improve docs v7: rebase to latest v6: retitle, rebase, and merge v5 40/46 and 41/46 into one patch --- scripts/qapi.py | 63 +++++++++++++++++++++++++-------- scripts/qapi-commands.py | 3 +- scripts/qapi-event.py | 5 ++- tests/test-qmp-commands.c | 8 +++++ docs/qapi-code-gen.txt | 27 ++++++++++++-- tests/Makefile.include | 5 +++ tests/qapi-schema/args-bad-box.err | 1 + tests/qapi-schema/args-bad-box.exit | 1 + tests/qapi-schema/args-bad-box.json | 2 ++ tests/qapi-schema/args-bad-box.out | 0 tests/qapi-schema/args-box-anon.err | 1 + tests/qapi-schema/args-box-anon.exit | 1 + tests/qapi-schema/args-box-anon.json | 2 ++ tests/qapi-schema/args-box-anon.out | 0 tests/qapi-schema/args-box-empty.err | 1 + tests/qapi-schema/args-box-empty.exit | 1 + tests/qapi-schema/args-box-empty.json | 3 ++ tests/qapi-schema/args-box-empty.out | 0 tests/qapi-schema/args-box-string.err | 1 + tests/qapi-schema/args-box-string.exit | 1 + tests/qapi-schema/args-box-string.json | 2 ++ tests/qapi-schema/args-box-string.out | 0 tests/qapi-schema/args-union.err | 2 +- tests/qapi-schema/args-union.json | 3 +- tests/qapi-schema/event-box-empty.err | 1 + tests/qapi-schema/event-box-empty.exit | 1 + tests/qapi-schema/event-box-empty.json | 2 ++ tests/qapi-schema/event-box-empty.out | 0 tests/qapi-schema/qapi-schema-test.json | 4 +++ tests/qapi-schema/qapi-schema-test.out | 8 +++++ 30 files changed, 128 insertions(+), 21 deletions(-) create mode 100644 tests/qapi-schema/args-bad-box.err create mode 100644 tests/qapi-schema/args-bad-box.exit create mode 100644 tests/qapi-schema/args-bad-box.json create mode 100644 tests/qapi-schema/args-bad-box.out create mode 100644 tests/qapi-schema/args-box-anon.err create mode 100644 tests/qapi-schema/args-box-anon.exit create mode 100644 tests/qapi-schema/args-box-anon.json create mode 100644 tests/qapi-schema/args-box-anon.out create mode 100644 tests/qapi-schema/args-box-empty.err create mode 100644 tests/qapi-schema/args-box-empty.exit create mode 100644 tests/qapi-schema/args-box-empty.json create mode 100644 tests/qapi-schema/args-box-empty.out create mode 100644 tests/qapi-schema/args-box-string.err create mode 100644 tests/qapi-schema/args-box-string.exit create mode 100644 tests/qapi-schema/args-box-string.json create mode 100644 tests/qapi-schema/args-box-string.out create mode 100644 tests/qapi-schema/event-box-empty.err create mode 100644 tests/qapi-schema/event-box-empty.exit create mode 100644 tests/qapi-schema/event-box-empty.json create mode 100644 tests/qapi-schema/event-box-empty.out diff --git a/scripts/qapi.py b/scripts/qapi.py index f5e7697..48263c4 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -522,10 +522,14 @@ def check_type(expr_info, source, value, allow_array=False, def check_command(expr, expr_info): name = expr['command'] + box = expr.get('box', False) + args_meta = ['struct'] + if box: + args_meta += ['union', 'alternate'] check_type(expr_info, "'data' for command '%s'" % name, - expr.get('data'), allow_dict=True, allow_optional=True, - allow_metas=['struct']) + expr.get('data'), allow_dict=not box, allow_optional=True, + allow_metas=args_meta) returns_meta = ['union', 'struct'] if name in returns_whitelist: returns_meta += ['built-in', 'alternate', 'enum'] @@ -537,11 +541,15 @@ def check_command(expr, expr_info): def check_event(expr, expr_info): global events name = expr['event'] + box = expr.get('box', False) + meta = ['struct'] + if box: + meta += ['union', 'alternate'] events.append(name) check_type(expr_info, "'data' for event '%s'" % name, - expr.get('data'), allow_dict=True, allow_optional=True, - allow_metas=['struct']) + expr.get('data'), allow_dict=not box, allow_optional=True, + allow_metas=meta) def check_union(expr, expr_info): @@ -694,6 +702,10 @@ def check_keys(expr_elem, meta, required, optional=[]): raise QAPIExprError(info, "'%s' of %s '%s' should only use false value" % (key, meta, name)) + if key == 'box' and value is not True: + raise QAPIExprError(info, + "'%s' of %s '%s' should only use true value" + % (key, meta, name)) for key in required: if key not in expr: raise QAPIExprError(info, @@ -725,10 +737,10 @@ def check_exprs(exprs): add_struct(expr, info) elif 'command' in expr: check_keys(expr_elem, 'command', [], - ['data', 'returns', 'gen', 'success-response']) + ['data', 'returns', 'gen', 'success-response', 'box']) add_name(expr['command'], info, 'command') elif 'event' in expr: - check_keys(expr_elem, 'event', [], ['data']) + check_keys(expr_elem, 'event', [], ['data', 'box']) add_name(expr['event'], info, 'event') else: raise QAPIExprError(expr_elem['info'], @@ -1162,6 +1174,9 @@ class QAPISchemaAlternateType(QAPISchemaType): def visit(self, visitor): visitor.visit_alternate_type(self.name, self.info, self.variants) + def is_empty(self): + return False + class QAPISchemaCommand(QAPISchemaEntity): def __init__(self, name, info, arg_type, ret_type, gen, success_response, @@ -1180,9 +1195,18 @@ class QAPISchemaCommand(QAPISchemaEntity): def check(self, schema): if self._arg_type_name: self.arg_type = schema.lookup_type(self._arg_type_name) - assert isinstance(self.arg_type, QAPISchemaObjectType) - assert not self.arg_type.variants # not implemented - assert not self.box # not implemented + assert (isinstance(self.arg_type, QAPISchemaObjectType) or + isinstance(self.arg_type, QAPISchemaAlternateType)) + self.arg_type.check(schema) + if self.box: + if self.arg_type.is_empty(): + raise QAPIExprError(self.info, + "Cannot use 'box' with empty type") + else: + assert not self.arg_type.variants + elif self.box: + raise QAPIExprError(self.info, + "Use of 'box' requires 'data'") if self._ret_type_name: self.ret_type = schema.lookup_type(self._ret_type_name) assert isinstance(self.ret_type, QAPISchemaType) @@ -1204,9 +1228,18 @@ class QAPISchemaEvent(QAPISchemaEntity): def check(self, schema): if self._arg_type_name: self.arg_type = schema.lookup_type(self._arg_type_name) - assert isinstance(self.arg_type, QAPISchemaObjectType) - assert not self.arg_type.variants # not implemented - assert not self.box # not implemented + assert (isinstance(self.arg_type, QAPISchemaObjectType) or + isinstance(self.arg_type, QAPISchemaAlternateType)) + self.arg_type.check(schema) + if self.box: + if self.arg_type.is_empty(): + raise QAPIExprError(self.info, + "Cannot use 'box' with empty type") + else: + assert not self.arg_type.variants + elif self.box: + raise QAPIExprError(self.info, + "Use of 'box' requires 'data'") def visit(self, visitor): visitor.visit_event(self.name, self.info, self.arg_type, self.box) @@ -1646,12 +1679,14 @@ extern const char *const %(c_name)s_lookup[]; def gen_params(arg_type, box, extra): - if not arg_type: + if not arg_type or arg_type.is_empty(): + assert not box return extra ret = '' sep = '' if box: - assert False # not implemented + ret += '%s arg' % arg_type.c_param_type() + sep = ', ' else: assert not arg_type.variants for memb in arg_type.members: diff --git a/scripts/qapi-commands.py b/scripts/qapi-commands.py index 598c4c7..8d25701 100644 --- a/scripts/qapi-commands.py +++ b/scripts/qapi-commands.py @@ -30,7 +30,8 @@ def gen_call(name, arg_type, box, ret_type): argstr = '' if box: - assert False # not implemented + assert arg_type and not arg_type.is_empty() + argstr = '&arg, ' elif arg_type: assert not arg_type.variants for memb in arg_type.members: diff --git a/scripts/qapi-event.py b/scripts/qapi-event.py index 024be4d..2cab588 100644 --- a/scripts/qapi-event.py +++ b/scripts/qapi-event.py @@ -79,7 +79,10 @@ def gen_event_send(name, arg_type, box): QObject *obj; Visitor *v; ''') - ret += gen_param_var(arg_type) + if not box: + ret += gen_param_var(arg_type) + else: + assert not box ret += mcgen(''' diff --git a/tests/test-qmp-commands.c b/tests/test-qmp-commands.c index 8ffeb04..5af1a46 100644 --- a/tests/test-qmp-commands.c +++ b/tests/test-qmp-commands.c @@ -59,6 +59,14 @@ QObject *qmp_guest_sync(QObject *arg, Error **errp) return arg; } +void qmp_boxed_struct(UserDefZero *arg, Error **errp) +{ +} + +void qmp_boxed_union(UserDefNativeListUnion *arg, Error **errp) +{ +} + __org_qemu_x_Union1 *qmp___org_qemu_x_command(__org_qemu_x_EnumList *a, __org_qemu_x_StructList *b, __org_qemu_x_Union2 *c, diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index 48b0b31..74171b7 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -410,7 +410,7 @@ following example objects: === Commands === Usage: { 'command': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, - '*returns': TYPE-NAME, + '*returns': TYPE-NAME, '*box': true, '*gen': false, '*success-response': false } Commands are defined by using a dictionary containing several members, @@ -461,6 +461,20 @@ which would validate this Client JSON Protocol transaction: => { "execute": "my-second-command" } <= { "return": [ { "value": "one" }, { } ] } +The generator emits a prototype for the user's function implementing +the command. Normally, 'data' is a dictionary for an anonymous type, +or names a struct type (possibly empty, but not a union), and its +members are passed as separate arguments to this function. If the +command definition include a key 'box' with the boolean value true, +then 'data' is instead the name of any non-empty complex type +(struct, union, or alternate), and a pointer to that QAPI type is +passed as a single argument. + +The generator also emits a marshalling function that extracts +arguments for the user's function out of an input QDict, calls the +user's function, and if it succeeded, builds an output QObject from +its return value. + In rare cases, QAPI cannot express a type-safe representation of a corresponding Client JSON Protocol command. You then have to suppress generation of a marshalling function by including a key 'gen' with @@ -484,7 +498,8 @@ use of this member. === Events === -Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT } +Usage: { 'event': STRING, '*data': COMPLEX-TYPE-NAME-OR-DICT, + '*box': true } Events are defined with the keyword 'event'. It is not allowed to name an event 'MAX', since the generator also produces a C enumeration @@ -505,6 +520,14 @@ Resulting in this JSON object: "data": { "b": "test string" }, "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } +The generator emits a function to send the event. Normally, 'data' is +a dictionary for an anonymous type, or names a struct type (possibly +empty, but not a union), and its members are passed as separate +arguments to this function. If the event definition include a key +'box' with the boolean value true, then 'data' is instead the name of +any non-empty complex type (struct, union, or alternate), and a +pointer to that QAPI type is passed as a single argument. + == Client JSON Protocol introspection == diff --git a/tests/Makefile.include b/tests/Makefile.include index df232f6..f73f350 100644 --- a/tests/Makefile.include +++ b/tests/Makefile.include @@ -284,6 +284,10 @@ qapi-schema += args-alternate.json qapi-schema += args-any.json qapi-schema += args-array-empty.json qapi-schema += args-array-unknown.json +qapi-schema += args-bad-box.json +qapi-schema += args-box-anon.json +qapi-schema += args-box-empty.json +qapi-schema += args-box-string.json qapi-schema += args-int.json qapi-schema += args-invalid.json qapi-schema += args-member-array-bad.json @@ -317,6 +321,7 @@ qapi-schema += enum-wrong-data.json qapi-schema += escape-outside-string.json qapi-schema += escape-too-big.json qapi-schema += escape-too-short.json +qapi-schema += event-box-empty.json qapi-schema += event-case.json qapi-schema += event-nest-struct.json qapi-schema += flat-union-array-branch.json diff --git a/tests/qapi-schema/args-bad-box.err b/tests/qapi-schema/args-bad-box.err new file mode 100644 index 0000000..16afe3c --- /dev/null +++ b/tests/qapi-schema/args-bad-box.err @@ -0,0 +1 @@ +tests/qapi-schema/args-bad-box.json:2: 'box' of command 'foo' should only use true value diff --git a/tests/qapi-schema/args-bad-box.exit b/tests/qapi-schema/args-bad-box.exit new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/tests/qapi-schema/args-bad-box.exit @@ -0,0 +1 @@ +1 diff --git a/tests/qapi-schema/args-bad-box.json b/tests/qapi-schema/args-bad-box.json new file mode 100644 index 0000000..8d5737a --- /dev/null +++ b/tests/qapi-schema/args-bad-box.json @@ -0,0 +1,2 @@ +# 'box' should only appear with value true +{ 'command': 'foo', 'box': false } diff --git a/tests/qapi-schema/args-bad-box.out b/tests/qapi-schema/args-bad-box.out new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/args-box-anon.err b/tests/qapi-schema/args-box-anon.err new file mode 100644 index 0000000..11eaefc --- /dev/null +++ b/tests/qapi-schema/args-box-anon.err @@ -0,0 +1 @@ +tests/qapi-schema/args-box-anon.json:2: 'data' for command 'foo' should be a type name diff --git a/tests/qapi-schema/args-box-anon.exit b/tests/qapi-schema/args-box-anon.exit new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/tests/qapi-schema/args-box-anon.exit @@ -0,0 +1 @@ +1 diff --git a/tests/qapi-schema/args-box-anon.json b/tests/qapi-schema/args-box-anon.json new file mode 100644 index 0000000..947e3c6 --- /dev/null +++ b/tests/qapi-schema/args-box-anon.json @@ -0,0 +1,2 @@ +# 'box' can only be used with named types +{ 'command': 'foo', 'box': true, 'data': { 'string': 'str' } } diff --git a/tests/qapi-schema/args-box-anon.out b/tests/qapi-schema/args-box-anon.out new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/args-box-empty.err b/tests/qapi-schema/args-box-empty.err new file mode 100644 index 0000000..9546a95 --- /dev/null +++ b/tests/qapi-schema/args-box-empty.err @@ -0,0 +1 @@ +tests/qapi-schema/args-box-empty.json:3: Cannot use 'box' with empty type diff --git a/tests/qapi-schema/args-box-empty.exit b/tests/qapi-schema/args-box-empty.exit new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/tests/qapi-schema/args-box-empty.exit @@ -0,0 +1 @@ +1 diff --git a/tests/qapi-schema/args-box-empty.json b/tests/qapi-schema/args-box-empty.json new file mode 100644 index 0000000..dda6355 --- /dev/null +++ b/tests/qapi-schema/args-box-empty.json @@ -0,0 +1,3 @@ +# 'box' requires a non-empty type +{ 'struct': 'Empty', 'data': {} } +{ 'command': 'foo', 'box': true, 'data': 'Empty' } diff --git a/tests/qapi-schema/args-box-empty.out b/tests/qapi-schema/args-box-empty.out new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/args-box-string.err b/tests/qapi-schema/args-box-string.err new file mode 100644 index 0000000..4c12d96 --- /dev/null +++ b/tests/qapi-schema/args-box-string.err @@ -0,0 +1 @@ +tests/qapi-schema/args-box-string.json:2: 'data' for command 'foo' cannot use built-in type 'str' diff --git a/tests/qapi-schema/args-box-string.exit b/tests/qapi-schema/args-box-string.exit new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/tests/qapi-schema/args-box-string.exit @@ -0,0 +1 @@ +1 diff --git a/tests/qapi-schema/args-box-string.json b/tests/qapi-schema/args-box-string.json new file mode 100644 index 0000000..85bafc2 --- /dev/null +++ b/tests/qapi-schema/args-box-string.json @@ -0,0 +1,2 @@ +# 'box' requires a complex (not built-in) type +{ 'command': 'foo', 'box': true, 'data': 'str' } diff --git a/tests/qapi-schema/args-box-string.out b/tests/qapi-schema/args-box-string.out new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/args-union.err b/tests/qapi-schema/args-union.err index 1d693d7..f8ad223 100644 --- a/tests/qapi-schema/args-union.err +++ b/tests/qapi-schema/args-union.err @@ -1 +1 @@ -tests/qapi-schema/args-union.json:4: 'data' for command 'oops' cannot use union type 'Uni' +tests/qapi-schema/args-union.json:3: 'data' for command 'oops' cannot use union type 'Uni' diff --git a/tests/qapi-schema/args-union.json b/tests/qapi-schema/args-union.json index 7bdcbb7..c0ce091 100644 --- a/tests/qapi-schema/args-union.json +++ b/tests/qapi-schema/args-union.json @@ -1,4 +1,3 @@ -# we do not allow union arguments -# TODO should we support this? +# use of union arguments requires 'box':true { 'union': 'Uni', 'data': { 'case1': 'int', 'case2': 'str' } } { 'command': 'oops', 'data': 'Uni' } diff --git a/tests/qapi-schema/event-box-empty.err b/tests/qapi-schema/event-box-empty.err new file mode 100644 index 0000000..96b2bc3 --- /dev/null +++ b/tests/qapi-schema/event-box-empty.err @@ -0,0 +1 @@ +tests/qapi-schema/event-box-empty.json:2: Use of 'box' requires 'data' diff --git a/tests/qapi-schema/event-box-empty.exit b/tests/qapi-schema/event-box-empty.exit new file mode 100644 index 0000000..d00491f --- /dev/null +++ b/tests/qapi-schema/event-box-empty.exit @@ -0,0 +1 @@ +1 diff --git a/tests/qapi-schema/event-box-empty.json b/tests/qapi-schema/event-box-empty.json new file mode 100644 index 0000000..0129918 --- /dev/null +++ b/tests/qapi-schema/event-box-empty.json @@ -0,0 +1,2 @@ +# 'box' requires a non-empty type +{ 'event': 'FOO', 'box': true } diff --git a/tests/qapi-schema/event-box-empty.out b/tests/qapi-schema/event-box-empty.out new file mode 100644 index 0000000..e69de29 diff --git a/tests/qapi-schema/qapi-schema-test.json b/tests/qapi-schema/qapi-schema-test.json index f571e1b..919dc097 100644 --- a/tests/qapi-schema/qapi-schema-test.json +++ b/tests/qapi-schema/qapi-schema-test.json @@ -127,6 +127,8 @@ { 'command': 'guest-get-time', 'data': {'a': 'int', '*b': 'int' }, 'returns': 'int' } { 'command': 'guest-sync', 'data': { 'arg': 'any' }, 'returns': 'any' } +{ 'command': 'boxed-struct', 'box': true, 'data': 'UserDefZero' } +{ 'command': 'boxed-union', 'data': 'UserDefNativeListUnion', 'box': true } # For testing integer range flattening in opts-visitor. The following schema # corresponds to the option format: @@ -154,6 +156,8 @@ 'data': { '*a': 'int', '*b': 'UserDefOne', 'c': 'str' } } { 'event': 'EVENT_D', 'data': { 'a' : 'EventStructOne', 'b' : 'str', '*c': 'str', '*enum3': 'EnumOne' } } +{ 'event': 'EVENT_E', 'box': true, 'data': 'UserDefZero' } +{ 'event': 'EVENT_F', 'box': true, 'data': 'UserDefAlternate' } # test that we correctly compile downstream extensions, as well as munge # ticklish names diff --git a/tests/qapi-schema/qapi-schema-test.out b/tests/qapi-schema/qapi-schema-test.out index 754a926..e7ea242 100644 --- a/tests/qapi-schema/qapi-schema-test.out +++ b/tests/qapi-schema/qapi-schema-test.out @@ -30,6 +30,10 @@ event EVENT_C q_obj_EVENT_C-arg box=False event EVENT_D q_obj_EVENT_D-arg box=False +event EVENT_E UserDefZero + box=True +event EVENT_F UserDefAlternate + box=True object Empty1 object Empty2 base Empty1 @@ -153,6 +157,10 @@ object __org.qemu_x-Union2 case __org.qemu_x-value: __org.qemu_x-Struct2 command __org.qemu_x-command q_obj___org.qemu_x-command-arg -> __org.qemu_x-Union1 gen=True success_response=True box=False +command boxed-struct UserDefZero -> None + gen=True success_response=True box=True +command boxed-union UserDefNativeListUnion -> None + gen=True success_response=True box=True command guest-get-time q_obj_guest-get-time-arg -> int gen=True success_response=True box=False command guest-sync q_obj_guest-sync-arg -> any -- 2.5.5