4 # Copyright IBM, Corp. 2011
5 # Copyright (c) 2013-2018 Red Hat Inc.
8 # Anthony Liguori <aliguori@us.ibm.com>
9 # Markus Armbruster <armbru@redhat.com>
11 # This work is licensed under the terms of the GNU GPL, version 2.
12 # See the COPYING file in the top-level directory.
14 from __future__
import print_function
15 from contextlib
import contextmanager
21 from collections
import OrderedDict
24 'null': 'QTYPE_QNULL',
25 'str': 'QTYPE_QSTRING',
27 'number': 'QTYPE_QNUM',
28 'bool': 'QTYPE_QBOOL',
30 'int16': 'QTYPE_QNUM',
31 'int32': 'QTYPE_QNUM',
32 'int64': 'QTYPE_QNUM',
33 'uint8': 'QTYPE_QNUM',
34 'uint16': 'QTYPE_QNUM',
35 'uint32': 'QTYPE_QNUM',
36 'uint64': 'QTYPE_QNUM',
38 'any': None, # any QType possible, actually
39 'QType': 'QTYPE_QSTRING',
42 # Are documentation comments required?
45 # Whitelist of commands allowed to return a non-dictionary
46 returns_whitelist
= []
48 # Whitelist of entities allowed to violate case conventions
49 name_case_whitelist
= []
57 # Parsing the schema into expressions
61 def error_path(parent
):
64 res
= ('In file included from %s:%d:\n' % (parent
['file'],
65 parent
['line'])) + res
66 parent
= parent
['parent']
70 class QAPIError(Exception):
71 def __init__(self
, fname
, line
, col
, incl_info
, msg
):
72 Exception.__init
__(self
)
80 loc
= '%s:%d' % (self
.fname
, self
.line
)
81 if self
.col
is not None:
82 loc
+= ':%s' % self
.col
83 return error_path(self
.info
) + '%s: %s' % (loc
, self
.msg
)
86 class QAPIParseError(QAPIError
):
87 def __init__(self
, parser
, msg
):
89 for ch
in parser
.src
[parser
.line_pos
:parser
.pos
]:
91 col
= (col
+ 7) % 8 + 1
94 QAPIError
.__init
__(self
, parser
.fname
, parser
.line
, col
,
95 parser
.incl_info
, msg
)
98 class QAPISemError(QAPIError
):
99 def __init__(self
, info
, msg
):
100 QAPIError
.__init
__(self
, info
['file'], info
['line'], None,
104 class QAPIDoc(object):
105 class Section(object):
106 def __init__(self
, name
=None):
107 # optional section name (argument/member or section name)
109 # the list of lines for this section
112 def append(self
, line
):
113 self
.text
+= line
.rstrip() + '\n'
115 class ArgSection(Section
):
116 def __init__(self
, name
):
117 QAPIDoc
.Section
.__init
__(self
, name
)
120 def connect(self
, member
):
123 def __init__(self
, parser
, info
):
124 # self._parser is used to report errors with QAPIParseError. The
125 # resulting error position depends on the state of the parser.
126 # It happens to be the beginning of the comment. More or less
127 # servicable, but action at a distance.
128 self
._parser
= parser
131 self
.body
= QAPIDoc
.Section()
132 # dict mapping parameter name to ArgSection
133 self
.args
= OrderedDict()
136 # the current section
137 self
._section
= self
.body
139 def has_section(self
, name
):
140 """Return True if we have a section with this name."""
141 for i
in self
.sections
:
146 def append(self
, line
):
147 """Parse a comment line and add it to the documentation."""
150 self
._append
_freeform
(line
)
154 raise QAPIParseError(self
._parser
, "Missing space after #")
157 # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't
158 # recognized, and get silently treated as ordinary text
160 self
._append
_symbol
_line
(line
)
161 elif not self
.body
.text
and line
.startswith('@'):
162 if not line
.endswith(':'):
163 raise QAPIParseError(self
._parser
, "Line should end with :")
164 self
.symbol
= line
[1:-1]
165 # FIXME invalid names other than the empty string aren't flagged
167 raise QAPIParseError(self
._parser
, "Invalid name")
169 self
._append
_freeform
(line
)
171 def end_comment(self
):
174 def _append_symbol_line(self
, line
):
175 name
= line
.split(' ', 1)[0]
177 if name
.startswith('@') and name
.endswith(':'):
178 line
= line
[len(name
)+1:]
179 self
._start
_args
_section
(name
[1:-1])
180 elif name
in ('Returns:', 'Since:',
181 # those are often singular or plural
183 'Example:', 'Examples:',
185 line
= line
[len(name
)+1:]
186 self
._start
_section
(name
[:-1])
188 self
._append
_freeform
(line
)
190 def _start_args_section(self
, name
):
191 # FIXME invalid names other than the empty string aren't flagged
193 raise QAPIParseError(self
._parser
, "Invalid parameter name")
194 if name
in self
.args
:
195 raise QAPIParseError(self
._parser
,
196 "'%s' parameter name duplicated" % name
)
198 raise QAPIParseError(self
._parser
,
199 "'@%s:' can't follow '%s' section"
200 % (name
, self
.sections
[0].name
))
202 self
._section
= QAPIDoc
.ArgSection(name
)
203 self
.args
[name
] = self
._section
205 def _start_section(self
, name
=None):
206 if name
in ('Returns', 'Since') and self
.has_section(name
):
207 raise QAPIParseError(self
._parser
,
208 "Duplicated '%s' section" % name
)
210 self
._section
= QAPIDoc
.Section(name
)
211 self
.sections
.append(self
._section
)
213 def _end_section(self
):
215 text
= self
._section
.text
= self
._section
.text
.strip()
216 if self
._section
.name
and (not text
or text
.isspace()):
217 raise QAPIParseError(self
._parser
, "Empty doc section '%s'"
218 % self
._section
.name
)
221 def _append_freeform(self
, line
):
222 in_arg
= isinstance(self
._section
, QAPIDoc
.ArgSection
)
223 if (in_arg
and self
._section
.text
.endswith('\n\n')
224 and line
and not line
[0].isspace()):
225 self
._start
_section
()
226 if (in_arg
or not self
._section
.name
227 or not self
._section
.name
.startswith('Example')):
229 match
= re
.match(r
'(@\S+:)', line
)
231 raise QAPIParseError(self
._parser
,
232 "'%s' not allowed in free-form documentation"
234 self
._section
.append(line
)
236 def connect_member(self
, member
):
237 if member
.name
not in self
.args
:
238 # Undocumented TODO outlaw
239 self
.args
[member
.name
] = QAPIDoc
.ArgSection(member
.name
)
240 self
.args
[member
.name
].connect(member
)
242 def check_expr(self
, expr
):
243 if self
.has_section('Returns') and 'command' not in expr
:
244 raise QAPISemError(self
.info
,
245 "'Returns:' is only valid for commands")
248 bogus
= [name
for name
, section
in self
.args
.items()
249 if not section
.member
]
253 "The following documented members are not in "
254 "the declaration: %s" % ", ".join(bogus
))
257 class QAPISchemaParser(object):
259 def __init__(self
, fp
, previously_included
=[], incl_info
=None):
261 previously_included
.append(os
.path
.abspath(fp
.name
))
262 self
.incl_info
= incl_info
264 if self
.src
== '' or self
.src
[-1] != '\n':
274 while self
.tok
is not None:
275 info
= {'file': self
.fname
, 'line': self
.line
,
276 'parent': self
.incl_info
}
278 self
.reject_expr_doc(cur_doc
)
279 cur_doc
= self
.get_doc(info
)
280 self
.docs
.append(cur_doc
)
283 expr
= self
.get_expr(False)
284 if 'include' in expr
:
285 self
.reject_expr_doc(cur_doc
)
287 raise QAPISemError(info
, "Invalid 'include' directive")
288 include
= expr
['include']
289 if not isinstance(include
, str):
290 raise QAPISemError(info
,
291 "Value of 'include' must be a string")
292 incl_fname
= os
.path
.join(os
.path
.dirname(self
.fname
),
294 self
.exprs
.append({'expr': {'include': incl_fname
},
296 exprs_include
= self
._include
(include
, info
, incl_fname
,
299 self
.exprs
.extend(exprs_include
.exprs
)
300 self
.docs
.extend(exprs_include
.docs
)
301 elif "pragma" in expr
:
302 self
.reject_expr_doc(cur_doc
)
304 raise QAPISemError(info
, "Invalid 'pragma' directive")
305 pragma
= expr
['pragma']
306 if not isinstance(pragma
, dict):
308 info
, "Value of 'pragma' must be a dictionary")
309 for name
, value
in pragma
.items():
310 self
._pragma
(name
, value
, info
)
312 expr_elem
= {'expr': expr
,
315 if not cur_doc
.symbol
:
317 cur_doc
.info
, "Expression documentation required")
318 expr_elem
['doc'] = cur_doc
319 self
.exprs
.append(expr_elem
)
321 self
.reject_expr_doc(cur_doc
)
324 def reject_expr_doc(doc
):
325 if doc
and doc
.symbol
:
328 "Documentation for '%s' is not followed by the definition"
331 def _include(self
, include
, info
, incl_fname
, previously_included
):
332 incl_abs_fname
= os
.path
.abspath(incl_fname
)
333 # catch inclusion cycle
336 if incl_abs_fname
== os
.path
.abspath(inf
['file']):
337 raise QAPISemError(info
, "Inclusion loop for %s" % include
)
340 # skip multiple include of the same file
341 if incl_abs_fname
in previously_included
:
345 if sys
.version_info
[0] >= 3:
346 fobj
= open(incl_fname
, 'r', encoding
='utf-8')
348 fobj
= open(incl_fname
, 'r')
350 raise QAPISemError(info
, '%s: %s' % (e
.strerror
, incl_fname
))
351 return QAPISchemaParser(fobj
, previously_included
, info
)
353 def _pragma(self
, name
, value
, info
):
354 global doc_required
, returns_whitelist
, name_case_whitelist
355 if name
== 'doc-required':
356 if not isinstance(value
, bool):
357 raise QAPISemError(info
,
358 "Pragma 'doc-required' must be boolean")
360 elif name
== 'returns-whitelist':
361 if (not isinstance(value
, list)
362 or any([not isinstance(elt
, str) for elt
in value
])):
363 raise QAPISemError(info
,
364 "Pragma returns-whitelist must be"
365 " a list of strings")
366 returns_whitelist
= value
367 elif name
== 'name-case-whitelist':
368 if (not isinstance(value
, list)
369 or any([not isinstance(elt
, str) for elt
in value
])):
370 raise QAPISemError(info
,
371 "Pragma name-case-whitelist must be"
372 " a list of strings")
373 name_case_whitelist
= value
375 raise QAPISemError(info
, "Unknown pragma '%s'" % name
)
377 def accept(self
, skip_comment
=True):
379 self
.tok
= self
.src
[self
.cursor
]
380 self
.pos
= self
.cursor
385 if self
.src
[self
.cursor
] == '#':
386 # Start of doc comment
388 self
.cursor
= self
.src
.find('\n', self
.cursor
)
390 self
.val
= self
.src
[self
.pos
:self
.cursor
]
392 elif self
.tok
in '{}:,[]':
394 elif self
.tok
== "'":
398 ch
= self
.src
[self
.cursor
]
401 raise QAPIParseError(self
, 'Missing terminating "\'"')
415 for _
in range(0, 4):
416 ch
= self
.src
[self
.cursor
]
418 if ch
not in '0123456789abcdefABCDEF':
419 raise QAPIParseError(self
,
420 '\\u escape needs 4 '
422 value
= (value
<< 4) + int(ch
, 16)
423 # If Python 2 and 3 didn't disagree so much on
424 # how to handle Unicode, then we could allow
425 # Unicode string defaults. But most of QAPI is
426 # ASCII-only, so we aren't losing much for now.
427 if not value
or value
> 0x7f:
428 raise QAPIParseError(self
,
429 'For now, \\u escape '
430 'only supports non-zero '
431 'values up to \\u007f')
436 raise QAPIParseError(self
,
437 "Unknown escape \\%s" % ch
)
446 elif self
.src
.startswith('true', self
.pos
):
450 elif self
.src
.startswith('false', self
.pos
):
454 elif self
.src
.startswith('null', self
.pos
):
458 elif self
.tok
== '\n':
459 if self
.cursor
== len(self
.src
):
463 self
.line_pos
= self
.cursor
464 elif not self
.tok
.isspace():
465 raise QAPIParseError(self
, 'Stray "%s"' % self
.tok
)
467 def get_members(self
):
473 raise QAPIParseError(self
, 'Expected string or "}"')
478 raise QAPIParseError(self
, 'Expected ":"')
481 raise QAPIParseError(self
, 'Duplicate key "%s"' % key
)
482 expr
[key
] = self
.get_expr(True)
487 raise QAPIParseError(self
, 'Expected "," or "}"')
490 raise QAPIParseError(self
, 'Expected string')
492 def get_values(self
):
497 if self
.tok
not in "{['tfn":
498 raise QAPIParseError(self
, 'Expected "{", "[", "]", string, '
501 expr
.append(self
.get_expr(True))
506 raise QAPIParseError(self
, 'Expected "," or "]"')
509 def get_expr(self
, nested
):
510 if self
.tok
!= '{' and not nested
:
511 raise QAPIParseError(self
, 'Expected "{"')
514 expr
= self
.get_members()
515 elif self
.tok
== '[':
517 expr
= self
.get_values()
518 elif self
.tok
in "'tfn":
522 raise QAPIParseError(self
, 'Expected "{", "[", string, '
526 def get_doc(self
, info
):
528 raise QAPIParseError(self
, "Junk after '##' at start of "
529 "documentation comment")
531 doc
= QAPIDoc(self
, info
)
533 while self
.tok
== '#':
534 if self
.val
.startswith('##'):
537 raise QAPIParseError(self
, "Junk after '##' at end of "
538 "documentation comment")
546 raise QAPIParseError(self
, "Documentation comment must end with '##'")
550 # Semantic analysis of schema expressions
551 # TODO fold into QAPISchema
552 # TODO catching name collisions in generated code would be nice
556 def find_base_members(base
):
557 if isinstance(base
, dict):
559 base_struct_define
= struct_types
.get(base
)
560 if not base_struct_define
:
562 return base_struct_define
['data']
565 # Return the qtype of an alternate branch, or None on error.
566 def find_alternate_member_qtype(qapi_type
):
567 if qapi_type
in builtin_types
:
568 return builtin_types
[qapi_type
]
569 elif qapi_type
in struct_types
:
571 elif qapi_type
in enum_types
:
572 return 'QTYPE_QSTRING'
573 elif qapi_type
in union_types
:
578 # Return the discriminator enum define if discriminator is specified as an
579 # enum type, otherwise return None.
580 def discriminator_find_enum_define(expr
):
581 base
= expr
.get('base')
582 discriminator
= expr
.get('discriminator')
584 if not (discriminator
and base
):
587 base_members
= find_base_members(base
)
591 discriminator_value
= base_members
.get(discriminator
)
592 if not discriminator_value
:
595 return enum_types
.get(discriminator_value
['type'])
598 # Names must be letters, numbers, -, and _. They must start with letter,
599 # except for downstream extensions which must start with __RFQDN_.
600 # Dots are only valid in the downstream extension prefix.
601 valid_name
= re
.compile(r
'^(__[a-zA-Z0-9.-]+_)?'
602 '[a-zA-Z][a-zA-Z0-9_-]*$')
605 def check_name(info
, source
, name
, allow_optional
=False,
610 if not isinstance(name
, str):
611 raise QAPISemError(info
, "%s requires a string name" % source
)
612 if name
.startswith('*'):
613 membername
= name
[1:]
614 if not allow_optional
:
615 raise QAPISemError(info
, "%s does not allow optional name '%s'"
617 # Enum members can start with a digit, because the generated C
618 # code always prefixes it with the enum name
619 if enum_member
and membername
[0].isdigit():
620 membername
= 'D' + membername
621 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
622 # and 'q_obj_*' implicit type names.
623 if not valid_name
.match(membername
) or \
624 c_name(membername
, False).startswith('q_'):
625 raise QAPISemError(info
, "%s uses invalid name '%s'" % (source
, name
))
628 def add_name(name
, info
, meta
, implicit
=False):
630 check_name(info
, "'%s'" % meta
, name
)
631 # FIXME should reject names that differ only in '_' vs. '.'
632 # vs. '-', because they're liable to clash in generated C.
633 if name
in all_names
:
634 raise QAPISemError(info
, "%s '%s' is already defined"
635 % (all_names
[name
], name
))
636 if not implicit
and (name
.endswith('Kind') or name
.endswith('List')):
637 raise QAPISemError(info
, "%s '%s' should not end in '%s'"
638 % (meta
, name
, name
[-4:]))
639 all_names
[name
] = meta
642 def check_if(expr
, info
):
644 def check_if_str(ifcond
, info
):
645 if not isinstance(ifcond
, str):
647 info
, "'if' condition must be a string or a list of strings")
649 raise QAPISemError(info
, "'if' condition '' makes no sense")
651 ifcond
= expr
.get('if')
654 if isinstance(ifcond
, list):
656 raise QAPISemError(info
, "'if' condition [] is useless")
658 check_if_str(elt
, info
)
660 check_if_str(ifcond
, info
)
663 def check_type(info
, source
, value
, allow_array
=False,
664 allow_dict
=False, allow_optional
=False,
671 # Check if array type for value is okay
672 if isinstance(value
, list):
674 raise QAPISemError(info
, "%s cannot be an array" % source
)
675 if len(value
) != 1 or not isinstance(value
[0], str):
676 raise QAPISemError(info
,
677 "%s: array type must contain single type name" %
681 # Check if type name for value is okay
682 if isinstance(value
, str):
683 if value
not in all_names
:
684 raise QAPISemError(info
, "%s uses unknown type '%s'"
686 if not all_names
[value
] in allow_metas
:
687 raise QAPISemError(info
, "%s cannot use %s type '%s'" %
688 (source
, all_names
[value
], value
))
692 raise QAPISemError(info
, "%s should be a type name" % source
)
694 if not isinstance(value
, OrderedDict
):
695 raise QAPISemError(info
,
696 "%s should be a dictionary or type name" % source
)
698 # value is a dictionary, check that each member is okay
699 for (key
, arg
) in value
.items():
700 check_name(info
, "Member of %s" % source
, key
,
701 allow_optional
=allow_optional
)
702 if c_name(key
, False) == 'u' or c_name(key
, False).startswith('has_'):
703 raise QAPISemError(info
, "Member of %s uses reserved name '%s'"
705 # Todo: allow dictionaries to represent default values of
706 # an optional argument.
707 check_known_keys(info
, "member '%s' of %s" % (key
, source
),
709 check_type(info
, "Member '%s' of %s" % (key
, source
),
710 arg
['type'], allow_array
=True,
711 allow_metas
=['built-in', 'union', 'alternate', 'struct',
715 def check_command(expr
, info
):
716 name
= expr
['command']
717 boxed
= expr
.get('boxed', False)
719 args_meta
= ['struct']
721 args_meta
+= ['union', 'alternate']
722 check_type(info
, "'data' for command '%s'" % name
,
723 expr
.get('data'), allow_dict
=not boxed
, allow_optional
=True,
724 allow_metas
=args_meta
)
725 returns_meta
= ['union', 'struct']
726 if name
in returns_whitelist
:
727 returns_meta
+= ['built-in', 'alternate', 'enum']
728 check_type(info
, "'returns' for command '%s'" % name
,
729 expr
.get('returns'), allow_array
=True,
730 allow_optional
=True, allow_metas
=returns_meta
)
733 def check_event(expr
, info
):
735 boxed
= expr
.get('boxed', False)
739 meta
+= ['union', 'alternate']
740 check_type(info
, "'data' for event '%s'" % name
,
741 expr
.get('data'), allow_dict
=not boxed
, allow_optional
=True,
745 def enum_get_names(expr
):
746 return [e
['name'] for e
in expr
['data']]
749 def check_union(expr
, info
):
751 base
= expr
.get('base')
752 discriminator
= expr
.get('discriminator')
753 members
= expr
['data']
755 # Two types of unions, determined by discriminator.
757 # With no discriminator it is a simple union.
758 if discriminator
is None:
760 allow_metas
= ['built-in', 'union', 'alternate', 'struct', 'enum']
762 raise QAPISemError(info
, "Simple union '%s' must not have a base" %
765 # Else, it's a flat union.
767 # The object must have a string or dictionary 'base'.
768 check_type(info
, "'base' for union '%s'" % name
,
769 base
, allow_dict
=True, allow_optional
=True,
770 allow_metas
=['struct'])
772 raise QAPISemError(info
, "Flat union '%s' must have a base"
774 base_members
= find_base_members(base
)
775 assert base_members
is not None
777 # The value of member 'discriminator' must name a non-optional
778 # member of the base struct.
779 check_name(info
, "Discriminator of flat union '%s'" % name
,
781 discriminator_value
= base_members
.get(discriminator
)
782 if not discriminator_value
:
783 raise QAPISemError(info
,
784 "Discriminator '%s' is not a member of base "
786 % (discriminator
, base
))
787 enum_define
= enum_types
.get(discriminator_value
['type'])
788 allow_metas
= ['struct']
789 # Do not allow string discriminator
791 raise QAPISemError(info
,
792 "Discriminator '%s' must be of enumeration "
793 "type" % discriminator
)
795 # Check every branch; don't allow an empty union
796 if len(members
) == 0:
797 raise QAPISemError(info
, "Union '%s' cannot have empty 'data'" % name
)
798 for (key
, value
) in members
.items():
799 check_name(info
, "Member of union '%s'" % name
, key
)
801 check_known_keys(info
, "member '%s' of union '%s'" % (key
, name
),
803 # Each value must name a known type
804 check_type(info
, "Member '%s' of union '%s'" % (key
, name
),
806 allow_array
=not base
, allow_metas
=allow_metas
)
808 # If the discriminator names an enum type, then all members
809 # of 'data' must also be members of the enum type.
811 if key
not in enum_get_names(enum_define
):
812 raise QAPISemError(info
,
813 "Discriminator value '%s' is not found in "
815 % (key
, enum_define
['enum']))
818 def check_alternate(expr
, info
):
819 name
= expr
['alternate']
820 members
= expr
['data']
823 # Check every branch; require at least two branches
825 raise QAPISemError(info
,
826 "Alternate '%s' should have at least two branches "
828 for (key
, value
) in members
.items():
829 check_name(info
, "Member of alternate '%s'" % name
, key
)
830 check_known_keys(info
,
831 "member '%s' of alternate '%s'" % (key
, name
),
835 # Ensure alternates have no type conflicts.
836 check_type(info
, "Member '%s' of alternate '%s'" % (key
, name
), typ
,
837 allow_metas
=['built-in', 'union', 'struct', 'enum'])
838 qtype
= find_alternate_member_qtype(typ
)
840 raise QAPISemError(info
, "Alternate '%s' member '%s' cannot use "
841 "type '%s'" % (name
, key
, typ
))
842 conflicting
= set([qtype
])
843 if qtype
== 'QTYPE_QSTRING':
844 enum_expr
= enum_types
.get(typ
)
846 for v
in enum_get_names(enum_expr
):
847 if v
in ['on', 'off']:
848 conflicting
.add('QTYPE_QBOOL')
849 if re
.match(r
'[-+0-9.]', v
): # lazy, could be tightened
850 conflicting
.add('QTYPE_QNUM')
852 conflicting
.add('QTYPE_QNUM')
853 conflicting
.add('QTYPE_QBOOL')
854 for qt
in conflicting
:
856 raise QAPISemError(info
, "Alternate '%s' member '%s' can't "
857 "be distinguished from member '%s'"
858 % (name
, key
, types_seen
[qt
]))
862 def check_enum(expr
, info
):
864 members
= expr
['data']
865 prefix
= expr
.get('prefix')
867 if not isinstance(members
, list):
868 raise QAPISemError(info
,
869 "Enum '%s' requires an array for 'data'" % name
)
870 if prefix
is not None and not isinstance(prefix
, str):
871 raise QAPISemError(info
,
872 "Enum '%s' requires a string for 'prefix'" % name
)
874 for member
in members
:
875 source
= "dictionary member of enum '%s'" % name
876 check_known_keys(info
, source
, member
, ['name'], ['if'])
877 check_if(member
, info
)
878 check_name(info
, "Member of enum '%s'" % name
, member
['name'],
882 def check_struct(expr
, info
):
883 name
= expr
['struct']
884 members
= expr
['data']
886 check_type(info
, "'data' for struct '%s'" % name
, members
,
887 allow_dict
=True, allow_optional
=True)
888 check_type(info
, "'base' for struct '%s'" % name
, expr
.get('base'),
889 allow_metas
=['struct'])
892 def check_known_keys(info
, source
, keys
, required
, optional
):
895 return ', '.join("'" + e
+ "'" for e
in sorted(elems
))
897 missing
= set(required
) - set(keys
)
899 raise QAPISemError(info
, "Key%s %s %s missing from %s"
900 % ('s' if len(missing
) > 1 else '', pprint(missing
),
901 'are' if len(missing
) > 1 else 'is', source
))
902 allowed
= set(required
+ optional
)
903 unknown
= set(keys
) - allowed
905 raise QAPISemError(info
, "Unknown key%s %s in %s\nValid keys are %s."
906 % ('s' if len(unknown
) > 1 else '', pprint(unknown
),
907 source
, pprint(allowed
)))
910 def check_keys(expr_elem
, meta
, required
, optional
=[]):
911 expr
= expr_elem
['expr']
912 info
= expr_elem
['info']
914 if not isinstance(name
, str):
915 raise QAPISemError(info
, "'%s' key must have a string value" % meta
)
916 required
= required
+ [meta
]
917 source
= "%s '%s'" % (meta
, name
)
918 check_known_keys(info
, source
, expr
.keys(), required
, optional
)
919 for (key
, value
) in expr
.items():
920 if key
in ['gen', 'success-response'] and value
is not False:
921 raise QAPISemError(info
,
922 "'%s' of %s '%s' should only use false value"
924 if (key
in ['boxed', 'allow-oob', 'allow-preconfig']
925 and value
is not True):
926 raise QAPISemError(info
,
927 "'%s' of %s '%s' should only use true value"
933 def normalize_enum(expr
):
934 if isinstance(expr
['data'], list):
935 expr
['data'] = [m
if isinstance(m
, dict) else {'name': m
}
936 for m
in expr
['data']]
939 def normalize_members(members
):
940 if isinstance(members
, OrderedDict
):
941 for key
, arg
in members
.items():
942 if isinstance(arg
, dict):
944 members
[key
] = {'type': arg
}
947 def check_exprs(exprs
):
950 # Populate name table with names of built-in types
951 for builtin
in builtin_types
.keys():
952 all_names
[builtin
] = 'built-in'
954 # Learn the types and check for valid expression keys
955 for expr_elem
in exprs
:
956 expr
= expr_elem
['expr']
957 info
= expr_elem
['info']
958 doc
= expr_elem
.get('doc')
960 if 'include' in expr
:
963 if not doc
and doc_required
:
964 raise QAPISemError(info
,
965 "Expression missing documentation comment")
969 check_keys(expr_elem
, 'enum', ['data'], ['if', 'prefix'])
971 enum_types
[expr
[meta
]] = expr
972 elif 'union' in expr
:
974 check_keys(expr_elem
, 'union', ['data'],
975 ['base', 'discriminator', 'if'])
976 normalize_members(expr
.get('base'))
977 normalize_members(expr
['data'])
978 union_types
[expr
[meta
]] = expr
979 elif 'alternate' in expr
:
981 check_keys(expr_elem
, 'alternate', ['data'], ['if'])
982 normalize_members(expr
['data'])
983 elif 'struct' in expr
:
985 check_keys(expr_elem
, 'struct', ['data'], ['base', 'if'])
986 normalize_members(expr
['data'])
987 struct_types
[expr
[meta
]] = expr
988 elif 'command' in expr
:
990 check_keys(expr_elem
, 'command', [],
991 ['data', 'returns', 'gen', 'success-response',
992 'boxed', 'allow-oob', 'allow-preconfig', 'if'])
993 normalize_members(expr
.get('data'))
994 elif 'event' in expr
:
996 check_keys(expr_elem
, 'event', [], ['data', 'boxed', 'if'])
997 normalize_members(expr
.get('data'))
999 raise QAPISemError(expr_elem
['info'],
1000 "Expression is missing metatype")
1002 add_name(name
, info
, meta
)
1003 if doc
and doc
.symbol
!= name
:
1004 raise QAPISemError(info
, "Definition of '%s' follows documentation"
1005 " for '%s'" % (name
, doc
.symbol
))
1007 # Try again for hidden UnionKind enum
1008 for expr_elem
in exprs
:
1009 expr
= expr_elem
['expr']
1011 if 'include' in expr
:
1013 if 'union' in expr
and not discriminator_find_enum_define(expr
):
1014 name
= '%sKind' % expr
['union']
1015 elif 'alternate' in expr
:
1016 name
= '%sKind' % expr
['alternate']
1019 enum_types
[name
] = {'enum': name
}
1020 add_name(name
, info
, 'enum', implicit
=True)
1022 # Validate that exprs make sense
1023 for expr_elem
in exprs
:
1024 expr
= expr_elem
['expr']
1025 info
= expr_elem
['info']
1026 doc
= expr_elem
.get('doc')
1028 if 'include' in expr
:
1031 check_enum(expr
, info
)
1032 elif 'union' in expr
:
1033 check_union(expr
, info
)
1034 elif 'alternate' in expr
:
1035 check_alternate(expr
, info
)
1036 elif 'struct' in expr
:
1037 check_struct(expr
, info
)
1038 elif 'command' in expr
:
1039 check_command(expr
, info
)
1040 elif 'event' in expr
:
1041 check_event(expr
, info
)
1043 assert False, 'unexpected meta type'
1046 doc
.check_expr(expr
)
1052 # Schema compiler frontend
1055 def listify_cond(ifcond
):
1058 if not isinstance(ifcond
, list):
1063 class QAPISchemaEntity(object):
1064 def __init__(self
, name
, info
, doc
, ifcond
=None):
1065 assert name
is None or isinstance(name
, str)
1068 # For explicitly defined entities, info points to the (explicit)
1069 # definition. For builtins (and their arrays), info is None.
1070 # For implicitly defined entities, info points to a place that
1071 # triggered the implicit definition (there may be more than one
1075 self
._ifcond
= ifcond
# self.ifcond is set only after .check()
1078 return c_name(self
.name
)
1080 def check(self
, schema
):
1081 if isinstance(self
._ifcond
, QAPISchemaType
):
1082 # inherit the condition from a type
1085 self
.ifcond
= typ
.ifcond
1087 self
.ifcond
= listify_cond(self
._ifcond
)
1089 def is_implicit(self
):
1090 return not self
.info
1092 def visit(self
, visitor
):
1096 class QAPISchemaVisitor(object):
1097 def visit_begin(self
, schema
):
1100 def visit_end(self
):
1103 def visit_module(self
, fname
):
1106 def visit_needed(self
, entity
):
1107 # Default to visiting everything
1110 def visit_include(self
, fname
, info
):
1113 def visit_builtin_type(self
, name
, info
, json_type
):
1116 def visit_enum_type(self
, name
, info
, ifcond
, members
, prefix
):
1119 def visit_array_type(self
, name
, info
, ifcond
, element_type
):
1122 def visit_object_type(self
, name
, info
, ifcond
, base
, members
, variants
):
1125 def visit_object_type_flat(self
, name
, info
, ifcond
, members
, variants
):
1128 def visit_alternate_type(self
, name
, info
, ifcond
, variants
):
1131 def visit_command(self
, name
, info
, ifcond
, arg_type
, ret_type
, gen
,
1132 success_response
, boxed
, allow_oob
, allow_preconfig
):
1135 def visit_event(self
, name
, info
, ifcond
, arg_type
, boxed
):
1139 class QAPISchemaInclude(QAPISchemaEntity
):
1141 def __init__(self
, fname
, info
):
1142 QAPISchemaEntity
.__init
__(self
, None, info
, None)
1145 def visit(self
, visitor
):
1146 visitor
.visit_include(self
.fname
, self
.info
)
1149 class QAPISchemaType(QAPISchemaEntity
):
1150 # Return the C type for common use.
1151 # For the types we commonly box, this is a pointer type.
1155 # Return the C type to be used in a parameter list.
1156 def c_param_type(self
):
1157 return self
.c_type()
1159 # Return the C type to be used where we suppress boxing.
1160 def c_unboxed_type(self
):
1161 return self
.c_type()
1163 def json_type(self
):
1166 def alternate_qtype(self
):
1168 'null': 'QTYPE_QNULL',
1169 'string': 'QTYPE_QSTRING',
1170 'number': 'QTYPE_QNUM',
1171 'int': 'QTYPE_QNUM',
1172 'boolean': 'QTYPE_QBOOL',
1173 'object': 'QTYPE_QDICT'
1175 return json2qtype
.get(self
.json_type())
1178 if self
.is_implicit():
1183 class QAPISchemaBuiltinType(QAPISchemaType
):
1184 def __init__(self
, name
, json_type
, c_type
):
1185 QAPISchemaType
.__init
__(self
, name
, None, None)
1186 assert not c_type
or isinstance(c_type
, str)
1187 assert json_type
in ('string', 'number', 'int', 'boolean', 'null',
1189 self
._json
_type
_name
= json_type
1190 self
._c
_type
_name
= c_type
1196 return self
._c
_type
_name
1198 def c_param_type(self
):
1199 if self
.name
== 'str':
1200 return 'const ' + self
._c
_type
_name
1201 return self
._c
_type
_name
1203 def json_type(self
):
1204 return self
._json
_type
_name
1207 return self
.json_type()
1209 def visit(self
, visitor
):
1210 visitor
.visit_builtin_type(self
.name
, self
.info
, self
.json_type())
1213 class QAPISchemaEnumType(QAPISchemaType
):
1214 def __init__(self
, name
, info
, doc
, ifcond
, members
, prefix
):
1215 QAPISchemaType
.__init
__(self
, name
, info
, doc
, ifcond
)
1217 assert isinstance(m
, QAPISchemaMember
)
1219 assert prefix
is None or isinstance(prefix
, str)
1220 self
.members
= members
1221 self
.prefix
= prefix
1223 def check(self
, schema
):
1224 QAPISchemaType
.check(self
, schema
)
1226 for m
in self
.members
:
1227 m
.check_clash(self
.info
, seen
)
1229 self
.doc
.connect_member(m
)
1231 def is_implicit(self
):
1232 # See QAPISchema._make_implicit_enum_type() and ._def_predefineds()
1233 return self
.name
.endswith('Kind') or self
.name
== 'QType'
1236 return c_name(self
.name
)
1238 def member_names(self
):
1239 return [m
.name
for m
in self
.members
]
1241 def json_type(self
):
1244 def visit(self
, visitor
):
1245 visitor
.visit_enum_type(self
.name
, self
.info
, self
.ifcond
,
1246 self
.members
, self
.prefix
)
1249 class QAPISchemaArrayType(QAPISchemaType
):
1250 def __init__(self
, name
, info
, element_type
):
1251 QAPISchemaType
.__init
__(self
, name
, info
, None, None)
1252 assert isinstance(element_type
, str)
1253 self
._element
_type
_name
= element_type
1254 self
.element_type
= None
1256 def check(self
, schema
):
1257 QAPISchemaType
.check(self
, schema
)
1258 self
.element_type
= schema
.lookup_type(self
._element
_type
_name
)
1259 assert self
.element_type
1260 self
.element_type
.check(schema
)
1261 self
.ifcond
= self
.element_type
.ifcond
1263 def is_implicit(self
):
1267 return c_name(self
.name
) + pointer_suffix
1269 def json_type(self
):
1273 elt_doc_type
= self
.element_type
.doc_type()
1274 if not elt_doc_type
:
1276 return 'array of ' + elt_doc_type
1278 def visit(self
, visitor
):
1279 visitor
.visit_array_type(self
.name
, self
.info
, self
.ifcond
,
1283 class QAPISchemaObjectType(QAPISchemaType
):
1284 def __init__(self
, name
, info
, doc
, ifcond
,
1285 base
, local_members
, variants
):
1286 # struct has local_members, optional base, and no variants
1287 # flat union has base, variants, and no local_members
1288 # simple union has local_members, variants, and no base
1289 QAPISchemaType
.__init
__(self
, name
, info
, doc
, ifcond
)
1290 assert base
is None or isinstance(base
, str)
1291 for m
in local_members
:
1292 assert isinstance(m
, QAPISchemaObjectTypeMember
)
1294 if variants
is not None:
1295 assert isinstance(variants
, QAPISchemaObjectTypeVariants
)
1296 variants
.set_owner(name
)
1297 self
._base
_name
= base
1299 self
.local_members
= local_members
1300 self
.variants
= variants
1303 def check(self
, schema
):
1304 QAPISchemaType
.check(self
, schema
)
1305 if self
.members
is False: # check for cycles
1306 raise QAPISemError(self
.info
,
1307 "Object %s contains itself" % self
.name
)
1310 self
.members
= False # mark as being checked
1311 seen
= OrderedDict()
1313 self
.base
= schema
.lookup_type(self
._base
_name
)
1314 assert isinstance(self
.base
, QAPISchemaObjectType
)
1315 self
.base
.check(schema
)
1316 self
.base
.check_clash(self
.info
, seen
)
1317 for m
in self
.local_members
:
1319 m
.check_clash(self
.info
, seen
)
1321 self
.doc
.connect_member(m
)
1322 self
.members
= seen
.values()
1324 self
.variants
.check(schema
, seen
)
1325 assert self
.variants
.tag_member
in self
.members
1326 self
.variants
.check_clash(self
.info
, seen
)
1330 # Check that the members of this type do not cause duplicate JSON members,
1331 # and update seen to track the members seen so far. Report any errors
1332 # on behalf of info, which is not necessarily self.info
1333 def check_clash(self
, info
, seen
):
1334 assert not self
.variants
# not implemented
1335 for m
in self
.members
:
1336 m
.check_clash(info
, seen
)
1338 def is_implicit(self
):
1339 # See QAPISchema._make_implicit_object_type(), as well as
1340 # _def_predefineds()
1341 return self
.name
.startswith('q_')
1344 assert self
.members
is not None
1345 return not self
.members
and not self
.variants
1348 assert self
.name
!= 'q_empty'
1349 return QAPISchemaType
.c_name(self
)
1352 assert not self
.is_implicit()
1353 return c_name(self
.name
) + pointer_suffix
1355 def c_unboxed_type(self
):
1356 return c_name(self
.name
)
1358 def json_type(self
):
1361 def visit(self
, visitor
):
1362 visitor
.visit_object_type(self
.name
, self
.info
, self
.ifcond
,
1363 self
.base
, self
.local_members
, self
.variants
)
1364 visitor
.visit_object_type_flat(self
.name
, self
.info
, self
.ifcond
,
1365 self
.members
, self
.variants
)
1368 class QAPISchemaMember(object):
1371 def __init__(self
, name
, ifcond
=None):
1372 assert isinstance(name
, str)
1374 self
.ifcond
= listify_cond(ifcond
)
1377 def set_owner(self
, name
):
1378 assert not self
.owner
1381 def check_clash(self
, info
, seen
):
1382 cname
= c_name(self
.name
)
1383 if cname
.lower() != cname
and self
.owner
not in name_case_whitelist
:
1384 raise QAPISemError(info
,
1385 "%s should not use uppercase" % self
.describe())
1387 raise QAPISemError(info
, "%s collides with %s" %
1388 (self
.describe(), seen
[cname
].describe()))
1391 def _pretty_owner(self
):
1393 if owner
.startswith('q_obj_'):
1394 # See QAPISchema._make_implicit_object_type() - reverse the
1395 # mapping there to create a nice human-readable description
1397 if owner
.endswith('-arg'):
1398 return '(parameter of %s)' % owner
[:-4]
1399 elif owner
.endswith('-base'):
1400 return '(base of %s)' % owner
[:-5]
1402 assert owner
.endswith('-wrapper')
1403 # Unreachable and not implemented
1405 if owner
.endswith('Kind'):
1406 # See QAPISchema._make_implicit_enum_type()
1407 return '(branch of %s)' % owner
[:-4]
1408 return '(%s of %s)' % (self
.role
, owner
)
1411 return "'%s' %s" % (self
.name
, self
._pretty
_owner
())
1414 class QAPISchemaObjectTypeMember(QAPISchemaMember
):
1415 def __init__(self
, name
, typ
, optional
):
1416 QAPISchemaMember
.__init
__(self
, name
)
1417 assert isinstance(typ
, str)
1418 assert isinstance(optional
, bool)
1419 self
._type
_name
= typ
1421 self
.optional
= optional
1423 def check(self
, schema
):
1425 self
.type = schema
.lookup_type(self
._type
_name
)
1429 class QAPISchemaObjectTypeVariants(object):
1430 def __init__(self
, tag_name
, tag_member
, variants
):
1431 # Flat unions pass tag_name but not tag_member.
1432 # Simple unions and alternates pass tag_member but not tag_name.
1433 # After check(), tag_member is always set, and tag_name remains
1434 # a reliable witness of being used by a flat union.
1435 assert bool(tag_member
) != bool(tag_name
)
1436 assert (isinstance(tag_name
, str) or
1437 isinstance(tag_member
, QAPISchemaObjectTypeMember
))
1438 assert len(variants
) > 0
1440 assert isinstance(v
, QAPISchemaObjectTypeVariant
)
1441 self
._tag
_name
= tag_name
1442 self
.tag_member
= tag_member
1443 self
.variants
= variants
1445 def set_owner(self
, name
):
1446 for v
in self
.variants
:
1449 def check(self
, schema
, seen
):
1450 if not self
.tag_member
: # flat union
1451 self
.tag_member
= seen
[c_name(self
._tag
_name
)]
1452 assert self
._tag
_name
== self
.tag_member
.name
1453 assert isinstance(self
.tag_member
.type, QAPISchemaEnumType
)
1454 if self
._tag
_name
: # flat union
1455 # branches that are not explicitly covered get an empty type
1456 cases
= set([v
.name
for v
in self
.variants
])
1457 for m
in self
.tag_member
.type.members
:
1458 if m
.name
not in cases
:
1459 v
= QAPISchemaObjectTypeVariant(m
.name
, 'q_empty')
1460 v
.set_owner(self
.tag_member
.owner
)
1461 self
.variants
.append(v
)
1462 for v
in self
.variants
:
1464 # Union names must match enum values; alternate names are
1465 # checked separately. Use 'seen' to tell the two apart.
1467 assert v
.name
in self
.tag_member
.type.member_names()
1468 assert isinstance(v
.type, QAPISchemaObjectType
)
1469 v
.type.check(schema
)
1471 def check_clash(self
, info
, seen
):
1472 for v
in self
.variants
:
1473 # Reset seen map for each variant, since qapi names from one
1474 # branch do not affect another branch
1475 assert isinstance(v
.type, QAPISchemaObjectType
)
1476 v
.type.check_clash(info
, dict(seen
))
1479 class QAPISchemaObjectTypeVariant(QAPISchemaObjectTypeMember
):
1482 def __init__(self
, name
, typ
):
1483 QAPISchemaObjectTypeMember
.__init
__(self
, name
, typ
, False)
1486 class QAPISchemaAlternateType(QAPISchemaType
):
1487 def __init__(self
, name
, info
, doc
, ifcond
, variants
):
1488 QAPISchemaType
.__init
__(self
, name
, info
, doc
, ifcond
)
1489 assert isinstance(variants
, QAPISchemaObjectTypeVariants
)
1490 assert variants
.tag_member
1491 variants
.set_owner(name
)
1492 variants
.tag_member
.set_owner(self
.name
)
1493 self
.variants
= variants
1495 def check(self
, schema
):
1496 QAPISchemaType
.check(self
, schema
)
1497 self
.variants
.tag_member
.check(schema
)
1498 # Not calling self.variants.check_clash(), because there's nothing
1500 self
.variants
.check(schema
, {})
1501 # Alternate branch names have no relation to the tag enum values;
1502 # so we have to check for potential name collisions ourselves.
1504 for v
in self
.variants
.variants
:
1505 v
.check_clash(self
.info
, seen
)
1507 self
.doc
.connect_member(v
)
1512 return c_name(self
.name
) + pointer_suffix
1514 def json_type(self
):
1517 def visit(self
, visitor
):
1518 visitor
.visit_alternate_type(self
.name
, self
.info
, self
.ifcond
,
1525 class QAPISchemaCommand(QAPISchemaEntity
):
1526 def __init__(self
, name
, info
, doc
, ifcond
, arg_type
, ret_type
,
1527 gen
, success_response
, boxed
, allow_oob
, allow_preconfig
):
1528 QAPISchemaEntity
.__init
__(self
, name
, info
, doc
, ifcond
)
1529 assert not arg_type
or isinstance(arg_type
, str)
1530 assert not ret_type
or isinstance(ret_type
, str)
1531 self
._arg
_type
_name
= arg_type
1532 self
.arg_type
= None
1533 self
._ret
_type
_name
= ret_type
1534 self
.ret_type
= None
1536 self
.success_response
= success_response
1538 self
.allow_oob
= allow_oob
1539 self
.allow_preconfig
= allow_preconfig
1541 def check(self
, schema
):
1542 QAPISchemaEntity
.check(self
, schema
)
1543 if self
._arg
_type
_name
:
1544 self
.arg_type
= schema
.lookup_type(self
._arg
_type
_name
)
1545 assert (isinstance(self
.arg_type
, QAPISchemaObjectType
) or
1546 isinstance(self
.arg_type
, QAPISchemaAlternateType
))
1547 self
.arg_type
.check(schema
)
1549 if self
.arg_type
.is_empty():
1550 raise QAPISemError(self
.info
,
1551 "Cannot use 'boxed' with empty type")
1553 assert not isinstance(self
.arg_type
, QAPISchemaAlternateType
)
1554 assert not self
.arg_type
.variants
1556 raise QAPISemError(self
.info
, "Use of 'boxed' requires 'data'")
1557 if self
._ret
_type
_name
:
1558 self
.ret_type
= schema
.lookup_type(self
._ret
_type
_name
)
1559 assert isinstance(self
.ret_type
, QAPISchemaType
)
1561 def visit(self
, visitor
):
1562 visitor
.visit_command(self
.name
, self
.info
, self
.ifcond
,
1563 self
.arg_type
, self
.ret_type
,
1564 self
.gen
, self
.success_response
,
1565 self
.boxed
, self
.allow_oob
,
1566 self
.allow_preconfig
)
1569 class QAPISchemaEvent(QAPISchemaEntity
):
1570 def __init__(self
, name
, info
, doc
, ifcond
, arg_type
, boxed
):
1571 QAPISchemaEntity
.__init
__(self
, name
, info
, doc
, ifcond
)
1572 assert not arg_type
or isinstance(arg_type
, str)
1573 self
._arg
_type
_name
= arg_type
1574 self
.arg_type
= None
1577 def check(self
, schema
):
1578 QAPISchemaEntity
.check(self
, schema
)
1579 if self
._arg
_type
_name
:
1580 self
.arg_type
= schema
.lookup_type(self
._arg
_type
_name
)
1581 assert (isinstance(self
.arg_type
, QAPISchemaObjectType
) or
1582 isinstance(self
.arg_type
, QAPISchemaAlternateType
))
1583 self
.arg_type
.check(schema
)
1585 if self
.arg_type
.is_empty():
1586 raise QAPISemError(self
.info
,
1587 "Cannot use 'boxed' with empty type")
1589 assert not isinstance(self
.arg_type
, QAPISchemaAlternateType
)
1590 assert not self
.arg_type
.variants
1592 raise QAPISemError(self
.info
, "Use of 'boxed' requires 'data'")
1594 def visit(self
, visitor
):
1595 visitor
.visit_event(self
.name
, self
.info
, self
.ifcond
,
1596 self
.arg_type
, self
.boxed
)
1599 class QAPISchema(object):
1600 def __init__(self
, fname
):
1602 if sys
.version_info
[0] >= 3:
1603 f
= open(fname
, 'r', encoding
='utf-8')
1605 f
= open(fname
, 'r')
1606 parser
= QAPISchemaParser(f
)
1607 exprs
= check_exprs(parser
.exprs
)
1608 self
.docs
= parser
.docs
1609 self
._entity
_list
= []
1610 self
._entity
_dict
= {}
1611 self
._predefining
= True
1612 self
._def
_predefineds
()
1613 self
._predefining
= False
1614 self
._def
_exprs
(exprs
)
1617 def _def_entity(self
, ent
):
1618 # Only the predefined types are allowed to not have info
1619 assert ent
.info
or self
._predefining
1620 assert ent
.name
is None or ent
.name
not in self
._entity
_dict
1621 self
._entity
_list
.append(ent
)
1622 if ent
.name
is not None:
1623 self
._entity
_dict
[ent
.name
] = ent
1625 ent
.module
= os
.path
.relpath(ent
.info
['file'],
1626 os
.path
.dirname(self
._fname
))
1628 def lookup_entity(self
, name
, typ
=None):
1629 ent
= self
._entity
_dict
.get(name
)
1630 if typ
and not isinstance(ent
, typ
):
1634 def lookup_type(self
, name
):
1635 return self
.lookup_entity(name
, QAPISchemaType
)
1637 def _def_include(self
, expr
, info
, doc
):
1638 include
= expr
['include']
1641 while main_info
['parent']:
1642 main_info
= main_info
['parent']
1643 fname
= os
.path
.relpath(include
, os
.path
.dirname(main_info
['file']))
1644 self
._def
_entity
(QAPISchemaInclude(fname
, info
))
1646 def _def_builtin_type(self
, name
, json_type
, c_type
):
1647 self
._def
_entity
(QAPISchemaBuiltinType(name
, json_type
, c_type
))
1648 # Instantiating only the arrays that are actually used would
1649 # be nice, but we can't as long as their generated code
1650 # (qapi-builtin-types.[ch]) may be shared by some other
1652 self
._make
_array
_type
(name
, None)
1654 def _def_predefineds(self
):
1655 for t
in [('str', 'string', 'char' + pointer_suffix
),
1656 ('number', 'number', 'double'),
1657 ('int', 'int', 'int64_t'),
1658 ('int8', 'int', 'int8_t'),
1659 ('int16', 'int', 'int16_t'),
1660 ('int32', 'int', 'int32_t'),
1661 ('int64', 'int', 'int64_t'),
1662 ('uint8', 'int', 'uint8_t'),
1663 ('uint16', 'int', 'uint16_t'),
1664 ('uint32', 'int', 'uint32_t'),
1665 ('uint64', 'int', 'uint64_t'),
1666 ('size', 'int', 'uint64_t'),
1667 ('bool', 'boolean', 'bool'),
1668 ('any', 'value', 'QObject' + pointer_suffix
),
1669 ('null', 'null', 'QNull' + pointer_suffix
)]:
1670 self
._def
_builtin
_type
(*t
)
1671 self
.the_empty_object_type
= QAPISchemaObjectType(
1672 'q_empty', None, None, None, None, [], None)
1673 self
._def
_entity
(self
.the_empty_object_type
)
1675 qtypes
= ['none', 'qnull', 'qnum', 'qstring', 'qdict', 'qlist',
1677 qtype_values
= self
._make
_enum
_members
([{'name': n
} for n
in qtypes
])
1679 self
._def
_entity
(QAPISchemaEnumType('QType', None, None, None,
1680 qtype_values
, 'QTYPE'))
1682 def _make_enum_members(self
, values
):
1683 return [QAPISchemaMember(v
['name'], v
.get('if')) for v
in values
]
1685 def _make_implicit_enum_type(self
, name
, info
, ifcond
, values
):
1686 # See also QAPISchemaObjectTypeMember._pretty_owner()
1687 name
= name
+ 'Kind' # Use namespace reserved by add_name()
1688 self
._def
_entity
(QAPISchemaEnumType(
1689 name
, info
, None, ifcond
, self
._make
_enum
_members
(values
), None))
1692 def _make_array_type(self
, element_type
, info
):
1693 name
= element_type
+ 'List' # Use namespace reserved by add_name()
1694 if not self
.lookup_type(name
):
1695 self
._def
_entity
(QAPISchemaArrayType(name
, info
, element_type
))
1698 def _make_implicit_object_type(self
, name
, info
, doc
, ifcond
,
1702 # See also QAPISchemaObjectTypeMember._pretty_owner()
1703 name
= 'q_obj_%s-%s' % (name
, role
)
1704 typ
= self
.lookup_entity(name
, QAPISchemaObjectType
)
1706 # The implicit object type has multiple users. This can
1707 # happen only for simple unions' implicit wrapper types.
1708 # Its ifcond should be the disjunction of its user's
1709 # ifconds. Not implemented. Instead, we always pass the
1710 # wrapped type's ifcond, which is trivially the same for all
1711 # users. It's also necessary for the wrapper to compile.
1712 # But it's not tight: the disjunction need not imply it. We
1713 # may end up compiling useless wrapper types.
1714 # TODO kill simple unions or implement the disjunction
1715 assert ifcond
== typ
._ifcond
# pylint: disable=protected-access
1717 self
._def
_entity
(QAPISchemaObjectType(name
, info
, doc
, ifcond
,
1718 None, members
, None))
1721 def _def_enum_type(self
, expr
, info
, doc
):
1724 prefix
= expr
.get('prefix')
1725 ifcond
= expr
.get('if')
1726 self
._def
_entity
(QAPISchemaEnumType(
1727 name
, info
, doc
, ifcond
,
1728 self
._make
_enum
_members
(data
), prefix
))
1730 def _make_member(self
, name
, typ
, info
):
1732 if name
.startswith('*'):
1735 if isinstance(typ
, list):
1736 assert len(typ
) == 1
1737 typ
= self
._make
_array
_type
(typ
[0], info
)
1738 return QAPISchemaObjectTypeMember(name
, typ
, optional
)
1740 def _make_members(self
, data
, info
):
1741 return [self
._make
_member
(key
, value
['type'], info
)
1742 for (key
, value
) in data
.items()]
1744 def _def_struct_type(self
, expr
, info
, doc
):
1745 name
= expr
['struct']
1746 base
= expr
.get('base')
1748 ifcond
= expr
.get('if')
1749 self
._def
_entity
(QAPISchemaObjectType(name
, info
, doc
, ifcond
, base
,
1750 self
._make
_members
(data
, info
),
1753 def _make_variant(self
, case
, typ
):
1754 return QAPISchemaObjectTypeVariant(case
, typ
)
1756 def _make_simple_variant(self
, case
, typ
, info
):
1757 if isinstance(typ
, list):
1758 assert len(typ
) == 1
1759 typ
= self
._make
_array
_type
(typ
[0], info
)
1760 typ
= self
._make
_implicit
_object
_type
(
1761 typ
, info
, None, self
.lookup_type(typ
),
1762 'wrapper', [self
._make
_member
('data', typ
, info
)])
1763 return QAPISchemaObjectTypeVariant(case
, typ
)
1765 def _def_union_type(self
, expr
, info
, doc
):
1766 name
= expr
['union']
1768 base
= expr
.get('base')
1769 ifcond
= expr
.get('if')
1770 tag_name
= expr
.get('discriminator')
1772 if isinstance(base
, dict):
1773 base
= self
._make
_implicit
_object
_type
(
1774 name
, info
, doc
, ifcond
,
1775 'base', self
._make
_members
(base
, info
))
1777 variants
= [self
._make
_variant
(key
, value
['type'])
1778 for (key
, value
) in data
.items()]
1781 variants
= [self
._make
_simple
_variant
(key
, value
['type'], info
)
1782 for (key
, value
) in data
.items()]
1783 enum
= [{'name': v
.name
} for v
in variants
]
1784 typ
= self
._make
_implicit
_enum
_type
(name
, info
, ifcond
, enum
)
1785 tag_member
= QAPISchemaObjectTypeMember('type', typ
, False)
1786 members
= [tag_member
]
1788 QAPISchemaObjectType(name
, info
, doc
, ifcond
, base
, members
,
1789 QAPISchemaObjectTypeVariants(tag_name
,
1793 def _def_alternate_type(self
, expr
, info
, doc
):
1794 name
= expr
['alternate']
1796 ifcond
= expr
.get('if')
1797 variants
= [self
._make
_variant
(key
, value
['type'])
1798 for (key
, value
) in data
.items()]
1799 tag_member
= QAPISchemaObjectTypeMember('type', 'QType', False)
1801 QAPISchemaAlternateType(name
, info
, doc
, ifcond
,
1802 QAPISchemaObjectTypeVariants(None,
1806 def _def_command(self
, expr
, info
, doc
):
1807 name
= expr
['command']
1808 data
= expr
.get('data')
1809 rets
= expr
.get('returns')
1810 gen
= expr
.get('gen', True)
1811 success_response
= expr
.get('success-response', True)
1812 boxed
= expr
.get('boxed', False)
1813 allow_oob
= expr
.get('allow-oob', False)
1814 allow_preconfig
= expr
.get('allow-preconfig', False)
1815 ifcond
= expr
.get('if')
1816 if isinstance(data
, OrderedDict
):
1817 data
= self
._make
_implicit
_object
_type
(
1818 name
, info
, doc
, ifcond
, 'arg', self
._make
_members
(data
, info
))
1819 if isinstance(rets
, list):
1820 assert len(rets
) == 1
1821 rets
= self
._make
_array
_type
(rets
[0], info
)
1822 self
._def
_entity
(QAPISchemaCommand(name
, info
, doc
, ifcond
, data
, rets
,
1823 gen
, success_response
,
1824 boxed
, allow_oob
, allow_preconfig
))
1826 def _def_event(self
, expr
, info
, doc
):
1827 name
= expr
['event']
1828 data
= expr
.get('data')
1829 boxed
= expr
.get('boxed', False)
1830 ifcond
= expr
.get('if')
1831 if isinstance(data
, OrderedDict
):
1832 data
= self
._make
_implicit
_object
_type
(
1833 name
, info
, doc
, ifcond
, 'arg', self
._make
_members
(data
, info
))
1834 self
._def
_entity
(QAPISchemaEvent(name
, info
, doc
, ifcond
, data
, boxed
))
1836 def _def_exprs(self
, exprs
):
1837 for expr_elem
in exprs
:
1838 expr
= expr_elem
['expr']
1839 info
= expr_elem
['info']
1840 doc
= expr_elem
.get('doc')
1842 self
._def
_enum
_type
(expr
, info
, doc
)
1843 elif 'struct' in expr
:
1844 self
._def
_struct
_type
(expr
, info
, doc
)
1845 elif 'union' in expr
:
1846 self
._def
_union
_type
(expr
, info
, doc
)
1847 elif 'alternate' in expr
:
1848 self
._def
_alternate
_type
(expr
, info
, doc
)
1849 elif 'command' in expr
:
1850 self
._def
_command
(expr
, info
, doc
)
1851 elif 'event' in expr
:
1852 self
._def
_event
(expr
, info
, doc
)
1853 elif 'include' in expr
:
1854 self
._def
_include
(expr
, info
, doc
)
1859 for ent
in self
._entity
_list
:
1862 def visit(self
, visitor
):
1863 visitor
.visit_begin(self
)
1865 for entity
in self
._entity
_list
:
1866 if visitor
.visit_needed(entity
):
1867 if entity
.module
!= module
:
1868 module
= entity
.module
1869 visitor
.visit_module(module
)
1870 entity
.visit(visitor
)
1875 # Code generation helpers
1878 def camel_case(name
):
1882 if ch
in ['_', '-']:
1885 new_name
+= ch
.upper()
1888 new_name
+= ch
.lower()
1892 # ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1
1893 # ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2
1894 # ENUM24_Name -> ENUM24_NAME
1895 def camel_to_upper(value
):
1896 c_fun_str
= c_name(value
, False)
1901 length
= len(c_fun_str
)
1902 for i
in range(length
):
1904 # When c is upper and no '_' appears before, do more checks
1905 if c
.isupper() and (i
> 0) and c_fun_str
[i
- 1] != '_':
1906 if i
< length
- 1 and c_fun_str
[i
+ 1].islower():
1908 elif c_fun_str
[i
- 1].isdigit():
1911 return new_name
.lstrip('_').upper()
1914 def c_enum_const(type_name
, const_name
, prefix
=None):
1915 if prefix
is not None:
1917 return camel_to_upper(type_name
) + '_' + c_name(const_name
, False).upper()
1920 if hasattr(str, 'maketrans'):
1921 c_name_trans
= str.maketrans('.-', '__')
1923 c_name_trans
= string
.maketrans('.-', '__')
1926 # Map @name to a valid C identifier.
1927 # If @protect, avoid returning certain ticklish identifiers (like
1928 # C keywords) by prepending 'q_'.
1930 # Used for converting 'name' from a 'name':'type' qapi definition
1931 # into a generated struct member, as well as converting type names
1932 # into substrings of a generated C function name.
1933 # '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
1934 # protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'
1935 def c_name(name
, protect
=True):
1936 # ANSI X3J11/88-090, 3.1.1
1937 c89_words
= set(['auto', 'break', 'case', 'char', 'const', 'continue',
1938 'default', 'do', 'double', 'else', 'enum', 'extern',
1939 'float', 'for', 'goto', 'if', 'int', 'long', 'register',
1940 'return', 'short', 'signed', 'sizeof', 'static',
1941 'struct', 'switch', 'typedef', 'union', 'unsigned',
1942 'void', 'volatile', 'while'])
1943 # ISO/IEC 9899:1999, 6.4.1
1944 c99_words
= set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary'])
1945 # ISO/IEC 9899:2011, 6.4.1
1946 c11_words
= set(['_Alignas', '_Alignof', '_Atomic', '_Generic',
1947 '_Noreturn', '_Static_assert', '_Thread_local'])
1948 # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html
1950 gcc_words
= set(['asm', 'typeof'])
1951 # C++ ISO/IEC 14882:2003 2.11
1952 cpp_words
= set(['bool', 'catch', 'class', 'const_cast', 'delete',
1953 'dynamic_cast', 'explicit', 'false', 'friend', 'mutable',
1954 'namespace', 'new', 'operator', 'private', 'protected',
1955 'public', 'reinterpret_cast', 'static_cast', 'template',
1956 'this', 'throw', 'true', 'try', 'typeid', 'typename',
1957 'using', 'virtual', 'wchar_t',
1958 # alternative representations
1959 'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not',
1960 'not_eq', 'or', 'or_eq', 'xor', 'xor_eq'])
1961 # namespace pollution:
1962 polluted_words
= set(['unix', 'errno', 'mips', 'sparc', 'i386'])
1963 name
= name
.translate(c_name_trans
)
1964 if protect
and (name
in c89_words | c99_words | c11_words | gcc_words
1965 | cpp_words | polluted_words
):
1970 eatspace
= '\033EATSPACE.'
1971 pointer_suffix
= ' *' + eatspace
1974 def genindent(count
):
1976 for _
in range(count
):
1984 def push_indent(indent_amount
=4):
1986 indent_level
+= indent_amount
1989 def pop_indent(indent_amount
=4):
1991 indent_level
-= indent_amount
1994 # Generate @code with @kwds interpolated.
1995 # Obey indent_level, and strip eatspace.
1996 def cgen(code
, **kwds
):
1999 indent
= genindent(indent_level
)
2000 # re.subn() lacks flags support before Python 2.7, use re.compile()
2001 raw
= re
.subn(re
.compile(r
'^(?!(#|$))', re
.MULTILINE
),
2004 return re
.sub(re
.escape(eatspace
) + r
' *', '', raw
)
2007 def mcgen(code
, **kwds
):
2010 return cgen(code
, **kwds
)
2013 def guardname(filename
):
2014 return re
.sub(r
'[^A-Za-z0-9_]', '_', filename
).upper()
2017 def guardstart(name
):
2023 name
=guardname(name
))
2029 #endif /* %(name)s */
2031 name
=guardname(name
))
2043 def gen_endif(ifcond
):
2045 for ifc
in reversed(ifcond
):
2047 #endif /* %(cond)s */
2052 def _wrap_ifcond(ifcond
, before
, after
):
2054 return after
# suppress empty #if ... #endif
2056 assert after
.startswith(before
)
2058 added
= after
[len(before
):]
2059 if added
[0] == '\n':
2062 out
+= gen_if(ifcond
)
2064 out
+= gen_endif(ifcond
)
2068 def gen_enum_lookup(name
, members
, prefix
=None):
2071 const QEnumLookup %(c_name)s_lookup = {
2072 .array = (const char *const[]) {
2074 c_name
=c_name(name
))
2076 index
= c_enum_const(name
, m
.name
, prefix
)
2078 [%(index)s] = "%(name)s",
2080 index
=index
, name
=m
.name
)
2084 .size = %(max_index)s
2087 max_index
=c_enum_const(name
, '_MAX', prefix
))
2091 def gen_enum(name
, members
, prefix
=None):
2092 # append automatically generated _MAX value
2093 enum_members
= members
+ [QAPISchemaMember('_MAX')]
2097 typedef enum %(c_name)s {
2099 c_name
=c_name(name
))
2101 for m
in enum_members
:
2105 c_enum
=c_enum_const(name
, m
.name
, prefix
))
2110 c_name
=c_name(name
))
2114 #define %(c_name)s_str(val) \\
2115 qapi_enum_lookup(&%(c_name)s_lookup, (val))
2117 extern const QEnumLookup %(c_name)s_lookup;
2119 c_name
=c_name(name
))
2123 def build_params(arg_type
, boxed
, extra
=None):
2128 ret
+= '%s arg' % arg_type
.c_param_type()
2131 assert not arg_type
.variants
2132 for memb
in arg_type
.members
:
2136 ret
+= 'bool has_%s, ' % c_name(memb
.name
)
2137 ret
+= '%s %s' % (memb
.type.c_param_type(),
2141 return ret
if ret
else 'void'
2145 # Accumulate and write output
2148 class QAPIGen(object):
2154 def preamble_add(self
, text
):
2155 self
._preamble
+= text
2157 def add(self
, text
):
2160 def get_content(self
, fname
=None):
2161 return (self
._top
(fname
) + self
._preamble
+ self
._body
2162 + self
._bottom
(fname
))
2164 def _top(self
, fname
):
2167 def _bottom(self
, fname
):
2170 def write(self
, output_dir
, fname
):
2171 pathname
= os
.path
.join(output_dir
, fname
)
2172 dir = os
.path
.dirname(pathname
)
2176 except os
.error
as e
:
2177 if e
.errno
!= errno
.EEXIST
:
2179 fd
= os
.open(pathname
, os
.O_RDWR | os
.O_CREAT
, 0o666)
2180 if sys
.version_info
[0] >= 3:
2181 f
= open(fd
, 'r+', encoding
='utf-8')
2183 f
= os
.fdopen(fd
, 'r+')
2184 text
= self
.get_content(fname
)
2185 oldtext
= f
.read(len(text
) + 1)
2194 def ifcontext(ifcond
, *args
):
2195 """A 'with' statement context manager to wrap with start_if()/end_if()
2197 *args: any number of QAPIGenCCode
2201 with ifcontext(ifcond, self._genh, self._genc):
2202 modify self._genh and self._genc ...
2204 Is equivalent to calling::
2206 self._genh.start_if(ifcond)
2207 self._genc.start_if(ifcond)
2208 modify self._genh and self._genc ...
2213 arg
.start_if(ifcond
)
2219 class QAPIGenCCode(QAPIGen
):
2222 QAPIGen
.__init
__(self
)
2223 self
._start
_if
= None
2225 def start_if(self
, ifcond
):
2226 assert self
._start
_if
is None
2227 self
._start
_if
= (ifcond
, self
._body
, self
._preamble
)
2230 assert self
._start
_if
2232 self
._start
_if
= None
2234 def _wrap_ifcond(self
):
2235 self
._body
= _wrap_ifcond(self
._start
_if
[0],
2236 self
._start
_if
[1], self
._body
)
2237 self
._preamble
= _wrap_ifcond(self
._start
_if
[0],
2238 self
._start
_if
[2], self
._preamble
)
2240 def get_content(self
, fname
=None):
2241 assert self
._start
_if
is None
2242 return QAPIGen
.get_content(self
, fname
)
2245 class QAPIGenC(QAPIGenCCode
):
2247 def __init__(self
, blurb
, pydoc
):
2248 QAPIGenCCode
.__init
__(self
)
2250 self
._copyright
= '\n * '.join(re
.findall(r
'^Copyright .*', pydoc
,
2253 def _top(self
, fname
):
2255 /* AUTOMATICALLY GENERATED, DO NOT MODIFY */
2262 * This work is licensed under the terms of the GNU LGPL, version 2.1 or later.
2263 * See the COPYING.LIB file in the top-level directory.
2267 blurb
=self
._blurb
, copyright
=self
._copyright
)
2269 def _bottom(self
, fname
):
2272 /* Dummy declaration to prevent empty .o file */
2273 char dummy_%(name)s;
2278 class QAPIGenH(QAPIGenC
):
2280 def _top(self
, fname
):
2281 return QAPIGenC
._top
(self
, fname
) + guardstart(fname
)
2283 def _bottom(self
, fname
):
2284 return guardend(fname
)
2287 class QAPIGenDoc(QAPIGen
):
2289 def _top(self
, fname
):
2290 return (QAPIGen
._top
(self
, fname
)
2291 + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n')
2294 class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor
):
2296 def __init__(self
, prefix
, what
, blurb
, pydoc
):
2297 self
._prefix
= prefix
2299 self
._genc
= QAPIGenC(blurb
, pydoc
)
2300 self
._genh
= QAPIGenH(blurb
, pydoc
)
2302 def write(self
, output_dir
):
2303 self
._genc
.write(output_dir
, self
._prefix
+ self
._what
+ '.c')
2304 self
._genh
.write(output_dir
, self
._prefix
+ self
._what
+ '.h')
2307 class QAPISchemaModularCVisitor(QAPISchemaVisitor
):
2309 def __init__(self
, prefix
, what
, blurb
, pydoc
):
2310 self
._prefix
= prefix
2315 self
._main
_module
= None
2317 def _module_basename(self
, what
, name
):
2319 return re
.sub(r
'-', '-builtin-', what
)
2320 basename
= os
.path
.join(os
.path
.dirname(name
),
2321 self
._prefix
+ what
)
2322 if name
== self
._main
_module
:
2324 return basename
+ '-' + os
.path
.splitext(os
.path
.basename(name
))[0]
2326 def _add_module(self
, name
, blurb
):
2327 if self
._main
_module
is None and name
is not None:
2328 self
._main
_module
= name
2329 genc
= QAPIGenC(blurb
, self
._pydoc
)
2330 genh
= QAPIGenH(blurb
, self
._pydoc
)
2331 self
._module
[name
] = (genc
, genh
)
2332 self
._set
_module
(name
)
2334 def _set_module(self
, name
):
2335 self
._genc
, self
._genh
= self
._module
[name
]
2337 def write(self
, output_dir
, opt_builtins
=False):
2338 for name
in self
._module
:
2339 if name
is None and not opt_builtins
:
2341 basename
= self
._module
_basename
(self
._what
, name
)
2342 (genc
, genh
) = self
._module
[name
]
2343 genc
.write(output_dir
, basename
+ '.c')
2344 genh
.write(output_dir
, basename
+ '.h')
2346 def _begin_module(self
, name
):
2349 def visit_module(self
, name
):
2350 if name
in self
._module
:
2351 self
._set
_module
(name
)
2353 self
._add
_module
(name
, self
._blurb
)
2354 self
._begin
_module
(name
)
2356 def visit_include(self
, name
, info
):
2357 basename
= self
._module
_basename
(self
._what
, name
)
2358 self
._genh
.preamble_add(mcgen('''
2359 #include "%(basename)s.h"