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