introspect.py 14 KB

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