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