xref: /qemu/scripts/qapi/introspect.py (revision 82b52f6b) 
1"""
2QAPI introspection generator
3
4Copyright (C) 2015-2018 Red Hat, Inc.
5
6Authors:
7 Markus Armbruster <armbru@redhat.com>
8
9This work is licensed under the terms of the GNU GPL, version 2.
10See the COPYING file in the top-level directory.
11"""
12
13from typing import (
14    Any,
15    Dict,
16    Generic,
17    Iterable,
18    List,
19    Optional,
20    Sequence,
21    Tuple,
22    TypeVar,
23    Union,
24)
25
26from .common import (
27    c_name,
28    gen_endif,
29    gen_if,
30    mcgen,
31)
32from .gen import QAPISchemaMonolithicCVisitor
33from .schema import (
34    QAPISchema,
35    QAPISchemaArrayType,
36    QAPISchemaBuiltinType,
37    QAPISchemaEntity,
38    QAPISchemaEnumMember,
39    QAPISchemaFeature,
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: Iterable[str],
94                 comment: Optional[str] = None):
95        self.value = value
96        self.comment: Optional[str] = comment
97        self.ifcond: Tuple[str, ...] = tuple(ifcond)
98
99
100def _tree_to_qlit(obj: JSONValue,
101                  level: int = 0,
102                  dict_value: bool = False) -> str:
103
104    def indent(level: int) -> str:
105        return level * 4 * ' '
106
107    if isinstance(obj, Annotated):
108        # NB: _tree_to_qlit is called recursively on the values of a
109        # key:value pair; those values can't be decorated with
110        # comments or conditionals.
111        msg = "dict values cannot have attached comments or if-conditionals."
112        assert not dict_value, msg
113
114        ret = ''
115        if obj.comment:
116            ret += indent(level) + f"/* {obj.comment} */\n"
117        if obj.ifcond:
118            ret += gen_if(obj.ifcond)
119        ret += _tree_to_qlit(obj.value, level)
120        if obj.ifcond:
121            ret += '\n' + gen_endif(obj.ifcond)
122        return ret
123
124    ret = ''
125    if not dict_value:
126        ret += indent(level)
127
128    # Scalars:
129    if obj is None:
130        ret += 'QLIT_QNULL'
131    elif isinstance(obj, str):
132        ret += f"QLIT_QSTR({to_c_string(obj)})"
133    elif isinstance(obj, bool):
134        ret += f"QLIT_QBOOL({str(obj).lower()})"
135
136    # Non-scalars:
137    elif isinstance(obj, list):
138        ret += 'QLIT_QLIST(((QLitObject[]) {\n'
139        for value in obj:
140            ret += _tree_to_qlit(value, level + 1).strip('\n') + '\n'
141        ret += indent(level + 1) + '{}\n'
142        ret += indent(level) + '}))'
143    elif isinstance(obj, dict):
144        ret += 'QLIT_QDICT(((QLitDictEntry[]) {\n'
145        for key, value in sorted(obj.items()):
146            ret += indent(level + 1) + "{{ {:s}, {:s} }},\n".format(
147                to_c_string(key),
148                _tree_to_qlit(value, level + 1, dict_value=True)
149            )
150        ret += indent(level + 1) + '{}\n'
151        ret += indent(level) + '}))'
152    else:
153        raise NotImplementedError(
154            f"type '{type(obj).__name__}' not implemented"
155        )
156
157    if level > 0:
158        ret += ','
159    return ret
160
161
162def to_c_string(string: str) -> str:
163    return '"' + string.replace('\\', r'\\').replace('"', r'\"') + '"'
164
165
166class QAPISchemaGenIntrospectVisitor(QAPISchemaMonolithicCVisitor):
167
168    def __init__(self, prefix: str, unmask: bool):
169        super().__init__(
170            prefix, 'qapi-introspect',
171            ' * QAPI/QMP schema introspection', __doc__)
172        self._unmask = unmask
173        self._schema: Optional[QAPISchema] = None
174        self._trees: List[Annotated[SchemaInfo]] = []
175        self._used_types: List[QAPISchemaType] = []
176        self._name_map: Dict[str, str] = {}
177        self._genc.add(mcgen('''
178#include "qemu/osdep.h"
179#include "%(prefix)sqapi-introspect.h"
180
181''',
182                             prefix=prefix))
183
184    def visit_begin(self, schema: QAPISchema) -> None:
185        self._schema = schema
186
187    def visit_end(self) -> None:
188        # visit the types that are actually used
189        for typ in self._used_types:
190            typ.visit(self)
191        # generate C
192        name = c_name(self._prefix, protect=False) + 'qmp_schema_qlit'
193        self._genh.add(mcgen('''
194#include "qapi/qmp/qlit.h"
195
196extern const QLitObject %(c_name)s;
197''',
198                             c_name=c_name(name)))
199        self._genc.add(mcgen('''
200const QLitObject %(c_name)s = %(c_string)s;
201''',
202                             c_name=c_name(name),
203                             c_string=_tree_to_qlit(self._trees)))
204        self._schema = None
205        self._trees = []
206        self._used_types = []
207        self._name_map = {}
208
209    def visit_needed(self, entity: QAPISchemaEntity) -> bool:
210        # Ignore types on first pass; visit_end() will pick up used types
211        return not isinstance(entity, QAPISchemaType)
212
213    def _name(self, name: str) -> str:
214        if self._unmask:
215            return name
216        if name not in self._name_map:
217            self._name_map[name] = '%d' % len(self._name_map)
218        return self._name_map[name]
219
220    def _use_type(self, typ: QAPISchemaType) -> str:
221        assert self._schema is not None
222
223        # Map the various integer types to plain int
224        if typ.json_type() == 'int':
225            typ = self._schema.lookup_type('int')
226        elif (isinstance(typ, QAPISchemaArrayType) and
227              typ.element_type.json_type() == 'int'):
228            typ = self._schema.lookup_type('intList')
229        # Add type to work queue if new
230        if typ not in self._used_types:
231            self._used_types.append(typ)
232        # Clients should examine commands and events, not types.  Hide
233        # type names as integers to reduce the temptation.  Also, it
234        # saves a few characters on the wire.
235        if isinstance(typ, QAPISchemaBuiltinType):
236            return typ.name
237        if isinstance(typ, QAPISchemaArrayType):
238            return '[' + self._use_type(typ.element_type) + ']'
239        return self._name(typ.name)
240
241    @staticmethod
242    def _gen_features(features: List[QAPISchemaFeature]
243                      ) -> List[Annotated[str]]:
244        return [Annotated(f.name, f.ifcond) for f in features]
245
246    def _gen_tree(self, name: str, mtype: str, obj: Dict[str, object],
247                  ifcond: Sequence[str],
248                  features: Optional[List[QAPISchemaFeature]]) -> None:
249        comment: Optional[str] = None
250        if mtype not in ('command', 'event', 'builtin', 'array'):
251            if not self._unmask:
252                # Output a comment to make it easy to map masked names
253                # back to the source when reading the generated output.
254                comment = f'"{self._name(name)}" = {name}'
255            name = self._name(name)
256        obj['name'] = name
257        obj['meta-type'] = mtype
258        if features:
259            obj['features'] = self._gen_features(features)
260        self._trees.append(Annotated(obj, ifcond, comment))
261
262    def _gen_member(self, member: QAPISchemaObjectTypeMember
263                    ) -> Annotated[SchemaInfoObjectMember]:
264        obj: SchemaInfoObjectMember = {
265            'name': member.name,
266            'type': self._use_type(member.type)
267        }
268        if member.optional:
269            obj['default'] = None
270        if member.features:
271            obj['features'] = self._gen_features(member.features)
272        return Annotated(obj, member.ifcond)
273
274    def _gen_variant(self, variant: QAPISchemaVariant
275                     ) -> Annotated[SchemaInfoObjectVariant]:
276        obj: SchemaInfoObjectVariant = {
277            'case': variant.name,
278            'type': self._use_type(variant.type)
279        }
280        return Annotated(obj, variant.ifcond)
281
282    def visit_builtin_type(self, name: str, info: Optional[QAPISourceInfo],
283                           json_type: str) -> None:
284        self._gen_tree(name, 'builtin', {'json-type': json_type}, [], None)
285
286    def visit_enum_type(self, name: str, info: Optional[QAPISourceInfo],
287                        ifcond: Sequence[str],
288                        features: List[QAPISchemaFeature],
289                        members: List[QAPISchemaEnumMember],
290                        prefix: Optional[str]) -> None:
291        self._gen_tree(
292            name, 'enum',
293            {'values': [Annotated(m.name, m.ifcond) for m in members]},
294            ifcond, features
295        )
296
297    def visit_array_type(self, name: str, info: Optional[QAPISourceInfo],
298                         ifcond: Sequence[str],
299                         element_type: QAPISchemaType) -> None:
300        element = self._use_type(element_type)
301        self._gen_tree('[' + element + ']', 'array', {'element-type': element},
302                       ifcond, None)
303
304    def visit_object_type_flat(self, name: str, info: Optional[QAPISourceInfo],
305                               ifcond: Sequence[str],
306                               features: List[QAPISchemaFeature],
307                               members: List[QAPISchemaObjectTypeMember],
308                               variants: Optional[QAPISchemaVariants]) -> None:
309        obj: SchemaInfoObject = {
310            'members': [self._gen_member(m) for m in members]
311        }
312        if variants:
313            obj['tag'] = variants.tag_member.name
314            obj['variants'] = [self._gen_variant(v) for v in variants.variants]
315        self._gen_tree(name, 'object', obj, ifcond, features)
316
317    def visit_alternate_type(self, name: str, info: Optional[QAPISourceInfo],
318                             ifcond: Sequence[str],
319                             features: List[QAPISchemaFeature],
320                             variants: QAPISchemaVariants) -> None:
321        self._gen_tree(
322            name, 'alternate',
323            {'members': [Annotated({'type': self._use_type(m.type)},
324                                   m.ifcond)
325                         for m in variants.variants]},
326            ifcond, features
327        )
328
329    def visit_command(self, name: str, info: Optional[QAPISourceInfo],
330                      ifcond: Sequence[str],
331                      features: List[QAPISchemaFeature],
332                      arg_type: Optional[QAPISchemaObjectType],
333                      ret_type: Optional[QAPISchemaType], gen: bool,
334                      success_response: bool, boxed: bool, allow_oob: bool,
335                      allow_preconfig: bool, coroutine: bool) -> None:
336        assert self._schema is not None
337
338        arg_type = arg_type or self._schema.the_empty_object_type
339        ret_type = ret_type or self._schema.the_empty_object_type
340        obj: SchemaInfoCommand = {
341            'arg-type': self._use_type(arg_type),
342            'ret-type': self._use_type(ret_type)
343        }
344        if allow_oob:
345            obj['allow-oob'] = allow_oob
346        self._gen_tree(name, 'command', obj, ifcond, features)
347
348    def visit_event(self, name: str, info: Optional[QAPISourceInfo],
349                    ifcond: Sequence[str], features: List[QAPISchemaFeature],
350                    arg_type: Optional[QAPISchemaObjectType],
351                    boxed: bool) -> None:
352        assert self._schema is not None
353
354        arg_type = arg_type or self._schema.the_empty_object_type
355        self._gen_tree(name, 'event', {'arg-type': self._use_type(arg_type)},
356                       ifcond, features)
357
358
359def gen_introspect(schema: QAPISchema, output_dir: str, prefix: str,
360                   opt_unmask: bool) -> None:
361    vis = QAPISchemaGenIntrospectVisitor(prefix, opt_unmask)
362    schema.visit(vis)
363    vis.write(output_dir)
364