| 1 | """ |
| 2 | QAPI introspection generator |
| 3 | |
| 4 | Copyright (C) 2015-2021 Red Hat, Inc. |
| 5 | |
| 6 | Authors: |
| 7 | Markus Armbruster <armbru@redhat.com> |
| 8 | John Snow <jsnow@redhat.com> |
| 9 | |
| 10 | This work is licensed under the terms of the GNU GPL, version 2. |
| 11 | See the COPYING file in the top-level directory. |
| 12 | """ |
| 13 | |
| 14 | from dataclasses import dataclass |
| 15 | from typing import ( |
| 16 | Any, |
| 17 | Dict, |
| 18 | Generic, |
| 19 | List, |
| 20 | Optional, |
| 21 | Sequence, |
| 22 | TypeVar, |
| 23 | Union, |
| 24 | ) |
| 25 | |
| 26 | from .common import c_name, mcgen |
| 27 | from .gen import QAPISchemaMonolithicCVisitor |
| 28 | from .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 | ) |
| 43 | from .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 # pylint: disable=invalid-name |
| 63 | _Scalar = Union[str, bool, None] |
| 64 | _NonScalar = Union[Dict[str, _Stub], List[_Stub]] |
| 65 | _Value = Union[_Scalar, _NonScalar] |
| 66 | JSONValue = 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. |
| 72 | SchemaInfo = Dict[str, object] |
| 73 | SchemaInfoEnumMember = Dict[str, object] |
| 74 | SchemaInfoObject = Dict[str, object] |
| 75 | SchemaInfoObjectVariant = Dict[str, object] |
| 76 | SchemaInfoObjectMember = Dict[str, object] |
| 77 | SchemaInfoCommand = Dict[str, object] |
| 78 | |
| 79 | |
| 80 | _ValueT = TypeVar('_ValueT', bound=_Value) |
| 81 | |
| 82 | |
| 83 | @dataclass |
| 84 | class 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 | |
| 95 | def _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 | |
| 166 | def to_c_string(string: str) -> str: |
| 167 | return '"' + string.replace('\\', r'\\').replace('"', r'\"') + '"' |
| 168 | |
| 169 | |
| 170 | class 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 | |
| 200 | extern const QLitObject %(c_name)s; |
| 201 | ''', |
| 202 | c_name=c_name(name))) |
| 203 | self._genc.add(mcgen(''' |
| 204 | const 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 | |
| 389 | def 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) |