qapi: Split .connect_doc(), .check_doc() off .check()
[qemu.git] / scripts / qapi / schema.py
1 # -*- coding: utf-8 -*-
2 #
3 # QAPI schema internal representation
4 #
5 # Copyright (c) 2015-2019 Red Hat Inc.
6 #
7 # Authors:
8 # Markus Armbruster <armbru@redhat.com>
9 # Eric Blake <eblake@redhat.com>
10 # Marc-André Lureau <marcandre.lureau@redhat.com>
11 #
12 # This work is licensed under the terms of the GNU GPL, version 2.
13 # See the COPYING file in the top-level directory.
14
15 # TODO catching name collisions in generated code would be nice
16
17 import os
18 import re
19 from collections import OrderedDict
20
21 from qapi.common import c_name, pointer_suffix
22 from qapi.error import QAPIError, QAPIParseError, QAPISemError
23 from qapi.expr import check_exprs
24 from qapi.parser import QAPISchemaParser
25
26
27 class QAPISchemaEntity(object):
28 meta = None
29
30 def __init__(self, name, info, doc, ifcond=None):
31 assert name is None or isinstance(name, str)
32 self.name = name
33 self._module = None
34 # For explicitly defined entities, info points to the (explicit)
35 # definition. For builtins (and their arrays), info is None.
36 # For implicitly defined entities, info points to a place that
37 # triggered the implicit definition (there may be more than one
38 # such place).
39 self.info = info
40 self.doc = doc
41 self._ifcond = ifcond or []
42 self._checked = False
43
44 def c_name(self):
45 return c_name(self.name)
46
47 def check(self, schema):
48 assert not self._checked
49 if self.info:
50 self._module = os.path.relpath(self.info.fname,
51 os.path.dirname(schema.fname))
52 self._checked = True
53
54 def connect_doc(self):
55 pass
56
57 def check_doc(self):
58 pass
59
60 @property
61 def ifcond(self):
62 assert self._checked
63 return self._ifcond
64
65 @property
66 def module(self):
67 assert self._checked
68 return self._module
69
70 def is_implicit(self):
71 return not self.info
72
73 def visit(self, visitor):
74 assert self._checked
75
76 def describe(self):
77 assert self.meta
78 return "%s '%s'" % (self.meta, self.name)
79
80
81 class QAPISchemaVisitor(object):
82 def visit_begin(self, schema):
83 pass
84
85 def visit_end(self):
86 pass
87
88 def visit_module(self, fname):
89 pass
90
91 def visit_needed(self, entity):
92 # Default to visiting everything
93 return True
94
95 def visit_include(self, fname, info):
96 pass
97
98 def visit_builtin_type(self, name, info, json_type):
99 pass
100
101 def visit_enum_type(self, name, info, ifcond, members, prefix):
102 pass
103
104 def visit_array_type(self, name, info, ifcond, element_type):
105 pass
106
107 def visit_object_type(self, name, info, ifcond, base, members, variants,
108 features):
109 pass
110
111 def visit_object_type_flat(self, name, info, ifcond, members, variants,
112 features):
113 pass
114
115 def visit_alternate_type(self, name, info, ifcond, variants):
116 pass
117
118 def visit_command(self, name, info, ifcond, arg_type, ret_type, gen,
119 success_response, boxed, allow_oob, allow_preconfig,
120 features):
121 pass
122
123 def visit_event(self, name, info, ifcond, arg_type, boxed):
124 pass
125
126
127 class QAPISchemaInclude(QAPISchemaEntity):
128
129 def __init__(self, fname, info):
130 QAPISchemaEntity.__init__(self, None, info, None)
131 self.fname = fname
132
133 def visit(self, visitor):
134 QAPISchemaEntity.visit(self, visitor)
135 visitor.visit_include(self.fname, self.info)
136
137
138 class QAPISchemaType(QAPISchemaEntity):
139 # Return the C type for common use.
140 # For the types we commonly box, this is a pointer type.
141 def c_type(self):
142 pass
143
144 # Return the C type to be used in a parameter list.
145 def c_param_type(self):
146 return self.c_type()
147
148 # Return the C type to be used where we suppress boxing.
149 def c_unboxed_type(self):
150 return self.c_type()
151
152 def json_type(self):
153 pass
154
155 def alternate_qtype(self):
156 json2qtype = {
157 'null': 'QTYPE_QNULL',
158 'string': 'QTYPE_QSTRING',
159 'number': 'QTYPE_QNUM',
160 'int': 'QTYPE_QNUM',
161 'boolean': 'QTYPE_QBOOL',
162 'object': 'QTYPE_QDICT'
163 }
164 return json2qtype.get(self.json_type())
165
166 def doc_type(self):
167 if self.is_implicit():
168 return None
169 return self.name
170
171 def describe(self):
172 assert self.meta
173 return "%s type '%s'" % (self.meta, self.name)
174
175
176 class QAPISchemaBuiltinType(QAPISchemaType):
177 meta = 'built-in'
178
179 def __init__(self, name, json_type, c_type):
180 QAPISchemaType.__init__(self, name, None, None)
181 assert not c_type or isinstance(c_type, str)
182 assert json_type in ('string', 'number', 'int', 'boolean', 'null',
183 'value')
184 self._json_type_name = json_type
185 self._c_type_name = c_type
186
187 def c_name(self):
188 return self.name
189
190 def c_type(self):
191 return self._c_type_name
192
193 def c_param_type(self):
194 if self.name == 'str':
195 return 'const ' + self._c_type_name
196 return self._c_type_name
197
198 def json_type(self):
199 return self._json_type_name
200
201 def doc_type(self):
202 return self.json_type()
203
204 def visit(self, visitor):
205 QAPISchemaType.visit(self, visitor)
206 visitor.visit_builtin_type(self.name, self.info, self.json_type())
207
208
209 class QAPISchemaEnumType(QAPISchemaType):
210 meta = 'enum'
211
212 def __init__(self, name, info, doc, ifcond, members, prefix):
213 QAPISchemaType.__init__(self, name, info, doc, ifcond)
214 for m in members:
215 assert isinstance(m, QAPISchemaEnumMember)
216 m.set_defined_in(name)
217 assert prefix is None or isinstance(prefix, str)
218 self.members = members
219 self.prefix = prefix
220
221 def check(self, schema):
222 QAPISchemaType.check(self, schema)
223 seen = {}
224 for m in self.members:
225 m.check_clash(self.info, seen)
226
227 def connect_doc(self):
228 if self.doc:
229 for m in self.members:
230 self.doc.connect_member(m)
231
232 def is_implicit(self):
233 # See QAPISchema._make_implicit_enum_type() and ._def_predefineds()
234 return self.name.endswith('Kind') or self.name == 'QType'
235
236 def c_type(self):
237 return c_name(self.name)
238
239 def member_names(self):
240 return [m.name for m in self.members]
241
242 def json_type(self):
243 return 'string'
244
245 def visit(self, visitor):
246 QAPISchemaType.visit(self, visitor)
247 visitor.visit_enum_type(self.name, self.info, self.ifcond,
248 self.members, self.prefix)
249
250
251 class QAPISchemaArrayType(QAPISchemaType):
252 meta = 'array'
253
254 def __init__(self, name, info, element_type):
255 QAPISchemaType.__init__(self, name, info, None, None)
256 assert isinstance(element_type, str)
257 self._element_type_name = element_type
258 self.element_type = None
259
260 def check(self, schema):
261 QAPISchemaType.check(self, schema)
262 self.element_type = schema.resolve_type(
263 self._element_type_name, self.info,
264 self.info and self.info.defn_meta)
265 assert not isinstance(self.element_type, QAPISchemaArrayType)
266
267 @property
268 def ifcond(self):
269 assert self._checked
270 return self.element_type.ifcond
271
272 @property
273 def module(self):
274 assert self._checked
275 return self.element_type.module
276
277 def is_implicit(self):
278 return True
279
280 def c_type(self):
281 return c_name(self.name) + pointer_suffix
282
283 def json_type(self):
284 return 'array'
285
286 def doc_type(self):
287 elt_doc_type = self.element_type.doc_type()
288 if not elt_doc_type:
289 return None
290 return 'array of ' + elt_doc_type
291
292 def visit(self, visitor):
293 QAPISchemaType.visit(self, visitor)
294 visitor.visit_array_type(self.name, self.info, self.ifcond,
295 self.element_type)
296
297 def describe(self):
298 assert self.meta
299 return "%s type ['%s']" % (self.meta, self._element_type_name)
300
301
302 class QAPISchemaObjectType(QAPISchemaType):
303 def __init__(self, name, info, doc, ifcond,
304 base, local_members, variants, features):
305 # struct has local_members, optional base, and no variants
306 # flat union has base, variants, and no local_members
307 # simple union has local_members, variants, and no base
308 QAPISchemaType.__init__(self, name, info, doc, ifcond)
309 self.meta = 'union' if variants else 'struct'
310 assert base is None or isinstance(base, str)
311 for m in local_members:
312 assert isinstance(m, QAPISchemaObjectTypeMember)
313 m.set_defined_in(name)
314 if variants is not None:
315 assert isinstance(variants, QAPISchemaObjectTypeVariants)
316 variants.set_defined_in(name)
317 for f in features:
318 assert isinstance(f, QAPISchemaFeature)
319 f.set_defined_in(name)
320 self._base_name = base
321 self.base = None
322 self.local_members = local_members
323 self.variants = variants
324 self.members = None
325 self.features = features
326
327 def check(self, schema):
328 # This calls another type T's .check() exactly when the C
329 # struct emitted by gen_object() contains that T's C struct
330 # (pointers don't count).
331 if self.members is not None:
332 # A previous .check() completed: nothing to do
333 return
334 if self._checked:
335 # Recursed: C struct contains itself
336 raise QAPISemError(self.info,
337 "object %s contains itself" % self.name)
338
339 QAPISchemaType.check(self, schema)
340 assert self._checked and self.members is None
341
342 seen = OrderedDict()
343 if self._base_name:
344 self.base = schema.resolve_type(self._base_name, self.info,
345 "'base'")
346 if (not isinstance(self.base, QAPISchemaObjectType)
347 or self.base.variants):
348 raise QAPISemError(
349 self.info,
350 "'base' requires a struct type, %s isn't"
351 % self.base.describe())
352 self.base.check(schema)
353 self.base.check_clash(self.info, seen)
354 for m in self.local_members:
355 m.check(schema)
356 m.check_clash(self.info, seen)
357 members = seen.values()
358
359 if self.variants:
360 self.variants.check(schema, seen)
361 self.variants.check_clash(self.info, seen)
362
363 # Features are in a name space separate from members
364 seen = {}
365 for f in self.features:
366 f.check_clash(self.info, seen)
367
368 self.members = members # mark completed
369
370 # Check that the members of this type do not cause duplicate JSON members,
371 # and update seen to track the members seen so far. Report any errors
372 # on behalf of info, which is not necessarily self.info
373 def check_clash(self, info, seen):
374 assert self._checked
375 assert not self.variants # not implemented
376 for m in self.members:
377 m.check_clash(info, seen)
378
379 def connect_doc(self):
380 if self.doc:
381 for m in self.local_members:
382 self.doc.connect_member(m)
383
384 def check_doc(self):
385 if self.doc:
386 self.doc.check()
387
388 @property
389 def ifcond(self):
390 assert self._checked
391 if isinstance(self._ifcond, QAPISchemaType):
392 # Simple union wrapper type inherits from wrapped type;
393 # see _make_implicit_object_type()
394 return self._ifcond.ifcond
395 return self._ifcond
396
397 def is_implicit(self):
398 # See QAPISchema._make_implicit_object_type(), as well as
399 # _def_predefineds()
400 return self.name.startswith('q_')
401
402 def is_empty(self):
403 assert self.members is not None
404 return not self.members and not self.variants
405
406 def c_name(self):
407 assert self.name != 'q_empty'
408 return QAPISchemaType.c_name(self)
409
410 def c_type(self):
411 assert not self.is_implicit()
412 return c_name(self.name) + pointer_suffix
413
414 def c_unboxed_type(self):
415 return c_name(self.name)
416
417 def json_type(self):
418 return 'object'
419
420 def visit(self, visitor):
421 QAPISchemaType.visit(self, visitor)
422 visitor.visit_object_type(self.name, self.info, self.ifcond,
423 self.base, self.local_members, self.variants,
424 self.features)
425 visitor.visit_object_type_flat(self.name, self.info, self.ifcond,
426 self.members, self.variants,
427 self.features)
428
429
430 class QAPISchemaMember(object):
431 """ Represents object members, enum members and features """
432 role = 'member'
433
434 def __init__(self, name, info, ifcond=None):
435 assert isinstance(name, str)
436 self.name = name
437 self.info = info
438 self.ifcond = ifcond or []
439 self.defined_in = None
440
441 def set_defined_in(self, name):
442 assert not self.defined_in
443 self.defined_in = name
444
445 def check_clash(self, info, seen):
446 cname = c_name(self.name)
447 if cname in seen:
448 raise QAPISemError(
449 info,
450 "%s collides with %s"
451 % (self.describe(info), seen[cname].describe(info)))
452 seen[cname] = self
453
454 def describe(self, info):
455 role = self.role
456 defined_in = self.defined_in
457 assert defined_in
458
459 if defined_in.startswith('q_obj_'):
460 # See QAPISchema._make_implicit_object_type() - reverse the
461 # mapping there to create a nice human-readable description
462 defined_in = defined_in[6:]
463 if defined_in.endswith('-arg'):
464 # Implicit type created for a command's dict 'data'
465 assert role == 'member'
466 role = 'parameter'
467 elif defined_in.endswith('-base'):
468 # Implicit type created for a flat union's dict 'base'
469 role = 'base ' + role
470 else:
471 # Implicit type created for a simple union's branch
472 assert defined_in.endswith('-wrapper')
473 # Unreachable and not implemented
474 assert False
475 elif defined_in.endswith('Kind'):
476 # See QAPISchema._make_implicit_enum_type()
477 # Implicit enum created for simple union's branches
478 assert role == 'value'
479 role = 'branch'
480 elif defined_in != info.defn_name:
481 return "%s '%s' of type '%s'" % (role, self.name, defined_in)
482 return "%s '%s'" % (role, self.name)
483
484
485 class QAPISchemaEnumMember(QAPISchemaMember):
486 role = 'value'
487
488
489 class QAPISchemaFeature(QAPISchemaMember):
490 role = 'feature'
491
492
493 class QAPISchemaObjectTypeMember(QAPISchemaMember):
494 def __init__(self, name, info, typ, optional, ifcond=None):
495 QAPISchemaMember.__init__(self, name, info, ifcond)
496 assert isinstance(typ, str)
497 assert isinstance(optional, bool)
498 self._type_name = typ
499 self.type = None
500 self.optional = optional
501
502 def check(self, schema):
503 assert self.defined_in
504 self.type = schema.resolve_type(self._type_name, self.info,
505 self.describe)
506
507
508 class QAPISchemaObjectTypeVariants(object):
509 def __init__(self, tag_name, info, tag_member, variants):
510 # Flat unions pass tag_name but not tag_member.
511 # Simple unions and alternates pass tag_member but not tag_name.
512 # After check(), tag_member is always set, and tag_name remains
513 # a reliable witness of being used by a flat union.
514 assert bool(tag_member) != bool(tag_name)
515 assert (isinstance(tag_name, str) or
516 isinstance(tag_member, QAPISchemaObjectTypeMember))
517 for v in variants:
518 assert isinstance(v, QAPISchemaObjectTypeVariant)
519 self._tag_name = tag_name
520 self.info = info
521 self.tag_member = tag_member
522 self.variants = variants
523
524 def set_defined_in(self, name):
525 for v in self.variants:
526 v.set_defined_in(name)
527
528 def check(self, schema, seen):
529 if not self.tag_member: # flat union
530 self.tag_member = seen.get(c_name(self._tag_name))
531 base = "'base'"
532 # Pointing to the base type when not implicit would be
533 # nice, but we don't know it here
534 if not self.tag_member or self._tag_name != self.tag_member.name:
535 raise QAPISemError(
536 self.info,
537 "discriminator '%s' is not a member of %s"
538 % (self._tag_name, base))
539 # Here we do:
540 base_type = schema.lookup_type(self.tag_member.defined_in)
541 assert base_type
542 if not base_type.is_implicit():
543 base = "base type '%s'" % self.tag_member.defined_in
544 if not isinstance(self.tag_member.type, QAPISchemaEnumType):
545 raise QAPISemError(
546 self.info,
547 "discriminator member '%s' of %s must be of enum type"
548 % (self._tag_name, base))
549 if self.tag_member.optional:
550 raise QAPISemError(
551 self.info,
552 "discriminator member '%s' of %s must not be optional"
553 % (self._tag_name, base))
554 if self.tag_member.ifcond:
555 raise QAPISemError(
556 self.info,
557 "discriminator member '%s' of %s must not be conditional"
558 % (self._tag_name, base))
559 else: # simple union
560 assert isinstance(self.tag_member.type, QAPISchemaEnumType)
561 assert not self.tag_member.optional
562 assert self.tag_member.ifcond == []
563 if self._tag_name: # flat union
564 # branches that are not explicitly covered get an empty type
565 cases = set([v.name for v in self.variants])
566 for m in self.tag_member.type.members:
567 if m.name not in cases:
568 v = QAPISchemaObjectTypeVariant(m.name, self.info,
569 'q_empty', m.ifcond)
570 v.set_defined_in(self.tag_member.defined_in)
571 self.variants.append(v)
572 if not self.variants:
573 raise QAPISemError(self.info, "union has no branches")
574 for v in self.variants:
575 v.check(schema)
576 # Union names must match enum values; alternate names are
577 # checked separately. Use 'seen' to tell the two apart.
578 if seen:
579 if v.name not in self.tag_member.type.member_names():
580 raise QAPISemError(
581 self.info,
582 "branch '%s' is not a value of %s"
583 % (v.name, self.tag_member.type.describe()))
584 if (not isinstance(v.type, QAPISchemaObjectType)
585 or v.type.variants):
586 raise QAPISemError(
587 self.info,
588 "%s cannot use %s"
589 % (v.describe(self.info), v.type.describe()))
590 v.type.check(schema)
591
592 def check_clash(self, info, seen):
593 for v in self.variants:
594 # Reset seen map for each variant, since qapi names from one
595 # branch do not affect another branch
596 v.type.check_clash(info, dict(seen))
597
598
599 class QAPISchemaObjectTypeVariant(QAPISchemaObjectTypeMember):
600 role = 'branch'
601
602 def __init__(self, name, info, typ, ifcond=None):
603 QAPISchemaObjectTypeMember.__init__(self, name, info, typ,
604 False, ifcond)
605
606
607 class QAPISchemaAlternateType(QAPISchemaType):
608 meta = 'alternate'
609
610 def __init__(self, name, info, doc, ifcond, variants):
611 QAPISchemaType.__init__(self, name, info, doc, ifcond)
612 assert isinstance(variants, QAPISchemaObjectTypeVariants)
613 assert variants.tag_member
614 variants.set_defined_in(name)
615 variants.tag_member.set_defined_in(self.name)
616 self.variants = variants
617
618 def check(self, schema):
619 QAPISchemaType.check(self, schema)
620 self.variants.tag_member.check(schema)
621 # Not calling self.variants.check_clash(), because there's nothing
622 # to clash with
623 self.variants.check(schema, {})
624 # Alternate branch names have no relation to the tag enum values;
625 # so we have to check for potential name collisions ourselves.
626 seen = {}
627 types_seen = {}
628 for v in self.variants.variants:
629 v.check_clash(self.info, seen)
630 qtype = v.type.alternate_qtype()
631 if not qtype:
632 raise QAPISemError(
633 self.info,
634 "%s cannot use %s"
635 % (v.describe(self.info), v.type.describe()))
636 conflicting = set([qtype])
637 if qtype == 'QTYPE_QSTRING':
638 if isinstance(v.type, QAPISchemaEnumType):
639 for m in v.type.members:
640 if m.name in ['on', 'off']:
641 conflicting.add('QTYPE_QBOOL')
642 if re.match(r'[-+0-9.]', m.name):
643 # lazy, could be tightened
644 conflicting.add('QTYPE_QNUM')
645 else:
646 conflicting.add('QTYPE_QNUM')
647 conflicting.add('QTYPE_QBOOL')
648 for qt in conflicting:
649 if qt in types_seen:
650 raise QAPISemError(
651 self.info,
652 "%s can't be distinguished from '%s'"
653 % (v.describe(self.info), types_seen[qt]))
654 types_seen[qt] = v.name
655
656 def connect_doc(self):
657 if self.doc:
658 for v in self.variants.variants:
659 self.doc.connect_member(v)
660
661 def check_doc(self):
662 if self.doc:
663 self.doc.check()
664
665 def c_type(self):
666 return c_name(self.name) + pointer_suffix
667
668 def json_type(self):
669 return 'value'
670
671 def visit(self, visitor):
672 QAPISchemaType.visit(self, visitor)
673 visitor.visit_alternate_type(self.name, self.info, self.ifcond,
674 self.variants)
675
676
677 class QAPISchemaCommand(QAPISchemaEntity):
678 meta = 'command'
679
680 def __init__(self, name, info, doc, ifcond, arg_type, ret_type,
681 gen, success_response, boxed, allow_oob, allow_preconfig,
682 features):
683 QAPISchemaEntity.__init__(self, name, info, doc, ifcond)
684 assert not arg_type or isinstance(arg_type, str)
685 assert not ret_type or isinstance(ret_type, str)
686 for f in features:
687 assert isinstance(f, QAPISchemaFeature)
688 f.set_defined_in(name)
689 self._arg_type_name = arg_type
690 self.arg_type = None
691 self._ret_type_name = ret_type
692 self.ret_type = None
693 self.gen = gen
694 self.success_response = success_response
695 self.boxed = boxed
696 self.allow_oob = allow_oob
697 self.allow_preconfig = allow_preconfig
698 self.features = features
699
700 def check(self, schema):
701 QAPISchemaEntity.check(self, schema)
702 if self._arg_type_name:
703 self.arg_type = schema.resolve_type(
704 self._arg_type_name, self.info, "command's 'data'")
705 if not isinstance(self.arg_type, QAPISchemaObjectType):
706 raise QAPISemError(
707 self.info,
708 "command's 'data' cannot take %s"
709 % self.arg_type.describe())
710 if self.arg_type.variants and not self.boxed:
711 raise QAPISemError(
712 self.info,
713 "command's 'data' can take %s only with 'boxed': true"
714 % self.arg_type.describe())
715 if self._ret_type_name:
716 self.ret_type = schema.resolve_type(
717 self._ret_type_name, self.info, "command's 'returns'")
718 if self.name not in self.info.pragma.returns_whitelist:
719 if not (isinstance(self.ret_type, QAPISchemaObjectType)
720 or (isinstance(self.ret_type, QAPISchemaArrayType)
721 and isinstance(self.ret_type.element_type,
722 QAPISchemaObjectType))):
723 raise QAPISemError(
724 self.info,
725 "command's 'returns' cannot take %s"
726 % self.ret_type.describe())
727
728 # Features are in a name space separate from members
729 seen = {}
730 for f in self.features:
731 f.check_clash(self.info, seen)
732
733 def visit(self, visitor):
734 QAPISchemaEntity.visit(self, visitor)
735 visitor.visit_command(self.name, self.info, self.ifcond,
736 self.arg_type, self.ret_type,
737 self.gen, self.success_response,
738 self.boxed, self.allow_oob,
739 self.allow_preconfig,
740 self.features)
741
742
743 class QAPISchemaEvent(QAPISchemaEntity):
744 meta = 'event'
745
746 def __init__(self, name, info, doc, ifcond, arg_type, boxed):
747 QAPISchemaEntity.__init__(self, name, info, doc, ifcond)
748 assert not arg_type or isinstance(arg_type, str)
749 self._arg_type_name = arg_type
750 self.arg_type = None
751 self.boxed = boxed
752
753 def check(self, schema):
754 QAPISchemaEntity.check(self, schema)
755 if self._arg_type_name:
756 self.arg_type = schema.resolve_type(
757 self._arg_type_name, self.info, "event's 'data'")
758 if not isinstance(self.arg_type, QAPISchemaObjectType):
759 raise QAPISemError(
760 self.info,
761 "event's 'data' cannot take %s"
762 % self.arg_type.describe())
763 if self.arg_type.variants and not self.boxed:
764 raise QAPISemError(
765 self.info,
766 "event's 'data' can take %s only with 'boxed': true"
767 % self.arg_type.describe())
768
769 def visit(self, visitor):
770 QAPISchemaEntity.visit(self, visitor)
771 visitor.visit_event(self.name, self.info, self.ifcond,
772 self.arg_type, self.boxed)
773
774
775 class QAPISchema(object):
776 def __init__(self, fname):
777 self.fname = fname
778 parser = QAPISchemaParser(fname)
779 exprs = check_exprs(parser.exprs)
780 self.docs = parser.docs
781 self._entity_list = []
782 self._entity_dict = {}
783 self._predefining = True
784 self._def_predefineds()
785 self._predefining = False
786 self._def_exprs(exprs)
787 self.check()
788
789 def _def_entity(self, ent):
790 # Only the predefined types are allowed to not have info
791 assert ent.info or self._predefining
792 self._entity_list.append(ent)
793 if ent.name is None:
794 return
795 # TODO reject names that differ only in '_' vs. '.' vs. '-',
796 # because they're liable to clash in generated C.
797 other_ent = self._entity_dict.get(ent.name)
798 if other_ent:
799 if other_ent.info:
800 where = QAPIError(other_ent.info, None, "previous definition")
801 raise QAPISemError(
802 ent.info,
803 "'%s' is already defined\n%s" % (ent.name, where))
804 raise QAPISemError(
805 ent.info, "%s is already defined" % other_ent.describe())
806 self._entity_dict[ent.name] = ent
807
808 def lookup_entity(self, name, typ=None):
809 ent = self._entity_dict.get(name)
810 if typ and not isinstance(ent, typ):
811 return None
812 return ent
813
814 def lookup_type(self, name):
815 return self.lookup_entity(name, QAPISchemaType)
816
817 def resolve_type(self, name, info, what):
818 typ = self.lookup_type(name)
819 if not typ:
820 if callable(what):
821 what = what(info)
822 raise QAPISemError(
823 info, "%s uses unknown type '%s'" % (what, name))
824 return typ
825
826 def _def_include(self, expr, info, doc):
827 include = expr['include']
828 assert doc is None
829 main_info = info
830 while main_info.parent:
831 main_info = main_info.parent
832 fname = os.path.relpath(include, os.path.dirname(main_info.fname))
833 self._def_entity(QAPISchemaInclude(fname, info))
834
835 def _def_builtin_type(self, name, json_type, c_type):
836 self._def_entity(QAPISchemaBuiltinType(name, json_type, c_type))
837 # Instantiating only the arrays that are actually used would
838 # be nice, but we can't as long as their generated code
839 # (qapi-builtin-types.[ch]) may be shared by some other
840 # schema.
841 self._make_array_type(name, None)
842
843 def _def_predefineds(self):
844 for t in [('str', 'string', 'char' + pointer_suffix),
845 ('number', 'number', 'double'),
846 ('int', 'int', 'int64_t'),
847 ('int8', 'int', 'int8_t'),
848 ('int16', 'int', 'int16_t'),
849 ('int32', 'int', 'int32_t'),
850 ('int64', 'int', 'int64_t'),
851 ('uint8', 'int', 'uint8_t'),
852 ('uint16', 'int', 'uint16_t'),
853 ('uint32', 'int', 'uint32_t'),
854 ('uint64', 'int', 'uint64_t'),
855 ('size', 'int', 'uint64_t'),
856 ('bool', 'boolean', 'bool'),
857 ('any', 'value', 'QObject' + pointer_suffix),
858 ('null', 'null', 'QNull' + pointer_suffix)]:
859 self._def_builtin_type(*t)
860 self.the_empty_object_type = QAPISchemaObjectType(
861 'q_empty', None, None, None, None, [], None, [])
862 self._def_entity(self.the_empty_object_type)
863
864 qtypes = ['none', 'qnull', 'qnum', 'qstring', 'qdict', 'qlist',
865 'qbool']
866 qtype_values = self._make_enum_members(
867 [{'name': n} for n in qtypes], None)
868
869 self._def_entity(QAPISchemaEnumType('QType', None, None, None,
870 qtype_values, 'QTYPE'))
871
872 def _make_features(self, features, info):
873 return [QAPISchemaFeature(f['name'], info, f.get('if'))
874 for f in features]
875
876 def _make_enum_members(self, values, info):
877 return [QAPISchemaEnumMember(v['name'], info, v.get('if'))
878 for v in values]
879
880 def _make_implicit_enum_type(self, name, info, ifcond, values):
881 # See also QAPISchemaObjectTypeMember.describe()
882 name = name + 'Kind' # reserved by check_defn_name_str()
883 self._def_entity(QAPISchemaEnumType(
884 name, info, None, ifcond, self._make_enum_members(values, info),
885 None))
886 return name
887
888 def _make_array_type(self, element_type, info):
889 name = element_type + 'List' # reserved by check_defn_name_str()
890 if not self.lookup_type(name):
891 self._def_entity(QAPISchemaArrayType(name, info, element_type))
892 return name
893
894 def _make_implicit_object_type(self, name, info, doc, ifcond,
895 role, members):
896 if not members:
897 return None
898 # See also QAPISchemaObjectTypeMember.describe()
899 name = 'q_obj_%s-%s' % (name, role)
900 typ = self.lookup_entity(name, QAPISchemaObjectType)
901 if typ:
902 # The implicit object type has multiple users. This can
903 # happen only for simple unions' implicit wrapper types.
904 # Its ifcond should be the disjunction of its user's
905 # ifconds. Not implemented. Instead, we always pass the
906 # wrapped type's ifcond, which is trivially the same for all
907 # users. It's also necessary for the wrapper to compile.
908 # But it's not tight: the disjunction need not imply it. We
909 # may end up compiling useless wrapper types.
910 # TODO kill simple unions or implement the disjunction
911 assert (ifcond or []) == typ._ifcond # pylint: disable=protected-access
912 else:
913 self._def_entity(QAPISchemaObjectType(name, info, doc, ifcond,
914 None, members, None, []))
915 return name
916
917 def _def_enum_type(self, expr, info, doc):
918 name = expr['enum']
919 data = expr['data']
920 prefix = expr.get('prefix')
921 ifcond = expr.get('if')
922 self._def_entity(QAPISchemaEnumType(
923 name, info, doc, ifcond,
924 self._make_enum_members(data, info), prefix))
925
926 def _make_member(self, name, typ, ifcond, info):
927 optional = False
928 if name.startswith('*'):
929 name = name[1:]
930 optional = True
931 if isinstance(typ, list):
932 assert len(typ) == 1
933 typ = self._make_array_type(typ[0], info)
934 return QAPISchemaObjectTypeMember(name, info, typ, optional, ifcond)
935
936 def _make_members(self, data, info):
937 return [self._make_member(key, value['type'], value.get('if'), info)
938 for (key, value) in data.items()]
939
940 def _def_struct_type(self, expr, info, doc):
941 name = expr['struct']
942 base = expr.get('base')
943 data = expr['data']
944 ifcond = expr.get('if')
945 features = expr.get('features', [])
946 self._def_entity(QAPISchemaObjectType(
947 name, info, doc, ifcond, base,
948 self._make_members(data, info),
949 None,
950 self._make_features(features, info)))
951
952 def _make_variant(self, case, typ, ifcond, info):
953 return QAPISchemaObjectTypeVariant(case, info, typ, ifcond)
954
955 def _make_simple_variant(self, case, typ, ifcond, info):
956 if isinstance(typ, list):
957 assert len(typ) == 1
958 typ = self._make_array_type(typ[0], info)
959 typ = self._make_implicit_object_type(
960 typ, info, None, self.lookup_type(typ),
961 'wrapper', [self._make_member('data', typ, None, info)])
962 return QAPISchemaObjectTypeVariant(case, info, typ, ifcond)
963
964 def _def_union_type(self, expr, info, doc):
965 name = expr['union']
966 data = expr['data']
967 base = expr.get('base')
968 ifcond = expr.get('if')
969 tag_name = expr.get('discriminator')
970 tag_member = None
971 if isinstance(base, dict):
972 base = self._make_implicit_object_type(
973 name, info, doc, ifcond,
974 'base', self._make_members(base, info))
975 if tag_name:
976 variants = [self._make_variant(key, value['type'],
977 value.get('if'), info)
978 for (key, value) in data.items()]
979 members = []
980 else:
981 variants = [self._make_simple_variant(key, value['type'],
982 value.get('if'), info)
983 for (key, value) in data.items()]
984 enum = [{'name': v.name, 'if': v.ifcond} for v in variants]
985 typ = self._make_implicit_enum_type(name, info, ifcond, enum)
986 tag_member = QAPISchemaObjectTypeMember('type', info, typ, False)
987 members = [tag_member]
988 self._def_entity(
989 QAPISchemaObjectType(name, info, doc, ifcond, base, members,
990 QAPISchemaObjectTypeVariants(
991 tag_name, info, tag_member, variants),
992 []))
993
994 def _def_alternate_type(self, expr, info, doc):
995 name = expr['alternate']
996 data = expr['data']
997 ifcond = expr.get('if')
998 variants = [self._make_variant(key, value['type'], value.get('if'),
999 info)
1000 for (key, value) in data.items()]
1001 tag_member = QAPISchemaObjectTypeMember('type', info, 'QType', False)
1002 self._def_entity(
1003 QAPISchemaAlternateType(name, info, doc, ifcond,
1004 QAPISchemaObjectTypeVariants(
1005 None, info, tag_member, variants)))
1006
1007 def _def_command(self, expr, info, doc):
1008 name = expr['command']
1009 data = expr.get('data')
1010 rets = expr.get('returns')
1011 gen = expr.get('gen', True)
1012 success_response = expr.get('success-response', True)
1013 boxed = expr.get('boxed', False)
1014 allow_oob = expr.get('allow-oob', False)
1015 allow_preconfig = expr.get('allow-preconfig', False)
1016 ifcond = expr.get('if')
1017 features = expr.get('features', [])
1018 if isinstance(data, OrderedDict):
1019 data = self._make_implicit_object_type(
1020 name, info, doc, ifcond, 'arg', self._make_members(data, info))
1021 if isinstance(rets, list):
1022 assert len(rets) == 1
1023 rets = self._make_array_type(rets[0], info)
1024 self._def_entity(QAPISchemaCommand(name, info, doc, ifcond, data, rets,
1025 gen, success_response,
1026 boxed, allow_oob, allow_preconfig,
1027 self._make_features(features, info)))
1028
1029 def _def_event(self, expr, info, doc):
1030 name = expr['event']
1031 data = expr.get('data')
1032 boxed = expr.get('boxed', False)
1033 ifcond = expr.get('if')
1034 if isinstance(data, OrderedDict):
1035 data = self._make_implicit_object_type(
1036 name, info, doc, ifcond, 'arg', self._make_members(data, info))
1037 self._def_entity(QAPISchemaEvent(name, info, doc, ifcond, data, boxed))
1038
1039 def _def_exprs(self, exprs):
1040 for expr_elem in exprs:
1041 expr = expr_elem['expr']
1042 info = expr_elem['info']
1043 doc = expr_elem.get('doc')
1044 if 'enum' in expr:
1045 self._def_enum_type(expr, info, doc)
1046 elif 'struct' in expr:
1047 self._def_struct_type(expr, info, doc)
1048 elif 'union' in expr:
1049 self._def_union_type(expr, info, doc)
1050 elif 'alternate' in expr:
1051 self._def_alternate_type(expr, info, doc)
1052 elif 'command' in expr:
1053 self._def_command(expr, info, doc)
1054 elif 'event' in expr:
1055 self._def_event(expr, info, doc)
1056 elif 'include' in expr:
1057 self._def_include(expr, info, doc)
1058 else:
1059 assert False
1060
1061 def check(self):
1062 for ent in self._entity_list:
1063 ent.check(self)
1064 ent.connect_doc()
1065 ent.check_doc()
1066
1067 def visit(self, visitor):
1068 visitor.visit_begin(self)
1069 module = None
1070 visitor.visit_module(module)
1071 for entity in self._entity_list:
1072 if visitor.visit_needed(entity):
1073 if entity.module != module:
1074 module = entity.module
1075 visitor.visit_module(module)
1076 entity.visit(visitor)
1077 visitor.visit_end()