From fb0bc835e56b894cbc7236294921e5393c786ad8 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Mon, 26 Feb 2018 13:48:58 -0600 Subject: qapi-gen: New common driver for code and doc generators MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Whenever qapi-schema.json changes, we run six programs eleven times to update eleven files. Similar for qga/qapi-schema.json. This is silly. Replace the six programs by a single program that spits out all eleven files. The programs become modules in new Python package qapi, along with the helper library. This requires moving them to scripts/qapi/. While moving them, consistently drop executable mode bits. Signed-off-by: Markus Armbruster Reviewed-by: Marc-AndrĂ© Lureau Message-Id: <20180211093607.27351-9-armbru@redhat.com> Reviewed-by: Eric Blake Reviewed-by: Michael Roth [eblake: move change to one-line 'blurb' earlier in series, mention mode bit change as intentional, update qapi-code-gen.txt to match actual generated events.c file] Signed-off-by: Eric Blake --- scripts/qapi-commands.py | 304 ------- scripts/qapi-event.py | 215 ----- scripts/qapi-gen.py | 41 + scripts/qapi-introspect.py | 208 ----- scripts/qapi-types.py | 288 ------- scripts/qapi-visit.py | 375 -------- scripts/qapi.py | 2051 -------------------------------------------- scripts/qapi/__init__.py | 0 scripts/qapi/commands.py | 293 +++++++ scripts/qapi/common.py | 2041 +++++++++++++++++++++++++++++++++++++++++++ scripts/qapi/doc.py | 278 ++++++ scripts/qapi/events.py | 204 +++++ scripts/qapi/introspect.py | 188 ++++ scripts/qapi/types.py | 266 ++++++ scripts/qapi/visit.py | 353 ++++++++ scripts/qapi2texi.py | 291 ------- 16 files changed, 3664 insertions(+), 3732 deletions(-) delete mode 100644 scripts/qapi-commands.py delete mode 100644 scripts/qapi-event.py create mode 100755 scripts/qapi-gen.py delete mode 100644 scripts/qapi-introspect.py delete mode 100644 scripts/qapi-types.py delete mode 100644 scripts/qapi-visit.py delete mode 100644 scripts/qapi.py create mode 100644 scripts/qapi/__init__.py create mode 100644 scripts/qapi/commands.py create mode 100644 scripts/qapi/common.py create mode 100644 scripts/qapi/doc.py create mode 100644 scripts/qapi/events.py create mode 100644 scripts/qapi/introspect.py create mode 100644 scripts/qapi/types.py create mode 100644 scripts/qapi/visit.py delete mode 100755 scripts/qapi2texi.py (limited to 'scripts') diff --git a/scripts/qapi-commands.py b/scripts/qapi-commands.py deleted file mode 100644 index c20b22020e..0000000000 --- a/scripts/qapi-commands.py +++ /dev/null @@ -1,304 +0,0 @@ -""" -QAPI command marshaller generator - -Copyright IBM, Corp. 2011 -Copyright (C) 2014-2018 Red Hat, Inc. - -Authors: - Anthony Liguori - Michael Roth - Markus Armbruster - -This work is licensed under the terms of the GNU GPL, version 2. -See the COPYING file in the top-level directory. -""" - -from qapi import * - - -def gen_command_decl(name, arg_type, boxed, ret_type): - return mcgen(''' -%(c_type)s qmp_%(c_name)s(%(params)s); -''', - c_type=(ret_type and ret_type.c_type()) or 'void', - c_name=c_name(name), - params=build_params(arg_type, boxed, 'Error **errp')) - - -def gen_call(name, arg_type, boxed, ret_type): - ret = '' - - argstr = '' - if boxed: - 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: - if memb.optional: - argstr += 'arg.has_%s, ' % c_name(memb.name) - argstr += 'arg.%s, ' % c_name(memb.name) - - lhs = '' - if ret_type: - lhs = 'retval = ' - - ret = mcgen(''' - - %(lhs)sqmp_%(c_name)s(%(args)s&err); -''', - c_name=c_name(name), args=argstr, lhs=lhs) - if ret_type: - ret += mcgen(''' - if (err) { - goto out; - } - - qmp_marshal_output_%(c_name)s(retval, ret, &err); -''', - c_name=ret_type.c_name()) - return ret - - -def gen_marshal_output(ret_type): - return mcgen(''' - -static void qmp_marshal_output_%(c_name)s(%(c_type)s ret_in, QObject **ret_out, Error **errp) -{ - Error *err = NULL; - Visitor *v; - - v = qobject_output_visitor_new(ret_out); - visit_type_%(c_name)s(v, "unused", &ret_in, &err); - if (!err) { - visit_complete(v, ret_out); - } - error_propagate(errp, err); - visit_free(v); - v = qapi_dealloc_visitor_new(); - visit_type_%(c_name)s(v, "unused", &ret_in, NULL); - visit_free(v); -} -''', - c_type=ret_type.c_type(), c_name=ret_type.c_name()) - - -def build_marshal_proto(name): - return ('void qmp_marshal_%s(QDict *args, QObject **ret, Error **errp)' - % c_name(name)) - - -def gen_marshal_decl(name): - return mcgen(''' -%(proto)s; -''', - proto=build_marshal_proto(name)) - - -def gen_marshal(name, arg_type, boxed, ret_type): - have_args = arg_type and not arg_type.is_empty() - - ret = mcgen(''' - -%(proto)s -{ - Error *err = NULL; -''', - proto=build_marshal_proto(name)) - - if ret_type: - ret += mcgen(''' - %(c_type)s retval; -''', - c_type=ret_type.c_type()) - - if have_args: - visit_members = ('visit_type_%s_members(v, &arg, &err);' - % arg_type.c_name()) - ret += mcgen(''' - Visitor *v; - %(c_name)s arg = {0}; - -''', - c_name=arg_type.c_name()) - else: - visit_members = '' - ret += mcgen(''' - Visitor *v = NULL; - - if (args) { -''') - push_indent() - - ret += mcgen(''' - v = qobject_input_visitor_new(QOBJECT(args)); - visit_start_struct(v, NULL, NULL, 0, &err); - if (err) { - goto out; - } - %(visit_members)s - if (!err) { - visit_check_struct(v, &err); - } - visit_end_struct(v, NULL); - if (err) { - goto out; - } -''', - visit_members=visit_members) - - if not have_args: - pop_indent() - ret += mcgen(''' - } -''') - - ret += gen_call(name, arg_type, boxed, ret_type) - - ret += mcgen(''' - -out: - error_propagate(errp, err); - visit_free(v); -''') - - if have_args: - visit_members = ('visit_type_%s_members(v, &arg, NULL);' - % arg_type.c_name()) - else: - visit_members = '' - ret += mcgen(''' - if (args) { -''') - push_indent() - - ret += mcgen(''' - v = qapi_dealloc_visitor_new(); - visit_start_struct(v, NULL, NULL, 0, NULL); - %(visit_members)s - visit_end_struct(v, NULL); - visit_free(v); -''', - visit_members=visit_members) - - if not have_args: - pop_indent() - ret += mcgen(''' - } -''') - - ret += mcgen(''' -} -''') - return ret - - -def gen_register_command(name, success_response): - options = 'QCO_NO_OPTIONS' - if not success_response: - options = 'QCO_NO_SUCCESS_RESP' - - ret = mcgen(''' - qmp_register_command(cmds, "%(name)s", - qmp_marshal_%(c_name)s, %(opts)s); -''', - name=name, c_name=c_name(name), - opts=options) - return ret - - -def gen_registry(registry, prefix): - ret = mcgen(''' - -void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds) -{ - QTAILQ_INIT(cmds); - -''', - c_prefix=c_name(prefix, protect=False)) - ret += registry - ret += mcgen(''' -} -''') - return ret - - -class QAPISchemaGenCommandVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._prefix = prefix - self.decl = None - self.defn = None - self._regy = None - self._visited_ret_types = None - - def visit_begin(self, schema): - self.decl = '' - self.defn = '' - self._regy = '' - self._visited_ret_types = set() - - def visit_end(self): - self.defn += gen_registry(self._regy, self._prefix) - self._regy = None - self._visited_ret_types = None - - def visit_command(self, name, info, arg_type, ret_type, - gen, success_response, boxed): - if not gen: - return - self.decl += gen_command_decl(name, arg_type, boxed, ret_type) - if ret_type and ret_type not in self._visited_ret_types: - self._visited_ret_types.add(ret_type) - self.defn += gen_marshal_output(ret_type) - self.decl += gen_marshal_decl(name) - self.defn += gen_marshal(name, arg_type, boxed, ret_type) - self._regy += gen_register_command(name, success_response) - - -def main(argv): - (input_file, output_dir, do_c, do_h, prefix, opts) = parse_command_line() - - blurb = ' * Schema-defined QAPI/QMP commands' - - genc = QAPIGenC(blurb, __doc__) - genh = QAPIGenH(blurb, __doc__) - - genc.add(mcgen(''' -#include "qemu/osdep.h" -#include "qemu-common.h" -#include "qemu/module.h" -#include "qapi/visitor.h" -#include "qapi/qmp/qdict.h" -#include "qapi/qobject-output-visitor.h" -#include "qapi/qobject-input-visitor.h" -#include "qapi/dealloc-visitor.h" -#include "qapi/error.h" -#include "%(prefix)sqapi-types.h" -#include "%(prefix)sqapi-visit.h" -#include "%(prefix)sqmp-commands.h" - -''', - prefix=prefix)) - - genh.add(mcgen(''' -#include "%(prefix)sqapi-types.h" -#include "qapi/qmp/dispatch.h" - -void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds); -''', - prefix=prefix, c_prefix=c_name(prefix, protect=False))) - - schema = QAPISchema(input_file) - vis = QAPISchemaGenCommandVisitor(prefix) - schema.visit(vis) - genc.add(vis.defn) - genh.add(vis.decl) - - if do_c: - genc.write(output_dir, prefix + 'qmp-marshal.c') - if do_h: - genh.write(output_dir, prefix + 'qmp-commands.h') - - -if __name__ == '__main__': - main(sys.argv) diff --git a/scripts/qapi-event.py b/scripts/qapi-event.py deleted file mode 100644 index 1f8bf62c8b..0000000000 --- a/scripts/qapi-event.py +++ /dev/null @@ -1,215 +0,0 @@ -""" -QAPI event generator - -Copyright (c) 2014 Wenchao Xia -Copyright (c) 2015-2018 Red Hat Inc. - -Authors: - Wenchao Xia - Markus Armbruster - -This work is licensed under the terms of the GNU GPL, version 2. -See the COPYING file in the top-level directory. -""" - -from qapi import * - - -def build_event_send_proto(name, arg_type, boxed): - return 'void qapi_event_send_%(c_name)s(%(param)s)' % { - 'c_name': c_name(name.lower()), - 'param': build_params(arg_type, boxed, 'Error **errp')} - - -def gen_event_send_decl(name, arg_type, boxed): - return mcgen(''' - -%(proto)s; -''', - proto=build_event_send_proto(name, arg_type, boxed)) - - -# Declare and initialize an object 'qapi' using parameters from build_params() -def gen_param_var(typ): - assert not typ.variants - ret = mcgen(''' - %(c_name)s param = { -''', - c_name=typ.c_name()) - sep = ' ' - for memb in typ.members: - ret += sep - sep = ', ' - if memb.optional: - ret += 'has_' + c_name(memb.name) + sep - if memb.type.name == 'str': - # Cast away const added in build_params() - ret += '(char *)' - ret += c_name(memb.name) - ret += mcgen(''' - - }; -''') - if not typ.is_implicit(): - ret += mcgen(''' - %(c_name)s *arg = ¶m; -''', - c_name=typ.c_name()) - return ret - - -def gen_event_send(name, arg_type, boxed, event_enum_name): - # FIXME: Our declaration of local variables (and of 'errp' in the - # parameter list) can collide with exploded members of the event's - # data type passed in as parameters. If this collision ever hits in - # practice, we can rename our local variables with a leading _ prefix, - # or split the code into a wrapper function that creates a boxed - # 'param' object then calls another to do the real work. - ret = mcgen(''' - -%(proto)s -{ - QDict *qmp; - Error *err = NULL; - QMPEventFuncEmit emit; -''', - proto=build_event_send_proto(name, arg_type, boxed)) - - if arg_type and not arg_type.is_empty(): - ret += mcgen(''' - QObject *obj; - Visitor *v; -''') - if not boxed: - ret += gen_param_var(arg_type) - else: - assert not boxed - - ret += mcgen(''' - - emit = qmp_event_get_func_emit(); - if (!emit) { - return; - } - - qmp = qmp_event_build_dict("%(name)s"); - -''', - name=name) - - if arg_type and not arg_type.is_empty(): - ret += mcgen(''' - v = qobject_output_visitor_new(&obj); -''') - if not arg_type.is_implicit(): - ret += mcgen(''' - visit_type_%(c_name)s(v, "%(name)s", &arg, &err); -''', - name=name, c_name=arg_type.c_name()) - else: - ret += mcgen(''' - - visit_start_struct(v, "%(name)s", NULL, 0, &err); - if (err) { - goto out; - } - visit_type_%(c_name)s_members(v, ¶m, &err); - if (!err) { - visit_check_struct(v, &err); - } - visit_end_struct(v, NULL); -''', - name=name, c_name=arg_type.c_name()) - ret += mcgen(''' - if (err) { - goto out; - } - - visit_complete(v, &obj); - qdict_put_obj(qmp, "data", obj); -''') - - ret += mcgen(''' - emit(%(c_enum)s, qmp, &err); - -''', - c_enum=c_enum_const(event_enum_name, name)) - - if arg_type and not arg_type.is_empty(): - ret += mcgen(''' -out: - visit_free(v); -''') - ret += mcgen(''' - error_propagate(errp, err); - QDECREF(qmp); -} -''') - return ret - - -class QAPISchemaGenEventVisitor(QAPISchemaVisitor): - def __init__(self, prefix): - self._enum_name = c_name(prefix + 'QAPIEvent', protect=False) - self.decl = None - self.defn = None - self._event_names = None - - def visit_begin(self, schema): - self.decl = '' - self.defn = '' - self._event_names = [] - - def visit_end(self): - self.decl += gen_enum(self._enum_name, self._event_names) - self.defn += gen_enum_lookup(self._enum_name, self._event_names) - self._event_names = None - - def visit_event(self, name, info, arg_type, boxed): - self.decl += gen_event_send_decl(name, arg_type, boxed) - self.defn += gen_event_send(name, arg_type, boxed, self._enum_name) - self._event_names.append(name) - - -def main(argv): - (input_file, output_dir, do_c, do_h, prefix, dummy) = parse_command_line() - - blurb = ' * Schema-defined QAPI/QMP events' - - genc = QAPIGenC(blurb, __doc__) - genh = QAPIGenH(blurb, __doc__) - - genc.add(mcgen(''' -#include "qemu/osdep.h" -#include "qemu-common.h" -#include "%(prefix)sqapi-event.h" -#include "%(prefix)sqapi-visit.h" -#include "qapi/error.h" -#include "qapi/qmp/qdict.h" -#include "qapi/qobject-output-visitor.h" -#include "qapi/qmp-event.h" - -''', - prefix=prefix)) - - genh.add(mcgen(''' -#include "qapi/util.h" -#include "%(prefix)sqapi-types.h" - -''', - prefix=prefix)) - - schema = QAPISchema(input_file) - vis = QAPISchemaGenEventVisitor(prefix) - schema.visit(vis) - genc.add(vis.defn) - genh.add(vis.decl) - - if do_c: - genc.write(output_dir, prefix + 'qapi-event.c') - if do_h: - genh.write(output_dir, prefix + 'qapi-event.h') - - -if __name__ == '__main__': - main(sys.argv) diff --git a/scripts/qapi-gen.py b/scripts/qapi-gen.py new file mode 100755 index 0000000000..2100ca1145 --- /dev/null +++ b/scripts/qapi-gen.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python +# QAPI generator +# +# This work is licensed under the terms of the GNU GPL, version 2 or later. +# See the COPYING file in the top-level directory. + +import sys +from qapi.common import parse_command_line, QAPISchema +from qapi.types import gen_types +from qapi.visit import gen_visit +from qapi.commands import gen_commands +from qapi.events import gen_events +from qapi.introspect import gen_introspect +from qapi.doc import gen_doc + + +def main(argv): + (input_file, output_dir, prefix, opts) = \ + parse_command_line('bu', ['builtins', 'unmask-non-abi-names']) + + opt_builtins = False + opt_unmask = False + + for o, a in opts: + if o in ('-b', '--builtins'): + opt_builtins = True + if o in ('-u', '--unmask-non-abi-names'): + opt_unmask = True + + schema = QAPISchema(input_file) + + gen_types(schema, output_dir, prefix, opt_builtins) + gen_visit(schema, output_dir, prefix, opt_builtins) + gen_commands(schema, output_dir, prefix) + gen_events(schema, output_dir, prefix) + gen_introspect(schema, output_dir, prefix, opt_unmask) + gen_doc(schema, output_dir, prefix) + + +if __name__ == '__main__': + main(sys.argv) diff --git a/scripts/qapi-introspect.py b/scripts/qapi-introspect.py deleted file mode 100644 index cac219b4d8..0000000000 --- a/scripts/qapi-introspect.py +++ /dev/null @@ -1,208 +0,0 @@ -""" -QAPI introspection generator - -Copyright (C) 2015-2018 Red Hat, Inc. - -Authors: - Markus Armbruster - -This work is licensed under the terms of the GNU GPL, version 2. -See the COPYING file in the top-level directory. -""" - -from qapi import * - - -# Caveman's json.dumps() replacement (we're stuck at Python 2.4) -# TODO try to use json.dumps() once we get unstuck -def to_json(obj, level=0): - if obj is None: - ret = 'null' - elif isinstance(obj, str): - ret = '"' + obj.replace('"', r'\"') + '"' - elif isinstance(obj, list): - elts = [to_json(elt, level + 1) - for elt in obj] - ret = '[' + ', '.join(elts) + ']' - elif isinstance(obj, dict): - elts = ['"%s": %s' % (key.replace('"', r'\"'), - to_json(obj[key], level + 1)) - for key in sorted(obj.keys())] - ret = '{' + ', '.join(elts) + '}' - else: - assert False # not implemented - if level == 1: - ret = '\n' + ret - return ret - - -def to_c_string(string): - return '"' + string.replace('\\', r'\\').replace('"', r'\"') + '"' - - -class QAPISchemaGenIntrospectVisitor(QAPISchemaVisitor): - def __init__(self, prefix, unmask): - self._prefix = prefix - self._unmask = unmask - self.defn = None - self.decl = None - self._schema = None - self._jsons = None - self._used_types = None - self._name_map = None - - def visit_begin(self, schema): - self._schema = schema - self._jsons = [] - self._used_types = [] - self._name_map = {} - - def visit_end(self): - # visit the types that are actually used - jsons = self._jsons - self._jsons = [] - for typ in self._used_types: - typ.visit(self) - # generate C - # TODO can generate awfully long lines - jsons.extend(self._jsons) - name = c_name(self._prefix, protect=False) + 'qmp_schema_json' - self.decl = mcgen(''' -extern const char %(c_name)s[]; -''', - c_name=c_name(name)) - lines = to_json(jsons).split('\n') - c_string = '\n '.join([to_c_string(line) for line in lines]) - self.defn = mcgen(''' -const char %(c_name)s[] = %(c_string)s; -''', - c_name=c_name(name), - c_string=c_string) - self._schema = None - self._jsons = None - self._used_types = None - self._name_map = None - - def visit_needed(self, entity): - # Ignore types on first pass; visit_end() will pick up used types - return not isinstance(entity, QAPISchemaType) - - def _name(self, name): - if self._unmask: - return name - if name not in self._name_map: - self._name_map[name] = '%d' % len(self._name_map) - return self._name_map[name] - - def _use_type(self, typ): - # Map the various integer types to plain int - if typ.json_type() == 'int': - typ = self._schema.lookup_type('int') - elif (isinstance(typ, QAPISchemaArrayType) and - typ.element_type.json_type() == 'int'): - typ = self._schema.lookup_type('intList') - # Add type to work queue if new - if typ not in self._used_types: - self._used_types.append(typ) - # Clients should examine commands and events, not types. Hide - # type names to reduce the temptation. Also saves a few - # characters. - if isinstance(typ, QAPISchemaBuiltinType): - return typ.name - if isinstance(typ, QAPISchemaArrayType): - return '[' + self._use_type(typ.element_type) + ']' - return self._name(typ.name) - - def _gen_json(self, name, mtype, obj): - if mtype not in ('command', 'event', 'builtin', 'array'): - name = self._name(name) - obj['name'] = name - obj['meta-type'] = mtype - self._jsons.append(obj) - - def _gen_member(self, member): - ret = {'name': member.name, 'type': self._use_type(member.type)} - if member.optional: - ret['default'] = None - return ret - - def _gen_variants(self, tag_name, variants): - return {'tag': tag_name, - 'variants': [self._gen_variant(v) for v in variants]} - - def _gen_variant(self, variant): - return {'case': variant.name, 'type': self._use_type(variant.type)} - - def visit_builtin_type(self, name, info, json_type): - self._gen_json(name, 'builtin', {'json-type': json_type}) - - def visit_enum_type(self, name, info, values, prefix): - self._gen_json(name, 'enum', {'values': values}) - - def visit_array_type(self, name, info, element_type): - element = self._use_type(element_type) - self._gen_json('[' + element + ']', 'array', {'element-type': element}) - - def visit_object_type_flat(self, name, info, members, variants): - obj = {'members': [self._gen_member(m) for m in members]} - if variants: - obj.update(self._gen_variants(variants.tag_member.name, - variants.variants)) - self._gen_json(name, 'object', obj) - - def visit_alternate_type(self, name, info, variants): - self._gen_json(name, 'alternate', - {'members': [{'type': self._use_type(m.type)} - for m in variants.variants]}) - - def visit_command(self, name, info, arg_type, ret_type, - gen, success_response, boxed): - arg_type = arg_type or self._schema.the_empty_object_type - ret_type = ret_type or self._schema.the_empty_object_type - self._gen_json(name, 'command', - {'arg-type': self._use_type(arg_type), - 'ret-type': self._use_type(ret_type)}) - - def visit_event(self, name, info, arg_type, boxed): - arg_type = arg_type or self._schema.the_empty_object_type - self._gen_json(name, 'event', {'arg-type': self._use_type(arg_type)}) - - -def main(argv): - # Debugging aid: unmask QAPI schema's type names - # We normally mask them, because they're not QMP wire ABI - opt_unmask = False - - (input_file, output_dir, do_c, do_h, prefix, opts) = \ - parse_command_line('u', ['unmask-non-abi-names']) - - for o, a in opts: - if o in ('-u', '--unmask-non-abi-names'): - opt_unmask = True - - blurb = ' * QAPI/QMP schema introspection' - - genc = QAPIGenC(blurb, __doc__) - genh = QAPIGenH(blurb, __doc__) - - genc.add(mcgen(''' -#include "qemu/osdep.h" -#include "%(prefix)sqmp-introspect.h" - -''', - prefix=prefix)) - - schema = QAPISchema(input_file) - vis = QAPISchemaGenIntrospectVisitor(prefix, opt_unmask) - schema.visit(vis) - genc.add(vis.defn) - genh.add(vis.decl) - - if do_c: - genc.write(output_dir, prefix + 'qmp-introspect.c') - if do_h: - genh.write(output_dir, prefix + 'qmp-introspect.h') - - -if __name__ == '__main__': - main(sys.argv) diff --git a/scripts/qapi-types.py b/scripts/qapi-types.py deleted file mode 100644 index 7d23544228..0000000000 --- a/scripts/qapi-types.py +++ /dev/null @@ -1,288 +0,0 @@ -""" -QAPI types generator - -Copyright IBM, Corp. 2011 -Copyright (c) 2013-2018 Red Hat Inc. - -Authors: - Anthony Liguori - Michael Roth - Markus Armbruster - -This work is licensed under the terms of the GNU GPL, version 2. -# See the COPYING file in the top-level directory. -""" - -from qapi import * - - -# variants must be emitted before their container; track what has already -# been output -objects_seen = set() - - -def gen_fwd_object_or_array(name): - return mcgen(''' - -typedef struct %(c_name)s %(c_name)s; -''', - c_name=c_name(name)) - - -def gen_array(name, element_type): - return mcgen(''' - -struct %(c_name)s { - %(c_name)s *next; - %(c_type)s value; -}; -''', - c_name=c_name(name), c_type=element_type.c_type()) - - -def gen_struct_members(members): - ret = '' - for memb in members: - if memb.optional: - ret += mcgen(''' - bool has_%(c_name)s; -''', - c_name=c_name(memb.name)) - ret += mcgen(''' - %(c_type)s %(c_name)s; -''', - c_type=memb.type.c_type(), c_name=c_name(memb.name)) - return ret - - -def gen_object(name, base, members, variants): - if name in objects_seen: - return '' - objects_seen.add(name) - - ret = '' - if variants: - for v in variants.variants: - if isinstance(v.type, QAPISchemaObjectType): - ret += gen_object(v.type.name, v.type.base, - v.type.local_members, v.type.variants) - - ret += mcgen(''' - -struct %(c_name)s { -''', - c_name=c_name(name)) - - if base: - if not base.is_implicit(): - ret += mcgen(''' - /* Members inherited from %(c_name)s: */ -''', - c_name=base.c_name()) - ret += gen_struct_members(base.members) - if not base.is_implicit(): - ret += mcgen(''' - /* Own members: */ -''') - ret += gen_struct_members(members) - - if variants: - ret += gen_variants(variants) - - # Make sure that all structs have at least one member; this avoids - # potential issues with attempting to malloc space for zero-length - # structs in C, and also incompatibility with C++ (where an empty - # struct is size 1). - if (not base or base.is_empty()) and not members and not variants: - ret += mcgen(''' - char qapi_dummy_for_empty_struct; -''') - - ret += mcgen(''' -}; -''') - - return ret - - -def gen_upcast(name, base): - # C makes const-correctness ugly. We have to cast away const to let - # this function work for both const and non-const obj. - return mcgen(''' - -static inline %(base)s *qapi_%(c_name)s_base(const %(c_name)s *obj) -{ - return (%(base)s *)obj; -} -''', - c_name=c_name(name), base=base.c_name()) - - -def gen_variants(variants): - ret = mcgen(''' - union { /* union tag is @%(c_name)s */ -''', - c_name=c_name(variants.tag_member.name)) - - for var in variants.variants: - ret += mcgen(''' - %(c_type)s %(c_name)s; -''', - c_type=var.type.c_unboxed_type(), - c_name=c_name(var.name)) - - ret += mcgen(''' - } u; -''') - - return ret - - -def gen_type_cleanup_decl(name): - ret = mcgen(''' - -void qapi_free_%(c_name)s(%(c_name)s *obj); -''', - c_name=c_name(name)) - return ret - - -def gen_type_cleanup(name): - ret = mcgen(''' - -void qapi_free_%(c_name)s(%(c_name)s *obj) -{ - Visitor *v; - - if (!obj) { - return; - } - - v = qapi_dealloc_visitor_new(); - visit_type_%(c_name)s(v, NULL, &obj, NULL); - visit_free(v); -} -''', - c_name=c_name(name)) - return ret - - -class QAPISchemaGenTypeVisitor(QAPISchemaVisitor): - def __init__(self, opt_builtins): - self._opt_builtins = opt_builtins - self.decl = None - self.defn = None - self._fwdecl = None - self._btin = None - - def visit_begin(self, schema): - # gen_object() is recursive, ensure it doesn't visit the empty type - objects_seen.add(schema.the_empty_object_type.name) - self.decl = '' - self.defn = '' - self._fwdecl = '' - self._btin = '\n' + guardstart('QAPI_TYPES_BUILTIN') - - def visit_end(self): - self.decl = self._fwdecl + self.decl - self._fwdecl = None - # To avoid header dependency hell, we always generate - # declarations for built-in types in our header files and - # simply guard them. See also opt_builtins (command line - # option -b). - self._btin += guardend('QAPI_TYPES_BUILTIN') - self.decl = self._btin + self.decl - self._btin = None - - def _gen_type_cleanup(self, name): - self.decl += gen_type_cleanup_decl(name) - self.defn += gen_type_cleanup(name) - - def visit_enum_type(self, name, info, values, prefix): - # Special case for our lone builtin enum type - # TODO use something cleaner than existence of info - if not info: - self._btin += gen_enum(name, values, prefix) - if self._opt_builtins: - self.defn += gen_enum_lookup(name, values, prefix) - else: - self._fwdecl += gen_enum(name, values, prefix) - self.defn += gen_enum_lookup(name, values, prefix) - - def visit_array_type(self, name, info, element_type): - if isinstance(element_type, QAPISchemaBuiltinType): - self._btin += gen_fwd_object_or_array(name) - self._btin += gen_array(name, element_type) - self._btin += gen_type_cleanup_decl(name) - if self._opt_builtins: - self.defn += gen_type_cleanup(name) - else: - self._fwdecl += gen_fwd_object_or_array(name) - self.decl += gen_array(name, element_type) - self._gen_type_cleanup(name) - - def visit_object_type(self, name, info, base, members, variants): - # Nothing to do for the special empty builtin - if name == 'q_empty': - return - self._fwdecl += gen_fwd_object_or_array(name) - self.decl += gen_object(name, base, members, variants) - if base and not base.is_implicit(): - self.decl += gen_upcast(name, base) - # TODO Worth changing the visitor signature, so we could - # directly use rather than repeat type.is_implicit()? - if not name.startswith('q_'): - # implicit types won't be directly allocated/freed - self._gen_type_cleanup(name) - - def visit_alternate_type(self, name, info, variants): - self._fwdecl += gen_fwd_object_or_array(name) - self.decl += gen_object(name, None, [variants.tag_member], variants) - self._gen_type_cleanup(name) - - -def main(argv): - # If you link code generated from multiple schemata, you want only one - # instance of the code for built-in types. Generate it only when - # opt_builtins, enabled by command line option -b. See also - # QAPISchemaGenTypeVisitor.visit_end(). - opt_builtins = False - - (input_file, output_dir, do_c, do_h, prefix, opts) = \ - parse_command_line('b', ['builtins']) - - for o, a in opts: - if o in ('-b', '--builtins'): - opt_builtins = True - - blurb = ' * Schema-defined QAPI types' - - genc = QAPIGenC(blurb, __doc__) - genh = QAPIGenH(blurb, __doc__) - - genc.add(mcgen(''' -#include "qemu/osdep.h" -#include "qapi/dealloc-visitor.h" -#include "%(prefix)sqapi-types.h" -#include "%(prefix)sqapi-visit.h" -''', - prefix=prefix)) - - genh.add(mcgen(''' -#include "qapi/util.h" -''')) - - schema = QAPISchema(input_file) - vis = QAPISchemaGenTypeVisitor(opt_builtins) - schema.visit(vis) - genc.add(vis.defn) - genh.add(vis.decl) - - if do_c: - genc.write(output_dir, prefix + 'qapi-types.c') - if do_h: - genh.write(output_dir, prefix + 'qapi-types.h') - - -if __name__ == '__main__': - main(sys.argv) diff --git a/scripts/qapi-visit.py b/scripts/qapi-visit.py deleted file mode 100644 index 3c23a9389d..0000000000 --- a/scripts/qapi-visit.py +++ /dev/null @@ -1,375 +0,0 @@ -""" -QAPI visitor generator - -Copyright IBM, Corp. 2011 -Copyright (C) 2014-2018 Red Hat, Inc. - -Authors: - Anthony Liguori - Michael Roth - Markus Armbruster - -This work is licensed under the terms of the GNU GPL, version 2. -See the COPYING file in the top-level directory. -""" - -from qapi import * - - -def gen_visit_decl(name, scalar=False): - c_type = c_name(name) + ' *' - if not scalar: - c_type += '*' - return mcgen(''' -void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_type)sobj, Error **errp); -''', - c_name=c_name(name), c_type=c_type) - - -def gen_visit_members_decl(name): - return mcgen(''' - -void visit_type_%(c_name)s_members(Visitor *v, %(c_name)s *obj, Error **errp); -''', - c_name=c_name(name)) - - -def gen_visit_object_members(name, base, members, variants): - ret = mcgen(''' - -void visit_type_%(c_name)s_members(Visitor *v, %(c_name)s *obj, Error **errp) -{ - Error *err = NULL; - -''', - c_name=c_name(name)) - - if base: - ret += mcgen(''' - visit_type_%(c_type)s_members(v, (%(c_type)s *)obj, &err); - if (err) { - goto out; - } -''', - c_type=base.c_name()) - - for memb in members: - if memb.optional: - ret += mcgen(''' - if (visit_optional(v, "%(name)s", &obj->has_%(c_name)s)) { -''', - name=memb.name, c_name=c_name(memb.name)) - push_indent() - ret += mcgen(''' - visit_type_%(c_type)s(v, "%(name)s", &obj->%(c_name)s, &err); - if (err) { - goto out; - } -''', - c_type=memb.type.c_name(), name=memb.name, - c_name=c_name(memb.name)) - if memb.optional: - pop_indent() - ret += mcgen(''' - } -''') - - if variants: - ret += mcgen(''' - switch (obj->%(c_name)s) { -''', - c_name=c_name(variants.tag_member.name)) - - for var in variants.variants: - ret += mcgen(''' - case %(case)s: - visit_type_%(c_type)s_members(v, &obj->u.%(c_name)s, &err); - break; -''', - case=c_enum_const(variants.tag_member.type.name, - var.name, - variants.tag_member.type.prefix), - c_type=var.type.c_name(), c_name=c_name(var.name)) - - ret += mcgen(''' - default: - abort(); - } -''') - - # 'goto out' produced for base, for each member, and if variants were - # present - if base or members or variants: - ret += mcgen(''' - -out: -''') - ret += mcgen(''' - error_propagate(errp, err); -} -''') - return ret - - -def gen_visit_list(name, element_type): - return mcgen(''' - -void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s **obj, Error **errp) -{ - Error *err = NULL; - %(c_name)s *tail; - size_t size = sizeof(**obj); - - visit_start_list(v, name, (GenericList **)obj, size, &err); - if (err) { - goto out; - } - - for (tail = *obj; tail; - tail = (%(c_name)s *)visit_next_list(v, (GenericList *)tail, size)) { - visit_type_%(c_elt_type)s(v, NULL, &tail->value, &err); - if (err) { - break; - } - } - - if (!err) { - visit_check_list(v, &err); - } - visit_end_list(v, (void **)obj); - if (err && visit_is_input(v)) { - qapi_free_%(c_name)s(*obj); - *obj = NULL; - } -out: - error_propagate(errp, err); -} -''', - c_name=c_name(name), c_elt_type=element_type.c_name()) - - -def gen_visit_enum(name): - return mcgen(''' - -void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s *obj, Error **errp) -{ - int value = *obj; - visit_type_enum(v, name, &value, &%(c_name)s_lookup, errp); - *obj = value; -} -''', - c_name=c_name(name)) - - -def gen_visit_alternate(name, variants): - ret = mcgen(''' - -void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s **obj, Error **errp) -{ - Error *err = NULL; - - visit_start_alternate(v, name, (GenericAlternate **)obj, sizeof(**obj), - &err); - if (err) { - goto out; - } - if (!*obj) { - goto out_obj; - } - switch ((*obj)->type) { -''', - c_name=c_name(name)) - - for var in variants.variants: - ret += mcgen(''' - case %(case)s: -''', - case=var.type.alternate_qtype()) - if isinstance(var.type, QAPISchemaObjectType): - ret += mcgen(''' - visit_start_struct(v, name, NULL, 0, &err); - if (err) { - break; - } - visit_type_%(c_type)s_members(v, &(*obj)->u.%(c_name)s, &err); - if (!err) { - visit_check_struct(v, &err); - } - visit_end_struct(v, NULL); -''', - c_type=var.type.c_name(), - c_name=c_name(var.name)) - else: - ret += mcgen(''' - visit_type_%(c_type)s(v, name, &(*obj)->u.%(c_name)s, &err); -''', - c_type=var.type.c_name(), - c_name=c_name(var.name)) - ret += mcgen(''' - break; -''') - - ret += mcgen(''' - case QTYPE_NONE: - abort(); - default: - error_setg(&err, QERR_INVALID_PARAMETER_TYPE, name ? name : "null", - "%(name)s"); - } -out_obj: - visit_end_alternate(v, (void **)obj); - if (err && visit_is_input(v)) { - qapi_free_%(c_name)s(*obj); - *obj = NULL; - } -out: - error_propagate(errp, err); -} -''', - name=name, c_name=c_name(name)) - - return ret - - -def gen_visit_object(name, base, members, variants): - return mcgen(''' - -void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s **obj, Error **errp) -{ - Error *err = NULL; - - visit_start_struct(v, name, (void **)obj, sizeof(%(c_name)s), &err); - if (err) { - goto out; - } - if (!*obj) { - goto out_obj; - } - visit_type_%(c_name)s_members(v, *obj, &err); - if (err) { - goto out_obj; - } - visit_check_struct(v, &err); -out_obj: - visit_end_struct(v, (void **)obj); - if (err && visit_is_input(v)) { - qapi_free_%(c_name)s(*obj); - *obj = NULL; - } -out: - error_propagate(errp, err); -} -''', - c_name=c_name(name)) - - -class QAPISchemaGenVisitVisitor(QAPISchemaVisitor): - def __init__(self, opt_builtins): - self._opt_builtins = opt_builtins - self.decl = None - self.defn = None - self._btin = None - - def visit_begin(self, schema): - self.decl = '' - self.defn = '' - self._btin = '\n' + guardstart('QAPI_VISIT_BUILTIN') - - def visit_end(self): - # To avoid header dependency hell, we always generate - # declarations for built-in types in our header files and - # simply guard them. See also opt_builtins (command line - # option -b). - self._btin += guardend('QAPI_VISIT_BUILTIN') - self.decl = self._btin + self.decl - self._btin = None - - def visit_enum_type(self, name, info, values, prefix): - # Special case for our lone builtin enum type - # TODO use something cleaner than existence of info - if not info: - self._btin += gen_visit_decl(name, scalar=True) - if self._opt_builtins: - self.defn += gen_visit_enum(name) - else: - self.decl += gen_visit_decl(name, scalar=True) - self.defn += gen_visit_enum(name) - - def visit_array_type(self, name, info, element_type): - decl = gen_visit_decl(name) - defn = gen_visit_list(name, element_type) - if isinstance(element_type, QAPISchemaBuiltinType): - self._btin += decl - if self._opt_builtins: - self.defn += defn - else: - self.decl += decl - self.defn += defn - - def visit_object_type(self, name, info, base, members, variants): - # Nothing to do for the special empty builtin - if name == 'q_empty': - return - self.decl += gen_visit_members_decl(name) - self.defn += gen_visit_object_members(name, base, members, variants) - # TODO Worth changing the visitor signature, so we could - # directly use rather than repeat type.is_implicit()? - if not name.startswith('q_'): - # only explicit types need an allocating visit - self.decl += gen_visit_decl(name) - self.defn += gen_visit_object(name, base, members, variants) - - def visit_alternate_type(self, name, info, variants): - self.decl += gen_visit_decl(name) - self.defn += gen_visit_alternate(name, variants) - - -def main(argv): - # If you link code generated from multiple schemata, you want only one - # instance of the code for built-in types. Generate it only when - # opt_builtins, enabled by command line option -b. See also - # QAPISchemaGenVisitVisitor.visit_end(). - opt_builtins = False - - (input_file, output_dir, do_c, do_h, prefix, opts) = \ - parse_command_line('b', ['builtins']) - - for o, a in opts: - if o in ('-b', '--builtins'): - opt_builtins = True - - blurb = ' * Schema-defined QAPI visitors' - - genc = QAPIGenC(blurb, __doc__) - genh = QAPIGenH(blurb, __doc__) - - genc.add(mcgen(''' -#include "qemu/osdep.h" -#include "qemu-common.h" -#include "qapi/error.h" -#include "qapi/qmp/qerror.h" -#include "%(prefix)sqapi-visit.h" -''', - prefix=prefix)) - - genh.add(mcgen(''' -#include "qapi/visitor.h" -#include "%(prefix)sqapi-types.h" - -''', - prefix=prefix)) - - schema = QAPISchema(input_file) - vis = QAPISchemaGenVisitVisitor(opt_builtins) - schema.visit(vis) - genc.add(vis.defn) - genh.add(vis.decl) - - if do_c: - genc.write(output_dir, prefix + 'qapi-visit.c') - if do_h: - genh.write(output_dir, prefix + 'qapi-visit.h') - - -if __name__ == '__main__': - main(sys.argv) diff --git a/scripts/qapi.py b/scripts/qapi.py deleted file mode 100644 index f12cdddce6..0000000000 --- a/scripts/qapi.py +++ /dev/null @@ -1,2051 +0,0 @@ -# -# QAPI helper library -# -# Copyright IBM, Corp. 2011 -# Copyright (c) 2013-2018 Red Hat Inc. -# -# Authors: -# Anthony Liguori -# Markus Armbruster -# -# This work is licensed under the terms of the GNU GPL, version 2. -# See the COPYING file in the top-level directory. - -from __future__ import print_function -import errno -import getopt -import os -import re -import string -import sys -try: - from collections import OrderedDict -except: - from ordereddict import OrderedDict - -builtin_types = { - 'null': 'QTYPE_QNULL', - 'str': 'QTYPE_QSTRING', - 'int': 'QTYPE_QNUM', - 'number': 'QTYPE_QNUM', - 'bool': 'QTYPE_QBOOL', - 'int8': 'QTYPE_QNUM', - 'int16': 'QTYPE_QNUM', - 'int32': 'QTYPE_QNUM', - 'int64': 'QTYPE_QNUM', - 'uint8': 'QTYPE_QNUM', - 'uint16': 'QTYPE_QNUM', - 'uint32': 'QTYPE_QNUM', - 'uint64': 'QTYPE_QNUM', - 'size': 'QTYPE_QNUM', - 'any': None, # any QType possible, actually - 'QType': 'QTYPE_QSTRING', -} - -# Are documentation comments required? -doc_required = False - -# Whitelist of commands allowed to return a non-dictionary -returns_whitelist = [] - -# Whitelist of entities allowed to violate case conventions -name_case_whitelist = [] - -enum_types = {} -struct_types = {} -union_types = {} -all_names = {} - -# -# Parsing the schema into expressions -# - - -def error_path(parent): - res = '' - while parent: - res = ('In file included from %s:%d:\n' % (parent['file'], - parent['line'])) + res - parent = parent['parent'] - return res - - -class QAPIError(Exception): - def __init__(self, fname, line, col, incl_info, msg): - Exception.__init__(self) - self.fname = fname - self.line = line - self.col = col - self.info = incl_info - self.msg = msg - - def __str__(self): - loc = '%s:%d' % (self.fname, self.line) - if self.col is not None: - loc += ':%s' % self.col - return error_path(self.info) + '%s: %s' % (loc, self.msg) - - -class QAPIParseError(QAPIError): - def __init__(self, parser, msg): - col = 1 - for ch in parser.src[parser.line_pos:parser.pos]: - if ch == '\t': - col = (col + 7) % 8 + 1 - else: - col += 1 - QAPIError.__init__(self, parser.fname, parser.line, col, - parser.incl_info, msg) - - -class QAPISemError(QAPIError): - def __init__(self, info, msg): - QAPIError.__init__(self, info['file'], info['line'], None, - info['parent'], msg) - - -class QAPIDoc(object): - class Section(object): - def __init__(self, name=None): - # optional section name (argument/member or section name) - self.name = name - # the list of lines for this section - self.text = '' - - def append(self, line): - self.text += line.rstrip() + '\n' - - class ArgSection(Section): - def __init__(self, name): - QAPIDoc.Section.__init__(self, name) - self.member = None - - def connect(self, member): - self.member = member - - def __init__(self, parser, info): - # self._parser is used to report errors with QAPIParseError. The - # resulting error position depends on the state of the parser. - # It happens to be the beginning of the comment. More or less - # servicable, but action at a distance. - self._parser = parser - self.info = info - self.symbol = None - self.body = QAPIDoc.Section() - # dict mapping parameter name to ArgSection - self.args = OrderedDict() - # a list of Section - self.sections = [] - # the current section - self._section = self.body - - def has_section(self, name): - """Return True if we have a section with this name.""" - for i in self.sections: - if i.name == name: - return True - return False - - def append(self, line): - """Parse a comment line and add it to the documentation.""" - line = line[1:] - if not line: - self._append_freeform(line) - return - - if line[0] != ' ': - raise QAPIParseError(self._parser, "Missing space after #") - line = line[1:] - - # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't - # recognized, and get silently treated as ordinary text - if self.symbol: - self._append_symbol_line(line) - elif not self.body.text and line.startswith('@'): - if not line.endswith(':'): - raise QAPIParseError(self._parser, "Line should end with :") - self.symbol = line[1:-1] - # FIXME invalid names other than the empty string aren't flagged - if not self.symbol: - raise QAPIParseError(self._parser, "Invalid name") - else: - self._append_freeform(line) - - def end_comment(self): - self._end_section() - - def _append_symbol_line(self, line): - name = line.split(' ', 1)[0] - - if name.startswith('@') and name.endswith(':'): - line = line[len(name)+1:] - self._start_args_section(name[1:-1]) - elif name in ('Returns:', 'Since:', - # those are often singular or plural - 'Note:', 'Notes:', - 'Example:', 'Examples:', - 'TODO:'): - line = line[len(name)+1:] - self._start_section(name[:-1]) - - self._append_freeform(line) - - def _start_args_section(self, name): - # FIXME invalid names other than the empty string aren't flagged - if not name: - raise QAPIParseError(self._parser, "Invalid parameter name") - if name in self.args: - raise QAPIParseError(self._parser, - "'%s' parameter name duplicated" % name) - if self.sections: - raise QAPIParseError(self._parser, - "'@%s:' can't follow '%s' section" - % (name, self.sections[0].name)) - self._end_section() - self._section = QAPIDoc.ArgSection(name) - self.args[name] = self._section - - def _start_section(self, name=None): - if name in ('Returns', 'Since') and self.has_section(name): - raise QAPIParseError(self._parser, - "Duplicated '%s' section" % name) - self._end_section() - self._section = QAPIDoc.Section(name) - self.sections.append(self._section) - - def _end_section(self): - if self._section: - text = self._section.text = self._section.text.strip() - if self._section.name and (not text or text.isspace()): - raise QAPIParseError(self._parser, "Empty doc section '%s'" - % self._section.name) - self._section = None - - def _append_freeform(self, line): - in_arg = isinstance(self._section, QAPIDoc.ArgSection) - if (in_arg and self._section.text.endswith('\n\n') - and line and not line[0].isspace()): - self._start_section() - if (in_arg or not self._section.name - or not self._section.name.startswith('Example')): - line = line.strip() - match = re.match(r'(@\S+:)', line) - if match: - raise QAPIParseError(self._parser, - "'%s' not allowed in free-form documentation" - % match.group(1)) - self._section.append(line) - - def connect_member(self, member): - if member.name not in self.args: - # Undocumented TODO outlaw - self.args[member.name] = QAPIDoc.ArgSection(member.name) - self.args[member.name].connect(member) - - def check_expr(self, expr): - if self.has_section('Returns') and 'command' not in expr: - raise QAPISemError(self.info, - "'Returns:' is only valid for commands") - - def check(self): - bogus = [name for name, section in self.args.items() - if not section.member] - if bogus: - raise QAPISemError( - self.info, - "The following documented members are not in " - "the declaration: %s" % ", ".join(bogus)) - - -class QAPISchemaParser(object): - - def __init__(self, fp, previously_included=[], incl_info=None): - abs_fname = os.path.abspath(fp.name) - self.fname = fp.name - previously_included.append(abs_fname) - self.incl_info = incl_info - self.src = fp.read() - if self.src == '' or self.src[-1] != '\n': - self.src += '\n' - self.cursor = 0 - self.line = 1 - self.line_pos = 0 - self.exprs = [] - self.docs = [] - self.accept() - cur_doc = None - - while self.tok is not None: - info = {'file': self.fname, 'line': self.line, - 'parent': self.incl_info} - if self.tok == '#': - self.reject_expr_doc(cur_doc) - cur_doc = self.get_doc(info) - self.docs.append(cur_doc) - continue - - expr = self.get_expr(False) - if 'include' in expr: - self.reject_expr_doc(cur_doc) - if len(expr) != 1: - raise QAPISemError(info, "Invalid 'include' directive") - include = expr['include'] - if not isinstance(include, str): - raise QAPISemError(info, - "Value of 'include' must be a string") - self._include(include, info, os.path.dirname(abs_fname), - previously_included) - elif "pragma" in expr: - self.reject_expr_doc(cur_doc) - if len(expr) != 1: - raise QAPISemError(info, "Invalid 'pragma' directive") - pragma = expr['pragma'] - if not isinstance(pragma, dict): - raise QAPISemError( - info, "Value of 'pragma' must be a dictionary") - for name, value in pragma.items(): - self._pragma(name, value, info) - else: - expr_elem = {'expr': expr, - 'info': info} - if cur_doc: - if not cur_doc.symbol: - raise QAPISemError( - cur_doc.info, "Expression documentation required") - expr_elem['doc'] = cur_doc - self.exprs.append(expr_elem) - cur_doc = None - self.reject_expr_doc(cur_doc) - - @staticmethod - def reject_expr_doc(doc): - if doc and doc.symbol: - raise QAPISemError( - doc.info, - "Documentation for '%s' is not followed by the definition" - % doc.symbol) - - def _include(self, include, info, base_dir, previously_included): - incl_abs_fname = os.path.join(base_dir, include) - # catch inclusion cycle - inf = info - while inf: - if incl_abs_fname == os.path.abspath(inf['file']): - raise QAPISemError(info, "Inclusion loop for %s" % include) - inf = inf['parent'] - - # skip multiple include of the same file - if incl_abs_fname in previously_included: - return - try: - fobj = open(incl_abs_fname, 'r') - except IOError as e: - raise QAPISemError(info, '%s: %s' % (e.strerror, include)) - exprs_include = QAPISchemaParser(fobj, previously_included, info) - self.exprs.extend(exprs_include.exprs) - self.docs.extend(exprs_include.docs) - - def _pragma(self, name, value, info): - global doc_required, returns_whitelist, name_case_whitelist - if name == 'doc-required': - if not isinstance(value, bool): - raise QAPISemError(info, - "Pragma 'doc-required' must be boolean") - doc_required = value - elif name == 'returns-whitelist': - if (not isinstance(value, list) - or any([not isinstance(elt, str) for elt in value])): - raise QAPISemError(info, - "Pragma returns-whitelist must be" - " a list of strings") - returns_whitelist = value - elif name == 'name-case-whitelist': - if (not isinstance(value, list) - or any([not isinstance(elt, str) for elt in value])): - raise QAPISemError(info, - "Pragma name-case-whitelist must be" - " a list of strings") - name_case_whitelist = value - else: - raise QAPISemError(info, "Unknown pragma '%s'" % name) - - def accept(self, skip_comment=True): - while True: - self.tok = self.src[self.cursor] - self.pos = self.cursor - self.cursor += 1 - self.val = None - - if self.tok == '#': - if self.src[self.cursor] == '#': - # Start of doc comment - skip_comment = False - self.cursor = self.src.find('\n', self.cursor) - if not skip_comment: - self.val = self.src[self.pos:self.cursor] - return - elif self.tok in '{}:,[]': - return - elif self.tok == "'": - string = '' - esc = False - while True: - ch = self.src[self.cursor] - self.cursor += 1 - if ch == '\n': - raise QAPIParseError(self, 'Missing terminating "\'"') - if esc: - if ch == 'b': - string += '\b' - elif ch == 'f': - string += '\f' - elif ch == 'n': - string += '\n' - elif ch == 'r': - string += '\r' - elif ch == 't': - string += '\t' - elif ch == 'u': - value = 0 - for _ in range(0, 4): - ch = self.src[self.cursor] - self.cursor += 1 - if ch not in '0123456789abcdefABCDEF': - raise QAPIParseError(self, - '\\u escape needs 4 ' - 'hex digits') - value = (value << 4) + int(ch, 16) - # If Python 2 and 3 didn't disagree so much on - # how to handle Unicode, then we could allow - # Unicode string defaults. But most of QAPI is - # ASCII-only, so we aren't losing much for now. - if not value or value > 0x7f: - raise QAPIParseError(self, - 'For now, \\u escape ' - 'only supports non-zero ' - 'values up to \\u007f') - string += chr(value) - elif ch in '\\/\'"': - string += ch - else: - raise QAPIParseError(self, - "Unknown escape \\%s" % ch) - esc = False - elif ch == '\\': - esc = True - elif ch == "'": - self.val = string - return - else: - string += ch - elif self.src.startswith('true', self.pos): - self.val = True - self.cursor += 3 - return - elif self.src.startswith('false', self.pos): - self.val = False - self.cursor += 4 - return - elif self.src.startswith('null', self.pos): - self.val = None - self.cursor += 3 - return - elif self.tok == '\n': - if self.cursor == len(self.src): - self.tok = None - return - self.line += 1 - self.line_pos = self.cursor - elif not self.tok.isspace(): - raise QAPIParseError(self, 'Stray "%s"' % self.tok) - - def get_members(self): - expr = OrderedDict() - if self.tok == '}': - self.accept() - return expr - if self.tok != "'": - raise QAPIParseError(self, 'Expected string or "}"') - while True: - key = self.val - self.accept() - if self.tok != ':': - raise QAPIParseError(self, 'Expected ":"') - self.accept() - if key in expr: - raise QAPIParseError(self, 'Duplicate key "%s"' % key) - expr[key] = self.get_expr(True) - if self.tok == '}': - self.accept() - return expr - if self.tok != ',': - raise QAPIParseError(self, 'Expected "," or "}"') - self.accept() - if self.tok != "'": - raise QAPIParseError(self, 'Expected string') - - def get_values(self): - expr = [] - if self.tok == ']': - self.accept() - return expr - if self.tok not in "{['tfn": - raise QAPIParseError(self, 'Expected "{", "[", "]", string, ' - 'boolean or "null"') - while True: - expr.append(self.get_expr(True)) - if self.tok == ']': - self.accept() - return expr - if self.tok != ',': - raise QAPIParseError(self, 'Expected "," or "]"') - self.accept() - - def get_expr(self, nested): - if self.tok != '{' and not nested: - raise QAPIParseError(self, 'Expected "{"') - if self.tok == '{': - self.accept() - expr = self.get_members() - elif self.tok == '[': - self.accept() - expr = self.get_values() - elif self.tok in "'tfn": - expr = self.val - self.accept() - else: - raise QAPIParseError(self, 'Expected "{", "[", string, ' - 'boolean or "null"') - return expr - - def get_doc(self, info): - if self.val != '##': - raise QAPIParseError(self, "Junk after '##' at start of " - "documentation comment") - - doc = QAPIDoc(self, info) - self.accept(False) - while self.tok == '#': - if self.val.startswith('##'): - # End of doc comment - if self.val != '##': - raise QAPIParseError(self, "Junk after '##' at end of " - "documentation comment") - doc.end_comment() - self.accept() - return doc - else: - doc.append(self.val) - self.accept(False) - - raise QAPIParseError(self, "Documentation comment must end with '##'") - - -# -# Semantic analysis of schema expressions -# TODO fold into QAPISchema -# TODO catching name collisions in generated code would be nice -# - - -def find_base_members(base): - if isinstance(base, dict): - return base - base_struct_define = struct_types.get(base) - if not base_struct_define: - return None - return base_struct_define['data'] - - -# Return the qtype of an alternate branch, or None on error. -def find_alternate_member_qtype(qapi_type): - if qapi_type in builtin_types: - return builtin_types[qapi_type] - elif qapi_type in struct_types: - return 'QTYPE_QDICT' - elif qapi_type in enum_types: - return 'QTYPE_QSTRING' - elif qapi_type in union_types: - return 'QTYPE_QDICT' - return None - - -# Return the discriminator enum define if discriminator is specified as an -# enum type, otherwise return None. -def discriminator_find_enum_define(expr): - base = expr.get('base') - discriminator = expr.get('discriminator') - - if not (discriminator and base): - return None - - base_members = find_base_members(base) - if not base_members: - return None - - discriminator_type = base_members.get(discriminator) - if not discriminator_type: - return None - - return enum_types.get(discriminator_type) - - -# Names must be letters, numbers, -, and _. They must start with letter, -# except for downstream extensions which must start with __RFQDN_. -# Dots are only valid in the downstream extension prefix. -valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?' - '[a-zA-Z][a-zA-Z0-9_-]*$') - - -def check_name(info, source, name, allow_optional=False, - enum_member=False): - global valid_name - membername = name - - if not isinstance(name, str): - raise QAPISemError(info, "%s requires a string name" % source) - if name.startswith('*'): - membername = name[1:] - if not allow_optional: - raise QAPISemError(info, "%s does not allow optional name '%s'" - % (source, name)) - # Enum members can start with a digit, because the generated C - # code always prefixes it with the enum name - if enum_member and membername[0].isdigit(): - membername = 'D' + membername - # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty' - # and 'q_obj_*' implicit type names. - if not valid_name.match(membername) or \ - c_name(membername, False).startswith('q_'): - raise QAPISemError(info, "%s uses invalid name '%s'" % (source, name)) - - -def add_name(name, info, meta, implicit=False): - global all_names - check_name(info, "'%s'" % meta, name) - # FIXME should reject names that differ only in '_' vs. '.' - # vs. '-', because they're liable to clash in generated C. - if name in all_names: - raise QAPISemError(info, "%s '%s' is already defined" - % (all_names[name], name)) - if not implicit and (name.endswith('Kind') or name.endswith('List')): - raise QAPISemError(info, "%s '%s' should not end in '%s'" - % (meta, name, name[-4:])) - all_names[name] = meta - - -def check_type(info, source, value, allow_array=False, - allow_dict=False, allow_optional=False, - allow_metas=[]): - global all_names - - if value is None: - return - - # Check if array type for value is okay - if isinstance(value, list): - if not allow_array: - raise QAPISemError(info, "%s cannot be an array" % source) - if len(value) != 1 or not isinstance(value[0], str): - raise QAPISemError(info, - "%s: array type must contain single type name" % - source) - value = value[0] - - # Check if type name for value is okay - if isinstance(value, str): - if value not in all_names: - raise QAPISemError(info, "%s uses unknown type '%s'" - % (source, value)) - if not all_names[value] in allow_metas: - raise QAPISemError(info, "%s cannot use %s type '%s'" % - (source, all_names[value], value)) - return - - if not allow_dict: - raise QAPISemError(info, "%s should be a type name" % source) - - if not isinstance(value, OrderedDict): - raise QAPISemError(info, - "%s should be a dictionary or type name" % source) - - # value is a dictionary, check that each member is okay - for (key, arg) in value.items(): - check_name(info, "Member of %s" % source, key, - allow_optional=allow_optional) - if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'): - raise QAPISemError(info, "Member of %s uses reserved name '%s'" - % (source, key)) - # Todo: allow dictionaries to represent default values of - # an optional argument. - check_type(info, "Member '%s' of %s" % (key, source), arg, - allow_array=True, - allow_metas=['built-in', 'union', 'alternate', 'struct', - 'enum']) - - -def check_command(expr, info): - name = expr['command'] - boxed = expr.get('boxed', False) - - args_meta = ['struct'] - if boxed: - args_meta += ['union', 'alternate'] - check_type(info, "'data' for command '%s'" % name, - expr.get('data'), allow_dict=not boxed, allow_optional=True, - allow_metas=args_meta) - returns_meta = ['union', 'struct'] - if name in returns_whitelist: - returns_meta += ['built-in', 'alternate', 'enum'] - check_type(info, "'returns' for command '%s'" % name, - expr.get('returns'), allow_array=True, - allow_optional=True, allow_metas=returns_meta) - - -def check_event(expr, info): - name = expr['event'] - boxed = expr.get('boxed', False) - - meta = ['struct'] - if boxed: - meta += ['union', 'alternate'] - check_type(info, "'data' for event '%s'" % name, - expr.get('data'), allow_dict=not boxed, allow_optional=True, - allow_metas=meta) - - -def check_union(expr, info): - name = expr['union'] - base = expr.get('base') - discriminator = expr.get('discriminator') - members = expr['data'] - - # Two types of unions, determined by discriminator. - - # With no discriminator it is a simple union. - if discriminator is None: - enum_define = None - allow_metas = ['built-in', 'union', 'alternate', 'struct', 'enum'] - if base is not None: - raise QAPISemError(info, "Simple union '%s' must not have a base" % - name) - - # Else, it's a flat union. - else: - # The object must have a string or dictionary 'base'. - check_type(info, "'base' for union '%s'" % name, - base, allow_dict=True, allow_optional=True, - allow_metas=['struct']) - if not base: - raise QAPISemError(info, "Flat union '%s' must have a base" - % name) - base_members = find_base_members(base) - assert base_members is not None - - # The value of member 'discriminator' must name a non-optional - # member of the base struct. - check_name(info, "Discriminator of flat union '%s'" % name, - discriminator) - discriminator_type = base_members.get(discriminator) - if not discriminator_type: - raise QAPISemError(info, - "Discriminator '%s' is not a member of base " - "struct '%s'" - % (discriminator, base)) - enum_define = enum_types.get(discriminator_type) - allow_metas = ['struct'] - # Do not allow string discriminator - if not enum_define: - raise QAPISemError(info, - "Discriminator '%s' must be of enumeration " - "type" % discriminator) - - # Check every branch; don't allow an empty union - if len(members) == 0: - raise QAPISemError(info, "Union '%s' cannot have empty 'data'" % name) - for (key, value) in members.items(): - check_name(info, "Member of union '%s'" % name, key) - - # Each value must name a known type - check_type(info, "Member '%s' of union '%s'" % (key, name), - value, allow_array=not base, allow_metas=allow_metas) - - # If the discriminator names an enum type, then all members - # of 'data' must also be members of the enum type. - if enum_define: - if key not in enum_define['data']: - raise QAPISemError(info, - "Discriminator value '%s' is not found in " - "enum '%s'" - % (key, enum_define['enum'])) - - # If discriminator is user-defined, ensure all values are covered - if enum_define: - for value in enum_define['data']: - if value not in members.keys(): - raise QAPISemError(info, "Union '%s' data missing '%s' branch" - % (name, value)) - - -def check_alternate(expr, info): - name = expr['alternate'] - members = expr['data'] - types_seen = {} - - # Check every branch; require at least two branches - if len(members) < 2: - raise QAPISemError(info, - "Alternate '%s' should have at least two branches " - "in 'data'" % name) - for (key, value) in members.items(): - check_name(info, "Member of alternate '%s'" % name, key) - - # Ensure alternates have no type conflicts. - check_type(info, "Member '%s' of alternate '%s'" % (key, name), - value, - allow_metas=['built-in', 'union', 'struct', 'enum']) - qtype = find_alternate_member_qtype(value) - if not qtype: - raise QAPISemError(info, "Alternate '%s' member '%s' cannot use " - "type '%s'" % (name, key, value)) - conflicting = set([qtype]) - if qtype == 'QTYPE_QSTRING': - enum_expr = enum_types.get(value) - if enum_expr: - for v in enum_expr['data']: - if v in ['on', 'off']: - conflicting.add('QTYPE_QBOOL') - if re.match(r'[-+0-9.]', v): # lazy, could be tightened - conflicting.add('QTYPE_QNUM') - else: - conflicting.add('QTYPE_QNUM') - conflicting.add('QTYPE_QBOOL') - for qt in conflicting: - if qt in types_seen: - raise QAPISemError(info, "Alternate '%s' member '%s' can't " - "be distinguished from member '%s'" - % (name, key, types_seen[qt])) - types_seen[qt] = key - - -def check_enum(expr, info): - name = expr['enum'] - members = expr.get('data') - prefix = expr.get('prefix') - - if not isinstance(members, list): - raise QAPISemError(info, - "Enum '%s' requires an array for 'data'" % name) - if prefix is not None and not isinstance(prefix, str): - raise QAPISemError(info, - "Enum '%s' requires a string for 'prefix'" % name) - for member in members: - check_name(info, "Member of enum '%s'" % name, member, - enum_member=True) - - -def check_struct(expr, info): - name = expr['struct'] - members = expr['data'] - - check_type(info, "'data' for struct '%s'" % name, members, - allow_dict=True, allow_optional=True) - check_type(info, "'base' for struct '%s'" % name, expr.get('base'), - allow_metas=['struct']) - - -def check_keys(expr_elem, meta, required, optional=[]): - expr = expr_elem['expr'] - info = expr_elem['info'] - name = expr[meta] - if not isinstance(name, str): - raise QAPISemError(info, "'%s' key must have a string value" % meta) - required = required + [meta] - for (key, value) in expr.items(): - if key not in required and key not in optional: - raise QAPISemError(info, "Unknown key '%s' in %s '%s'" - % (key, meta, name)) - if (key == 'gen' or key == 'success-response') and value is not False: - raise QAPISemError(info, - "'%s' of %s '%s' should only use false value" - % (key, meta, name)) - if key == 'boxed' and value is not True: - raise QAPISemError(info, - "'%s' of %s '%s' should only use true value" - % (key, meta, name)) - for key in required: - if key not in expr: - raise QAPISemError(info, "Key '%s' is missing from %s '%s'" - % (key, meta, name)) - - -def check_exprs(exprs): - global all_names - - # Populate name table with names of built-in types - for builtin in builtin_types.keys(): - all_names[builtin] = 'built-in' - - # Learn the types and check for valid expression keys - for expr_elem in exprs: - expr = expr_elem['expr'] - info = expr_elem['info'] - doc = expr_elem.get('doc') - - if not doc and doc_required: - raise QAPISemError(info, - "Expression missing documentation comment") - - if 'enum' in expr: - meta = 'enum' - check_keys(expr_elem, 'enum', ['data'], ['prefix']) - enum_types[expr[meta]] = expr - elif 'union' in expr: - meta = 'union' - check_keys(expr_elem, 'union', ['data'], - ['base', 'discriminator']) - union_types[expr[meta]] = expr - elif 'alternate' in expr: - meta = 'alternate' - check_keys(expr_elem, 'alternate', ['data']) - elif 'struct' in expr: - meta = 'struct' - check_keys(expr_elem, 'struct', ['data'], ['base']) - struct_types[expr[meta]] = expr - elif 'command' in expr: - meta = 'command' - check_keys(expr_elem, 'command', [], - ['data', 'returns', 'gen', 'success-response', 'boxed']) - elif 'event' in expr: - meta = 'event' - check_keys(expr_elem, 'event', [], ['data', 'boxed']) - else: - raise QAPISemError(expr_elem['info'], - "Expression is missing metatype") - name = expr[meta] - add_name(name, info, meta) - if doc and doc.symbol != name: - raise QAPISemError(info, "Definition of '%s' follows documentation" - " for '%s'" % (name, doc.symbol)) - - # Try again for hidden UnionKind enum - for expr_elem in exprs: - expr = expr_elem['expr'] - if 'union' in expr and not discriminator_find_enum_define(expr): - name = '%sKind' % expr['union'] - elif 'alternate' in expr: - name = '%sKind' % expr['alternate'] - else: - continue - enum_types[name] = {'enum': name} - add_name(name, info, 'enum', implicit=True) - - # Validate that exprs make sense - for expr_elem in exprs: - expr = expr_elem['expr'] - info = expr_elem['info'] - doc = expr_elem.get('doc') - - if 'enum' in expr: - check_enum(expr, info) - elif 'union' in expr: - check_union(expr, info) - elif 'alternate' in expr: - check_alternate(expr, info) - elif 'struct' in expr: - check_struct(expr, info) - elif 'command' in expr: - check_command(expr, info) - elif 'event' in expr: - check_event(expr, info) - else: - assert False, 'unexpected meta type' - - if doc: - doc.check_expr(expr) - - return exprs - - -# -# Schema compiler frontend -# - -class QAPISchemaEntity(object): - def __init__(self, name, info, doc): - assert isinstance(name, str) - self.name = name - # For explicitly defined entities, info points to the (explicit) - # definition. For builtins (and their arrays), info is None. - # For implicitly defined entities, info points to a place that - # triggered the implicit definition (there may be more than one - # such place). - self.info = info - self.doc = doc - - def c_name(self): - return c_name(self.name) - - def check(self, schema): - pass - - def is_implicit(self): - return not self.info - - def visit(self, visitor): - pass - - -class QAPISchemaVisitor(object): - def visit_begin(self, schema): - pass - - def visit_end(self): - pass - - def visit_needed(self, entity): - # Default to visiting everything - return True - - def visit_builtin_type(self, name, info, json_type): - pass - - def visit_enum_type(self, name, info, values, prefix): - pass - - def visit_array_type(self, name, info, element_type): - pass - - def visit_object_type(self, name, info, base, members, variants): - pass - - def visit_object_type_flat(self, name, info, members, variants): - pass - - def visit_alternate_type(self, name, info, variants): - pass - - def visit_command(self, name, info, arg_type, ret_type, - gen, success_response, boxed): - pass - - def visit_event(self, name, info, arg_type, boxed): - pass - - -class QAPISchemaType(QAPISchemaEntity): - # Return the C type for common use. - # For the types we commonly box, this is a pointer type. - def c_type(self): - pass - - # Return the C type to be used in a parameter list. - def c_param_type(self): - return self.c_type() - - # Return the C type to be used where we suppress boxing. - def c_unboxed_type(self): - return self.c_type() - - def json_type(self): - pass - - def alternate_qtype(self): - json2qtype = { - 'null': 'QTYPE_QNULL', - 'string': 'QTYPE_QSTRING', - 'number': 'QTYPE_QNUM', - 'int': 'QTYPE_QNUM', - 'boolean': 'QTYPE_QBOOL', - 'object': 'QTYPE_QDICT' - } - return json2qtype.get(self.json_type()) - - def doc_type(self): - if self.is_implicit(): - return None - return self.name - - -class QAPISchemaBuiltinType(QAPISchemaType): - def __init__(self, name, json_type, c_type): - QAPISchemaType.__init__(self, name, None, None) - assert not c_type or isinstance(c_type, str) - assert json_type in ('string', 'number', 'int', 'boolean', 'null', - 'value') - self._json_type_name = json_type - self._c_type_name = c_type - - def c_name(self): - return self.name - - def c_type(self): - return self._c_type_name - - def c_param_type(self): - if self.name == 'str': - return 'const ' + self._c_type_name - return self._c_type_name - - def json_type(self): - return self._json_type_name - - def doc_type(self): - return self.json_type() - - def visit(self, visitor): - visitor.visit_builtin_type(self.name, self.info, self.json_type()) - - -class QAPISchemaEnumType(QAPISchemaType): - def __init__(self, name, info, doc, values, prefix): - QAPISchemaType.__init__(self, name, info, doc) - for v in values: - assert isinstance(v, QAPISchemaMember) - v.set_owner(name) - assert prefix is None or isinstance(prefix, str) - self.values = values - self.prefix = prefix - - def check(self, schema): - seen = {} - for v in self.values: - v.check_clash(self.info, seen) - if self.doc: - self.doc.connect_member(v) - - def is_implicit(self): - # See QAPISchema._make_implicit_enum_type() and ._def_predefineds() - return self.name.endswith('Kind') or self.name == 'QType' - - def c_type(self): - return c_name(self.name) - - def member_names(self): - return [v.name for v in self.values] - - def json_type(self): - return 'string' - - def visit(self, visitor): - visitor.visit_enum_type(self.name, self.info, - self.member_names(), self.prefix) - - -class QAPISchemaArrayType(QAPISchemaType): - def __init__(self, name, info, element_type): - QAPISchemaType.__init__(self, name, info, None) - assert isinstance(element_type, str) - self._element_type_name = element_type - self.element_type = None - - def check(self, schema): - self.element_type = schema.lookup_type(self._element_type_name) - assert self.element_type - - def is_implicit(self): - return True - - def c_type(self): - return c_name(self.name) + pointer_suffix - - def json_type(self): - return 'array' - - def doc_type(self): - elt_doc_type = self.element_type.doc_type() - if not elt_doc_type: - return None - return 'array of ' + elt_doc_type - - def visit(self, visitor): - visitor.visit_array_type(self.name, self.info, self.element_type) - - -class QAPISchemaObjectType(QAPISchemaType): - def __init__(self, name, info, doc, base, local_members, variants): - # struct has local_members, optional base, and no variants - # flat union has base, variants, and no local_members - # simple union has local_members, variants, and no base - QAPISchemaType.__init__(self, name, info, doc) - assert base is None or isinstance(base, str) - for m in local_members: - assert isinstance(m, QAPISchemaObjectTypeMember) - m.set_owner(name) - if variants is not None: - assert isinstance(variants, QAPISchemaObjectTypeVariants) - variants.set_owner(name) - self._base_name = base - self.base = None - self.local_members = local_members - self.variants = variants - self.members = None - - def check(self, schema): - if self.members is False: # check for cycles - raise QAPISemError(self.info, - "Object %s contains itself" % self.name) - if self.members: - return - self.members = False # mark as being checked - seen = OrderedDict() - if self._base_name: - self.base = schema.lookup_type(self._base_name) - assert isinstance(self.base, QAPISchemaObjectType) - self.base.check(schema) - self.base.check_clash(self.info, seen) - for m in self.local_members: - m.check(schema) - m.check_clash(self.info, seen) - if self.doc: - self.doc.connect_member(m) - self.members = seen.values() - if self.variants: - self.variants.check(schema, seen) - assert self.variants.tag_member in self.members - self.variants.check_clash(self.info, seen) - if self.doc: - self.doc.check() - - # Check that the members of this type do not cause duplicate JSON members, - # and update seen to track the members seen so far. Report any errors - # on behalf of info, which is not necessarily self.info - def check_clash(self, info, seen): - assert not self.variants # not implemented - for m in self.members: - m.check_clash(info, seen) - - def is_implicit(self): - # See QAPISchema._make_implicit_object_type(), as well as - # _def_predefineds() - return self.name.startswith('q_') - - def is_empty(self): - assert self.members is not None - return not self.members and not self.variants - - def c_name(self): - assert self.name != 'q_empty' - return QAPISchemaType.c_name(self) - - def c_type(self): - assert not self.is_implicit() - return c_name(self.name) + pointer_suffix - - def c_unboxed_type(self): - return c_name(self.name) - - def json_type(self): - return 'object' - - def visit(self, visitor): - visitor.visit_object_type(self.name, self.info, - self.base, self.local_members, self.variants) - visitor.visit_object_type_flat(self.name, self.info, - self.members, self.variants) - - -class QAPISchemaMember(object): - role = 'member' - - def __init__(self, name): - assert isinstance(name, str) - self.name = name - self.owner = None - - def set_owner(self, name): - assert not self.owner - self.owner = name - - def check_clash(self, info, seen): - cname = c_name(self.name) - if cname.lower() != cname and self.owner not in name_case_whitelist: - raise QAPISemError(info, - "%s should not use uppercase" % self.describe()) - if cname in seen: - raise QAPISemError(info, "%s collides with %s" % - (self.describe(), seen[cname].describe())) - seen[cname] = self - - def _pretty_owner(self): - owner = self.owner - if owner.startswith('q_obj_'): - # See QAPISchema._make_implicit_object_type() - reverse the - # mapping there to create a nice human-readable description - owner = owner[6:] - if owner.endswith('-arg'): - return '(parameter of %s)' % owner[:-4] - elif owner.endswith('-base'): - return '(base of %s)' % owner[:-5] - else: - assert owner.endswith('-wrapper') - # Unreachable and not implemented - assert False - if owner.endswith('Kind'): - # See QAPISchema._make_implicit_enum_type() - return '(branch of %s)' % owner[:-4] - return '(%s of %s)' % (self.role, owner) - - def describe(self): - return "'%s' %s" % (self.name, self._pretty_owner()) - - -class QAPISchemaObjectTypeMember(QAPISchemaMember): - def __init__(self, name, typ, optional): - QAPISchemaMember.__init__(self, name) - assert isinstance(typ, str) - assert isinstance(optional, bool) - self._type_name = typ - self.type = None - self.optional = optional - - def check(self, schema): - assert self.owner - self.type = schema.lookup_type(self._type_name) - assert self.type - - -class QAPISchemaObjectTypeVariants(object): - def __init__(self, tag_name, tag_member, variants): - # Flat unions pass tag_name but not tag_member. - # Simple unions and alternates pass tag_member but not tag_name. - # After check(), tag_member is always set, and tag_name remains - # a reliable witness of being used by a flat union. - assert bool(tag_member) != bool(tag_name) - assert (isinstance(tag_name, str) or - isinstance(tag_member, QAPISchemaObjectTypeMember)) - assert len(variants) > 0 - for v in variants: - assert isinstance(v, QAPISchemaObjectTypeVariant) - self._tag_name = tag_name - self.tag_member = tag_member - self.variants = variants - - def set_owner(self, name): - for v in self.variants: - v.set_owner(name) - - def check(self, schema, seen): - if not self.tag_member: # flat union - self.tag_member = seen[c_name(self._tag_name)] - assert self._tag_name == self.tag_member.name - assert isinstance(self.tag_member.type, QAPISchemaEnumType) - for v in self.variants: - v.check(schema) - # Union names must match enum values; alternate names are - # checked separately. Use 'seen' to tell the two apart. - if seen: - assert v.name in self.tag_member.type.member_names() - assert isinstance(v.type, QAPISchemaObjectType) - v.type.check(schema) - - def check_clash(self, info, seen): - for v in self.variants: - # Reset seen map for each variant, since qapi names from one - # branch do not affect another branch - assert isinstance(v.type, QAPISchemaObjectType) - v.type.check_clash(info, dict(seen)) - - -class QAPISchemaObjectTypeVariant(QAPISchemaObjectTypeMember): - role = 'branch' - - def __init__(self, name, typ): - QAPISchemaObjectTypeMember.__init__(self, name, typ, False) - - -class QAPISchemaAlternateType(QAPISchemaType): - def __init__(self, name, info, doc, variants): - QAPISchemaType.__init__(self, name, info, doc) - assert isinstance(variants, QAPISchemaObjectTypeVariants) - assert variants.tag_member - variants.set_owner(name) - variants.tag_member.set_owner(self.name) - self.variants = variants - - def check(self, schema): - self.variants.tag_member.check(schema) - # Not calling self.variants.check_clash(), because there's nothing - # to clash with - self.variants.check(schema, {}) - # Alternate branch names have no relation to the tag enum values; - # so we have to check for potential name collisions ourselves. - seen = {} - for v in self.variants.variants: - v.check_clash(self.info, seen) - if self.doc: - self.doc.connect_member(v) - if self.doc: - self.doc.check() - - def c_type(self): - return c_name(self.name) + pointer_suffix - - def json_type(self): - return 'value' - - 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, doc, arg_type, ret_type, - gen, success_response, boxed): - QAPISchemaEntity.__init__(self, name, info, doc) - assert not arg_type or isinstance(arg_type, str) - assert not ret_type or isinstance(ret_type, str) - self._arg_type_name = arg_type - self.arg_type = None - self._ret_type_name = ret_type - self.ret_type = None - self.gen = gen - self.success_response = success_response - self.boxed = boxed - - 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) or - isinstance(self.arg_type, QAPISchemaAlternateType)) - self.arg_type.check(schema) - if self.boxed: - if self.arg_type.is_empty(): - raise QAPISemError(self.info, - "Cannot use 'boxed' with empty type") - else: - assert not isinstance(self.arg_type, QAPISchemaAlternateType) - assert not self.arg_type.variants - elif self.boxed: - raise QAPISemError(self.info, "Use of 'boxed' requires 'data'") - if self._ret_type_name: - self.ret_type = schema.lookup_type(self._ret_type_name) - assert isinstance(self.ret_type, QAPISchemaType) - - def visit(self, visitor): - visitor.visit_command(self.name, self.info, - self.arg_type, self.ret_type, - self.gen, self.success_response, self.boxed) - - -class QAPISchemaEvent(QAPISchemaEntity): - def __init__(self, name, info, doc, arg_type, boxed): - QAPISchemaEntity.__init__(self, name, info, doc) - assert not arg_type or isinstance(arg_type, str) - self._arg_type_name = arg_type - self.arg_type = None - self.boxed = boxed - - 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) or - isinstance(self.arg_type, QAPISchemaAlternateType)) - self.arg_type.check(schema) - if self.boxed: - if self.arg_type.is_empty(): - raise QAPISemError(self.info, - "Cannot use 'boxed' with empty type") - else: - assert not isinstance(self.arg_type, QAPISchemaAlternateType) - assert not self.arg_type.variants - elif self.boxed: - raise QAPISemError(self.info, "Use of 'boxed' requires 'data'") - - def visit(self, visitor): - visitor.visit_event(self.name, self.info, self.arg_type, self.boxed) - - -class QAPISchema(object): - def __init__(self, fname): - try: - parser = QAPISchemaParser(open(fname, 'r')) - self.exprs = check_exprs(parser.exprs) - self.docs = parser.docs - self._entity_dict = {} - self._predefining = True - self._def_predefineds() - self._predefining = False - self._def_exprs() - self.check() - except QAPIError as err: - print(err, file=sys.stderr) - exit(1) - - def _def_entity(self, ent): - # Only the predefined types are allowed to not have info - assert ent.info or self._predefining - assert ent.name not in self._entity_dict - self._entity_dict[ent.name] = ent - - def lookup_entity(self, name, typ=None): - ent = self._entity_dict.get(name) - if typ and not isinstance(ent, typ): - return None - return ent - - def lookup_type(self, name): - return self.lookup_entity(name, QAPISchemaType) - - def _def_builtin_type(self, name, json_type, c_type): - self._def_entity(QAPISchemaBuiltinType(name, json_type, c_type)) - # TODO As long as we have QAPI_TYPES_BUILTIN to share multiple - # qapi-types.h from a single .c, all arrays of builtins must be - # declared in the first file whether or not they are used. Nicer - # would be to use lazy instantiation, while figuring out how to - # avoid compilation issues with multiple qapi-types.h. - self._make_array_type(name, None) - - def _def_predefineds(self): - for t in [('str', 'string', 'char' + pointer_suffix), - ('number', 'number', 'double'), - ('int', 'int', 'int64_t'), - ('int8', 'int', 'int8_t'), - ('int16', 'int', 'int16_t'), - ('int32', 'int', 'int32_t'), - ('int64', 'int', 'int64_t'), - ('uint8', 'int', 'uint8_t'), - ('uint16', 'int', 'uint16_t'), - ('uint32', 'int', 'uint32_t'), - ('uint64', 'int', 'uint64_t'), - ('size', 'int', 'uint64_t'), - ('bool', 'boolean', 'bool'), - ('any', 'value', 'QObject' + pointer_suffix), - ('null', 'null', 'QNull' + pointer_suffix)]: - self._def_builtin_type(*t) - self.the_empty_object_type = QAPISchemaObjectType( - 'q_empty', None, None, None, [], None) - self._def_entity(self.the_empty_object_type) - qtype_values = self._make_enum_members(['none', 'qnull', 'qnum', - 'qstring', 'qdict', 'qlist', - 'qbool']) - self._def_entity(QAPISchemaEnumType('QType', None, None, - qtype_values, 'QTYPE')) - - def _make_enum_members(self, values): - return [QAPISchemaMember(v) for v in values] - - def _make_implicit_enum_type(self, name, info, values): - # See also QAPISchemaObjectTypeMember._pretty_owner() - name = name + 'Kind' # Use namespace reserved by add_name() - self._def_entity(QAPISchemaEnumType( - name, info, None, self._make_enum_members(values), None)) - return name - - def _make_array_type(self, element_type, info): - name = element_type + 'List' # Use namespace reserved by add_name() - if not self.lookup_type(name): - self._def_entity(QAPISchemaArrayType(name, info, element_type)) - return name - - def _make_implicit_object_type(self, name, info, doc, role, members): - if not members: - return None - # See also QAPISchemaObjectTypeMember._pretty_owner() - name = 'q_obj_%s-%s' % (name, role) - if not self.lookup_entity(name, QAPISchemaObjectType): - self._def_entity(QAPISchemaObjectType(name, info, doc, None, - members, None)) - return name - - def _def_enum_type(self, expr, info, doc): - name = expr['enum'] - data = expr['data'] - prefix = expr.get('prefix') - self._def_entity(QAPISchemaEnumType( - name, info, doc, self._make_enum_members(data), prefix)) - - def _make_member(self, name, typ, info): - optional = False - if name.startswith('*'): - name = name[1:] - optional = True - if isinstance(typ, list): - assert len(typ) == 1 - typ = self._make_array_type(typ[0], info) - return QAPISchemaObjectTypeMember(name, typ, optional) - - def _make_members(self, data, info): - return [self._make_member(key, value, info) - for (key, value) in data.items()] - - def _def_struct_type(self, expr, info, doc): - name = expr['struct'] - base = expr.get('base') - data = expr['data'] - self._def_entity(QAPISchemaObjectType(name, info, doc, base, - self._make_members(data, info), - None)) - - def _make_variant(self, case, typ): - return QAPISchemaObjectTypeVariant(case, typ) - - def _make_simple_variant(self, case, typ, info): - if isinstance(typ, list): - assert len(typ) == 1 - typ = self._make_array_type(typ[0], info) - typ = self._make_implicit_object_type( - typ, info, None, 'wrapper', [self._make_member('data', typ, info)]) - return QAPISchemaObjectTypeVariant(case, typ) - - def _def_union_type(self, expr, info, doc): - name = expr['union'] - data = expr['data'] - base = expr.get('base') - tag_name = expr.get('discriminator') - tag_member = None - if isinstance(base, dict): - base = (self._make_implicit_object_type( - name, info, doc, 'base', self._make_members(base, info))) - if tag_name: - variants = [self._make_variant(key, value) - for (key, value) in data.items()] - members = [] - else: - variants = [self._make_simple_variant(key, value, info) - for (key, value) in data.items()] - typ = self._make_implicit_enum_type(name, info, - [v.name for v in variants]) - tag_member = QAPISchemaObjectTypeMember('type', typ, False) - members = [tag_member] - self._def_entity( - QAPISchemaObjectType(name, info, doc, base, members, - QAPISchemaObjectTypeVariants(tag_name, - tag_member, - variants))) - - def _def_alternate_type(self, expr, info, doc): - name = expr['alternate'] - data = expr['data'] - variants = [self._make_variant(key, value) - for (key, value) in data.items()] - tag_member = QAPISchemaObjectTypeMember('type', 'QType', False) - self._def_entity( - QAPISchemaAlternateType(name, info, doc, - QAPISchemaObjectTypeVariants(None, - tag_member, - variants))) - - def _def_command(self, expr, info, doc): - name = expr['command'] - data = expr.get('data') - rets = expr.get('returns') - gen = expr.get('gen', True) - success_response = expr.get('success-response', True) - boxed = expr.get('boxed', False) - if isinstance(data, OrderedDict): - data = self._make_implicit_object_type( - name, info, doc, 'arg', self._make_members(data, info)) - if isinstance(rets, list): - assert len(rets) == 1 - rets = self._make_array_type(rets[0], info) - self._def_entity(QAPISchemaCommand(name, info, doc, data, rets, - gen, success_response, boxed)) - - def _def_event(self, expr, info, doc): - name = expr['event'] - data = expr.get('data') - boxed = expr.get('boxed', False) - if isinstance(data, OrderedDict): - data = self._make_implicit_object_type( - name, info, doc, 'arg', self._make_members(data, info)) - self._def_entity(QAPISchemaEvent(name, info, doc, data, boxed)) - - def _def_exprs(self): - for expr_elem in self.exprs: - expr = expr_elem['expr'] - info = expr_elem['info'] - doc = expr_elem.get('doc') - if 'enum' in expr: - self._def_enum_type(expr, info, doc) - elif 'struct' in expr: - self._def_struct_type(expr, info, doc) - elif 'union' in expr: - self._def_union_type(expr, info, doc) - elif 'alternate' in expr: - self._def_alternate_type(expr, info, doc) - elif 'command' in expr: - self._def_command(expr, info, doc) - elif 'event' in expr: - self._def_event(expr, info, doc) - else: - assert False - - def check(self): - for (name, ent) in sorted(self._entity_dict.items()): - ent.check(self) - - def visit(self, visitor): - visitor.visit_begin(self) - for (name, entity) in sorted(self._entity_dict.items()): - if visitor.visit_needed(entity): - entity.visit(visitor) - visitor.visit_end() - - -# -# Code generation helpers -# - -def camel_case(name): - new_name = '' - first = True - for ch in name: - if ch in ['_', '-']: - first = True - elif first: - new_name += ch.upper() - first = False - else: - new_name += ch.lower() - return new_name - - -# ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1 -# ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2 -# ENUM24_Name -> ENUM24_NAME -def camel_to_upper(value): - c_fun_str = c_name(value, False) - if value.isupper(): - return c_fun_str - - new_name = '' - l = len(c_fun_str) - for i in range(l): - c = c_fun_str[i] - # When c is upper and no '_' appears before, do more checks - if c.isupper() and (i > 0) and c_fun_str[i - 1] != '_': - if i < l - 1 and c_fun_str[i + 1].islower(): - new_name += '_' - elif c_fun_str[i - 1].isdigit(): - new_name += '_' - new_name += c - return new_name.lstrip('_').upper() - - -def c_enum_const(type_name, const_name, prefix=None): - if prefix is not None: - type_name = prefix - return camel_to_upper(type_name) + '_' + c_name(const_name, False).upper() - -if hasattr(str, 'maketrans'): - c_name_trans = str.maketrans('.-', '__') -else: - c_name_trans = string.maketrans('.-', '__') - - -# Map @name to a valid C identifier. -# If @protect, avoid returning certain ticklish identifiers (like -# C keywords) by prepending 'q_'. -# -# Used for converting 'name' from a 'name':'type' qapi definition -# into a generated struct member, as well as converting type names -# into substrings of a generated C function name. -# '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo' -# protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int' -def c_name(name, protect=True): - # ANSI X3J11/88-090, 3.1.1 - c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue', - 'default', 'do', 'double', 'else', 'enum', 'extern', - 'float', 'for', 'goto', 'if', 'int', 'long', 'register', - 'return', 'short', 'signed', 'sizeof', 'static', - 'struct', 'switch', 'typedef', 'union', 'unsigned', - 'void', 'volatile', 'while']) - # ISO/IEC 9899:1999, 6.4.1 - c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary']) - # ISO/IEC 9899:2011, 6.4.1 - c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic', - '_Noreturn', '_Static_assert', '_Thread_local']) - # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html - # excluding _.* - gcc_words = set(['asm', 'typeof']) - # C++ ISO/IEC 14882:2003 2.11 - cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete', - 'dynamic_cast', 'explicit', 'false', 'friend', 'mutable', - 'namespace', 'new', 'operator', 'private', 'protected', - 'public', 'reinterpret_cast', 'static_cast', 'template', - 'this', 'throw', 'true', 'try', 'typeid', 'typename', - 'using', 'virtual', 'wchar_t', - # alternative representations - 'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not', - 'not_eq', 'or', 'or_eq', 'xor', 'xor_eq']) - # namespace pollution: - polluted_words = set(['unix', 'errno', 'mips', 'sparc']) - name = name.translate(c_name_trans) - if protect and (name in c89_words | c99_words | c11_words | gcc_words - | cpp_words | polluted_words): - return 'q_' + name - return name - -eatspace = '\033EATSPACE.' -pointer_suffix = ' *' + eatspace - - -def genindent(count): - ret = '' - for _ in range(count): - ret += ' ' - return ret - -indent_level = 0 - - -def push_indent(indent_amount=4): - global indent_level - indent_level += indent_amount - - -def pop_indent(indent_amount=4): - global indent_level - indent_level -= indent_amount - - -# Generate @code with @kwds interpolated. -# Obey indent_level, and strip eatspace. -def cgen(code, **kwds): - raw = code % kwds - if indent_level: - indent = genindent(indent_level) - # re.subn() lacks flags support before Python 2.7, use re.compile() - raw = re.subn(re.compile(r'^.', re.MULTILINE), - indent + r'\g<0>', raw) - raw = raw[0] - return re.sub(re.escape(eatspace) + r' *', '', raw) - - -def mcgen(code, **kwds): - if code[0] == '\n': - code = code[1:] - return cgen(code, **kwds) - - -def guardname(filename): - return c_name(filename, protect=False).upper() - - -def guardstart(name): - return mcgen(''' -#ifndef %(name)s -#define %(name)s - -''', - name=guardname(name)) - - -def guardend(name): - return mcgen(''' - -#endif /* %(name)s */ -''', - name=guardname(name)) - - -def gen_enum_lookup(name, values, prefix=None): - ret = mcgen(''' - -const QEnumLookup %(c_name)s_lookup = { - .array = (const char *const[]) { -''', - c_name=c_name(name)) - for value in values: - index = c_enum_const(name, value, prefix) - ret += mcgen(''' - [%(index)s] = "%(value)s", -''', - index=index, value=value) - - ret += mcgen(''' - }, - .size = %(max_index)s -}; -''', - max_index=c_enum_const(name, '_MAX', prefix)) - return ret - - -def gen_enum(name, values, prefix=None): - # append automatically generated _MAX value - enum_values = values + ['_MAX'] - - ret = mcgen(''' - -typedef enum %(c_name)s { -''', - c_name=c_name(name)) - - i = 0 - for value in enum_values: - ret += mcgen(''' - %(c_enum)s = %(i)d, -''', - c_enum=c_enum_const(name, value, prefix), - i=i) - i += 1 - - ret += mcgen(''' -} %(c_name)s; -''', - c_name=c_name(name)) - - ret += mcgen(''' - -#define %(c_name)s_str(val) \\ - qapi_enum_lookup(&%(c_name)s_lookup, (val)) - -extern const QEnumLookup %(c_name)s_lookup; -''', - c_name=c_name(name)) - return ret - - -def build_params(arg_type, boxed, extra): - if not arg_type: - assert not boxed - return extra - ret = '' - sep = '' - if boxed: - ret += '%s arg' % arg_type.c_param_type() - sep = ', ' - else: - assert not arg_type.variants - for memb in arg_type.members: - ret += sep - sep = ', ' - if memb.optional: - ret += 'bool has_%s, ' % c_name(memb.name) - ret += '%s %s' % (memb.type.c_param_type(), - c_name(memb.name)) - if extra: - ret += sep + extra - return ret - - -# -# Common command line parsing -# - - -def parse_command_line(extra_options='', extra_long_options=[]): - - try: - opts, args = getopt.gnu_getopt(sys.argv[1:], - 'chp:o:' + extra_options, - ['source', 'header', 'prefix=', - 'output-dir='] + extra_long_options) - except getopt.GetoptError as err: - print("%s: %s" % (sys.argv[0], str(err)), file=sys.stderr) - sys.exit(1) - - output_dir = '' - prefix = '' - do_c = False - do_h = False - extra_opts = [] - - for oa in opts: - o, a = oa - if o in ('-p', '--prefix'): - match = re.match(r'([A-Za-z_.-][A-Za-z0-9_.-]*)?', a) - if match.end() != len(a): - print("%s: 'funny character '%s' in argument of --prefix" \ - % (sys.argv[0], a[match.end()]), file=sys.stderr) - sys.exit(1) - prefix = a - elif o in ('-o', '--output-dir'): - output_dir = a + '/' - elif o in ('-c', '--source'): - do_c = True - elif o in ('-h', '--header'): - do_h = True - else: - extra_opts.append(oa) - - if not do_c and not do_h: - do_c = True - do_h = True - - if len(args) != 1: - print("%s: need exactly one argument" % sys.argv[0], file=sys.stderr) - sys.exit(1) - fname = args[0] - - return (fname, output_dir, do_c, do_h, prefix, extra_opts) - - -# -# Accumulate and write output -# - -class QAPIGen(object): - - def __init__(self): - self._preamble = '' - self._body = '' - - def preamble_add(self, text): - self._preamble += text - - def add(self, text): - self._body += text - - def _top(self, fname): - return '' - - def _bottom(self, fname): - return '' - - def write(self, output_dir, fname): - if output_dir: - try: - os.makedirs(output_dir) - except os.error as e: - if e.errno != errno.EEXIST: - raise - f = open(os.path.join(output_dir, fname), 'w') - f.write(self._top(fname) + self._preamble + self._body - + self._bottom(fname)) - f.close() - - -class QAPIGenC(QAPIGen): - - def __init__(self, blurb, pydoc): - QAPIGen.__init__(self) - self._blurb = blurb - self._copyright = '\n * '.join(re.findall(r'^Copyright .*', pydoc, - re.MULTILINE)) - - def _top(self, fname): - return mcgen(''' -/* AUTOMATICALLY GENERATED, DO NOT MODIFY */ - -/* -%(blurb)s - * - * %(copyright)s - * - * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. - * See the COPYING.LIB file in the top-level directory. - */ - -''', - blurb=self._blurb, copyright=self._copyright) - - -class QAPIGenH(QAPIGenC): - - def _top(self, fname): - return QAPIGenC._top(self, fname) + guardstart(fname) - - def _bottom(self, fname): - return guardend(fname) - - -class QAPIGenDoc(QAPIGen): - - def _top(self, fname): - return (QAPIGen._top(self, fname) - + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') diff --git a/scripts/qapi/__init__.py b/scripts/qapi/__init__.py new file mode 100644 index 0000000000..e69de29bb2 diff --git a/scripts/qapi/commands.py b/scripts/qapi/commands.py new file mode 100644 index 0000000000..a744611d58 --- /dev/null +++ b/scripts/qapi/commands.py @@ -0,0 +1,293 @@ +""" +QAPI command marshaller generator + +Copyright IBM, Corp. 2011 +Copyright (C) 2014-2018 Red Hat, Inc. + +Authors: + Anthony Liguori + Michael Roth + Markus Armbruster + +This work is licensed under the terms of the GNU GPL, version 2. +See the COPYING file in the top-level directory. +""" + +from qapi.common import * + + +def gen_command_decl(name, arg_type, boxed, ret_type): + return mcgen(''' +%(c_type)s qmp_%(c_name)s(%(params)s); +''', + c_type=(ret_type and ret_type.c_type()) or 'void', + c_name=c_name(name), + params=build_params(arg_type, boxed, 'Error **errp')) + + +def gen_call(name, arg_type, boxed, ret_type): + ret = '' + + argstr = '' + if boxed: + 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: + if memb.optional: + argstr += 'arg.has_%s, ' % c_name(memb.name) + argstr += 'arg.%s, ' % c_name(memb.name) + + lhs = '' + if ret_type: + lhs = 'retval = ' + + ret = mcgen(''' + + %(lhs)sqmp_%(c_name)s(%(args)s&err); +''', + c_name=c_name(name), args=argstr, lhs=lhs) + if ret_type: + ret += mcgen(''' + if (err) { + goto out; + } + + qmp_marshal_output_%(c_name)s(retval, ret, &err); +''', + c_name=ret_type.c_name()) + return ret + + +def gen_marshal_output(ret_type): + return mcgen(''' + +static void qmp_marshal_output_%(c_name)s(%(c_type)s ret_in, QObject **ret_out, Error **errp) +{ + Error *err = NULL; + Visitor *v; + + v = qobject_output_visitor_new(ret_out); + visit_type_%(c_name)s(v, "unused", &ret_in, &err); + if (!err) { + visit_complete(v, ret_out); + } + error_propagate(errp, err); + visit_free(v); + v = qapi_dealloc_visitor_new(); + visit_type_%(c_name)s(v, "unused", &ret_in, NULL); + visit_free(v); +} +''', + c_type=ret_type.c_type(), c_name=ret_type.c_name()) + + +def build_marshal_proto(name): + return ('void qmp_marshal_%s(QDict *args, QObject **ret, Error **errp)' + % c_name(name)) + + +def gen_marshal_decl(name): + return mcgen(''' +%(proto)s; +''', + proto=build_marshal_proto(name)) + + +def gen_marshal(name, arg_type, boxed, ret_type): + have_args = arg_type and not arg_type.is_empty() + + ret = mcgen(''' + +%(proto)s +{ + Error *err = NULL; +''', + proto=build_marshal_proto(name)) + + if ret_type: + ret += mcgen(''' + %(c_type)s retval; +''', + c_type=ret_type.c_type()) + + if have_args: + visit_members = ('visit_type_%s_members(v, &arg, &err);' + % arg_type.c_name()) + ret += mcgen(''' + Visitor *v; + %(c_name)s arg = {0}; + +''', + c_name=arg_type.c_name()) + else: + visit_members = '' + ret += mcgen(''' + Visitor *v = NULL; + + if (args) { +''') + push_indent() + + ret += mcgen(''' + v = qobject_input_visitor_new(QOBJECT(args)); + visit_start_struct(v, NULL, NULL, 0, &err); + if (err) { + goto out; + } + %(visit_members)s + if (!err) { + visit_check_struct(v, &err); + } + visit_end_struct(v, NULL); + if (err) { + goto out; + } +''', + visit_members=visit_members) + + if not have_args: + pop_indent() + ret += mcgen(''' + } +''') + + ret += gen_call(name, arg_type, boxed, ret_type) + + ret += mcgen(''' + +out: + error_propagate(errp, err); + visit_free(v); +''') + + if have_args: + visit_members = ('visit_type_%s_members(v, &arg, NULL);' + % arg_type.c_name()) + else: + visit_members = '' + ret += mcgen(''' + if (args) { +''') + push_indent() + + ret += mcgen(''' + v = qapi_dealloc_visitor_new(); + visit_start_struct(v, NULL, NULL, 0, NULL); + %(visit_members)s + visit_end_struct(v, NULL); + visit_free(v); +''', + visit_members=visit_members) + + if not have_args: + pop_indent() + ret += mcgen(''' + } +''') + + ret += mcgen(''' +} +''') + return ret + + +def gen_register_command(name, success_response): + options = 'QCO_NO_OPTIONS' + if not success_response: + options = 'QCO_NO_SUCCESS_RESP' + + ret = mcgen(''' + qmp_register_command(cmds, "%(name)s", + qmp_marshal_%(c_name)s, %(opts)s); +''', + name=name, c_name=c_name(name), + opts=options) + return ret + + +def gen_registry(registry, prefix): + ret = mcgen(''' + +void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds) +{ + QTAILQ_INIT(cmds); + +''', + c_prefix=c_name(prefix, protect=False)) + ret += registry + ret += mcgen(''' +} +''') + return ret + + +class QAPISchemaGenCommandVisitor(QAPISchemaVisitor): + def __init__(self, prefix): + self._prefix = prefix + self.decl = None + self.defn = None + self._regy = None + self._visited_ret_types = None + + def visit_begin(self, schema): + self.decl = '' + self.defn = '' + self._regy = '' + self._visited_ret_types = set() + + def visit_end(self): + self.defn += gen_registry(self._regy, self._prefix) + self._regy = None + self._visited_ret_types = None + + def visit_command(self, name, info, arg_type, ret_type, + gen, success_response, boxed): + if not gen: + return + self.decl += gen_command_decl(name, arg_type, boxed, ret_type) + if ret_type and ret_type not in self._visited_ret_types: + self._visited_ret_types.add(ret_type) + self.defn += gen_marshal_output(ret_type) + self.decl += gen_marshal_decl(name) + self.defn += gen_marshal(name, arg_type, boxed, ret_type) + self._regy += gen_register_command(name, success_response) + + +def gen_commands(schema, output_dir, prefix): + blurb = ' * Schema-defined QAPI/QMP commands' + genc = QAPIGenC(blurb, __doc__) + genh = QAPIGenH(blurb, __doc__) + + genc.add(mcgen(''' +#include "qemu/osdep.h" +#include "qemu-common.h" +#include "qemu/module.h" +#include "qapi/visitor.h" +#include "qapi/qmp/qdict.h" +#include "qapi/qobject-output-visitor.h" +#include "qapi/qobject-input-visitor.h" +#include "qapi/dealloc-visitor.h" +#include "qapi/error.h" +#include "%(prefix)sqapi-types.h" +#include "%(prefix)sqapi-visit.h" +#include "%(prefix)sqmp-commands.h" + +''', + prefix=prefix)) + + genh.add(mcgen(''' +#include "%(prefix)sqapi-types.h" +#include "qapi/qmp/dispatch.h" + +void %(c_prefix)sqmp_init_marshal(QmpCommandList *cmds); +''', + prefix=prefix, c_prefix=c_name(prefix, protect=False))) + + vis = QAPISchemaGenCommandVisitor(prefix) + schema.visit(vis) + genc.add(vis.defn) + genh.add(vis.decl) + genc.write(output_dir, prefix + 'qmp-marshal.c') + genh.write(output_dir, prefix + 'qmp-commands.h') diff --git a/scripts/qapi/common.py b/scripts/qapi/common.py new file mode 100644 index 0000000000..3bc31a03ce --- /dev/null +++ b/scripts/qapi/common.py @@ -0,0 +1,2041 @@ +# +# QAPI helper library +# +# Copyright IBM, Corp. 2011 +# Copyright (c) 2013-2018 Red Hat Inc. +# +# Authors: +# Anthony Liguori +# Markus Armbruster +# +# This work is licensed under the terms of the GNU GPL, version 2. +# See the COPYING file in the top-level directory. + +from __future__ import print_function +import errno +import getopt +import os +import re +import string +import sys +try: + from collections import OrderedDict +except: + from ordereddict import OrderedDict + +builtin_types = { + 'null': 'QTYPE_QNULL', + 'str': 'QTYPE_QSTRING', + 'int': 'QTYPE_QNUM', + 'number': 'QTYPE_QNUM', + 'bool': 'QTYPE_QBOOL', + 'int8': 'QTYPE_QNUM', + 'int16': 'QTYPE_QNUM', + 'int32': 'QTYPE_QNUM', + 'int64': 'QTYPE_QNUM', + 'uint8': 'QTYPE_QNUM', + 'uint16': 'QTYPE_QNUM', + 'uint32': 'QTYPE_QNUM', + 'uint64': 'QTYPE_QNUM', + 'size': 'QTYPE_QNUM', + 'any': None, # any QType possible, actually + 'QType': 'QTYPE_QSTRING', +} + +# Are documentation comments required? +doc_required = False + +# Whitelist of commands allowed to return a non-dictionary +returns_whitelist = [] + +# Whitelist of entities allowed to violate case conventions +name_case_whitelist = [] + +enum_types = {} +struct_types = {} +union_types = {} +all_names = {} + +# +# Parsing the schema into expressions +# + + +def error_path(parent): + res = '' + while parent: + res = ('In file included from %s:%d:\n' % (parent['file'], + parent['line'])) + res + parent = parent['parent'] + return res + + +class QAPIError(Exception): + def __init__(self, fname, line, col, incl_info, msg): + Exception.__init__(self) + self.fname = fname + self.line = line + self.col = col + self.info = incl_info + self.msg = msg + + def __str__(self): + loc = '%s:%d' % (self.fname, self.line) + if self.col is not None: + loc += ':%s' % self.col + return error_path(self.info) + '%s: %s' % (loc, self.msg) + + +class QAPIParseError(QAPIError): + def __init__(self, parser, msg): + col = 1 + for ch in parser.src[parser.line_pos:parser.pos]: + if ch == '\t': + col = (col + 7) % 8 + 1 + else: + col += 1 + QAPIError.__init__(self, parser.fname, parser.line, col, + parser.incl_info, msg) + + +class QAPISemError(QAPIError): + def __init__(self, info, msg): + QAPIError.__init__(self, info['file'], info['line'], None, + info['parent'], msg) + + +class QAPIDoc(object): + class Section(object): + def __init__(self, name=None): + # optional section name (argument/member or section name) + self.name = name + # the list of lines for this section + self.text = '' + + def append(self, line): + self.text += line.rstrip() + '\n' + + class ArgSection(Section): + def __init__(self, name): + QAPIDoc.Section.__init__(self, name) + self.member = None + + def connect(self, member): + self.member = member + + def __init__(self, parser, info): + # self._parser is used to report errors with QAPIParseError. The + # resulting error position depends on the state of the parser. + # It happens to be the beginning of the comment. More or less + # servicable, but action at a distance. + self._parser = parser + self.info = info + self.symbol = None + self.body = QAPIDoc.Section() + # dict mapping parameter name to ArgSection + self.args = OrderedDict() + # a list of Section + self.sections = [] + # the current section + self._section = self.body + + def has_section(self, name): + """Return True if we have a section with this name.""" + for i in self.sections: + if i.name == name: + return True + return False + + def append(self, line): + """Parse a comment line and add it to the documentation.""" + line = line[1:] + if not line: + self._append_freeform(line) + return + + if line[0] != ' ': + raise QAPIParseError(self._parser, "Missing space after #") + line = line[1:] + + # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't + # recognized, and get silently treated as ordinary text + if self.symbol: + self._append_symbol_line(line) + elif not self.body.text and line.startswith('@'): + if not line.endswith(':'): + raise QAPIParseError(self._parser, "Line should end with :") + self.symbol = line[1:-1] + # FIXME invalid names other than the empty string aren't flagged + if not self.symbol: + raise QAPIParseError(self._parser, "Invalid name") + else: + self._append_freeform(line) + + def end_comment(self): + self._end_section() + + def _append_symbol_line(self, line): + name = line.split(' ', 1)[0] + + if name.startswith('@') and name.endswith(':'): + line = line[len(name)+1:] + self._start_args_section(name[1:-1]) + elif name in ('Returns:', 'Since:', + # those are often singular or plural + 'Note:', 'Notes:', + 'Example:', 'Examples:', + 'TODO:'): + line = line[len(name)+1:] + self._start_section(name[:-1]) + + self._append_freeform(line) + + def _start_args_section(self, name): + # FIXME invalid names other than the empty string aren't flagged + if not name: + raise QAPIParseError(self._parser, "Invalid parameter name") + if name in self.args: + raise QAPIParseError(self._parser, + "'%s' parameter name duplicated" % name) + if self.sections: + raise QAPIParseError(self._parser, + "'@%s:' can't follow '%s' section" + % (name, self.sections[0].name)) + self._end_section() + self._section = QAPIDoc.ArgSection(name) + self.args[name] = self._section + + def _start_section(self, name=None): + if name in ('Returns', 'Since') and self.has_section(name): + raise QAPIParseError(self._parser, + "Duplicated '%s' section" % name) + self._end_section() + self._section = QAPIDoc.Section(name) + self.sections.append(self._section) + + def _end_section(self): + if self._section: + text = self._section.text = self._section.text.strip() + if self._section.name and (not text or text.isspace()): + raise QAPIParseError(self._parser, "Empty doc section '%s'" + % self._section.name) + self._section = None + + def _append_freeform(self, line): + in_arg = isinstance(self._section, QAPIDoc.ArgSection) + if (in_arg and self._section.text.endswith('\n\n') + and line and not line[0].isspace()): + self._start_section() + if (in_arg or not self._section.name + or not self._section.name.startswith('Example')): + line = line.strip() + match = re.match(r'(@\S+:)', line) + if match: + raise QAPIParseError(self._parser, + "'%s' not allowed in free-form documentation" + % match.group(1)) + self._section.append(line) + + def connect_member(self, member): + if member.name not in self.args: + # Undocumented TODO outlaw + self.args[member.name] = QAPIDoc.ArgSection(member.name) + self.args[member.name].connect(member) + + def check_expr(self, expr): + if self.has_section('Returns') and 'command' not in expr: + raise QAPISemError(self.info, + "'Returns:' is only valid for commands") + + def check(self): + bogus = [name for name, section in self.args.items() + if not section.member] + if bogus: + raise QAPISemError( + self.info, + "The following documented members are not in " + "the declaration: %s" % ", ".join(bogus)) + + +class QAPISchemaParser(object): + + def __init__(self, fp, previously_included=[], incl_info=None): + abs_fname = os.path.abspath(fp.name) + self.fname = fp.name + previously_included.append(abs_fname) + self.incl_info = incl_info + self.src = fp.read() + if self.src == '' or self.src[-1] != '\n': + self.src += '\n' + self.cursor = 0 + self.line = 1 + self.line_pos = 0 + self.exprs = [] + self.docs = [] + self.accept() + cur_doc = None + + while self.tok is not None: + info = {'file': self.fname, 'line': self.line, + 'parent': self.incl_info} + if self.tok == '#': + self.reject_expr_doc(cur_doc) + cur_doc = self.get_doc(info) + self.docs.append(cur_doc) + continue + + expr = self.get_expr(False) + if 'include' in expr: + self.reject_expr_doc(cur_doc) + if len(expr) != 1: + raise QAPISemError(info, "Invalid 'include' directive") + include = expr['include'] + if not isinstance(include, str): + raise QAPISemError(info, + "Value of 'include' must be a string") + self._include(include, info, os.path.dirname(abs_fname), + previously_included) + elif "pragma" in expr: + self.reject_expr_doc(cur_doc) + if len(expr) != 1: + raise QAPISemError(info, "Invalid 'pragma' directive") + pragma = expr['pragma'] + if not isinstance(pragma, dict): + raise QAPISemError( + info, "Value of 'pragma' must be a dictionary") + for name, value in pragma.items(): + self._pragma(name, value, info) + else: + expr_elem = {'expr': expr, + 'info': info} + if cur_doc: + if not cur_doc.symbol: + raise QAPISemError( + cur_doc.info, "Expression documentation required") + expr_elem['doc'] = cur_doc + self.exprs.append(expr_elem) + cur_doc = None + self.reject_expr_doc(cur_doc) + + @staticmethod + def reject_expr_doc(doc): + if doc and doc.symbol: + raise QAPISemError( + doc.info, + "Documentation for '%s' is not followed by the definition" + % doc.symbol) + + def _include(self, include, info, base_dir, previously_included): + incl_abs_fname = os.path.join(base_dir, include) + # catch inclusion cycle + inf = info + while inf: + if incl_abs_fname == os.path.abspath(inf['file']): + raise QAPISemError(info, "Inclusion loop for %s" % include) + inf = inf['parent'] + + # skip multiple include of the same file + if incl_abs_fname in previously_included: + return + try: + fobj = open(incl_abs_fname, 'r') + except IOError as e: + raise QAPISemError(info, '%s: %s' % (e.strerror, include)) + exprs_include = QAPISchemaParser(fobj, previously_included, info) + self.exprs.extend(exprs_include.exprs) + self.docs.extend(exprs_include.docs) + + def _pragma(self, name, value, info): + global doc_required, returns_whitelist, name_case_whitelist + if name == 'doc-required': + if not isinstance(value, bool): + raise QAPISemError(info, + "Pragma 'doc-required' must be boolean") + doc_required = value + elif name == 'returns-whitelist': + if (not isinstance(value, list) + or any([not isinstance(elt, str) for elt in value])): + raise QAPISemError(info, + "Pragma returns-whitelist must be" + " a list of strings") + returns_whitelist = value + elif name == 'name-case-whitelist': + if (not isinstance(value, list) + or any([not isinstance(elt, str) for elt in value])): + raise QAPISemError(info, + "Pragma name-case-whitelist must be" + " a list of strings") + name_case_whitelist = value + else: + raise QAPISemError(info, "Unknown pragma '%s'" % name) + + def accept(self, skip_comment=True): + while True: + self.tok = self.src[self.cursor] + self.pos = self.cursor + self.cursor += 1 + self.val = None + + if self.tok == '#': + if self.src[self.cursor] == '#': + # Start of doc comment + skip_comment = False + self.cursor = self.src.find('\n', self.cursor) + if not skip_comment: + self.val = self.src[self.pos:self.cursor] + return + elif self.tok in '{}:,[]': + return + elif self.tok == "'": + string = '' + esc = False + while True: + ch = self.src[self.cursor] + self.cursor += 1 + if ch == '\n': + raise QAPIParseError(self, 'Missing terminating "\'"') + if esc: + if ch == 'b': + string += '\b' + elif ch == 'f': + string += '\f' + elif ch == 'n': + string += '\n' + elif ch == 'r': + string += '\r' + elif ch == 't': + string += '\t' + elif ch == 'u': + value = 0 + for _ in range(0, 4): + ch = self.src[self.cursor] + self.cursor += 1 + if ch not in '0123456789abcdefABCDEF': + raise QAPIParseError(self, + '\\u escape needs 4 ' + 'hex digits') + value = (value << 4) + int(ch, 16) + # If Python 2 and 3 didn't disagree so much on + # how to handle Unicode, then we could allow + # Unicode string defaults. But most of QAPI is + # ASCII-only, so we aren't losing much for now. + if not value or value > 0x7f: + raise QAPIParseError(self, + 'For now, \\u escape ' + 'only supports non-zero ' + 'values up to \\u007f') + string += chr(value) + elif ch in '\\/\'"': + string += ch + else: + raise QAPIParseError(self, + "Unknown escape \\%s" % ch) + esc = False + elif ch == '\\': + esc = True + elif ch == "'": + self.val = string + return + else: + string += ch + elif self.src.startswith('true', self.pos): + self.val = True + self.cursor += 3 + return + elif self.src.startswith('false', self.pos): + self.val = False + self.cursor += 4 + return + elif self.src.startswith('null', self.pos): + self.val = None + self.cursor += 3 + return + elif self.tok == '\n': + if self.cursor == len(self.src): + self.tok = None + return + self.line += 1 + self.line_pos = self.cursor + elif not self.tok.isspace(): + raise QAPIParseError(self, 'Stray "%s"' % self.tok) + + def get_members(self): + expr = OrderedDict() + if self.tok == '}': + self.accept() + return expr + if self.tok != "'": + raise QAPIParseError(self, 'Expected string or "}"') + while True: + key = self.val + self.accept() + if self.tok != ':': + raise QAPIParseError(self, 'Expected ":"') + self.accept() + if key in expr: + raise QAPIParseError(self, 'Duplicate key "%s"' % key) + expr[key] = self.get_expr(True) + if self.tok == '}': + self.accept() + return expr + if self.tok != ',': + raise QAPIParseError(self, 'Expected "," or "}"') + self.accept() + if self.tok != "'": + raise QAPIParseError(self, 'Expected string') + + def get_values(self): + expr = [] + if self.tok == ']': + self.accept() + return expr + if self.tok not in "{['tfn": + raise QAPIParseError(self, 'Expected "{", "[", "]", string, ' + 'boolean or "null"') + while True: + expr.append(self.get_expr(True)) + if self.tok == ']': + self.accept() + return expr + if self.tok != ',': + raise QAPIParseError(self, 'Expected "," or "]"') + self.accept() + + def get_expr(self, nested): + if self.tok != '{' and not nested: + raise QAPIParseError(self, 'Expected "{"') + if self.tok == '{': + self.accept() + expr = self.get_members() + elif self.tok == '[': + self.accept() + expr = self.get_values() + elif self.tok in "'tfn": + expr = self.val + self.accept() + else: + raise QAPIParseError(self, 'Expected "{", "[", string, ' + 'boolean or "null"') + return expr + + def get_doc(self, info): + if self.val != '##': + raise QAPIParseError(self, "Junk after '##' at start of " + "documentation comment") + + doc = QAPIDoc(self, info) + self.accept(False) + while self.tok == '#': + if self.val.startswith('##'): + # End of doc comment + if self.val != '##': + raise QAPIParseError(self, "Junk after '##' at end of " + "documentation comment") + doc.end_comment() + self.accept() + return doc + else: + doc.append(self.val) + self.accept(False) + + raise QAPIParseError(self, "Documentation comment must end with '##'") + + +# +# Semantic analysis of schema expressions +# TODO fold into QAPISchema +# TODO catching name collisions in generated code would be nice +# + + +def find_base_members(base): + if isinstance(base, dict): + return base + base_struct_define = struct_types.get(base) + if not base_struct_define: + return None + return base_struct_define['data'] + + +# Return the qtype of an alternate branch, or None on error. +def find_alternate_member_qtype(qapi_type): + if qapi_type in builtin_types: + return builtin_types[qapi_type] + elif qapi_type in struct_types: + return 'QTYPE_QDICT' + elif qapi_type in enum_types: + return 'QTYPE_QSTRING' + elif qapi_type in union_types: + return 'QTYPE_QDICT' + return None + + +# Return the discriminator enum define if discriminator is specified as an +# enum type, otherwise return None. +def discriminator_find_enum_define(expr): + base = expr.get('base') + discriminator = expr.get('discriminator') + + if not (discriminator and base): + return None + + base_members = find_base_members(base) + if not base_members: + return None + + discriminator_type = base_members.get(discriminator) + if not discriminator_type: + return None + + return enum_types.get(discriminator_type) + + +# Names must be letters, numbers, -, and _. They must start with letter, +# except for downstream extensions which must start with __RFQDN_. +# Dots are only valid in the downstream extension prefix. +valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?' + '[a-zA-Z][a-zA-Z0-9_-]*$') + + +def check_name(info, source, name, allow_optional=False, + enum_member=False): + global valid_name + membername = name + + if not isinstance(name, str): + raise QAPISemError(info, "%s requires a string name" % source) + if name.startswith('*'): + membername = name[1:] + if not allow_optional: + raise QAPISemError(info, "%s does not allow optional name '%s'" + % (source, name)) + # Enum members can start with a digit, because the generated C + # code always prefixes it with the enum name + if enum_member and membername[0].isdigit(): + membername = 'D' + membername + # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty' + # and 'q_obj_*' implicit type names. + if not valid_name.match(membername) or \ + c_name(membername, False).startswith('q_'): + raise QAPISemError(info, "%s uses invalid name '%s'" % (source, name)) + + +def add_name(name, info, meta, implicit=False): + global all_names + check_name(info, "'%s'" % meta, name) + # FIXME should reject names that differ only in '_' vs. '.' + # vs. '-', because they're liable to clash in generated C. + if name in all_names: + raise QAPISemError(info, "%s '%s' is already defined" + % (all_names[name], name)) + if not implicit and (name.endswith('Kind') or name.endswith('List')): + raise QAPISemError(info, "%s '%s' should not end in '%s'" + % (meta, name, name[-4:])) + all_names[name] = meta + + +def check_type(info, source, value, allow_array=False, + allow_dict=False, allow_optional=False, + allow_metas=[]): + global all_names + + if value is None: + return + + # Check if array type for value is okay + if isinstance(value, list): + if not allow_array: + raise QAPISemError(info, "%s cannot be an array" % source) + if len(value) != 1 or not isinstance(value[0], str): + raise QAPISemError(info, + "%s: array type must contain single type name" % + source) + value = value[0] + + # Check if type name for value is okay + if isinstance(value, str): + if value not in all_names: + raise QAPISemError(info, "%s uses unknown type '%s'" + % (source, value)) + if not all_names[value] in allow_metas: + raise QAPISemError(info, "%s cannot use %s type '%s'" % + (source, all_names[value], value)) + return + + if not allow_dict: + raise QAPISemError(info, "%s should be a type name" % source) + + if not isinstance(value, OrderedDict): + raise QAPISemError(info, + "%s should be a dictionary or type name" % source) + + # value is a dictionary, check that each member is okay + for (key, arg) in value.items(): + check_name(info, "Member of %s" % source, key, + allow_optional=allow_optional) + if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'): + raise QAPISemError(info, "Member of %s uses reserved name '%s'" + % (source, key)) + # Todo: allow dictionaries to represent default values of + # an optional argument. + check_type(info, "Member '%s' of %s" % (key, source), arg, + allow_array=True, + allow_metas=['built-in', 'union', 'alternate', 'struct', + 'enum']) + + +def check_command(expr, info): + name = expr['command'] + boxed = expr.get('boxed', False) + + args_meta = ['struct'] + if boxed: + args_meta += ['union', 'alternate'] + check_type(info, "'data' for command '%s'" % name, + expr.get('data'), allow_dict=not boxed, allow_optional=True, + allow_metas=args_meta) + returns_meta = ['union', 'struct'] + if name in returns_whitelist: + returns_meta += ['built-in', 'alternate', 'enum'] + check_type(info, "'returns' for command '%s'" % name, + expr.get('returns'), allow_array=True, + allow_optional=True, allow_metas=returns_meta) + + +def check_event(expr, info): + name = expr['event'] + boxed = expr.get('boxed', False) + + meta = ['struct'] + if boxed: + meta += ['union', 'alternate'] + check_type(info, "'data' for event '%s'" % name, + expr.get('data'), allow_dict=not boxed, allow_optional=True, + allow_metas=meta) + + +def check_union(expr, info): + name = expr['union'] + base = expr.get('base') + discriminator = expr.get('discriminator') + members = expr['data'] + + # Two types of unions, determined by discriminator. + + # With no discriminator it is a simple union. + if discriminator is None: + enum_define = None + allow_metas = ['built-in', 'union', 'alternate', 'struct', 'enum'] + if base is not None: + raise QAPISemError(info, "Simple union '%s' must not have a base" % + name) + + # Else, it's a flat union. + else: + # The object must have a string or dictionary 'base'. + check_type(info, "'base' for union '%s'" % name, + base, allow_dict=True, allow_optional=True, + allow_metas=['struct']) + if not base: + raise QAPISemError(info, "Flat union '%s' must have a base" + % name) + base_members = find_base_members(base) + assert base_members is not None + + # The value of member 'discriminator' must name a non-optional + # member of the base struct. + check_name(info, "Discriminator of flat union '%s'" % name, + discriminator) + discriminator_type = base_members.get(discriminator) + if not discriminator_type: + raise QAPISemError(info, + "Discriminator '%s' is not a member of base " + "struct '%s'" + % (discriminator, base)) + enum_define = enum_types.get(discriminator_type) + allow_metas = ['struct'] + # Do not allow string discriminator + if not enum_define: + raise QAPISemError(info, + "Discriminator '%s' must be of enumeration " + "type" % discriminator) + + # Check every branch; don't allow an empty union + if len(members) == 0: + raise QAPISemError(info, "Union '%s' cannot have empty 'data'" % name) + for (key, value) in members.items(): + check_name(info, "Member of union '%s'" % name, key) + + # Each value must name a known type + check_type(info, "Member '%s' of union '%s'" % (key, name), + value, allow_array=not base, allow_metas=allow_metas) + + # If the discriminator names an enum type, then all members + # of 'data' must also be members of the enum type. + if enum_define: + if key not in enum_define['data']: + raise QAPISemError(info, + "Discriminator value '%s' is not found in " + "enum '%s'" + % (key, enum_define['enum'])) + + # If discriminator is user-defined, ensure all values are covered + if enum_define: + for value in enum_define['data']: + if value not in members.keys(): + raise QAPISemError(info, "Union '%s' data missing '%s' branch" + % (name, value)) + + +def check_alternate(expr, info): + name = expr['alternate'] + members = expr['data'] + types_seen = {} + + # Check every branch; require at least two branches + if len(members) < 2: + raise QAPISemError(info, + "Alternate '%s' should have at least two branches " + "in 'data'" % name) + for (key, value) in members.items(): + check_name(info, "Member of alternate '%s'" % name, key) + + # Ensure alternates have no type conflicts. + check_type(info, "Member '%s' of alternate '%s'" % (key, name), + value, + allow_metas=['built-in', 'union', 'struct', 'enum']) + qtype = find_alternate_member_qtype(value) + if not qtype: + raise QAPISemError(info, "Alternate '%s' member '%s' cannot use " + "type '%s'" % (name, key, value)) + conflicting = set([qtype]) + if qtype == 'QTYPE_QSTRING': + enum_expr = enum_types.get(value) + if enum_expr: + for v in enum_expr['data']: + if v in ['on', 'off']: + conflicting.add('QTYPE_QBOOL') + if re.match(r'[-+0-9.]', v): # lazy, could be tightened + conflicting.add('QTYPE_QNUM') + else: + conflicting.add('QTYPE_QNUM') + conflicting.add('QTYPE_QBOOL') + for qt in conflicting: + if qt in types_seen: + raise QAPISemError(info, "Alternate '%s' member '%s' can't " + "be distinguished from member '%s'" + % (name, key, types_seen[qt])) + types_seen[qt] = key + + +def check_enum(expr, info): + name = expr['enum'] + members = expr.get('data') + prefix = expr.get('prefix') + + if not isinstance(members, list): + raise QAPISemError(info, + "Enum '%s' requires an array for 'data'" % name) + if prefix is not None and not isinstance(prefix, str): + raise QAPISemError(info, + "Enum '%s' requires a string for 'prefix'" % name) + for member in members: + check_name(info, "Member of enum '%s'" % name, member, + enum_member=True) + + +def check_struct(expr, info): + name = expr['struct'] + members = expr['data'] + + check_type(info, "'data' for struct '%s'" % name, members, + allow_dict=True, allow_optional=True) + check_type(info, "'base' for struct '%s'" % name, expr.get('base'), + allow_metas=['struct']) + + +def check_keys(expr_elem, meta, required, optional=[]): + expr = expr_elem['expr'] + info = expr_elem['info'] + name = expr[meta] + if not isinstance(name, str): + raise QAPISemError(info, "'%s' key must have a string value" % meta) + required = required + [meta] + for (key, value) in expr.items(): + if key not in required and key not in optional: + raise QAPISemError(info, "Unknown key '%s' in %s '%s'" + % (key, meta, name)) + if (key == 'gen' or key == 'success-response') and value is not False: + raise QAPISemError(info, + "'%s' of %s '%s' should only use false value" + % (key, meta, name)) + if key == 'boxed' and value is not True: + raise QAPISemError(info, + "'%s' of %s '%s' should only use true value" + % (key, meta, name)) + for key in required: + if key not in expr: + raise QAPISemError(info, "Key '%s' is missing from %s '%s'" + % (key, meta, name)) + + +def check_exprs(exprs): + global all_names + + # Populate name table with names of built-in types + for builtin in builtin_types.keys(): + all_names[builtin] = 'built-in' + + # Learn the types and check for valid expression keys + for expr_elem in exprs: + expr = expr_elem['expr'] + info = expr_elem['info'] + doc = expr_elem.get('doc') + + if not doc and doc_required: + raise QAPISemError(info, + "Expression missing documentation comment") + + if 'enum' in expr: + meta = 'enum' + check_keys(expr_elem, 'enum', ['data'], ['prefix']) + enum_types[expr[meta]] = expr + elif 'union' in expr: + meta = 'union' + check_keys(expr_elem, 'union', ['data'], + ['base', 'discriminator']) + union_types[expr[meta]] = expr + elif 'alternate' in expr: + meta = 'alternate' + check_keys(expr_elem, 'alternate', ['data']) + elif 'struct' in expr: + meta = 'struct' + check_keys(expr_elem, 'struct', ['data'], ['base']) + struct_types[expr[meta]] = expr + elif 'command' in expr: + meta = 'command' + check_keys(expr_elem, 'command', [], + ['data', 'returns', 'gen', 'success-response', 'boxed']) + elif 'event' in expr: + meta = 'event' + check_keys(expr_elem, 'event', [], ['data', 'boxed']) + else: + raise QAPISemError(expr_elem['info'], + "Expression is missing metatype") + name = expr[meta] + add_name(name, info, meta) + if doc and doc.symbol != name: + raise QAPISemError(info, "Definition of '%s' follows documentation" + " for '%s'" % (name, doc.symbol)) + + # Try again for hidden UnionKind enum + for expr_elem in exprs: + expr = expr_elem['expr'] + if 'union' in expr and not discriminator_find_enum_define(expr): + name = '%sKind' % expr['union'] + elif 'alternate' in expr: + name = '%sKind' % expr['alternate'] + else: + continue + enum_types[name] = {'enum': name} + add_name(name, info, 'enum', implicit=True) + + # Validate that exprs make sense + for expr_elem in exprs: + expr = expr_elem['expr'] + info = expr_elem['info'] + doc = expr_elem.get('doc') + + if 'enum' in expr: + check_enum(expr, info) + elif 'union' in expr: + check_union(expr, info) + elif 'alternate' in expr: + check_alternate(expr, info) + elif 'struct' in expr: + check_struct(expr, info) + elif 'command' in expr: + check_command(expr, info) + elif 'event' in expr: + check_event(expr, info) + else: + assert False, 'unexpected meta type' + + if doc: + doc.check_expr(expr) + + return exprs + + +# +# Schema compiler frontend +# + +class QAPISchemaEntity(object): + def __init__(self, name, info, doc): + assert isinstance(name, str) + self.name = name + # For explicitly defined entities, info points to the (explicit) + # definition. For builtins (and their arrays), info is None. + # For implicitly defined entities, info points to a place that + # triggered the implicit definition (there may be more than one + # such place). + self.info = info + self.doc = doc + + def c_name(self): + return c_name(self.name) + + def check(self, schema): + pass + + def is_implicit(self): + return not self.info + + def visit(self, visitor): + pass + + +class QAPISchemaVisitor(object): + def visit_begin(self, schema): + pass + + def visit_end(self): + pass + + def visit_needed(self, entity): + # Default to visiting everything + return True + + def visit_builtin_type(self, name, info, json_type): + pass + + def visit_enum_type(self, name, info, values, prefix): + pass + + def visit_array_type(self, name, info, element_type): + pass + + def visit_object_type(self, name, info, base, members, variants): + pass + + def visit_object_type_flat(self, name, info, members, variants): + pass + + def visit_alternate_type(self, name, info, variants): + pass + + def visit_command(self, name, info, arg_type, ret_type, + gen, success_response, boxed): + pass + + def visit_event(self, name, info, arg_type, boxed): + pass + + +class QAPISchemaType(QAPISchemaEntity): + # Return the C type for common use. + # For the types we commonly box, this is a pointer type. + def c_type(self): + pass + + # Return the C type to be used in a parameter list. + def c_param_type(self): + return self.c_type() + + # Return the C type to be used where we suppress boxing. + def c_unboxed_type(self): + return self.c_type() + + def json_type(self): + pass + + def alternate_qtype(self): + json2qtype = { + 'null': 'QTYPE_QNULL', + 'string': 'QTYPE_QSTRING', + 'number': 'QTYPE_QNUM', + 'int': 'QTYPE_QNUM', + 'boolean': 'QTYPE_QBOOL', + 'object': 'QTYPE_QDICT' + } + return json2qtype.get(self.json_type()) + + def doc_type(self): + if self.is_implicit(): + return None + return self.name + + +class QAPISchemaBuiltinType(QAPISchemaType): + def __init__(self, name, json_type, c_type): + QAPISchemaType.__init__(self, name, None, None) + assert not c_type or isinstance(c_type, str) + assert json_type in ('string', 'number', 'int', 'boolean', 'null', + 'value') + self._json_type_name = json_type + self._c_type_name = c_type + + def c_name(self): + return self.name + + def c_type(self): + return self._c_type_name + + def c_param_type(self): + if self.name == 'str': + return 'const ' + self._c_type_name + return self._c_type_name + + def json_type(self): + return self._json_type_name + + def doc_type(self): + return self.json_type() + + def visit(self, visitor): + visitor.visit_builtin_type(self.name, self.info, self.json_type()) + + +class QAPISchemaEnumType(QAPISchemaType): + def __init__(self, name, info, doc, values, prefix): + QAPISchemaType.__init__(self, name, info, doc) + for v in values: + assert isinstance(v, QAPISchemaMember) + v.set_owner(name) + assert prefix is None or isinstance(prefix, str) + self.values = values + self.prefix = prefix + + def check(self, schema): + seen = {} + for v in self.values: + v.check_clash(self.info, seen) + if self.doc: + self.doc.connect_member(v) + + def is_implicit(self): + # See QAPISchema._make_implicit_enum_type() and ._def_predefineds() + return self.name.endswith('Kind') or self.name == 'QType' + + def c_type(self): + return c_name(self.name) + + def member_names(self): + return [v.name for v in self.values] + + def json_type(self): + return 'string' + + def visit(self, visitor): + visitor.visit_enum_type(self.name, self.info, + self.member_names(), self.prefix) + + +class QAPISchemaArrayType(QAPISchemaType): + def __init__(self, name, info, element_type): + QAPISchemaType.__init__(self, name, info, None) + assert isinstance(element_type, str) + self._element_type_name = element_type + self.element_type = None + + def check(self, schema): + self.element_type = schema.lookup_type(self._element_type_name) + assert self.element_type + + def is_implicit(self): + return True + + def c_type(self): + return c_name(self.name) + pointer_suffix + + def json_type(self): + return 'array' + + def doc_type(self): + elt_doc_type = self.element_type.doc_type() + if not elt_doc_type: + return None + return 'array of ' + elt_doc_type + + def visit(self, visitor): + visitor.visit_array_type(self.name, self.info, self.element_type) + + +class QAPISchemaObjectType(QAPISchemaType): + def __init__(self, name, info, doc, base, local_members, variants): + # struct has local_members, optional base, and no variants + # flat union has base, variants, and no local_members + # simple union has local_members, variants, and no base + QAPISchemaType.__init__(self, name, info, doc) + assert base is None or isinstance(base, str) + for m in local_members: + assert isinstance(m, QAPISchemaObjectTypeMember) + m.set_owner(name) + if variants is not None: + assert isinstance(variants, QAPISchemaObjectTypeVariants) + variants.set_owner(name) + self._base_name = base + self.base = None + self.local_members = local_members + self.variants = variants + self.members = None + + def check(self, schema): + if self.members is False: # check for cycles + raise QAPISemError(self.info, + "Object %s contains itself" % self.name) + if self.members: + return + self.members = False # mark as being checked + seen = OrderedDict() + if self._base_name: + self.base = schema.lookup_type(self._base_name) + assert isinstance(self.base, QAPISchemaObjectType) + self.base.check(schema) + self.base.check_clash(self.info, seen) + for m in self.local_members: + m.check(schema) + m.check_clash(self.info, seen) + if self.doc: + self.doc.connect_member(m) + self.members = seen.values() + if self.variants: + self.variants.check(schema, seen) + assert self.variants.tag_member in self.members + self.variants.check_clash(self.info, seen) + if self.doc: + self.doc.check() + + # Check that the members of this type do not cause duplicate JSON members, + # and update seen to track the members seen so far. Report any errors + # on behalf of info, which is not necessarily self.info + def check_clash(self, info, seen): + assert not self.variants # not implemented + for m in self.members: + m.check_clash(info, seen) + + def is_implicit(self): + # See QAPISchema._make_implicit_object_type(), as well as + # _def_predefineds() + return self.name.startswith('q_') + + def is_empty(self): + assert self.members is not None + return not self.members and not self.variants + + def c_name(self): + assert self.name != 'q_empty' + return QAPISchemaType.c_name(self) + + def c_type(self): + assert not self.is_implicit() + return c_name(self.name) + pointer_suffix + + def c_unboxed_type(self): + return c_name(self.name) + + def json_type(self): + return 'object' + + def visit(self, visitor): + visitor.visit_object_type(self.name, self.info, + self.base, self.local_members, self.variants) + visitor.visit_object_type_flat(self.name, self.info, + self.members, self.variants) + + +class QAPISchemaMember(object): + role = 'member' + + def __init__(self, name): + assert isinstance(name, str) + self.name = name + self.owner = None + + def set_owner(self, name): + assert not self.owner + self.owner = name + + def check_clash(self, info, seen): + cname = c_name(self.name) + if cname.lower() != cname and self.owner not in name_case_whitelist: + raise QAPISemError(info, + "%s should not use uppercase" % self.describe()) + if cname in seen: + raise QAPISemError(info, "%s collides with %s" % + (self.describe(), seen[cname].describe())) + seen[cname] = self + + def _pretty_owner(self): + owner = self.owner + if owner.startswith('q_obj_'): + # See QAPISchema._make_implicit_object_type() - reverse the + # mapping there to create a nice human-readable description + owner = owner[6:] + if owner.endswith('-arg'): + return '(parameter of %s)' % owner[:-4] + elif owner.endswith('-base'): + return '(base of %s)' % owner[:-5] + else: + assert owner.endswith('-wrapper') + # Unreachable and not implemented + assert False + if owner.endswith('Kind'): + # See QAPISchema._make_implicit_enum_type() + return '(branch of %s)' % owner[:-4] + return '(%s of %s)' % (self.role, owner) + + def describe(self): + return "'%s' %s" % (self.name, self._pretty_owner()) + + +class QAPISchemaObjectTypeMember(QAPISchemaMember): + def __init__(self, name, typ, optional): + QAPISchemaMember.__init__(self, name) + assert isinstance(typ, str) + assert isinstance(optional, bool) + self._type_name = typ + self.type = None + self.optional = optional + + def check(self, schema): + assert self.owner + self.type = schema.lookup_type(self._type_name) + assert self.type + + +class QAPISchemaObjectTypeVariants(object): + def __init__(self, tag_name, tag_member, variants): + # Flat unions pass tag_name but not tag_member. + # Simple unions and alternates pass tag_member but not tag_name. + # After check(), tag_member is always set, and tag_name remains + # a reliable witness of being used by a flat union. + assert bool(tag_member) != bool(tag_name) + assert (isinstance(tag_name, str) or + isinstance(tag_member, QAPISchemaObjectTypeMember)) + assert len(variants) > 0 + for v in variants: + assert isinstance(v, QAPISchemaObjectTypeVariant) + self._tag_name = tag_name + self.tag_member = tag_member + self.variants = variants + + def set_owner(self, name): + for v in self.variants: + v.set_owner(name) + + def check(self, schema, seen): + if not self.tag_member: # flat union + self.tag_member = seen[c_name(self._tag_name)] + assert self._tag_name == self.tag_member.name + assert isinstance(self.tag_member.type, QAPISchemaEnumType) + for v in self.variants: + v.check(schema) + # Union names must match enum values; alternate names are + # checked separately. Use 'seen' to tell the two apart. + if seen: + assert v.name in self.tag_member.type.member_names() + assert isinstance(v.type, QAPISchemaObjectType) + v.type.check(schema) + + def check_clash(self, info, seen): + for v in self.variants: + # Reset seen map for each variant, since qapi names from one + # branch do not affect another branch + assert isinstance(v.type, QAPISchemaObjectType) + v.type.check_clash(info, dict(seen)) + + +class QAPISchemaObjectTypeVariant(QAPISchemaObjectTypeMember): + role = 'branch' + + def __init__(self, name, typ): + QAPISchemaObjectTypeMember.__init__(self, name, typ, False) + + +class QAPISchemaAlternateType(QAPISchemaType): + def __init__(self, name, info, doc, variants): + QAPISchemaType.__init__(self, name, info, doc) + assert isinstance(variants, QAPISchemaObjectTypeVariants) + assert variants.tag_member + variants.set_owner(name) + variants.tag_member.set_owner(self.name) + self.variants = variants + + def check(self, schema): + self.variants.tag_member.check(schema) + # Not calling self.variants.check_clash(), because there's nothing + # to clash with + self.variants.check(schema, {}) + # Alternate branch names have no relation to the tag enum values; + # so we have to check for potential name collisions ourselves. + seen = {} + for v in self.variants.variants: + v.check_clash(self.info, seen) + if self.doc: + self.doc.connect_member(v) + if self.doc: + self.doc.check() + + def c_type(self): + return c_name(self.name) + pointer_suffix + + def json_type(self): + return 'value' + + 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, doc, arg_type, ret_type, + gen, success_response, boxed): + QAPISchemaEntity.__init__(self, name, info, doc) + assert not arg_type or isinstance(arg_type, str) + assert not ret_type or isinstance(ret_type, str) + self._arg_type_name = arg_type + self.arg_type = None + self._ret_type_name = ret_type + self.ret_type = None + self.gen = gen + self.success_response = success_response + self.boxed = boxed + + 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) or + isinstance(self.arg_type, QAPISchemaAlternateType)) + self.arg_type.check(schema) + if self.boxed: + if self.arg_type.is_empty(): + raise QAPISemError(self.info, + "Cannot use 'boxed' with empty type") + else: + assert not isinstance(self.arg_type, QAPISchemaAlternateType) + assert not self.arg_type.variants + elif self.boxed: + raise QAPISemError(self.info, "Use of 'boxed' requires 'data'") + if self._ret_type_name: + self.ret_type = schema.lookup_type(self._ret_type_name) + assert isinstance(self.ret_type, QAPISchemaType) + + def visit(self, visitor): + visitor.visit_command(self.name, self.info, + self.arg_type, self.ret_type, + self.gen, self.success_response, self.boxed) + + +class QAPISchemaEvent(QAPISchemaEntity): + def __init__(self, name, info, doc, arg_type, boxed): + QAPISchemaEntity.__init__(self, name, info, doc) + assert not arg_type or isinstance(arg_type, str) + self._arg_type_name = arg_type + self.arg_type = None + self.boxed = boxed + + 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) or + isinstance(self.arg_type, QAPISchemaAlternateType)) + self.arg_type.check(schema) + if self.boxed: + if self.arg_type.is_empty(): + raise QAPISemError(self.info, + "Cannot use 'boxed' with empty type") + else: + assert not isinstance(self.arg_type, QAPISchemaAlternateType) + assert not self.arg_type.variants + elif self.boxed: + raise QAPISemError(self.info, "Use of 'boxed' requires 'data'") + + def visit(self, visitor): + visitor.visit_event(self.name, self.info, self.arg_type, self.boxed) + + +class QAPISchema(object): + def __init__(self, fname): + try: + parser = QAPISchemaParser(open(fname, 'r')) + self.exprs = check_exprs(parser.exprs) + self.docs = parser.docs + self._entity_dict = {} + self._predefining = True + self._def_predefineds() + self._predefining = False + self._def_exprs() + self.check() + except QAPIError as err: + print(err, file=sys.stderr) + exit(1) + + def _def_entity(self, ent): + # Only the predefined types are allowed to not have info + assert ent.info or self._predefining + assert ent.name not in self._entity_dict + self._entity_dict[ent.name] = ent + + def lookup_entity(self, name, typ=None): + ent = self._entity_dict.get(name) + if typ and not isinstance(ent, typ): + return None + return ent + + def lookup_type(self, name): + return self.lookup_entity(name, QAPISchemaType) + + def _def_builtin_type(self, name, json_type, c_type): + self._def_entity(QAPISchemaBuiltinType(name, json_type, c_type)) + # TODO As long as we have QAPI_TYPES_BUILTIN to share multiple + # qapi-types.h from a single .c, all arrays of builtins must be + # declared in the first file whether or not they are used. Nicer + # would be to use lazy instantiation, while figuring out how to + # avoid compilation issues with multiple qapi-types.h. + self._make_array_type(name, None) + + def _def_predefineds(self): + for t in [('str', 'string', 'char' + pointer_suffix), + ('number', 'number', 'double'), + ('int', 'int', 'int64_t'), + ('int8', 'int', 'int8_t'), + ('int16', 'int', 'int16_t'), + ('int32', 'int', 'int32_t'), + ('int64', 'int', 'int64_t'), + ('uint8', 'int', 'uint8_t'), + ('uint16', 'int', 'uint16_t'), + ('uint32', 'int', 'uint32_t'), + ('uint64', 'int', 'uint64_t'), + ('size', 'int', 'uint64_t'), + ('bool', 'boolean', 'bool'), + ('any', 'value', 'QObject' + pointer_suffix), + ('null', 'null', 'QNull' + pointer_suffix)]: + self._def_builtin_type(*t) + self.the_empty_object_type = QAPISchemaObjectType( + 'q_empty', None, None, None, [], None) + self._def_entity(self.the_empty_object_type) + qtype_values = self._make_enum_members(['none', 'qnull', 'qnum', + 'qstring', 'qdict', 'qlist', + 'qbool']) + self._def_entity(QAPISchemaEnumType('QType', None, None, + qtype_values, 'QTYPE')) + + def _make_enum_members(self, values): + return [QAPISchemaMember(v) for v in values] + + def _make_implicit_enum_type(self, name, info, values): + # See also QAPISchemaObjectTypeMember._pretty_owner() + name = name + 'Kind' # Use namespace reserved by add_name() + self._def_entity(QAPISchemaEnumType( + name, info, None, self._make_enum_members(values), None)) + return name + + def _make_array_type(self, element_type, info): + name = element_type + 'List' # Use namespace reserved by add_name() + if not self.lookup_type(name): + self._def_entity(QAPISchemaArrayType(name, info, element_type)) + return name + + def _make_implicit_object_type(self, name, info, doc, role, members): + if not members: + return None + # See also QAPISchemaObjectTypeMember._pretty_owner() + name = 'q_obj_%s-%s' % (name, role) + if not self.lookup_entity(name, QAPISchemaObjectType): + self._def_entity(QAPISchemaObjectType(name, info, doc, None, + members, None)) + return name + + def _def_enum_type(self, expr, info, doc): + name = expr['enum'] + data = expr['data'] + prefix = expr.get('prefix') + self._def_entity(QAPISchemaEnumType( + name, info, doc, self._make_enum_members(data), prefix)) + + def _make_member(self, name, typ, info): + optional = False + if name.startswith('*'): + name = name[1:] + optional = True + if isinstance(typ, list): + assert len(typ) == 1 + typ = self._make_array_type(typ[0], info) + return QAPISchemaObjectTypeMember(name, typ, optional) + + def _make_members(self, data, info): + return [self._make_member(key, value, info) + for (key, value) in data.items()] + + def _def_struct_type(self, expr, info, doc): + name = expr['struct'] + base = expr.get('base') + data = expr['data'] + self._def_entity(QAPISchemaObjectType(name, info, doc, base, + self._make_members(data, info), + None)) + + def _make_variant(self, case, typ): + return QAPISchemaObjectTypeVariant(case, typ) + + def _make_simple_variant(self, case, typ, info): + if isinstance(typ, list): + assert len(typ) == 1 + typ = self._make_array_type(typ[0], info) + typ = self._make_implicit_object_type( + typ, info, None, 'wrapper', [self._make_member('data', typ, info)]) + return QAPISchemaObjectTypeVariant(case, typ) + + def _def_union_type(self, expr, info, doc): + name = expr['union'] + data = expr['data'] + base = expr.get('base') + tag_name = expr.get('discriminator') + tag_member = None + if isinstance(base, dict): + base = (self._make_implicit_object_type( + name, info, doc, 'base', self._make_members(base, info))) + if tag_name: + variants = [self._make_variant(key, value) + for (key, value) in data.items()] + members = [] + else: + variants = [self._make_simple_variant(key, value, info) + for (key, value) in data.items()] + typ = self._make_implicit_enum_type(name, info, + [v.name for v in variants]) + tag_member = QAPISchemaObjectTypeMember('type', typ, False) + members = [tag_member] + self._def_entity( + QAPISchemaObjectType(name, info, doc, base, members, + QAPISchemaObjectTypeVariants(tag_name, + tag_member, + variants))) + + def _def_alternate_type(self, expr, info, doc): + name = expr['alternate'] + data = expr['data'] + variants = [self._make_variant(key, value) + for (key, value) in data.items()] + tag_member = QAPISchemaObjectTypeMember('type', 'QType', False) + self._def_entity( + QAPISchemaAlternateType(name, info, doc, + QAPISchemaObjectTypeVariants(None, + tag_member, + variants))) + + def _def_command(self, expr, info, doc): + name = expr['command'] + data = expr.get('data') + rets = expr.get('returns') + gen = expr.get('gen', True) + success_response = expr.get('success-response', True) + boxed = expr.get('boxed', False) + if isinstance(data, OrderedDict): + data = self._make_implicit_object_type( + name, info, doc, 'arg', self._make_members(data, info)) + if isinstance(rets, list): + assert len(rets) == 1 + rets = self._make_array_type(rets[0], info) + self._def_entity(QAPISchemaCommand(name, info, doc, data, rets, + gen, success_response, boxed)) + + def _def_event(self, expr, info, doc): + name = expr['event'] + data = expr.get('data') + boxed = expr.get('boxed', False) + if isinstance(data, OrderedDict): + data = self._make_implicit_object_type( + name, info, doc, 'arg', self._make_members(data, info)) + self._def_entity(QAPISchemaEvent(name, info, doc, data, boxed)) + + def _def_exprs(self): + for expr_elem in self.exprs: + expr = expr_elem['expr'] + info = expr_elem['info'] + doc = expr_elem.get('doc') + if 'enum' in expr: + self._def_enum_type(expr, info, doc) + elif 'struct' in expr: + self._def_struct_type(expr, info, doc) + elif 'union' in expr: + self._def_union_type(expr, info, doc) + elif 'alternate' in expr: + self._def_alternate_type(expr, info, doc) + elif 'command' in expr: + self._def_command(expr, info, doc) + elif 'event' in expr: + self._def_event(expr, info, doc) + else: + assert False + + def check(self): + for (name, ent) in sorted(self._entity_dict.items()): + ent.check(self) + + def visit(self, visitor): + visitor.visit_begin(self) + for (name, entity) in sorted(self._entity_dict.items()): + if visitor.visit_needed(entity): + entity.visit(visitor) + visitor.visit_end() + + +# +# Code generation helpers +# + +def camel_case(name): + new_name = '' + first = True + for ch in name: + if ch in ['_', '-']: + first = True + elif first: + new_name += ch.upper() + first = False + else: + new_name += ch.lower() + return new_name + + +# ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1 +# ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2 +# ENUM24_Name -> ENUM24_NAME +def camel_to_upper(value): + c_fun_str = c_name(value, False) + if value.isupper(): + return c_fun_str + + new_name = '' + l = len(c_fun_str) + for i in range(l): + c = c_fun_str[i] + # When c is upper and no '_' appears before, do more checks + if c.isupper() and (i > 0) and c_fun_str[i - 1] != '_': + if i < l - 1 and c_fun_str[i + 1].islower(): + new_name += '_' + elif c_fun_str[i - 1].isdigit(): + new_name += '_' + new_name += c + return new_name.lstrip('_').upper() + + +def c_enum_const(type_name, const_name, prefix=None): + if prefix is not None: + type_name = prefix + return camel_to_upper(type_name) + '_' + c_name(const_name, False).upper() + +if hasattr(str, 'maketrans'): + c_name_trans = str.maketrans('.-', '__') +else: + c_name_trans = string.maketrans('.-', '__') + + +# Map @name to a valid C identifier. +# If @protect, avoid returning certain ticklish identifiers (like +# C keywords) by prepending 'q_'. +# +# Used for converting 'name' from a 'name':'type' qapi definition +# into a generated struct member, as well as converting type names +# into substrings of a generated C function name. +# '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo' +# protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int' +def c_name(name, protect=True): + # ANSI X3J11/88-090, 3.1.1 + c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue', + 'default', 'do', 'double', 'else', 'enum', 'extern', + 'float', 'for', 'goto', 'if', 'int', 'long', 'register', + 'return', 'short', 'signed', 'sizeof', 'static', + 'struct', 'switch', 'typedef', 'union', 'unsigned', + 'void', 'volatile', 'while']) + # ISO/IEC 9899:1999, 6.4.1 + c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary']) + # ISO/IEC 9899:2011, 6.4.1 + c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic', + '_Noreturn', '_Static_assert', '_Thread_local']) + # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html + # excluding _.* + gcc_words = set(['asm', 'typeof']) + # C++ ISO/IEC 14882:2003 2.11 + cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete', + 'dynamic_cast', 'explicit', 'false', 'friend', 'mutable', + 'namespace', 'new', 'operator', 'private', 'protected', + 'public', 'reinterpret_cast', 'static_cast', 'template', + 'this', 'throw', 'true', 'try', 'typeid', 'typename', + 'using', 'virtual', 'wchar_t', + # alternative representations + 'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not', + 'not_eq', 'or', 'or_eq', 'xor', 'xor_eq']) + # namespace pollution: + polluted_words = set(['unix', 'errno', 'mips', 'sparc']) + name = name.translate(c_name_trans) + if protect and (name in c89_words | c99_words | c11_words | gcc_words + | cpp_words | polluted_words): + return 'q_' + name + return name + +eatspace = '\033EATSPACE.' +pointer_suffix = ' *' + eatspace + + +def genindent(count): + ret = '' + for _ in range(count): + ret += ' ' + return ret + +indent_level = 0 + + +def push_indent(indent_amount=4): + global indent_level + indent_level += indent_amount + + +def pop_indent(indent_amount=4): + global indent_level + indent_level -= indent_amount + + +# Generate @code with @kwds interpolated. +# Obey indent_level, and strip eatspace. +def cgen(code, **kwds): + raw = code % kwds + if indent_level: + indent = genindent(indent_level) + # re.subn() lacks flags support before Python 2.7, use re.compile() + raw = re.subn(re.compile(r'^.', re.MULTILINE), + indent + r'\g<0>', raw) + raw = raw[0] + return re.sub(re.escape(eatspace) + r' *', '', raw) + + +def mcgen(code, **kwds): + if code[0] == '\n': + code = code[1:] + return cgen(code, **kwds) + + +def guardname(filename): + return c_name(filename, protect=False).upper() + + +def guardstart(name): + return mcgen(''' +#ifndef %(name)s +#define %(name)s + +''', + name=guardname(name)) + + +def guardend(name): + return mcgen(''' + +#endif /* %(name)s */ +''', + name=guardname(name)) + + +def gen_enum_lookup(name, values, prefix=None): + ret = mcgen(''' + +const QEnumLookup %(c_name)s_lookup = { + .array = (const char *const[]) { +''', + c_name=c_name(name)) + for value in values: + index = c_enum_const(name, value, prefix) + ret += mcgen(''' + [%(index)s] = "%(value)s", +''', + index=index, value=value) + + ret += mcgen(''' + }, + .size = %(max_index)s +}; +''', + max_index=c_enum_const(name, '_MAX', prefix)) + return ret + + +def gen_enum(name, values, prefix=None): + # append automatically generated _MAX value + enum_values = values + ['_MAX'] + + ret = mcgen(''' + +typedef enum %(c_name)s { +''', + c_name=c_name(name)) + + i = 0 + for value in enum_values: + ret += mcgen(''' + %(c_enum)s = %(i)d, +''', + c_enum=c_enum_const(name, value, prefix), + i=i) + i += 1 + + ret += mcgen(''' +} %(c_name)s; +''', + c_name=c_name(name)) + + ret += mcgen(''' + +#define %(c_name)s_str(val) \\ + qapi_enum_lookup(&%(c_name)s_lookup, (val)) + +extern const QEnumLookup %(c_name)s_lookup; +''', + c_name=c_name(name)) + return ret + + +def build_params(arg_type, boxed, extra): + if not arg_type: + assert not boxed + return extra + ret = '' + sep = '' + if boxed: + ret += '%s arg' % arg_type.c_param_type() + sep = ', ' + else: + assert not arg_type.variants + for memb in arg_type.members: + ret += sep + sep = ', ' + if memb.optional: + ret += 'bool has_%s, ' % c_name(memb.name) + ret += '%s %s' % (memb.type.c_param_type(), + c_name(memb.name)) + if extra: + ret += sep + extra + return ret + + +# +# Common command line parsing +# + + +def parse_command_line(extra_options='', extra_long_options=[]): + + try: + opts, args = getopt.gnu_getopt(sys.argv[1:], + 'p:o:' + extra_options, + ['prefix=', 'output-dir='] + + extra_long_options) + except getopt.GetoptError as err: + print("%s: %s" % (sys.argv[0], str(err)), file=sys.stderr) + sys.exit(1) + + output_dir = '' + prefix = '' + extra_opts = [] + + for oa in opts: + o, a = oa + if o in ('-p', '--prefix'): + match = re.match(r'([A-Za-z_.-][A-Za-z0-9_.-]*)?', a) + if match.end() != len(a): + print("%s: 'funny character '%s' in argument of --prefix" \ + % (sys.argv[0], a[match.end()]), file=sys.stderr) + sys.exit(1) + prefix = a + elif o in ('-o', '--output-dir'): + output_dir = a + '/' + else: + extra_opts.append(oa) + + if len(args) != 1: + print("%s: need exactly one argument" % sys.argv[0], file=sys.stderr) + sys.exit(1) + fname = args[0] + + return (fname, output_dir, prefix, extra_opts) + + +# +# Accumulate and write output +# + +class QAPIGen(object): + + def __init__(self): + self._preamble = '' + self._body = '' + + def preamble_add(self, text): + self._preamble += text + + def add(self, text): + self._body += text + + def _top(self, fname): + return '' + + def _bottom(self, fname): + return '' + + def write(self, output_dir, fname): + if output_dir: + try: + os.makedirs(output_dir) + except os.error as e: + if e.errno != errno.EEXIST: + raise + f = open(os.path.join(output_dir, fname), 'w') + f.write(self._top(fname) + self._preamble + self._body + + self._bottom(fname)) + f.close() + + +class QAPIGenC(QAPIGen): + + def __init__(self, blurb, pydoc): + QAPIGen.__init__(self) + self._blurb = blurb + self._copyright = '\n * '.join(re.findall(r'^Copyright .*', pydoc, + re.MULTILINE)) + + def _top(self, fname): + return mcgen(''' +/* AUTOMATICALLY GENERATED, DO NOT MODIFY */ + +/* +%(blurb)s + * + * %(copyright)s + * + * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. + * See the COPYING.LIB file in the top-level directory. + */ + +''', + blurb=self._blurb, copyright=self._copyright) + + +class QAPIGenH(QAPIGenC): + + def _top(self, fname): + return QAPIGenC._top(self, fname) + guardstart(fname) + + def _bottom(self, fname): + return guardend(fname) + + +class QAPIGenDoc(QAPIGen): + + def _top(self, fname): + return (QAPIGen._top(self, fname) + + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py new file mode 100644 index 0000000000..cc4d5a43fb --- /dev/null +++ b/scripts/qapi/doc.py @@ -0,0 +1,278 @@ +#!/usr/bin/env python +# QAPI texi generator +# +# This work is licensed under the terms of the GNU LGPL, version 2+. +# See the COPYING file in the top-level directory. +"""This script produces the documentation of a qapi schema in texinfo format""" + +from __future__ import print_function +import re +import qapi.common + +MSG_FMT = """ +@deftypefn {type} {{}} {name} + +{body} +@end deftypefn + +""".format + +TYPE_FMT = """ +@deftp {{{type}}} {name} + +{body} +@end deftp + +""".format + +EXAMPLE_FMT = """@example +{code} +@end example +""".format + + +def subst_strong(doc): + """Replaces *foo* by @strong{foo}""" + return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) + + +def subst_emph(doc): + """Replaces _foo_ by @emph{foo}""" + return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) + + +def subst_vars(doc): + """Replaces @var by @code{var}""" + return re.sub(r'@([\w-]+)', r'@code{\1}', doc) + + +def subst_braces(doc): + """Replaces {} with @{ @}""" + return doc.replace('{', '@{').replace('}', '@}') + + +def texi_example(doc): + """Format @example""" + # TODO: Neglects to escape @ characters. + # We should probably escape them in subst_braces(), and rename the + # function to subst_special() or subs_texi_special(). If we do that, we + # need to delay it until after subst_vars() in texi_format(). + doc = subst_braces(doc).strip('\n') + return EXAMPLE_FMT(code=doc) + + +def texi_format(doc): + """ + Format documentation + + Lines starting with: + - |: generates an @example + - =: generates @section + - ==: generates @subsection + - 1. or 1): generates an @enumerate @item + - */-: generates an @itemize list + """ + ret = '' + doc = subst_braces(doc) + doc = subst_vars(doc) + doc = subst_emph(doc) + doc = subst_strong(doc) + inlist = '' + lastempty = False + for line in doc.split('\n'): + empty = line == '' + + # FIXME: Doing this in a single if / elif chain is + # problematic. For instance, a line without markup terminates + # a list if it follows a blank line (reaches the final elif), + # but a line with some *other* markup, such as a = title + # doesn't. + # + # Make sure to update section "Documentation markup" in + # docs/devel/qapi-code-gen.txt when fixing this. + if line.startswith('| '): + line = EXAMPLE_FMT(code=line[2:]) + elif line.startswith('= '): + line = '@section ' + line[2:] + elif line.startswith('== '): + line = '@subsection ' + line[3:] + elif re.match(r'^([0-9]*\.) ', line): + if not inlist: + ret += '@enumerate\n' + inlist = 'enumerate' + ret += '@item\n' + line = line[line.find(' ')+1:] + elif re.match(r'^[*-] ', line): + if not inlist: + ret += '@itemize %s\n' % {'*': '@bullet', + '-': '@minus'}[line[0]] + inlist = 'itemize' + ret += '@item\n' + line = line[2:] + elif lastempty and inlist: + ret += '@end %s\n\n' % inlist + inlist = '' + + lastempty = empty + ret += line + '\n' + + if inlist: + ret += '@end %s\n\n' % inlist + return ret + + +def texi_body(doc): + """Format the main documentation body""" + return texi_format(doc.body.text) + + +def texi_enum_value(value): + """Format a table of members item for an enumeration value""" + return '@item @code{%s}\n' % value.name + + +def texi_member(member, suffix=''): + """Format a table of members item for an object type member""" + typ = member.type.doc_type() + return '@item @code{%s%s%s}%s%s\n' % ( + member.name, + ': ' if typ else '', + typ if typ else '', + ' (optional)' if member.optional else '', + suffix) + + +def texi_members(doc, what, base, variants, member_func): + """Format the table of members""" + items = '' + for section in doc.args.values(): + # TODO Drop fallbacks when undocumented members are outlawed + if section.text: + desc = texi_format(section.text) + elif (variants and variants.tag_member == section.member + and not section.member.type.doc_type()): + values = section.member.type.member_names() + members_text = ', '.join(['@t{"%s"}' % v for v in values]) + desc = 'One of ' + members_text + '\n' + else: + desc = 'Not documented\n' + items += member_func(section.member) + desc + if base: + items += '@item The members of @code{%s}\n' % base.doc_type() + if variants: + for v in variants.variants: + when = ' when @code{%s} is @t{"%s"}' % ( + variants.tag_member.name, v.name) + if v.type.is_implicit(): + assert not v.type.base and not v.type.variants + for m in v.type.local_members: + items += member_func(m, when) + else: + items += '@item The members of @code{%s}%s\n' % ( + v.type.doc_type(), when) + if not items: + return '' + return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) + + +def texi_sections(doc): + """Format additional sections following arguments""" + body = '' + for section in doc.sections: + if section.name: + # prefer @b over @strong, so txt doesn't translate it to *Foo:* + body += '\n@b{%s:}\n' % section.name + if section.name and section.name.startswith('Example'): + body += texi_example(section.text) + else: + body += texi_format(section.text) + return body + + +def texi_entity(doc, what, base=None, variants=None, + member_func=texi_member): + return (texi_body(doc) + + texi_members(doc, what, base, variants, member_func) + + texi_sections(doc)) + + +class QAPISchemaGenDocVisitor(qapi.common.QAPISchemaVisitor): + def __init__(self): + self.out = None + self.cur_doc = None + + def visit_begin(self, schema): + self.out = '' + + def visit_enum_type(self, name, info, values, prefix): + doc = self.cur_doc + self.out += TYPE_FMT(type='Enum', + name=doc.symbol, + body=texi_entity(doc, 'Values', + member_func=texi_enum_value)) + + def visit_object_type(self, name, info, base, members, variants): + doc = self.cur_doc + if base and base.is_implicit(): + base = None + self.out += TYPE_FMT(type='Object', + name=doc.symbol, + body=texi_entity(doc, 'Members', base, variants)) + + def visit_alternate_type(self, name, info, variants): + doc = self.cur_doc + self.out += TYPE_FMT(type='Alternate', + name=doc.symbol, + body=texi_entity(doc, 'Members')) + + def visit_command(self, name, info, arg_type, ret_type, + gen, success_response, boxed): + doc = self.cur_doc + if boxed: + body = texi_body(doc) + body += ('\n@b{Arguments:} the members of @code{%s}\n' + % arg_type.name) + body += texi_sections(doc) + else: + body = texi_entity(doc, 'Arguments') + self.out += MSG_FMT(type='Command', + name=doc.symbol, + body=body) + + def visit_event(self, name, info, arg_type, boxed): + doc = self.cur_doc + self.out += MSG_FMT(type='Event', + name=doc.symbol, + body=texi_entity(doc, 'Arguments')) + + def symbol(self, doc, entity): + if self.out: + self.out += '\n' + self.cur_doc = doc + entity.visit(self) + self.cur_doc = None + + def freeform(self, doc): + assert not doc.args + if self.out: + self.out += '\n' + self.out += texi_body(doc) + texi_sections(doc) + + +def texi_schema(schema): + """Convert QAPI schema documentation to Texinfo""" + gen = QAPISchemaGenDocVisitor() + gen.visit_begin(schema) + for doc in schema.docs: + if doc.symbol: + gen.symbol(doc, schema.lookup_entity(doc.symbol)) + else: + gen.freeform(doc) + return gen.out + + +def gen_doc(schema, output_dir, prefix): + if qapi.common.doc_required: + gen = qapi.common.QAPIGenDoc() + gen.add(texi_schema(schema)) + gen.write(output_dir, prefix + 'qapi-doc.texi') diff --git a/scripts/qapi/events.py b/scripts/qapi/events.py new file mode 100644 index 0000000000..b7dc82004f --- /dev/null +++ b/scripts/qapi/events.py @@ -0,0 +1,204 @@ +""" +QAPI event generator + +Copyright (c) 2014 Wenchao Xia +Copyright (c) 2015-2018 Red Hat Inc. + +Authors: + Wenchao Xia + Markus Armbruster + +This work is licensed under the terms of the GNU GPL, version 2. +See the COPYING file in the top-level directory. +""" + +from qapi.common import * + + +def build_event_send_proto(name, arg_type, boxed): + return 'void qapi_event_send_%(c_name)s(%(param)s)' % { + 'c_name': c_name(name.lower()), + 'param': build_params(arg_type, boxed, 'Error **errp')} + + +def gen_event_send_decl(name, arg_type, boxed): + return mcgen(''' + +%(proto)s; +''', + proto=build_event_send_proto(name, arg_type, boxed)) + + +# Declare and initialize an object 'qapi' using parameters from build_params() +def gen_param_var(typ): + assert not typ.variants + ret = mcgen(''' + %(c_name)s param = { +''', + c_name=typ.c_name()) + sep = ' ' + for memb in typ.members: + ret += sep + sep = ', ' + if memb.optional: + ret += 'has_' + c_name(memb.name) + sep + if memb.type.name == 'str': + # Cast away const added in build_params() + ret += '(char *)' + ret += c_name(memb.name) + ret += mcgen(''' + + }; +''') + if not typ.is_implicit(): + ret += mcgen(''' + %(c_name)s *arg = ¶m; +''', + c_name=typ.c_name()) + return ret + + +def gen_event_send(name, arg_type, boxed, event_enum_name): + # FIXME: Our declaration of local variables (and of 'errp' in the + # parameter list) can collide with exploded members of the event's + # data type passed in as parameters. If this collision ever hits in + # practice, we can rename our local variables with a leading _ prefix, + # or split the code into a wrapper function that creates a boxed + # 'param' object then calls another to do the real work. + ret = mcgen(''' + +%(proto)s +{ + QDict *qmp; + Error *err = NULL; + QMPEventFuncEmit emit; +''', + proto=build_event_send_proto(name, arg_type, boxed)) + + if arg_type and not arg_type.is_empty(): + ret += mcgen(''' + QObject *obj; + Visitor *v; +''') + if not boxed: + ret += gen_param_var(arg_type) + else: + assert not boxed + + ret += mcgen(''' + + emit = qmp_event_get_func_emit(); + if (!emit) { + return; + } + + qmp = qmp_event_build_dict("%(name)s"); + +''', + name=name) + + if arg_type and not arg_type.is_empty(): + ret += mcgen(''' + v = qobject_output_visitor_new(&obj); +''') + if not arg_type.is_implicit(): + ret += mcgen(''' + visit_type_%(c_name)s(v, "%(name)s", &arg, &err); +''', + name=name, c_name=arg_type.c_name()) + else: + ret += mcgen(''' + + visit_start_struct(v, "%(name)s", NULL, 0, &err); + if (err) { + goto out; + } + visit_type_%(c_name)s_members(v, ¶m, &err); + if (!err) { + visit_check_struct(v, &err); + } + visit_end_struct(v, NULL); +''', + name=name, c_name=arg_type.c_name()) + ret += mcgen(''' + if (err) { + goto out; + } + + visit_complete(v, &obj); + qdict_put_obj(qmp, "data", obj); +''') + + ret += mcgen(''' + emit(%(c_enum)s, qmp, &err); + +''', + c_enum=c_enum_const(event_enum_name, name)) + + if arg_type and not arg_type.is_empty(): + ret += mcgen(''' +out: + visit_free(v); +''') + ret += mcgen(''' + error_propagate(errp, err); + QDECREF(qmp); +} +''') + return ret + + +class QAPISchemaGenEventVisitor(QAPISchemaVisitor): + def __init__(self, prefix): + self._enum_name = c_name(prefix + 'QAPIEvent', protect=False) + self.decl = None + self.defn = None + self._event_names = None + + def visit_begin(self, schema): + self.decl = '' + self.defn = '' + self._event_names = [] + + def visit_end(self): + self.decl += gen_enum(self._enum_name, self._event_names) + self.defn += gen_enum_lookup(self._enum_name, self._event_names) + self._event_names = None + + def visit_event(self, name, info, arg_type, boxed): + self.decl += gen_event_send_decl(name, arg_type, boxed) + self.defn += gen_event_send(name, arg_type, boxed, self._enum_name) + self._event_names.append(name) + + +def gen_events(schema, output_dir, prefix): + blurb = ' * Schema-defined QAPI/QMP events' + genc = QAPIGenC(blurb, __doc__) + genh = QAPIGenH(blurb, __doc__) + + genc.add(mcgen(''' +#include "qemu/osdep.h" +#include "qemu-common.h" +#include "%(prefix)sqapi-event.h" +#include "%(prefix)sqapi-visit.h" +#include "qapi/error.h" +#include "qapi/qmp/qdict.h" +#include "qapi/qobject-output-visitor.h" +#include "qapi/qmp-event.h" + +''', + prefix=prefix)) + + genh.add(mcgen(''' +#include "qapi/util.h" +#include "%(prefix)sqapi-types.h" + +''', + prefix=prefix)) + + vis = QAPISchemaGenEventVisitor(prefix) + schema.visit(vis) + genc.add(vis.defn) + genh.add(vis.decl) + genc.write(output_dir, prefix + 'qapi-event.c') + genh.write(output_dir, prefix + 'qapi-event.h') diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py new file mode 100644 index 0000000000..1e4f065164 --- /dev/null +++ b/scripts/qapi/introspect.py @@ -0,0 +1,188 @@ +""" +QAPI introspection generator + +Copyright (C) 2015-2018 Red Hat, Inc. + +Authors: + Markus Armbruster + +This work is licensed under the terms of the GNU GPL, version 2. +See the COPYING file in the top-level directory. +""" + +from qapi.common import * + + +# Caveman's json.dumps() replacement (we're stuck at Python 2.4) +# TODO try to use json.dumps() once we get unstuck +def to_json(obj, level=0): + if obj is None: + ret = 'null' + elif isinstance(obj, str): + ret = '"' + obj.replace('"', r'\"') + '"' + elif isinstance(obj, list): + elts = [to_json(elt, level + 1) + for elt in obj] + ret = '[' + ', '.join(elts) + ']' + elif isinstance(obj, dict): + elts = ['"%s": %s' % (key.replace('"', r'\"'), + to_json(obj[key], level + 1)) + for key in sorted(obj.keys())] + ret = '{' + ', '.join(elts) + '}' + else: + assert False # not implemented + if level == 1: + ret = '\n' + ret + return ret + + +def to_c_string(string): + return '"' + string.replace('\\', r'\\').replace('"', r'\"') + '"' + + +class QAPISchemaGenIntrospectVisitor(QAPISchemaVisitor): + def __init__(self, prefix, unmask): + self._prefix = prefix + self._unmask = unmask + self.defn = None + self.decl = None + self._schema = None + self._jsons = None + self._used_types = None + self._name_map = None + + def visit_begin(self, schema): + self._schema = schema + self._jsons = [] + self._used_types = [] + self._name_map = {} + + def visit_end(self): + # visit the types that are actually used + jsons = self._jsons + self._jsons = [] + for typ in self._used_types: + typ.visit(self) + # generate C + # TODO can generate awfully long lines + jsons.extend(self._jsons) + name = c_name(self._prefix, protect=False) + 'qmp_schema_json' + self.decl = mcgen(''' +extern const char %(c_name)s[]; +''', + c_name=c_name(name)) + lines = to_json(jsons).split('\n') + c_string = '\n '.join([to_c_string(line) for line in lines]) + self.defn = mcgen(''' +const char %(c_name)s[] = %(c_string)s; +''', + c_name=c_name(name), + c_string=c_string) + self._schema = None + self._jsons = None + self._used_types = None + self._name_map = None + + def visit_needed(self, entity): + # Ignore types on first pass; visit_end() will pick up used types + return not isinstance(entity, QAPISchemaType) + + def _name(self, name): + if self._unmask: + return name + if name not in self._name_map: + self._name_map[name] = '%d' % len(self._name_map) + return self._name_map[name] + + def _use_type(self, typ): + # Map the various integer types to plain int + if typ.json_type() == 'int': + typ = self._schema.lookup_type('int') + elif (isinstance(typ, QAPISchemaArrayType) and + typ.element_type.json_type() == 'int'): + typ = self._schema.lookup_type('intList') + # Add type to work queue if new + if typ not in self._used_types: + self._used_types.append(typ) + # Clients should examine commands and events, not types. Hide + # type names to reduce the temptation. Also saves a few + # characters. + if isinstance(typ, QAPISchemaBuiltinType): + return typ.name + if isinstance(typ, QAPISchemaArrayType): + return '[' + self._use_type(typ.element_type) + ']' + return self._name(typ.name) + + def _gen_json(self, name, mtype, obj): + if mtype not in ('command', 'event', 'builtin', 'array'): + name = self._name(name) + obj['name'] = name + obj['meta-type'] = mtype + self._jsons.append(obj) + + def _gen_member(self, member): + ret = {'name': member.name, 'type': self._use_type(member.type)} + if member.optional: + ret['default'] = None + return ret + + def _gen_variants(self, tag_name, variants): + return {'tag': tag_name, + 'variants': [self._gen_variant(v) for v in variants]} + + def _gen_variant(self, variant): + return {'case': variant.name, 'type': self._use_type(variant.type)} + + def visit_builtin_type(self, name, info, json_type): + self._gen_json(name, 'builtin', {'json-type': json_type}) + + def visit_enum_type(self, name, info, values, prefix): + self._gen_json(name, 'enum', {'values': values}) + + def visit_array_type(self, name, info, element_type): + element = self._use_type(element_type) + self._gen_json('[' + element + ']', 'array', {'element-type': element}) + + def visit_object_type_flat(self, name, info, members, variants): + obj = {'members': [self._gen_member(m) for m in members]} + if variants: + obj.update(self._gen_variants(variants.tag_member.name, + variants.variants)) + self._gen_json(name, 'object', obj) + + def visit_alternate_type(self, name, info, variants): + self._gen_json(name, 'alternate', + {'members': [{'type': self._use_type(m.type)} + for m in variants.variants]}) + + def visit_command(self, name, info, arg_type, ret_type, + gen, success_response, boxed): + arg_type = arg_type or self._schema.the_empty_object_type + ret_type = ret_type or self._schema.the_empty_object_type + self._gen_json(name, 'command', + {'arg-type': self._use_type(arg_type), + 'ret-type': self._use_type(ret_type)}) + + def visit_event(self, name, info, arg_type, boxed): + arg_type = arg_type or self._schema.the_empty_object_type + self._gen_json(name, 'event', {'arg-type': self._use_type(arg_type)}) + + +def gen_introspect(schema, output_dir, prefix, opt_unmask): + blurb = ' * QAPI/QMP schema introspection' + genc = QAPIGenC(blurb, __doc__) + genh = QAPIGenH(blurb, __doc__) + + genc.add(mcgen(''' +#include "qemu/osdep.h" +#include "%(prefix)sqmp-introspect.h" + +''', + prefix=prefix)) + + vis = QAPISchemaGenIntrospectVisitor(prefix, opt_unmask) + schema.visit(vis) + genc.add(vis.defn) + genh.add(vis.decl) + genc.write(output_dir, prefix + 'qmp-introspect.c') + genh.write(output_dir, prefix + 'qmp-introspect.h') diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py new file mode 100644 index 0000000000..aa3c01e750 --- /dev/null +++ b/scripts/qapi/types.py @@ -0,0 +1,266 @@ +""" +QAPI types generator + +Copyright IBM, Corp. 2011 +Copyright (c) 2013-2018 Red Hat Inc. + +Authors: + Anthony Liguori + Michael Roth + Markus Armbruster + +This work is licensed under the terms of the GNU GPL, version 2. +# See the COPYING file in the top-level directory. +""" + +from qapi.common import * + + +# variants must be emitted before their container; track what has already +# been output +objects_seen = set() + + +def gen_fwd_object_or_array(name): + return mcgen(''' + +typedef struct %(c_name)s %(c_name)s; +''', + c_name=c_name(name)) + + +def gen_array(name, element_type): + return mcgen(''' + +struct %(c_name)s { + %(c_name)s *next; + %(c_type)s value; +}; +''', + c_name=c_name(name), c_type=element_type.c_type()) + + +def gen_struct_members(members): + ret = '' + for memb in members: + if memb.optional: + ret += mcgen(''' + bool has_%(c_name)s; +''', + c_name=c_name(memb.name)) + ret += mcgen(''' + %(c_type)s %(c_name)s; +''', + c_type=memb.type.c_type(), c_name=c_name(memb.name)) + return ret + + +def gen_object(name, base, members, variants): + if name in objects_seen: + return '' + objects_seen.add(name) + + ret = '' + if variants: + for v in variants.variants: + if isinstance(v.type, QAPISchemaObjectType): + ret += gen_object(v.type.name, v.type.base, + v.type.local_members, v.type.variants) + + ret += mcgen(''' + +struct %(c_name)s { +''', + c_name=c_name(name)) + + if base: + if not base.is_implicit(): + ret += mcgen(''' + /* Members inherited from %(c_name)s: */ +''', + c_name=base.c_name()) + ret += gen_struct_members(base.members) + if not base.is_implicit(): + ret += mcgen(''' + /* Own members: */ +''') + ret += gen_struct_members(members) + + if variants: + ret += gen_variants(variants) + + # Make sure that all structs have at least one member; this avoids + # potential issues with attempting to malloc space for zero-length + # structs in C, and also incompatibility with C++ (where an empty + # struct is size 1). + if (not base or base.is_empty()) and not members and not variants: + ret += mcgen(''' + char qapi_dummy_for_empty_struct; +''') + + ret += mcgen(''' +}; +''') + + return ret + + +def gen_upcast(name, base): + # C makes const-correctness ugly. We have to cast away const to let + # this function work for both const and non-const obj. + return mcgen(''' + +static inline %(base)s *qapi_%(c_name)s_base(const %(c_name)s *obj) +{ + return (%(base)s *)obj; +} +''', + c_name=c_name(name), base=base.c_name()) + + +def gen_variants(variants): + ret = mcgen(''' + union { /* union tag is @%(c_name)s */ +''', + c_name=c_name(variants.tag_member.name)) + + for var in variants.variants: + ret += mcgen(''' + %(c_type)s %(c_name)s; +''', + c_type=var.type.c_unboxed_type(), + c_name=c_name(var.name)) + + ret += mcgen(''' + } u; +''') + + return ret + + +def gen_type_cleanup_decl(name): + ret = mcgen(''' + +void qapi_free_%(c_name)s(%(c_name)s *obj); +''', + c_name=c_name(name)) + return ret + + +def gen_type_cleanup(name): + ret = mcgen(''' + +void qapi_free_%(c_name)s(%(c_name)s *obj) +{ + Visitor *v; + + if (!obj) { + return; + } + + v = qapi_dealloc_visitor_new(); + visit_type_%(c_name)s(v, NULL, &obj, NULL); + visit_free(v); +} +''', + c_name=c_name(name)) + return ret + + +class QAPISchemaGenTypeVisitor(QAPISchemaVisitor): + def __init__(self, opt_builtins): + self._opt_builtins = opt_builtins + self.decl = None + self.defn = None + self._fwdecl = None + self._btin = None + + def visit_begin(self, schema): + # gen_object() is recursive, ensure it doesn't visit the empty type + objects_seen.add(schema.the_empty_object_type.name) + self.decl = '' + self.defn = '' + self._fwdecl = '' + self._btin = '\n' + guardstart('QAPI_TYPES_BUILTIN') + + def visit_end(self): + self.decl = self._fwdecl + self.decl + self._fwdecl = None + # To avoid header dependency hell, we always generate + # declarations for built-in types in our header files and + # simply guard them. See also opt_builtins (command line + # option -b). + self._btin += guardend('QAPI_TYPES_BUILTIN') + self.decl = self._btin + self.decl + self._btin = None + + def _gen_type_cleanup(self, name): + self.decl += gen_type_cleanup_decl(name) + self.defn += gen_type_cleanup(name) + + def visit_enum_type(self, name, info, values, prefix): + # Special case for our lone builtin enum type + # TODO use something cleaner than existence of info + if not info: + self._btin += gen_enum(name, values, prefix) + if self._opt_builtins: + self.defn += gen_enum_lookup(name, values, prefix) + else: + self._fwdecl += gen_enum(name, values, prefix) + self.defn += gen_enum_lookup(name, values, prefix) + + def visit_array_type(self, name, info, element_type): + if isinstance(element_type, QAPISchemaBuiltinType): + self._btin += gen_fwd_object_or_array(name) + self._btin += gen_array(name, element_type) + self._btin += gen_type_cleanup_decl(name) + if self._opt_builtins: + self.defn += gen_type_cleanup(name) + else: + self._fwdecl += gen_fwd_object_or_array(name) + self.decl += gen_array(name, element_type) + self._gen_type_cleanup(name) + + def visit_object_type(self, name, info, base, members, variants): + # Nothing to do for the special empty builtin + if name == 'q_empty': + return + self._fwdecl += gen_fwd_object_or_array(name) + self.decl += gen_object(name, base, members, variants) + if base and not base.is_implicit(): + self.decl += gen_upcast(name, base) + # TODO Worth changing the visitor signature, so we could + # directly use rather than repeat type.is_implicit()? + if not name.startswith('q_'): + # implicit types won't be directly allocated/freed + self._gen_type_cleanup(name) + + def visit_alternate_type(self, name, info, variants): + self._fwdecl += gen_fwd_object_or_array(name) + self.decl += gen_object(name, None, [variants.tag_member], variants) + self._gen_type_cleanup(name) + + +def gen_types(schema, output_dir, prefix, opt_builtins): + blurb = ' * Schema-defined QAPI types' + genc = QAPIGenC(blurb, __doc__) + genh = QAPIGenH(blurb, __doc__) + + genc.add(mcgen(''' +#include "qemu/osdep.h" +#include "qapi/dealloc-visitor.h" +#include "%(prefix)sqapi-types.h" +#include "%(prefix)sqapi-visit.h" +''', + prefix=prefix)) + + genh.add(mcgen(''' +#include "qapi/util.h" +''')) + + vis = QAPISchemaGenTypeVisitor(opt_builtins) + schema.visit(vis) + genc.add(vis.defn) + genh.add(vis.decl) + genc.write(output_dir, prefix + 'qapi-types.c') + genh.write(output_dir, prefix + 'qapi-types.h') diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py new file mode 100644 index 0000000000..3ed78165d7 --- /dev/null +++ b/scripts/qapi/visit.py @@ -0,0 +1,353 @@ +""" +QAPI visitor generator + +Copyright IBM, Corp. 2011 +Copyright (C) 2014-2018 Red Hat, Inc. + +Authors: + Anthony Liguori + Michael Roth + Markus Armbruster + +This work is licensed under the terms of the GNU GPL, version 2. +See the COPYING file in the top-level directory. +""" + +from qapi.common import * + + +def gen_visit_decl(name, scalar=False): + c_type = c_name(name) + ' *' + if not scalar: + c_type += '*' + return mcgen(''' +void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_type)sobj, Error **errp); +''', + c_name=c_name(name), c_type=c_type) + + +def gen_visit_members_decl(name): + return mcgen(''' + +void visit_type_%(c_name)s_members(Visitor *v, %(c_name)s *obj, Error **errp); +''', + c_name=c_name(name)) + + +def gen_visit_object_members(name, base, members, variants): + ret = mcgen(''' + +void visit_type_%(c_name)s_members(Visitor *v, %(c_name)s *obj, Error **errp) +{ + Error *err = NULL; + +''', + c_name=c_name(name)) + + if base: + ret += mcgen(''' + visit_type_%(c_type)s_members(v, (%(c_type)s *)obj, &err); + if (err) { + goto out; + } +''', + c_type=base.c_name()) + + for memb in members: + if memb.optional: + ret += mcgen(''' + if (visit_optional(v, "%(name)s", &obj->has_%(c_name)s)) { +''', + name=memb.name, c_name=c_name(memb.name)) + push_indent() + ret += mcgen(''' + visit_type_%(c_type)s(v, "%(name)s", &obj->%(c_name)s, &err); + if (err) { + goto out; + } +''', + c_type=memb.type.c_name(), name=memb.name, + c_name=c_name(memb.name)) + if memb.optional: + pop_indent() + ret += mcgen(''' + } +''') + + if variants: + ret += mcgen(''' + switch (obj->%(c_name)s) { +''', + c_name=c_name(variants.tag_member.name)) + + for var in variants.variants: + ret += mcgen(''' + case %(case)s: + visit_type_%(c_type)s_members(v, &obj->u.%(c_name)s, &err); + break; +''', + case=c_enum_const(variants.tag_member.type.name, + var.name, + variants.tag_member.type.prefix), + c_type=var.type.c_name(), c_name=c_name(var.name)) + + ret += mcgen(''' + default: + abort(); + } +''') + + # 'goto out' produced for base, for each member, and if variants were + # present + if base or members or variants: + ret += mcgen(''' + +out: +''') + ret += mcgen(''' + error_propagate(errp, err); +} +''') + return ret + + +def gen_visit_list(name, element_type): + return mcgen(''' + +void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s **obj, Error **errp) +{ + Error *err = NULL; + %(c_name)s *tail; + size_t size = sizeof(**obj); + + visit_start_list(v, name, (GenericList **)obj, size, &err); + if (err) { + goto out; + } + + for (tail = *obj; tail; + tail = (%(c_name)s *)visit_next_list(v, (GenericList *)tail, size)) { + visit_type_%(c_elt_type)s(v, NULL, &tail->value, &err); + if (err) { + break; + } + } + + if (!err) { + visit_check_list(v, &err); + } + visit_end_list(v, (void **)obj); + if (err && visit_is_input(v)) { + qapi_free_%(c_name)s(*obj); + *obj = NULL; + } +out: + error_propagate(errp, err); +} +''', + c_name=c_name(name), c_elt_type=element_type.c_name()) + + +def gen_visit_enum(name): + return mcgen(''' + +void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s *obj, Error **errp) +{ + int value = *obj; + visit_type_enum(v, name, &value, &%(c_name)s_lookup, errp); + *obj = value; +} +''', + c_name=c_name(name)) + + +def gen_visit_alternate(name, variants): + ret = mcgen(''' + +void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s **obj, Error **errp) +{ + Error *err = NULL; + + visit_start_alternate(v, name, (GenericAlternate **)obj, sizeof(**obj), + &err); + if (err) { + goto out; + } + if (!*obj) { + goto out_obj; + } + switch ((*obj)->type) { +''', + c_name=c_name(name)) + + for var in variants.variants: + ret += mcgen(''' + case %(case)s: +''', + case=var.type.alternate_qtype()) + if isinstance(var.type, QAPISchemaObjectType): + ret += mcgen(''' + visit_start_struct(v, name, NULL, 0, &err); + if (err) { + break; + } + visit_type_%(c_type)s_members(v, &(*obj)->u.%(c_name)s, &err); + if (!err) { + visit_check_struct(v, &err); + } + visit_end_struct(v, NULL); +''', + c_type=var.type.c_name(), + c_name=c_name(var.name)) + else: + ret += mcgen(''' + visit_type_%(c_type)s(v, name, &(*obj)->u.%(c_name)s, &err); +''', + c_type=var.type.c_name(), + c_name=c_name(var.name)) + ret += mcgen(''' + break; +''') + + ret += mcgen(''' + case QTYPE_NONE: + abort(); + default: + error_setg(&err, QERR_INVALID_PARAMETER_TYPE, name ? name : "null", + "%(name)s"); + } +out_obj: + visit_end_alternate(v, (void **)obj); + if (err && visit_is_input(v)) { + qapi_free_%(c_name)s(*obj); + *obj = NULL; + } +out: + error_propagate(errp, err); +} +''', + name=name, c_name=c_name(name)) + + return ret + + +def gen_visit_object(name, base, members, variants): + return mcgen(''' + +void visit_type_%(c_name)s(Visitor *v, const char *name, %(c_name)s **obj, Error **errp) +{ + Error *err = NULL; + + visit_start_struct(v, name, (void **)obj, sizeof(%(c_name)s), &err); + if (err) { + goto out; + } + if (!*obj) { + goto out_obj; + } + visit_type_%(c_name)s_members(v, *obj, &err); + if (err) { + goto out_obj; + } + visit_check_struct(v, &err); +out_obj: + visit_end_struct(v, (void **)obj); + if (err && visit_is_input(v)) { + qapi_free_%(c_name)s(*obj); + *obj = NULL; + } +out: + error_propagate(errp, err); +} +''', + c_name=c_name(name)) + + +class QAPISchemaGenVisitVisitor(QAPISchemaVisitor): + def __init__(self, opt_builtins): + self._opt_builtins = opt_builtins + self.decl = None + self.defn = None + self._btin = None + + def visit_begin(self, schema): + self.decl = '' + self.defn = '' + self._btin = '\n' + guardstart('QAPI_VISIT_BUILTIN') + + def visit_end(self): + # To avoid header dependency hell, we always generate + # declarations for built-in types in our header files and + # simply guard them. See also opt_builtins (command line + # option -b). + self._btin += guardend('QAPI_VISIT_BUILTIN') + self.decl = self._btin + self.decl + self._btin = None + + def visit_enum_type(self, name, info, values, prefix): + # Special case for our lone builtin enum type + # TODO use something cleaner than existence of info + if not info: + self._btin += gen_visit_decl(name, scalar=True) + if self._opt_builtins: + self.defn += gen_visit_enum(name) + else: + self.decl += gen_visit_decl(name, scalar=True) + self.defn += gen_visit_enum(name) + + def visit_array_type(self, name, info, element_type): + decl = gen_visit_decl(name) + defn = gen_visit_list(name, element_type) + if isinstance(element_type, QAPISchemaBuiltinType): + self._btin += decl + if self._opt_builtins: + self.defn += defn + else: + self.decl += decl + self.defn += defn + + def visit_object_type(self, name, info, base, members, variants): + # Nothing to do for the special empty builtin + if name == 'q_empty': + return + self.decl += gen_visit_members_decl(name) + self.defn += gen_visit_object_members(name, base, members, variants) + # TODO Worth changing the visitor signature, so we could + # directly use rather than repeat type.is_implicit()? + if not name.startswith('q_'): + # only explicit types need an allocating visit + self.decl += gen_visit_decl(name) + self.defn += gen_visit_object(name, base, members, variants) + + def visit_alternate_type(self, name, info, variants): + self.decl += gen_visit_decl(name) + self.defn += gen_visit_alternate(name, variants) + + +def gen_visit(schema, output_dir, prefix, opt_builtins): + blurb = ' * Schema-defined QAPI visitors' + genc = QAPIGenC(blurb, __doc__) + genh = QAPIGenH(blurb, __doc__) + + genc.add(mcgen(''' +#include "qemu/osdep.h" +#include "qemu-common.h" +#include "qapi/error.h" +#include "qapi/qmp/qerror.h" +#include "%(prefix)sqapi-visit.h" +''', + prefix=prefix)) + + genh.add(mcgen(''' +#include "qapi/visitor.h" +#include "%(prefix)sqapi-types.h" + +''', + prefix=prefix)) + + vis = QAPISchemaGenVisitVisitor(opt_builtins) + schema.visit(vis) + genc.add(vis.defn) + genh.add(vis.decl) + genc.write(output_dir, prefix + 'qapi-visit.c') + genh.write(output_dir, prefix + 'qapi-visit.h') diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py deleted file mode 100755 index 8a604d86a6..0000000000 --- a/scripts/qapi2texi.py +++ /dev/null @@ -1,291 +0,0 @@ -#!/usr/bin/env python -# QAPI texi generator -# -# This work is licensed under the terms of the GNU LGPL, version 2+. -# See the COPYING file in the top-level directory. -"""This script produces the documentation of a qapi schema in texinfo format""" -from __future__ import print_function -import re -import sys - -import qapi - -MSG_FMT = """ -@deftypefn {type} {{}} {name} - -{body} -@end deftypefn - -""".format - -TYPE_FMT = """ -@deftp {{{type}}} {name} - -{body} -@end deftp - -""".format - -EXAMPLE_FMT = """@example -{code} -@end example -""".format - - -def subst_strong(doc): - """Replaces *foo* by @strong{foo}""" - return re.sub(r'\*([^*\n]+)\*', r'@strong{\1}', doc) - - -def subst_emph(doc): - """Replaces _foo_ by @emph{foo}""" - return re.sub(r'\b_([^_\n]+)_\b', r'@emph{\1}', doc) - - -def subst_vars(doc): - """Replaces @var by @code{var}""" - return re.sub(r'@([\w-]+)', r'@code{\1}', doc) - - -def subst_braces(doc): - """Replaces {} with @{ @}""" - return doc.replace('{', '@{').replace('}', '@}') - - -def texi_example(doc): - """Format @example""" - # TODO: Neglects to escape @ characters. - # We should probably escape them in subst_braces(), and rename the - # function to subst_special() or subs_texi_special(). If we do that, we - # need to delay it until after subst_vars() in texi_format(). - doc = subst_braces(doc).strip('\n') - return EXAMPLE_FMT(code=doc) - - -def texi_format(doc): - """ - Format documentation - - Lines starting with: - - |: generates an @example - - =: generates @section - - ==: generates @subsection - - 1. or 1): generates an @enumerate @item - - */-: generates an @itemize list - """ - ret = '' - doc = subst_braces(doc) - doc = subst_vars(doc) - doc = subst_emph(doc) - doc = subst_strong(doc) - inlist = '' - lastempty = False - for line in doc.split('\n'): - empty = line == '' - - # FIXME: Doing this in a single if / elif chain is - # problematic. For instance, a line without markup terminates - # a list if it follows a blank line (reaches the final elif), - # but a line with some *other* markup, such as a = title - # doesn't. - # - # Make sure to update section "Documentation markup" in - # docs/devel/qapi-code-gen.txt when fixing this. - if line.startswith('| '): - line = EXAMPLE_FMT(code=line[2:]) - elif line.startswith('= '): - line = '@section ' + line[2:] - elif line.startswith('== '): - line = '@subsection ' + line[3:] - elif re.match(r'^([0-9]*\.) ', line): - if not inlist: - ret += '@enumerate\n' - inlist = 'enumerate' - ret += '@item\n' - line = line[line.find(' ')+1:] - elif re.match(r'^[*-] ', line): - if not inlist: - ret += '@itemize %s\n' % {'*': '@bullet', - '-': '@minus'}[line[0]] - inlist = 'itemize' - ret += '@item\n' - line = line[2:] - elif lastempty and inlist: - ret += '@end %s\n\n' % inlist - inlist = '' - - lastempty = empty - ret += line + '\n' - - if inlist: - ret += '@end %s\n\n' % inlist - return ret - - -def texi_body(doc): - """Format the main documentation body""" - return texi_format(doc.body.text) - - -def texi_enum_value(value): - """Format a table of members item for an enumeration value""" - return '@item @code{%s}\n' % value.name - - -def texi_member(member, suffix=''): - """Format a table of members item for an object type member""" - typ = member.type.doc_type() - return '@item @code{%s%s%s}%s%s\n' % ( - member.name, - ': ' if typ else '', - typ if typ else '', - ' (optional)' if member.optional else '', - suffix) - - -def texi_members(doc, what, base, variants, member_func): - """Format the table of members""" - items = '' - for section in doc.args.values(): - # TODO Drop fallbacks when undocumented members are outlawed - if section.text: - desc = texi_format(section.text) - elif (variants and variants.tag_member == section.member - and not section.member.type.doc_type()): - values = section.member.type.member_names() - members_text = ', '.join(['@t{"%s"}' % v for v in values]) - desc = 'One of ' + members_text + '\n' - else: - desc = 'Not documented\n' - items += member_func(section.member) + desc - if base: - items += '@item The members of @code{%s}\n' % base.doc_type() - if variants: - for v in variants.variants: - when = ' when @code{%s} is @t{"%s"}' % ( - variants.tag_member.name, v.name) - if v.type.is_implicit(): - assert not v.type.base and not v.type.variants - for m in v.type.local_members: - items += member_func(m, when) - else: - items += '@item The members of @code{%s}%s\n' % ( - v.type.doc_type(), when) - if not items: - return '' - return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) - - -def texi_sections(doc): - """Format additional sections following arguments""" - body = '' - for section in doc.sections: - if section.name: - # prefer @b over @strong, so txt doesn't translate it to *Foo:* - body += '\n@b{%s:}\n' % section.name - if section.name and section.name.startswith('Example'): - body += texi_example(section.text) - else: - body += texi_format(section.text) - return body - - -def texi_entity(doc, what, base=None, variants=None, - member_func=texi_member): - return (texi_body(doc) - + texi_members(doc, what, base, variants, member_func) - + texi_sections(doc)) - - -class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): - def __init__(self): - self.out = None - self.cur_doc = None - - def visit_begin(self, schema): - self.out = '' - - def visit_enum_type(self, name, info, values, prefix): - doc = self.cur_doc - self.out += TYPE_FMT(type='Enum', - name=doc.symbol, - body=texi_entity(doc, 'Values', - member_func=texi_enum_value)) - - def visit_object_type(self, name, info, base, members, variants): - doc = self.cur_doc - if base and base.is_implicit(): - base = None - self.out += TYPE_FMT(type='Object', - name=doc.symbol, - body=texi_entity(doc, 'Members', base, variants)) - - def visit_alternate_type(self, name, info, variants): - doc = self.cur_doc - self.out += TYPE_FMT(type='Alternate', - name=doc.symbol, - body=texi_entity(doc, 'Members')) - - def visit_command(self, name, info, arg_type, ret_type, - gen, success_response, boxed): - doc = self.cur_doc - if boxed: - body = texi_body(doc) - body += ('\n@b{Arguments:} the members of @code{%s}\n' - % arg_type.name) - body += texi_sections(doc) - else: - body = texi_entity(doc, 'Arguments') - self.out += MSG_FMT(type='Command', - name=doc.symbol, - body=body) - - def visit_event(self, name, info, arg_type, boxed): - doc = self.cur_doc - self.out += MSG_FMT(type='Event', - name=doc.symbol, - body=texi_entity(doc, 'Arguments')) - - def symbol(self, doc, entity): - if self.out: - self.out += '\n' - self.cur_doc = doc - entity.visit(self) - self.cur_doc = None - - def freeform(self, doc): - assert not doc.args - if self.out: - self.out += '\n' - self.out += texi_body(doc) + texi_sections(doc) - - -def texi_schema(schema): - """Convert QAPI schema documentation to Texinfo""" - gen = QAPISchemaGenDocVisitor() - gen.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - gen.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - gen.freeform(doc) - return gen.out - - -def main(argv): - """Takes schema argument, prints result to stdout""" - if len(argv) != 2: - print("%s: need exactly 1 argument: SCHEMA" % argv[0], file=sys.stderr) - sys.exit(1) - - schema = qapi.QAPISchema(argv[1]) - if not qapi.doc_required: - print("%s: need pragma 'doc-required' " - "to generate documentation" % argv[0], file=sys.stderr) - sys.exit(1) - print('@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n') - print(texi_schema(schema), end='') - - -if __name__ == '__main__': - main(sys.argv) -- cgit v1.2.1