xref: /qemu/scripts/qapi/introspect.py (revision f9734d5d) 
1"""
2QAPI introspection generator
3
4Copyright (C) 2015-2021 Red Hat, Inc.
5
6Authors:
7 Markus Armbruster <armbru@redhat.com>
8 John Snow <jsnow@redhat.com>
9
10This work is licensed under the terms of the GNU GPL, version 2.
11See the COPYING file in the top-level directory.
12"""
13
14from typing import (
15    Any,
16    Dict,
17    Generic,
18    List,
19    Optional,
20    Sequence,
21    TypeVar,
22    Union,
23)
24
25from .common import (
26    c_name,
27    gen_endif,
28    gen_if,
29    mcgen,
30)
31from .gen import QAPISchemaMonolithicCVisitor
32from .schema import (
33    QAPISchema,
34    QAPISchemaArrayType,
35    QAPISchemaBuiltinType,
36    QAPISchemaEntity,
37    QAPISchemaEnumMember,
38    QAPISchemaFeature,
39    QAPISchemaIfCond,
40    QAPISchemaObjectType,
41    QAPISchemaObjectTypeMember,
42    QAPISchemaType,
43    QAPISchemaVariant,
44    QAPISchemaVariants,
45)
46from .source import QAPISourceInfo
47
48
49# This module constructs a tree data structure that is used to
50# generate the introspection information for QEMU. It is shaped
51# like a JSON value.
52#
53# A complexity over JSON is that our values may or may not be annotated.
54#
55# Un-annotated values may be:
56#     Scalar: str, bool, None.
57#     Non-scalar: List, Dict
58# _value = Union[str, bool, None, Dict[str, JSONValue], List[JSONValue]]
59#
60# With optional annotations, the type of all values is:
61# JSONValue = Union[_Value, Annotated[_Value]]
62#
63# Sadly, mypy does not support recursive types; so the _Stub alias is used to
64# mark the imprecision in the type model where we'd otherwise use JSONValue.
65_Stub = Any
66_Scalar = Union[str, bool, None]
67_NonScalar = Union[Dict[str, _Stub], List[_Stub]]
68_Value = Union[_Scalar, _NonScalar]
69JSONValue = Union[_Value, 'Annotated[_Value]']
70
71# These types are based on structures defined in QEMU's schema, so we
72# lack precise types for them here. Python 3.6 does not offer
73# TypedDict constructs, so they are broadly typed here as simple
74# Python Dicts.
75SchemaInfo = Dict[str, object]
76SchemaInfoObject = Dict[str, object]
77SchemaInfoObjectVariant = Dict[str, object]
78SchemaInfoObjectMember = Dict[str, object]
79SchemaInfoCommand = Dict[str, object]
80
81
82_ValueT = TypeVar('_ValueT', bound=_Value)
83
84
85class Annotated(Generic[_ValueT]):
86    """
87    Annotated generally contains a SchemaInfo-like type (as a dict),
88    But it also used to wrap comments/ifconds around scalar leaf values,
89    for the benefit of features and enums.
90    """
91    # TODO: Remove after Python 3.7 adds @dataclass:
92    # pylint: disable=too-few-public-methods
93    def __init__(self, value: _ValueT, ifcond: QAPISchemaIfCond,
94                 comment: Optional[str] = None):
95        self.value = value
96        self.comment: Optional[str] = comment
97        self.ifcond = ifcond
98
99
100def _tree_to_qlit(obj: JSONValue,
101                  level: int = 0,
102                  dict_value: bool = False) -> str:
103    """
104    Convert the type tree into a QLIT C string, recursively.
105
106    :param obj: The value to convert.
107                This value may not be Annotated when dict_value is True.
108    :param level: The indentation level for this particular value.
109    :param dict_value: True when the value being processed belongs to a
110                       dict key; which suppresses the output indent.
111    """
112
113    def indent(level: int) -> str:
114        return level * 4 * ' '
115
116    if isinstance(obj, Annotated):
117        # NB: _tree_to_qlit is called recursively on the values of a
118        # key:value pair; those values can't be decorated with
119        # comments or conditionals.
120        msg = "dict values cannot have attached comments or if-conditionals."
121        assert not dict_value, msg
122
123        ret = ''
124        if obj.comment:
125            ret += indent(level) + f"/* {obj.comment} */\n"
126        if obj.ifcond.is_present():
127            ret += gen_if(obj.ifcond.cgen())
128        ret += _tree_to_qlit(obj.value, level)
129        if obj.ifcond.is_present():
130            ret += '\n' + gen_endif(obj.ifcond.cgen())
131        return ret
132
133    ret = ''
134    if not dict_value:
135        ret += indent(level)
136
137    # Scalars:
138    if obj is None:
139        ret += 'QLIT_QNULL'
140    elif isinstance(obj, str):
141        ret += f"QLIT_QSTR({to_c_string(obj)})"
142    elif isinstance(obj, bool):
143        ret += f"QLIT_QBOOL({str(obj).lower()})"
144
145    # Non-scalars:
146    elif isinstance(obj, list):
147        ret += 'QLIT_QLIST(((QLitObject[]) {\n'
148        for value in obj:
149            ret += _tree_to_qlit(value, level + 1).strip('\n') + '\n'
150        ret += indent(level + 1) + '{}\n'
151        ret += indent(level) + '}))'
152    elif isinstance(obj, dict):
153        ret += 'QLIT_QDICT(((QLitDictEntry[]) {\n'
154        for key, value in sorted(obj.items()):
155            ret += indent(level + 1) + "{{ {:s}, {:s} }},\n".format(
156                to_c_string(key),
157                _tree_to_qlit(value, level + 1, dict_value=True)
158            )
159        ret += indent(level + 1) + '{}\n'
160        ret += indent(level) + '}))'
161    else:
162        raise NotImplementedError(
163            f"type '{type(obj).__name__}' not implemented"
164        )
165
166    if level > 0:
167        ret += ','
168    return ret
169
170
171def to_c_string(string: str) -> str:
172    return '"' + string.replace('\\', r'\\').replace('"', r'\"') + '"'
173
174
175class QAPISchemaGenIntrospectVisitor(QAPISchemaMonolithicCVisitor):
176
177    def __init__(self, prefix: str, unmask: bool):
178        super().__init__(
179            prefix, 'qapi-introspect',
180            ' * QAPI/QMP schema introspection', __doc__)
181        self._unmask = unmask
182        self._schema: Optional[QAPISchema] = None
183        self._trees: List[Annotated[SchemaInfo]] = []
184        self._used_types: List[QAPISchemaType] = []
185        self._name_map: Dict[str, str] = {}
186        self._genc.add(mcgen('''
187#include "qemu/osdep.h"
188#include "%(prefix)sqapi-introspect.h"
189
190''',
191                             prefix=prefix))
192
193    def visit_begin(self, schema: QAPISchema) -> None:
194        self._schema = schema
195
196    def visit_end(self) -> None:
197        # visit the types that are actually used
198        for typ in self._used_types:
199            typ.visit(self)
200        # generate C
201        name = c_name(self._prefix, protect=False) + 'qmp_schema_qlit'
202        self._genh.add(mcgen('''
203#include "qapi/qmp/qlit.h"
204
205extern const QLitObject %(c_name)s;
206''',
207                             c_name=c_name(name)))
208        self._genc.add(mcgen('''
209const QLitObject %(c_name)s = %(c_string)s;
210''',
211                             c_name=c_name(name),
212                             c_string=_tree_to_qlit(self._trees)))
213        self._schema = None
214        self._trees = []
215        self._used_types = []
216        self._name_map = {}
217
218    def visit_needed(self, entity: QAPISchemaEntity) -> bool:
219        # Ignore types on first pass; visit_end() will pick up used types
220        return not isinstance(entity, QAPISchemaType)
221
222    def _name(self, name: str) -> str:
223        if self._unmask:
224            return name
225        if name not in self._name_map:
226            self._name_map[name] = '%d' % len(self._name_map)
227        return self._name_map[name]
228
229    def _use_type(self, typ: QAPISchemaType) -> str:
230        assert self._schema is not None
231
232        # Map the various integer types to plain int
233        if typ.json_type() == 'int':
234            typ = self._schema.lookup_type('int')
235        elif (isinstance(typ, QAPISchemaArrayType) and
236              typ.element_type.json_type() == 'int'):
237            typ = self._schema.lookup_type('intList')
238        # Add type to work queue if new
239        if typ not in self._used_types:
240            self._used_types.append(typ)
241        # Clients should examine commands and events, not types.  Hide
242        # type names as integers to reduce the temptation.  Also, it
243        # saves a few characters on the wire.
244        if isinstance(typ, QAPISchemaBuiltinType):
245            return typ.name
246        if isinstance(typ, QAPISchemaArrayType):
247            return '[' + self._use_type(typ.element_type) + ']'
248        return self._name(typ.name)
249
250    @staticmethod
251    def _gen_features(features: Sequence[QAPISchemaFeature]
252                      ) -> List[Annotated[str]]:
253        return [Annotated(f.name, f.ifcond) for f in features]
254
255    def _gen_tree(self, name: str, mtype: str, obj: Dict[str, object],
256                  ifcond: QAPISchemaIfCond = QAPISchemaIfCond(),
257                  features: Sequence[QAPISchemaFeature] = ()) -> None:
258        """
259        Build and append a SchemaInfo object to self._trees.
260
261        :param name: The SchemaInfo's name.
262        :param mtype: The SchemaInfo's meta-type.
263        :param obj: Additional SchemaInfo members, as appropriate for
264                    the meta-type.
265        :param ifcond: Conditionals to apply to the SchemaInfo.
266        :param features: The SchemaInfo's features.
267                         Will be omitted from the output if empty.
268        """
269        comment: Optional[str] = None
270        if mtype not in ('command', 'event', 'builtin', 'array'):
271            if not self._unmask:
272                # Output a comment to make it easy to map masked names
273                # back to the source when reading the generated output.
274                comment = f'"{self._name(name)}" = {name}'
275            name = self._name(name)
276        obj['name'] = name
277        obj['meta-type'] = mtype
278        if features:
279            obj['features'] = self._gen_features(features)
280        self._trees.append(Annotated(obj, ifcond, comment))
281
282    def _gen_member(self, member: QAPISchemaObjectTypeMember
283                    ) -> Annotated[SchemaInfoObjectMember]:
284        obj: SchemaInfoObjectMember = {
285            'name': member.name,
286            'type': self._use_type(member.type)
287        }
288        if member.optional:
289            obj['default'] = None
290        if member.features:
291            obj['features'] = self._gen_features(member.features)
292        return Annotated(obj, member.ifcond)
293
294    def _gen_variant(self, variant: QAPISchemaVariant
295                     ) -> Annotated[SchemaInfoObjectVariant]:
296        obj: SchemaInfoObjectVariant = {
297            'case': variant.name,
298            'type': self._use_type(variant.type)
299        }
300        return Annotated(obj, variant.ifcond)
301
302    def visit_builtin_type(self, name: str, info: Optional[QAPISourceInfo],
303                           json_type: str) -> None:
304        self._gen_tree(name, 'builtin', {'json-type': json_type})
305
306    def visit_enum_type(self, name: str, info: Optional[QAPISourceInfo],
307                        ifcond: QAPISchemaIfCond,
308                        features: List[QAPISchemaFeature],
309                        members: List[QAPISchemaEnumMember],
310                        prefix: Optional[str]) -> None:
311        self._gen_tree(
312            name, 'enum',
313            {'values': [Annotated(m.name, m.ifcond) for m in members]},
314            ifcond, features
315        )
316
317    def visit_array_type(self, name: str, info: Optional[QAPISourceInfo],
318                         ifcond: QAPISchemaIfCond,
319                         element_type: QAPISchemaType) -> None:
320        element = self._use_type(element_type)
321        self._gen_tree('[' + element + ']', 'array', {'element-type': element},
322                       ifcond)
323
324    def visit_object_type_flat(self, name: str, info: Optional[QAPISourceInfo],
325                               ifcond: QAPISchemaIfCond,
326                               features: List[QAPISchemaFeature],
327                               members: List[QAPISchemaObjectTypeMember],
328                               variants: Optional[QAPISchemaVariants]) -> None:
329        obj: SchemaInfoObject = {
330            'members': [self._gen_member(m) for m in members]
331        }
332        if variants:
333            obj['tag'] = variants.tag_member.name
334            obj['variants'] = [self._gen_variant(v) for v in variants.variants]
335        self._gen_tree(name, 'object', obj, ifcond, features)
336
337    def visit_alternate_type(self, name: str, info: Optional[QAPISourceInfo],
338                             ifcond: QAPISchemaIfCond,
339                             features: List[QAPISchemaFeature],
340                             variants: QAPISchemaVariants) -> None:
341        self._gen_tree(
342            name, 'alternate',
343            {'members': [Annotated({'type': self._use_type(m.type)},
344                                   m.ifcond)
345                         for m in variants.variants]},
346            ifcond, features
347        )
348
349    def visit_command(self, name: str, info: Optional[QAPISourceInfo],
350                      ifcond: QAPISchemaIfCond,
351                      features: List[QAPISchemaFeature],
352                      arg_type: Optional[QAPISchemaObjectType],
353                      ret_type: Optional[QAPISchemaType], gen: bool,
354                      success_response: bool, boxed: bool, allow_oob: bool,
355                      allow_preconfig: bool, coroutine: bool) -> None:
356        assert self._schema is not None
357
358        arg_type = arg_type or self._schema.the_empty_object_type
359        ret_type = ret_type or self._schema.the_empty_object_type
360        obj: SchemaInfoCommand = {
361            'arg-type': self._use_type(arg_type),
362            'ret-type': self._use_type(ret_type)
363        }
364        if allow_oob:
365            obj['allow-oob'] = allow_oob
366        self._gen_tree(name, 'command', obj, ifcond, features)
367
368    def visit_event(self, name: str, info: Optional[QAPISourceInfo],
369                    ifcond: QAPISchemaIfCond,
370                    features: List[QAPISchemaFeature],
371                    arg_type: Optional[QAPISchemaObjectType],
372                    boxed: bool) -> None:
373        assert self._schema is not None
374
375        arg_type = arg_type or self._schema.the_empty_object_type
376        self._gen_tree(name, 'event', {'arg-type': self._use_type(arg_type)},
377                       ifcond, features)
378
379
380def gen_introspect(schema: QAPISchema, output_dir: str, prefix: str,
381                   opt_unmask: bool) -> None:
382    vis = QAPISchemaGenIntrospectVisitor(prefix, opt_unmask)
383    schema.visit(vis)
384    vis.write(output_dir)
385