1# 2# QAPI helper library 3# 4# Copyright IBM, Corp. 2011 5# Copyright (c) 2013-2018 Red Hat Inc. 6# 7# Authors: 8# Anthony Liguori <aliguori@us.ibm.com> 9# Markus Armbruster <armbru@redhat.com> 10# 11# This work is licensed under the terms of the GNU GPL, version 2. 12# See the COPYING file in the top-level directory. 13 14from __future__ import print_function 15import errno 16import os 17import re 18import string 19try: 20 from collections import OrderedDict 21except: 22 from ordereddict import OrderedDict 23 24builtin_types = { 25 'null': 'QTYPE_QNULL', 26 'str': 'QTYPE_QSTRING', 27 'int': 'QTYPE_QNUM', 28 'number': 'QTYPE_QNUM', 29 'bool': 'QTYPE_QBOOL', 30 'int8': 'QTYPE_QNUM', 31 'int16': 'QTYPE_QNUM', 32 'int32': 'QTYPE_QNUM', 33 'int64': 'QTYPE_QNUM', 34 'uint8': 'QTYPE_QNUM', 35 'uint16': 'QTYPE_QNUM', 36 'uint32': 'QTYPE_QNUM', 37 'uint64': 'QTYPE_QNUM', 38 'size': 'QTYPE_QNUM', 39 'any': None, # any QType possible, actually 40 'QType': 'QTYPE_QSTRING', 41} 42 43# Are documentation comments required? 44doc_required = False 45 46# Whitelist of commands allowed to return a non-dictionary 47returns_whitelist = [] 48 49# Whitelist of entities allowed to violate case conventions 50name_case_whitelist = [] 51 52enum_types = {} 53struct_types = {} 54union_types = {} 55all_names = {} 56 57# 58# Parsing the schema into expressions 59# 60 61 62def error_path(parent): 63 res = '' 64 while parent: 65 res = ('In file included from %s:%d:\n' % (parent['file'], 66 parent['line'])) + res 67 parent = parent['parent'] 68 return res 69 70 71class QAPIError(Exception): 72 def __init__(self, fname, line, col, incl_info, msg): 73 Exception.__init__(self) 74 self.fname = fname 75 self.line = line 76 self.col = col 77 self.info = incl_info 78 self.msg = msg 79 80 def __str__(self): 81 loc = '%s:%d' % (self.fname, self.line) 82 if self.col is not None: 83 loc += ':%s' % self.col 84 return error_path(self.info) + '%s: %s' % (loc, self.msg) 85 86 87class QAPIParseError(QAPIError): 88 def __init__(self, parser, msg): 89 col = 1 90 for ch in parser.src[parser.line_pos:parser.pos]: 91 if ch == '\t': 92 col = (col + 7) % 8 + 1 93 else: 94 col += 1 95 QAPIError.__init__(self, parser.fname, parser.line, col, 96 parser.incl_info, msg) 97 98 99class QAPISemError(QAPIError): 100 def __init__(self, info, msg): 101 QAPIError.__init__(self, info['file'], info['line'], None, 102 info['parent'], msg) 103 104 105class QAPIDoc(object): 106 class Section(object): 107 def __init__(self, name=None): 108 # optional section name (argument/member or section name) 109 self.name = name 110 # the list of lines for this section 111 self.text = '' 112 113 def append(self, line): 114 self.text += line.rstrip() + '\n' 115 116 class ArgSection(Section): 117 def __init__(self, name): 118 QAPIDoc.Section.__init__(self, name) 119 self.member = None 120 121 def connect(self, member): 122 self.member = member 123 124 def __init__(self, parser, info): 125 # self._parser is used to report errors with QAPIParseError. The 126 # resulting error position depends on the state of the parser. 127 # It happens to be the beginning of the comment. More or less 128 # servicable, but action at a distance. 129 self._parser = parser 130 self.info = info 131 self.symbol = None 132 self.body = QAPIDoc.Section() 133 # dict mapping parameter name to ArgSection 134 self.args = OrderedDict() 135 # a list of Section 136 self.sections = [] 137 # the current section 138 self._section = self.body 139 140 def has_section(self, name): 141 """Return True if we have a section with this name.""" 142 for i in self.sections: 143 if i.name == name: 144 return True 145 return False 146 147 def append(self, line): 148 """Parse a comment line and add it to the documentation.""" 149 line = line[1:] 150 if not line: 151 self._append_freeform(line) 152 return 153 154 if line[0] != ' ': 155 raise QAPIParseError(self._parser, "Missing space after #") 156 line = line[1:] 157 158 # FIXME not nice: things like '# @foo:' and '# @foo: ' aren't 159 # recognized, and get silently treated as ordinary text 160 if self.symbol: 161 self._append_symbol_line(line) 162 elif not self.body.text and line.startswith('@'): 163 if not line.endswith(':'): 164 raise QAPIParseError(self._parser, "Line should end with :") 165 self.symbol = line[1:-1] 166 # FIXME invalid names other than the empty string aren't flagged 167 if not self.symbol: 168 raise QAPIParseError(self._parser, "Invalid name") 169 else: 170 self._append_freeform(line) 171 172 def end_comment(self): 173 self._end_section() 174 175 def _append_symbol_line(self, line): 176 name = line.split(' ', 1)[0] 177 178 if name.startswith('@') and name.endswith(':'): 179 line = line[len(name)+1:] 180 self._start_args_section(name[1:-1]) 181 elif name in ('Returns:', 'Since:', 182 # those are often singular or plural 183 'Note:', 'Notes:', 184 'Example:', 'Examples:', 185 'TODO:'): 186 line = line[len(name)+1:] 187 self._start_section(name[:-1]) 188 189 self._append_freeform(line) 190 191 def _start_args_section(self, name): 192 # FIXME invalid names other than the empty string aren't flagged 193 if not name: 194 raise QAPIParseError(self._parser, "Invalid parameter name") 195 if name in self.args: 196 raise QAPIParseError(self._parser, 197 "'%s' parameter name duplicated" % name) 198 if self.sections: 199 raise QAPIParseError(self._parser, 200 "'@%s:' can't follow '%s' section" 201 % (name, self.sections[0].name)) 202 self._end_section() 203 self._section = QAPIDoc.ArgSection(name) 204 self.args[name] = self._section 205 206 def _start_section(self, name=None): 207 if name in ('Returns', 'Since') and self.has_section(name): 208 raise QAPIParseError(self._parser, 209 "Duplicated '%s' section" % name) 210 self._end_section() 211 self._section = QAPIDoc.Section(name) 212 self.sections.append(self._section) 213 214 def _end_section(self): 215 if self._section: 216 text = self._section.text = self._section.text.strip() 217 if self._section.name and (not text or text.isspace()): 218 raise QAPIParseError(self._parser, "Empty doc section '%s'" 219 % self._section.name) 220 self._section = None 221 222 def _append_freeform(self, line): 223 in_arg = isinstance(self._section, QAPIDoc.ArgSection) 224 if (in_arg and self._section.text.endswith('\n\n') 225 and line and not line[0].isspace()): 226 self._start_section() 227 if (in_arg or not self._section.name 228 or not self._section.name.startswith('Example')): 229 line = line.strip() 230 match = re.match(r'(@\S+:)', line) 231 if match: 232 raise QAPIParseError(self._parser, 233 "'%s' not allowed in free-form documentation" 234 % match.group(1)) 235 self._section.append(line) 236 237 def connect_member(self, member): 238 if member.name not in self.args: 239 # Undocumented TODO outlaw 240 self.args[member.name] = QAPIDoc.ArgSection(member.name) 241 self.args[member.name].connect(member) 242 243 def check_expr(self, expr): 244 if self.has_section('Returns') and 'command' not in expr: 245 raise QAPISemError(self.info, 246 "'Returns:' is only valid for commands") 247 248 def check(self): 249 bogus = [name for name, section in self.args.items() 250 if not section.member] 251 if bogus: 252 raise QAPISemError( 253 self.info, 254 "The following documented members are not in " 255 "the declaration: %s" % ", ".join(bogus)) 256 257 258class QAPISchemaParser(object): 259 260 def __init__(self, fp, previously_included=[], incl_info=None): 261 self.fname = fp.name 262 previously_included.append(os.path.abspath(fp.name)) 263 self.incl_info = incl_info 264 self.src = fp.read() 265 if self.src == '' or self.src[-1] != '\n': 266 self.src += '\n' 267 self.cursor = 0 268 self.line = 1 269 self.line_pos = 0 270 self.exprs = [] 271 self.docs = [] 272 self.accept() 273 cur_doc = None 274 275 while self.tok is not None: 276 info = {'file': self.fname, 'line': self.line, 277 'parent': self.incl_info} 278 if self.tok == '#': 279 self.reject_expr_doc(cur_doc) 280 cur_doc = self.get_doc(info) 281 self.docs.append(cur_doc) 282 continue 283 284 expr = self.get_expr(False) 285 if 'include' in expr: 286 self.reject_expr_doc(cur_doc) 287 if len(expr) != 1: 288 raise QAPISemError(info, "Invalid 'include' directive") 289 include = expr['include'] 290 if not isinstance(include, str): 291 raise QAPISemError(info, 292 "Value of 'include' must be a string") 293 incl_fname = os.path.join(os.path.dirname(self.fname), 294 include) 295 self.exprs.append({'expr': {'include': incl_fname}, 296 'info': info}) 297 exprs_include = self._include(include, info, incl_fname, 298 previously_included) 299 if exprs_include: 300 self.exprs.extend(exprs_include.exprs) 301 self.docs.extend(exprs_include.docs) 302 elif "pragma" in expr: 303 self.reject_expr_doc(cur_doc) 304 if len(expr) != 1: 305 raise QAPISemError(info, "Invalid 'pragma' directive") 306 pragma = expr['pragma'] 307 if not isinstance(pragma, dict): 308 raise QAPISemError( 309 info, "Value of 'pragma' must be a dictionary") 310 for name, value in pragma.items(): 311 self._pragma(name, value, info) 312 else: 313 expr_elem = {'expr': expr, 314 'info': info} 315 if cur_doc: 316 if not cur_doc.symbol: 317 raise QAPISemError( 318 cur_doc.info, "Expression documentation required") 319 expr_elem['doc'] = cur_doc 320 self.exprs.append(expr_elem) 321 cur_doc = None 322 self.reject_expr_doc(cur_doc) 323 324 @staticmethod 325 def reject_expr_doc(doc): 326 if doc and doc.symbol: 327 raise QAPISemError( 328 doc.info, 329 "Documentation for '%s' is not followed by the definition" 330 % doc.symbol) 331 332 def _include(self, include, info, incl_fname, previously_included): 333 incl_abs_fname = os.path.abspath(incl_fname) 334 # catch inclusion cycle 335 inf = info 336 while inf: 337 if incl_abs_fname == os.path.abspath(inf['file']): 338 raise QAPISemError(info, "Inclusion loop for %s" % include) 339 inf = inf['parent'] 340 341 # skip multiple include of the same file 342 if incl_abs_fname in previously_included: 343 return None 344 345 try: 346 fobj = open(incl_fname, 'r') 347 except IOError as e: 348 raise QAPISemError(info, '%s: %s' % (e.strerror, incl_fname)) 349 return QAPISchemaParser(fobj, previously_included, info) 350 351 def _pragma(self, name, value, info): 352 global doc_required, returns_whitelist, name_case_whitelist 353 if name == 'doc-required': 354 if not isinstance(value, bool): 355 raise QAPISemError(info, 356 "Pragma 'doc-required' must be boolean") 357 doc_required = value 358 elif name == 'returns-whitelist': 359 if (not isinstance(value, list) 360 or any([not isinstance(elt, str) for elt in value])): 361 raise QAPISemError(info, 362 "Pragma returns-whitelist must be" 363 " a list of strings") 364 returns_whitelist = value 365 elif name == 'name-case-whitelist': 366 if (not isinstance(value, list) 367 or any([not isinstance(elt, str) for elt in value])): 368 raise QAPISemError(info, 369 "Pragma name-case-whitelist must be" 370 " a list of strings") 371 name_case_whitelist = value 372 else: 373 raise QAPISemError(info, "Unknown pragma '%s'" % name) 374 375 def accept(self, skip_comment=True): 376 while True: 377 self.tok = self.src[self.cursor] 378 self.pos = self.cursor 379 self.cursor += 1 380 self.val = None 381 382 if self.tok == '#': 383 if self.src[self.cursor] == '#': 384 # Start of doc comment 385 skip_comment = False 386 self.cursor = self.src.find('\n', self.cursor) 387 if not skip_comment: 388 self.val = self.src[self.pos:self.cursor] 389 return 390 elif self.tok in '{}:,[]': 391 return 392 elif self.tok == "'": 393 string = '' 394 esc = False 395 while True: 396 ch = self.src[self.cursor] 397 self.cursor += 1 398 if ch == '\n': 399 raise QAPIParseError(self, 'Missing terminating "\'"') 400 if esc: 401 if ch == 'b': 402 string += '\b' 403 elif ch == 'f': 404 string += '\f' 405 elif ch == 'n': 406 string += '\n' 407 elif ch == 'r': 408 string += '\r' 409 elif ch == 't': 410 string += '\t' 411 elif ch == 'u': 412 value = 0 413 for _ in range(0, 4): 414 ch = self.src[self.cursor] 415 self.cursor += 1 416 if ch not in '0123456789abcdefABCDEF': 417 raise QAPIParseError(self, 418 '\\u escape needs 4 ' 419 'hex digits') 420 value = (value << 4) + int(ch, 16) 421 # If Python 2 and 3 didn't disagree so much on 422 # how to handle Unicode, then we could allow 423 # Unicode string defaults. But most of QAPI is 424 # ASCII-only, so we aren't losing much for now. 425 if not value or value > 0x7f: 426 raise QAPIParseError(self, 427 'For now, \\u escape ' 428 'only supports non-zero ' 429 'values up to \\u007f') 430 string += chr(value) 431 elif ch in '\\/\'"': 432 string += ch 433 else: 434 raise QAPIParseError(self, 435 "Unknown escape \\%s" % ch) 436 esc = False 437 elif ch == '\\': 438 esc = True 439 elif ch == "'": 440 self.val = string 441 return 442 else: 443 string += ch 444 elif self.src.startswith('true', self.pos): 445 self.val = True 446 self.cursor += 3 447 return 448 elif self.src.startswith('false', self.pos): 449 self.val = False 450 self.cursor += 4 451 return 452 elif self.src.startswith('null', self.pos): 453 self.val = None 454 self.cursor += 3 455 return 456 elif self.tok == '\n': 457 if self.cursor == len(self.src): 458 self.tok = None 459 return 460 self.line += 1 461 self.line_pos = self.cursor 462 elif not self.tok.isspace(): 463 raise QAPIParseError(self, 'Stray "%s"' % self.tok) 464 465 def get_members(self): 466 expr = OrderedDict() 467 if self.tok == '}': 468 self.accept() 469 return expr 470 if self.tok != "'": 471 raise QAPIParseError(self, 'Expected string or "}"') 472 while True: 473 key = self.val 474 self.accept() 475 if self.tok != ':': 476 raise QAPIParseError(self, 'Expected ":"') 477 self.accept() 478 if key in expr: 479 raise QAPIParseError(self, 'Duplicate key "%s"' % key) 480 expr[key] = self.get_expr(True) 481 if self.tok == '}': 482 self.accept() 483 return expr 484 if self.tok != ',': 485 raise QAPIParseError(self, 'Expected "," or "}"') 486 self.accept() 487 if self.tok != "'": 488 raise QAPIParseError(self, 'Expected string') 489 490 def get_values(self): 491 expr = [] 492 if self.tok == ']': 493 self.accept() 494 return expr 495 if self.tok not in "{['tfn": 496 raise QAPIParseError(self, 'Expected "{", "[", "]", string, ' 497 'boolean or "null"') 498 while True: 499 expr.append(self.get_expr(True)) 500 if self.tok == ']': 501 self.accept() 502 return expr 503 if self.tok != ',': 504 raise QAPIParseError(self, 'Expected "," or "]"') 505 self.accept() 506 507 def get_expr(self, nested): 508 if self.tok != '{' and not nested: 509 raise QAPIParseError(self, 'Expected "{"') 510 if self.tok == '{': 511 self.accept() 512 expr = self.get_members() 513 elif self.tok == '[': 514 self.accept() 515 expr = self.get_values() 516 elif self.tok in "'tfn": 517 expr = self.val 518 self.accept() 519 else: 520 raise QAPIParseError(self, 'Expected "{", "[", string, ' 521 'boolean or "null"') 522 return expr 523 524 def get_doc(self, info): 525 if self.val != '##': 526 raise QAPIParseError(self, "Junk after '##' at start of " 527 "documentation comment") 528 529 doc = QAPIDoc(self, info) 530 self.accept(False) 531 while self.tok == '#': 532 if self.val.startswith('##'): 533 # End of doc comment 534 if self.val != '##': 535 raise QAPIParseError(self, "Junk after '##' at end of " 536 "documentation comment") 537 doc.end_comment() 538 self.accept() 539 return doc 540 else: 541 doc.append(self.val) 542 self.accept(False) 543 544 raise QAPIParseError(self, "Documentation comment must end with '##'") 545 546 547# 548# Semantic analysis of schema expressions 549# TODO fold into QAPISchema 550# TODO catching name collisions in generated code would be nice 551# 552 553 554def find_base_members(base): 555 if isinstance(base, dict): 556 return base 557 base_struct_define = struct_types.get(base) 558 if not base_struct_define: 559 return None 560 return base_struct_define['data'] 561 562 563# Return the qtype of an alternate branch, or None on error. 564def find_alternate_member_qtype(qapi_type): 565 if qapi_type in builtin_types: 566 return builtin_types[qapi_type] 567 elif qapi_type in struct_types: 568 return 'QTYPE_QDICT' 569 elif qapi_type in enum_types: 570 return 'QTYPE_QSTRING' 571 elif qapi_type in union_types: 572 return 'QTYPE_QDICT' 573 return None 574 575 576# Return the discriminator enum define if discriminator is specified as an 577# enum type, otherwise return None. 578def discriminator_find_enum_define(expr): 579 base = expr.get('base') 580 discriminator = expr.get('discriminator') 581 582 if not (discriminator and base): 583 return None 584 585 base_members = find_base_members(base) 586 if not base_members: 587 return None 588 589 discriminator_type = base_members.get(discriminator) 590 if not discriminator_type: 591 return None 592 593 return enum_types.get(discriminator_type) 594 595 596# Names must be letters, numbers, -, and _. They must start with letter, 597# except for downstream extensions which must start with __RFQDN_. 598# Dots are only valid in the downstream extension prefix. 599valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?' 600 '[a-zA-Z][a-zA-Z0-9_-]*$') 601 602 603def check_name(info, source, name, allow_optional=False, 604 enum_member=False): 605 global valid_name 606 membername = name 607 608 if not isinstance(name, str): 609 raise QAPISemError(info, "%s requires a string name" % source) 610 if name.startswith('*'): 611 membername = name[1:] 612 if not allow_optional: 613 raise QAPISemError(info, "%s does not allow optional name '%s'" 614 % (source, name)) 615 # Enum members can start with a digit, because the generated C 616 # code always prefixes it with the enum name 617 if enum_member and membername[0].isdigit(): 618 membername = 'D' + membername 619 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty' 620 # and 'q_obj_*' implicit type names. 621 if not valid_name.match(membername) or \ 622 c_name(membername, False).startswith('q_'): 623 raise QAPISemError(info, "%s uses invalid name '%s'" % (source, name)) 624 625 626def add_name(name, info, meta, implicit=False): 627 global all_names 628 check_name(info, "'%s'" % meta, name) 629 # FIXME should reject names that differ only in '_' vs. '.' 630 # vs. '-', because they're liable to clash in generated C. 631 if name in all_names: 632 raise QAPISemError(info, "%s '%s' is already defined" 633 % (all_names[name], name)) 634 if not implicit and (name.endswith('Kind') or name.endswith('List')): 635 raise QAPISemError(info, "%s '%s' should not end in '%s'" 636 % (meta, name, name[-4:])) 637 all_names[name] = meta 638 639 640def check_type(info, source, value, allow_array=False, 641 allow_dict=False, allow_optional=False, 642 allow_metas=[]): 643 global all_names 644 645 if value is None: 646 return 647 648 # Check if array type for value is okay 649 if isinstance(value, list): 650 if not allow_array: 651 raise QAPISemError(info, "%s cannot be an array" % source) 652 if len(value) != 1 or not isinstance(value[0], str): 653 raise QAPISemError(info, 654 "%s: array type must contain single type name" % 655 source) 656 value = value[0] 657 658 # Check if type name for value is okay 659 if isinstance(value, str): 660 if value not in all_names: 661 raise QAPISemError(info, "%s uses unknown type '%s'" 662 % (source, value)) 663 if not all_names[value] in allow_metas: 664 raise QAPISemError(info, "%s cannot use %s type '%s'" % 665 (source, all_names[value], value)) 666 return 667 668 if not allow_dict: 669 raise QAPISemError(info, "%s should be a type name" % source) 670 671 if not isinstance(value, OrderedDict): 672 raise QAPISemError(info, 673 "%s should be a dictionary or type name" % source) 674 675 # value is a dictionary, check that each member is okay 676 for (key, arg) in value.items(): 677 check_name(info, "Member of %s" % source, key, 678 allow_optional=allow_optional) 679 if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'): 680 raise QAPISemError(info, "Member of %s uses reserved name '%s'" 681 % (source, key)) 682 # Todo: allow dictionaries to represent default values of 683 # an optional argument. 684 check_type(info, "Member '%s' of %s" % (key, source), arg, 685 allow_array=True, 686 allow_metas=['built-in', 'union', 'alternate', 'struct', 687 'enum']) 688 689 690def check_command(expr, info): 691 name = expr['command'] 692 boxed = expr.get('boxed', False) 693 694 args_meta = ['struct'] 695 if boxed: 696 args_meta += ['union', 'alternate'] 697 check_type(info, "'data' for command '%s'" % name, 698 expr.get('data'), allow_dict=not boxed, allow_optional=True, 699 allow_metas=args_meta) 700 returns_meta = ['union', 'struct'] 701 if name in returns_whitelist: 702 returns_meta += ['built-in', 'alternate', 'enum'] 703 check_type(info, "'returns' for command '%s'" % name, 704 expr.get('returns'), allow_array=True, 705 allow_optional=True, allow_metas=returns_meta) 706 707 708def check_event(expr, info): 709 name = expr['event'] 710 boxed = expr.get('boxed', False) 711 712 meta = ['struct'] 713 if boxed: 714 meta += ['union', 'alternate'] 715 check_type(info, "'data' for event '%s'" % name, 716 expr.get('data'), allow_dict=not boxed, allow_optional=True, 717 allow_metas=meta) 718 719 720def check_union(expr, info): 721 name = expr['union'] 722 base = expr.get('base') 723 discriminator = expr.get('discriminator') 724 members = expr['data'] 725 726 # Two types of unions, determined by discriminator. 727 728 # With no discriminator it is a simple union. 729 if discriminator is None: 730 enum_define = None 731 allow_metas = ['built-in', 'union', 'alternate', 'struct', 'enum'] 732 if base is not None: 733 raise QAPISemError(info, "Simple union '%s' must not have a base" % 734 name) 735 736 # Else, it's a flat union. 737 else: 738 # The object must have a string or dictionary 'base'. 739 check_type(info, "'base' for union '%s'" % name, 740 base, allow_dict=True, allow_optional=True, 741 allow_metas=['struct']) 742 if not base: 743 raise QAPISemError(info, "Flat union '%s' must have a base" 744 % name) 745 base_members = find_base_members(base) 746 assert base_members is not None 747 748 # The value of member 'discriminator' must name a non-optional 749 # member of the base struct. 750 check_name(info, "Discriminator of flat union '%s'" % name, 751 discriminator) 752 discriminator_type = base_members.get(discriminator) 753 if not discriminator_type: 754 raise QAPISemError(info, 755 "Discriminator '%s' is not a member of base " 756 "struct '%s'" 757 % (discriminator, base)) 758 enum_define = enum_types.get(discriminator_type) 759 allow_metas = ['struct'] 760 # Do not allow string discriminator 761 if not enum_define: 762 raise QAPISemError(info, 763 "Discriminator '%s' must be of enumeration " 764 "type" % discriminator) 765 766 # Check every branch; don't allow an empty union 767 if len(members) == 0: 768 raise QAPISemError(info, "Union '%s' cannot have empty 'data'" % name) 769 for (key, value) in members.items(): 770 check_name(info, "Member of union '%s'" % name, key) 771 772 # Each value must name a known type 773 check_type(info, "Member '%s' of union '%s'" % (key, name), 774 value, allow_array=not base, allow_metas=allow_metas) 775 776 # If the discriminator names an enum type, then all members 777 # of 'data' must also be members of the enum type. 778 if enum_define: 779 if key not in enum_define['data']: 780 raise QAPISemError(info, 781 "Discriminator value '%s' is not found in " 782 "enum '%s'" 783 % (key, enum_define['enum'])) 784 785 # If discriminator is user-defined, ensure all values are covered 786 if enum_define: 787 for value in enum_define['data']: 788 if value not in members.keys(): 789 raise QAPISemError(info, "Union '%s' data missing '%s' branch" 790 % (name, value)) 791 792 793def check_alternate(expr, info): 794 name = expr['alternate'] 795 members = expr['data'] 796 types_seen = {} 797 798 # Check every branch; require at least two branches 799 if len(members) < 2: 800 raise QAPISemError(info, 801 "Alternate '%s' should have at least two branches " 802 "in 'data'" % name) 803 for (key, value) in members.items(): 804 check_name(info, "Member of alternate '%s'" % name, key) 805 806 # Ensure alternates have no type conflicts. 807 check_type(info, "Member '%s' of alternate '%s'" % (key, name), 808 value, 809 allow_metas=['built-in', 'union', 'struct', 'enum']) 810 qtype = find_alternate_member_qtype(value) 811 if not qtype: 812 raise QAPISemError(info, "Alternate '%s' member '%s' cannot use " 813 "type '%s'" % (name, key, value)) 814 conflicting = set([qtype]) 815 if qtype == 'QTYPE_QSTRING': 816 enum_expr = enum_types.get(value) 817 if enum_expr: 818 for v in enum_expr['data']: 819 if v in ['on', 'off']: 820 conflicting.add('QTYPE_QBOOL') 821 if re.match(r'[-+0-9.]', v): # lazy, could be tightened 822 conflicting.add('QTYPE_QNUM') 823 else: 824 conflicting.add('QTYPE_QNUM') 825 conflicting.add('QTYPE_QBOOL') 826 for qt in conflicting: 827 if qt in types_seen: 828 raise QAPISemError(info, "Alternate '%s' member '%s' can't " 829 "be distinguished from member '%s'" 830 % (name, key, types_seen[qt])) 831 types_seen[qt] = key 832 833 834def check_enum(expr, info): 835 name = expr['enum'] 836 members = expr.get('data') 837 prefix = expr.get('prefix') 838 839 if not isinstance(members, list): 840 raise QAPISemError(info, 841 "Enum '%s' requires an array for 'data'" % name) 842 if prefix is not None and not isinstance(prefix, str): 843 raise QAPISemError(info, 844 "Enum '%s' requires a string for 'prefix'" % name) 845 for member in members: 846 check_name(info, "Member of enum '%s'" % name, member, 847 enum_member=True) 848 849 850def check_struct(expr, info): 851 name = expr['struct'] 852 members = expr['data'] 853 854 check_type(info, "'data' for struct '%s'" % name, members, 855 allow_dict=True, allow_optional=True) 856 check_type(info, "'base' for struct '%s'" % name, expr.get('base'), 857 allow_metas=['struct']) 858 859 860def check_keys(expr_elem, meta, required, optional=[]): 861 expr = expr_elem['expr'] 862 info = expr_elem['info'] 863 name = expr[meta] 864 if not isinstance(name, str): 865 raise QAPISemError(info, "'%s' key must have a string value" % meta) 866 required = required + [meta] 867 for (key, value) in expr.items(): 868 if key not in required and key not in optional: 869 raise QAPISemError(info, "Unknown key '%s' in %s '%s'" 870 % (key, meta, name)) 871 if (key == 'gen' or key == 'success-response') and value is not False: 872 raise QAPISemError(info, 873 "'%s' of %s '%s' should only use false value" 874 % (key, meta, name)) 875 if (key == 'boxed' or key == 'allow-oob') and value is not True: 876 raise QAPISemError(info, 877 "'%s' of %s '%s' should only use true value" 878 % (key, meta, name)) 879 for key in required: 880 if key not in expr: 881 raise QAPISemError(info, "Key '%s' is missing from %s '%s'" 882 % (key, meta, name)) 883 884 885def check_exprs(exprs): 886 global all_names 887 888 # Populate name table with names of built-in types 889 for builtin in builtin_types.keys(): 890 all_names[builtin] = 'built-in' 891 892 # Learn the types and check for valid expression keys 893 for expr_elem in exprs: 894 expr = expr_elem['expr'] 895 info = expr_elem['info'] 896 doc = expr_elem.get('doc') 897 898 if 'include' in expr: 899 continue 900 901 if not doc and doc_required: 902 raise QAPISemError(info, 903 "Expression missing documentation comment") 904 905 if 'enum' in expr: 906 meta = 'enum' 907 check_keys(expr_elem, 'enum', ['data'], ['prefix']) 908 enum_types[expr[meta]] = expr 909 elif 'union' in expr: 910 meta = 'union' 911 check_keys(expr_elem, 'union', ['data'], 912 ['base', 'discriminator']) 913 union_types[expr[meta]] = expr 914 elif 'alternate' in expr: 915 meta = 'alternate' 916 check_keys(expr_elem, 'alternate', ['data']) 917 elif 'struct' in expr: 918 meta = 'struct' 919 check_keys(expr_elem, 'struct', ['data'], ['base']) 920 struct_types[expr[meta]] = expr 921 elif 'command' in expr: 922 meta = 'command' 923 check_keys(expr_elem, 'command', [], 924 ['data', 'returns', 'gen', 'success-response', 925 'boxed', 'allow-oob']) 926 elif 'event' in expr: 927 meta = 'event' 928 check_keys(expr_elem, 'event', [], ['data', 'boxed']) 929 else: 930 raise QAPISemError(expr_elem['info'], 931 "Expression is missing metatype") 932 name = expr[meta] 933 add_name(name, info, meta) 934 if doc and doc.symbol != name: 935 raise QAPISemError(info, "Definition of '%s' follows documentation" 936 " for '%s'" % (name, doc.symbol)) 937 938 # Try again for hidden UnionKind enum 939 for expr_elem in exprs: 940 expr = expr_elem['expr'] 941 942 if 'include' in expr: 943 continue 944 if 'union' in expr and not discriminator_find_enum_define(expr): 945 name = '%sKind' % expr['union'] 946 elif 'alternate' in expr: 947 name = '%sKind' % expr['alternate'] 948 else: 949 continue 950 enum_types[name] = {'enum': name} 951 add_name(name, info, 'enum', implicit=True) 952 953 # Validate that exprs make sense 954 for expr_elem in exprs: 955 expr = expr_elem['expr'] 956 info = expr_elem['info'] 957 doc = expr_elem.get('doc') 958 959 if 'include' in expr: 960 continue 961 if 'enum' in expr: 962 check_enum(expr, info) 963 elif 'union' in expr: 964 check_union(expr, info) 965 elif 'alternate' in expr: 966 check_alternate(expr, info) 967 elif 'struct' in expr: 968 check_struct(expr, info) 969 elif 'command' in expr: 970 check_command(expr, info) 971 elif 'event' in expr: 972 check_event(expr, info) 973 else: 974 assert False, 'unexpected meta type' 975 976 if doc: 977 doc.check_expr(expr) 978 979 return exprs 980 981 982# 983# Schema compiler frontend 984# 985 986class QAPISchemaEntity(object): 987 def __init__(self, name, info, doc): 988 assert name is None or isinstance(name, str) 989 self.name = name 990 self.module = None 991 # For explicitly defined entities, info points to the (explicit) 992 # definition. For builtins (and their arrays), info is None. 993 # For implicitly defined entities, info points to a place that 994 # triggered the implicit definition (there may be more than one 995 # such place). 996 self.info = info 997 self.doc = doc 998 999 def c_name(self): 1000 return c_name(self.name) 1001 1002 def check(self, schema): 1003 pass 1004 1005 def is_implicit(self): 1006 return not self.info 1007 1008 def visit(self, visitor): 1009 pass 1010 1011 1012class QAPISchemaVisitor(object): 1013 def visit_begin(self, schema): 1014 pass 1015 1016 def visit_end(self): 1017 pass 1018 1019 def visit_module(self, fname): 1020 pass 1021 1022 def visit_needed(self, entity): 1023 # Default to visiting everything 1024 return True 1025 1026 def visit_include(self, fname, info): 1027 pass 1028 1029 def visit_builtin_type(self, name, info, json_type): 1030 pass 1031 1032 def visit_enum_type(self, name, info, values, prefix): 1033 pass 1034 1035 def visit_array_type(self, name, info, element_type): 1036 pass 1037 1038 def visit_object_type(self, name, info, base, members, variants): 1039 pass 1040 1041 def visit_object_type_flat(self, name, info, members, variants): 1042 pass 1043 1044 def visit_alternate_type(self, name, info, variants): 1045 pass 1046 1047 def visit_command(self, name, info, arg_type, ret_type, 1048 gen, success_response, boxed, allow_oob): 1049 pass 1050 1051 def visit_event(self, name, info, arg_type, boxed): 1052 pass 1053 1054 1055class QAPISchemaInclude(QAPISchemaEntity): 1056 1057 def __init__(self, fname, info): 1058 QAPISchemaEntity.__init__(self, None, info, None) 1059 self.fname = fname 1060 1061 def visit(self, visitor): 1062 visitor.visit_include(self.fname, self.info) 1063 1064 1065class QAPISchemaType(QAPISchemaEntity): 1066 # Return the C type for common use. 1067 # For the types we commonly box, this is a pointer type. 1068 def c_type(self): 1069 pass 1070 1071 # Return the C type to be used in a parameter list. 1072 def c_param_type(self): 1073 return self.c_type() 1074 1075 # Return the C type to be used where we suppress boxing. 1076 def c_unboxed_type(self): 1077 return self.c_type() 1078 1079 def json_type(self): 1080 pass 1081 1082 def alternate_qtype(self): 1083 json2qtype = { 1084 'null': 'QTYPE_QNULL', 1085 'string': 'QTYPE_QSTRING', 1086 'number': 'QTYPE_QNUM', 1087 'int': 'QTYPE_QNUM', 1088 'boolean': 'QTYPE_QBOOL', 1089 'object': 'QTYPE_QDICT' 1090 } 1091 return json2qtype.get(self.json_type()) 1092 1093 def doc_type(self): 1094 if self.is_implicit(): 1095 return None 1096 return self.name 1097 1098 1099class QAPISchemaBuiltinType(QAPISchemaType): 1100 def __init__(self, name, json_type, c_type): 1101 QAPISchemaType.__init__(self, name, None, None) 1102 assert not c_type or isinstance(c_type, str) 1103 assert json_type in ('string', 'number', 'int', 'boolean', 'null', 1104 'value') 1105 self._json_type_name = json_type 1106 self._c_type_name = c_type 1107 1108 def c_name(self): 1109 return self.name 1110 1111 def c_type(self): 1112 return self._c_type_name 1113 1114 def c_param_type(self): 1115 if self.name == 'str': 1116 return 'const ' + self._c_type_name 1117 return self._c_type_name 1118 1119 def json_type(self): 1120 return self._json_type_name 1121 1122 def doc_type(self): 1123 return self.json_type() 1124 1125 def visit(self, visitor): 1126 visitor.visit_builtin_type(self.name, self.info, self.json_type()) 1127 1128 1129class QAPISchemaEnumType(QAPISchemaType): 1130 def __init__(self, name, info, doc, values, prefix): 1131 QAPISchemaType.__init__(self, name, info, doc) 1132 for v in values: 1133 assert isinstance(v, QAPISchemaMember) 1134 v.set_owner(name) 1135 assert prefix is None or isinstance(prefix, str) 1136 self.values = values 1137 self.prefix = prefix 1138 1139 def check(self, schema): 1140 seen = {} 1141 for v in self.values: 1142 v.check_clash(self.info, seen) 1143 if self.doc: 1144 self.doc.connect_member(v) 1145 1146 def is_implicit(self): 1147 # See QAPISchema._make_implicit_enum_type() and ._def_predefineds() 1148 return self.name.endswith('Kind') or self.name == 'QType' 1149 1150 def c_type(self): 1151 return c_name(self.name) 1152 1153 def member_names(self): 1154 return [v.name for v in self.values] 1155 1156 def json_type(self): 1157 return 'string' 1158 1159 def visit(self, visitor): 1160 visitor.visit_enum_type(self.name, self.info, 1161 self.member_names(), self.prefix) 1162 1163 1164class QAPISchemaArrayType(QAPISchemaType): 1165 def __init__(self, name, info, element_type): 1166 QAPISchemaType.__init__(self, name, info, None) 1167 assert isinstance(element_type, str) 1168 self._element_type_name = element_type 1169 self.element_type = None 1170 1171 def check(self, schema): 1172 self.element_type = schema.lookup_type(self._element_type_name) 1173 assert self.element_type 1174 1175 def is_implicit(self): 1176 return True 1177 1178 def c_type(self): 1179 return c_name(self.name) + pointer_suffix 1180 1181 def json_type(self): 1182 return 'array' 1183 1184 def doc_type(self): 1185 elt_doc_type = self.element_type.doc_type() 1186 if not elt_doc_type: 1187 return None 1188 return 'array of ' + elt_doc_type 1189 1190 def visit(self, visitor): 1191 visitor.visit_array_type(self.name, self.info, self.element_type) 1192 1193 1194class QAPISchemaObjectType(QAPISchemaType): 1195 def __init__(self, name, info, doc, base, local_members, variants): 1196 # struct has local_members, optional base, and no variants 1197 # flat union has base, variants, and no local_members 1198 # simple union has local_members, variants, and no base 1199 QAPISchemaType.__init__(self, name, info, doc) 1200 assert base is None or isinstance(base, str) 1201 for m in local_members: 1202 assert isinstance(m, QAPISchemaObjectTypeMember) 1203 m.set_owner(name) 1204 if variants is not None: 1205 assert isinstance(variants, QAPISchemaObjectTypeVariants) 1206 variants.set_owner(name) 1207 self._base_name = base 1208 self.base = None 1209 self.local_members = local_members 1210 self.variants = variants 1211 self.members = None 1212 1213 def check(self, schema): 1214 if self.members is False: # check for cycles 1215 raise QAPISemError(self.info, 1216 "Object %s contains itself" % self.name) 1217 if self.members: 1218 return 1219 self.members = False # mark as being checked 1220 seen = OrderedDict() 1221 if self._base_name: 1222 self.base = schema.lookup_type(self._base_name) 1223 assert isinstance(self.base, QAPISchemaObjectType) 1224 self.base.check(schema) 1225 self.base.check_clash(self.info, seen) 1226 for m in self.local_members: 1227 m.check(schema) 1228 m.check_clash(self.info, seen) 1229 if self.doc: 1230 self.doc.connect_member(m) 1231 self.members = seen.values() 1232 if self.variants: 1233 self.variants.check(schema, seen) 1234 assert self.variants.tag_member in self.members 1235 self.variants.check_clash(self.info, seen) 1236 if self.doc: 1237 self.doc.check() 1238 1239 # Check that the members of this type do not cause duplicate JSON members, 1240 # and update seen to track the members seen so far. Report any errors 1241 # on behalf of info, which is not necessarily self.info 1242 def check_clash(self, info, seen): 1243 assert not self.variants # not implemented 1244 for m in self.members: 1245 m.check_clash(info, seen) 1246 1247 def is_implicit(self): 1248 # See QAPISchema._make_implicit_object_type(), as well as 1249 # _def_predefineds() 1250 return self.name.startswith('q_') 1251 1252 def is_empty(self): 1253 assert self.members is not None 1254 return not self.members and not self.variants 1255 1256 def c_name(self): 1257 assert self.name != 'q_empty' 1258 return QAPISchemaType.c_name(self) 1259 1260 def c_type(self): 1261 assert not self.is_implicit() 1262 return c_name(self.name) + pointer_suffix 1263 1264 def c_unboxed_type(self): 1265 return c_name(self.name) 1266 1267 def json_type(self): 1268 return 'object' 1269 1270 def visit(self, visitor): 1271 visitor.visit_object_type(self.name, self.info, 1272 self.base, self.local_members, self.variants) 1273 visitor.visit_object_type_flat(self.name, self.info, 1274 self.members, self.variants) 1275 1276 1277class QAPISchemaMember(object): 1278 role = 'member' 1279 1280 def __init__(self, name): 1281 assert isinstance(name, str) 1282 self.name = name 1283 self.owner = None 1284 1285 def set_owner(self, name): 1286 assert not self.owner 1287 self.owner = name 1288 1289 def check_clash(self, info, seen): 1290 cname = c_name(self.name) 1291 if cname.lower() != cname and self.owner not in name_case_whitelist: 1292 raise QAPISemError(info, 1293 "%s should not use uppercase" % self.describe()) 1294 if cname in seen: 1295 raise QAPISemError(info, "%s collides with %s" % 1296 (self.describe(), seen[cname].describe())) 1297 seen[cname] = self 1298 1299 def _pretty_owner(self): 1300 owner = self.owner 1301 if owner.startswith('q_obj_'): 1302 # See QAPISchema._make_implicit_object_type() - reverse the 1303 # mapping there to create a nice human-readable description 1304 owner = owner[6:] 1305 if owner.endswith('-arg'): 1306 return '(parameter of %s)' % owner[:-4] 1307 elif owner.endswith('-base'): 1308 return '(base of %s)' % owner[:-5] 1309 else: 1310 assert owner.endswith('-wrapper') 1311 # Unreachable and not implemented 1312 assert False 1313 if owner.endswith('Kind'): 1314 # See QAPISchema._make_implicit_enum_type() 1315 return '(branch of %s)' % owner[:-4] 1316 return '(%s of %s)' % (self.role, owner) 1317 1318 def describe(self): 1319 return "'%s' %s" % (self.name, self._pretty_owner()) 1320 1321 1322class QAPISchemaObjectTypeMember(QAPISchemaMember): 1323 def __init__(self, name, typ, optional): 1324 QAPISchemaMember.__init__(self, name) 1325 assert isinstance(typ, str) 1326 assert isinstance(optional, bool) 1327 self._type_name = typ 1328 self.type = None 1329 self.optional = optional 1330 1331 def check(self, schema): 1332 assert self.owner 1333 self.type = schema.lookup_type(self._type_name) 1334 assert self.type 1335 1336 1337class QAPISchemaObjectTypeVariants(object): 1338 def __init__(self, tag_name, tag_member, variants): 1339 # Flat unions pass tag_name but not tag_member. 1340 # Simple unions and alternates pass tag_member but not tag_name. 1341 # After check(), tag_member is always set, and tag_name remains 1342 # a reliable witness of being used by a flat union. 1343 assert bool(tag_member) != bool(tag_name) 1344 assert (isinstance(tag_name, str) or 1345 isinstance(tag_member, QAPISchemaObjectTypeMember)) 1346 assert len(variants) > 0 1347 for v in variants: 1348 assert isinstance(v, QAPISchemaObjectTypeVariant) 1349 self._tag_name = tag_name 1350 self.tag_member = tag_member 1351 self.variants = variants 1352 1353 def set_owner(self, name): 1354 for v in self.variants: 1355 v.set_owner(name) 1356 1357 def check(self, schema, seen): 1358 if not self.tag_member: # flat union 1359 self.tag_member = seen[c_name(self._tag_name)] 1360 assert self._tag_name == self.tag_member.name 1361 assert isinstance(self.tag_member.type, QAPISchemaEnumType) 1362 for v in self.variants: 1363 v.check(schema) 1364 # Union names must match enum values; alternate names are 1365 # checked separately. Use 'seen' to tell the two apart. 1366 if seen: 1367 assert v.name in self.tag_member.type.member_names() 1368 assert isinstance(v.type, QAPISchemaObjectType) 1369 v.type.check(schema) 1370 1371 def check_clash(self, info, seen): 1372 for v in self.variants: 1373 # Reset seen map for each variant, since qapi names from one 1374 # branch do not affect another branch 1375 assert isinstance(v.type, QAPISchemaObjectType) 1376 v.type.check_clash(info, dict(seen)) 1377 1378 1379class QAPISchemaObjectTypeVariant(QAPISchemaObjectTypeMember): 1380 role = 'branch' 1381 1382 def __init__(self, name, typ): 1383 QAPISchemaObjectTypeMember.__init__(self, name, typ, False) 1384 1385 1386class QAPISchemaAlternateType(QAPISchemaType): 1387 def __init__(self, name, info, doc, variants): 1388 QAPISchemaType.__init__(self, name, info, doc) 1389 assert isinstance(variants, QAPISchemaObjectTypeVariants) 1390 assert variants.tag_member 1391 variants.set_owner(name) 1392 variants.tag_member.set_owner(self.name) 1393 self.variants = variants 1394 1395 def check(self, schema): 1396 self.variants.tag_member.check(schema) 1397 # Not calling self.variants.check_clash(), because there's nothing 1398 # to clash with 1399 self.variants.check(schema, {}) 1400 # Alternate branch names have no relation to the tag enum values; 1401 # so we have to check for potential name collisions ourselves. 1402 seen = {} 1403 for v in self.variants.variants: 1404 v.check_clash(self.info, seen) 1405 if self.doc: 1406 self.doc.connect_member(v) 1407 if self.doc: 1408 self.doc.check() 1409 1410 def c_type(self): 1411 return c_name(self.name) + pointer_suffix 1412 1413 def json_type(self): 1414 return 'value' 1415 1416 def visit(self, visitor): 1417 visitor.visit_alternate_type(self.name, self.info, self.variants) 1418 1419 def is_empty(self): 1420 return False 1421 1422 1423class QAPISchemaCommand(QAPISchemaEntity): 1424 def __init__(self, name, info, doc, arg_type, ret_type, 1425 gen, success_response, boxed, allow_oob): 1426 QAPISchemaEntity.__init__(self, name, info, doc) 1427 assert not arg_type or isinstance(arg_type, str) 1428 assert not ret_type or isinstance(ret_type, str) 1429 self._arg_type_name = arg_type 1430 self.arg_type = None 1431 self._ret_type_name = ret_type 1432 self.ret_type = None 1433 self.gen = gen 1434 self.success_response = success_response 1435 self.boxed = boxed 1436 self.allow_oob = allow_oob 1437 1438 def check(self, schema): 1439 if self._arg_type_name: 1440 self.arg_type = schema.lookup_type(self._arg_type_name) 1441 assert (isinstance(self.arg_type, QAPISchemaObjectType) or 1442 isinstance(self.arg_type, QAPISchemaAlternateType)) 1443 self.arg_type.check(schema) 1444 if self.boxed: 1445 if self.arg_type.is_empty(): 1446 raise QAPISemError(self.info, 1447 "Cannot use 'boxed' with empty type") 1448 else: 1449 assert not isinstance(self.arg_type, QAPISchemaAlternateType) 1450 assert not self.arg_type.variants 1451 elif self.boxed: 1452 raise QAPISemError(self.info, "Use of 'boxed' requires 'data'") 1453 if self._ret_type_name: 1454 self.ret_type = schema.lookup_type(self._ret_type_name) 1455 assert isinstance(self.ret_type, QAPISchemaType) 1456 1457 def visit(self, visitor): 1458 visitor.visit_command(self.name, self.info, 1459 self.arg_type, self.ret_type, 1460 self.gen, self.success_response, 1461 self.boxed, self.allow_oob) 1462 1463 1464class QAPISchemaEvent(QAPISchemaEntity): 1465 def __init__(self, name, info, doc, arg_type, boxed): 1466 QAPISchemaEntity.__init__(self, name, info, doc) 1467 assert not arg_type or isinstance(arg_type, str) 1468 self._arg_type_name = arg_type 1469 self.arg_type = None 1470 self.boxed = boxed 1471 1472 def check(self, schema): 1473 if self._arg_type_name: 1474 self.arg_type = schema.lookup_type(self._arg_type_name) 1475 assert (isinstance(self.arg_type, QAPISchemaObjectType) or 1476 isinstance(self.arg_type, QAPISchemaAlternateType)) 1477 self.arg_type.check(schema) 1478 if self.boxed: 1479 if self.arg_type.is_empty(): 1480 raise QAPISemError(self.info, 1481 "Cannot use 'boxed' with empty type") 1482 else: 1483 assert not isinstance(self.arg_type, QAPISchemaAlternateType) 1484 assert not self.arg_type.variants 1485 elif self.boxed: 1486 raise QAPISemError(self.info, "Use of 'boxed' requires 'data'") 1487 1488 def visit(self, visitor): 1489 visitor.visit_event(self.name, self.info, self.arg_type, self.boxed) 1490 1491 1492class QAPISchema(object): 1493 def __init__(self, fname): 1494 self._fname = fname 1495 parser = QAPISchemaParser(open(fname, 'r')) 1496 exprs = check_exprs(parser.exprs) 1497 self.docs = parser.docs 1498 self._entity_list = [] 1499 self._entity_dict = {} 1500 self._predefining = True 1501 self._def_predefineds() 1502 self._predefining = False 1503 self._def_exprs(exprs) 1504 self.check() 1505 1506 def _def_entity(self, ent): 1507 # Only the predefined types are allowed to not have info 1508 assert ent.info or self._predefining 1509 assert ent.name is None or ent.name not in self._entity_dict 1510 self._entity_list.append(ent) 1511 if ent.name is not None: 1512 self._entity_dict[ent.name] = ent 1513 if ent.info: 1514 ent.module = os.path.relpath(ent.info['file'], 1515 os.path.dirname(self._fname)) 1516 1517 def lookup_entity(self, name, typ=None): 1518 ent = self._entity_dict.get(name) 1519 if typ and not isinstance(ent, typ): 1520 return None 1521 return ent 1522 1523 def lookup_type(self, name): 1524 return self.lookup_entity(name, QAPISchemaType) 1525 1526 def _def_include(self, expr, info, doc): 1527 include = expr['include'] 1528 assert doc is None 1529 main_info = info 1530 while main_info['parent']: 1531 main_info = main_info['parent'] 1532 fname = os.path.relpath(include, os.path.dirname(main_info['file'])) 1533 self._def_entity(QAPISchemaInclude(fname, info)) 1534 1535 def _def_builtin_type(self, name, json_type, c_type): 1536 self._def_entity(QAPISchemaBuiltinType(name, json_type, c_type)) 1537 # Instantiating only the arrays that are actually used would 1538 # be nice, but we can't as long as their generated code 1539 # (qapi-builtin-types.[ch]) may be shared by some other 1540 # schema. 1541 self._make_array_type(name, None) 1542 1543 def _def_predefineds(self): 1544 for t in [('str', 'string', 'char' + pointer_suffix), 1545 ('number', 'number', 'double'), 1546 ('int', 'int', 'int64_t'), 1547 ('int8', 'int', 'int8_t'), 1548 ('int16', 'int', 'int16_t'), 1549 ('int32', 'int', 'int32_t'), 1550 ('int64', 'int', 'int64_t'), 1551 ('uint8', 'int', 'uint8_t'), 1552 ('uint16', 'int', 'uint16_t'), 1553 ('uint32', 'int', 'uint32_t'), 1554 ('uint64', 'int', 'uint64_t'), 1555 ('size', 'int', 'uint64_t'), 1556 ('bool', 'boolean', 'bool'), 1557 ('any', 'value', 'QObject' + pointer_suffix), 1558 ('null', 'null', 'QNull' + pointer_suffix)]: 1559 self._def_builtin_type(*t) 1560 self.the_empty_object_type = QAPISchemaObjectType( 1561 'q_empty', None, None, None, [], None) 1562 self._def_entity(self.the_empty_object_type) 1563 qtype_values = self._make_enum_members(['none', 'qnull', 'qnum', 1564 'qstring', 'qdict', 'qlist', 1565 'qbool']) 1566 self._def_entity(QAPISchemaEnumType('QType', None, None, 1567 qtype_values, 'QTYPE')) 1568 1569 def _make_enum_members(self, values): 1570 return [QAPISchemaMember(v) for v in values] 1571 1572 def _make_implicit_enum_type(self, name, info, values): 1573 # See also QAPISchemaObjectTypeMember._pretty_owner() 1574 name = name + 'Kind' # Use namespace reserved by add_name() 1575 self._def_entity(QAPISchemaEnumType( 1576 name, info, None, self._make_enum_members(values), None)) 1577 return name 1578 1579 def _make_array_type(self, element_type, info): 1580 name = element_type + 'List' # Use namespace reserved by add_name() 1581 if not self.lookup_type(name): 1582 self._def_entity(QAPISchemaArrayType(name, info, element_type)) 1583 return name 1584 1585 def _make_implicit_object_type(self, name, info, doc, role, members): 1586 if not members: 1587 return None 1588 # See also QAPISchemaObjectTypeMember._pretty_owner() 1589 name = 'q_obj_%s-%s' % (name, role) 1590 if not self.lookup_entity(name, QAPISchemaObjectType): 1591 self._def_entity(QAPISchemaObjectType(name, info, doc, None, 1592 members, None)) 1593 return name 1594 1595 def _def_enum_type(self, expr, info, doc): 1596 name = expr['enum'] 1597 data = expr['data'] 1598 prefix = expr.get('prefix') 1599 self._def_entity(QAPISchemaEnumType( 1600 name, info, doc, self._make_enum_members(data), prefix)) 1601 1602 def _make_member(self, name, typ, info): 1603 optional = False 1604 if name.startswith('*'): 1605 name = name[1:] 1606 optional = True 1607 if isinstance(typ, list): 1608 assert len(typ) == 1 1609 typ = self._make_array_type(typ[0], info) 1610 return QAPISchemaObjectTypeMember(name, typ, optional) 1611 1612 def _make_members(self, data, info): 1613 return [self._make_member(key, value, info) 1614 for (key, value) in data.items()] 1615 1616 def _def_struct_type(self, expr, info, doc): 1617 name = expr['struct'] 1618 base = expr.get('base') 1619 data = expr['data'] 1620 self._def_entity(QAPISchemaObjectType(name, info, doc, base, 1621 self._make_members(data, info), 1622 None)) 1623 1624 def _make_variant(self, case, typ): 1625 return QAPISchemaObjectTypeVariant(case, typ) 1626 1627 def _make_simple_variant(self, case, typ, info): 1628 if isinstance(typ, list): 1629 assert len(typ) == 1 1630 typ = self._make_array_type(typ[0], info) 1631 typ = self._make_implicit_object_type( 1632 typ, info, None, 'wrapper', [self._make_member('data', typ, info)]) 1633 return QAPISchemaObjectTypeVariant(case, typ) 1634 1635 def _def_union_type(self, expr, info, doc): 1636 name = expr['union'] 1637 data = expr['data'] 1638 base = expr.get('base') 1639 tag_name = expr.get('discriminator') 1640 tag_member = None 1641 if isinstance(base, dict): 1642 base = (self._make_implicit_object_type( 1643 name, info, doc, 'base', self._make_members(base, info))) 1644 if tag_name: 1645 variants = [self._make_variant(key, value) 1646 for (key, value) in data.items()] 1647 members = [] 1648 else: 1649 variants = [self._make_simple_variant(key, value, info) 1650 for (key, value) in data.items()] 1651 typ = self._make_implicit_enum_type(name, info, 1652 [v.name for v in variants]) 1653 tag_member = QAPISchemaObjectTypeMember('type', typ, False) 1654 members = [tag_member] 1655 self._def_entity( 1656 QAPISchemaObjectType(name, info, doc, base, members, 1657 QAPISchemaObjectTypeVariants(tag_name, 1658 tag_member, 1659 variants))) 1660 1661 def _def_alternate_type(self, expr, info, doc): 1662 name = expr['alternate'] 1663 data = expr['data'] 1664 variants = [self._make_variant(key, value) 1665 for (key, value) in data.items()] 1666 tag_member = QAPISchemaObjectTypeMember('type', 'QType', False) 1667 self._def_entity( 1668 QAPISchemaAlternateType(name, info, doc, 1669 QAPISchemaObjectTypeVariants(None, 1670 tag_member, 1671 variants))) 1672 1673 def _def_command(self, expr, info, doc): 1674 name = expr['command'] 1675 data = expr.get('data') 1676 rets = expr.get('returns') 1677 gen = expr.get('gen', True) 1678 success_response = expr.get('success-response', True) 1679 boxed = expr.get('boxed', False) 1680 allow_oob = expr.get('allow-oob', False) 1681 if isinstance(data, OrderedDict): 1682 data = self._make_implicit_object_type( 1683 name, info, doc, 'arg', self._make_members(data, info)) 1684 if isinstance(rets, list): 1685 assert len(rets) == 1 1686 rets = self._make_array_type(rets[0], info) 1687 self._def_entity(QAPISchemaCommand(name, info, doc, data, rets, 1688 gen, success_response, 1689 boxed, allow_oob)) 1690 1691 def _def_event(self, expr, info, doc): 1692 name = expr['event'] 1693 data = expr.get('data') 1694 boxed = expr.get('boxed', False) 1695 if isinstance(data, OrderedDict): 1696 data = self._make_implicit_object_type( 1697 name, info, doc, 'arg', self._make_members(data, info)) 1698 self._def_entity(QAPISchemaEvent(name, info, doc, data, boxed)) 1699 1700 def _def_exprs(self, exprs): 1701 for expr_elem in exprs: 1702 expr = expr_elem['expr'] 1703 info = expr_elem['info'] 1704 doc = expr_elem.get('doc') 1705 if 'enum' in expr: 1706 self._def_enum_type(expr, info, doc) 1707 elif 'struct' in expr: 1708 self._def_struct_type(expr, info, doc) 1709 elif 'union' in expr: 1710 self._def_union_type(expr, info, doc) 1711 elif 'alternate' in expr: 1712 self._def_alternate_type(expr, info, doc) 1713 elif 'command' in expr: 1714 self._def_command(expr, info, doc) 1715 elif 'event' in expr: 1716 self._def_event(expr, info, doc) 1717 elif 'include' in expr: 1718 self._def_include(expr, info, doc) 1719 else: 1720 assert False 1721 1722 def check(self): 1723 for ent in self._entity_list: 1724 ent.check(self) 1725 1726 def visit(self, visitor): 1727 visitor.visit_begin(self) 1728 module = None 1729 for entity in self._entity_list: 1730 if visitor.visit_needed(entity): 1731 if entity.module != module: 1732 module = entity.module 1733 visitor.visit_module(module) 1734 entity.visit(visitor) 1735 visitor.visit_end() 1736 1737 1738# 1739# Code generation helpers 1740# 1741 1742def camel_case(name): 1743 new_name = '' 1744 first = True 1745 for ch in name: 1746 if ch in ['_', '-']: 1747 first = True 1748 elif first: 1749 new_name += ch.upper() 1750 first = False 1751 else: 1752 new_name += ch.lower() 1753 return new_name 1754 1755 1756# ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1 1757# ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2 1758# ENUM24_Name -> ENUM24_NAME 1759def camel_to_upper(value): 1760 c_fun_str = c_name(value, False) 1761 if value.isupper(): 1762 return c_fun_str 1763 1764 new_name = '' 1765 l = len(c_fun_str) 1766 for i in range(l): 1767 c = c_fun_str[i] 1768 # When c is upper and no '_' appears before, do more checks 1769 if c.isupper() and (i > 0) and c_fun_str[i - 1] != '_': 1770 if i < l - 1 and c_fun_str[i + 1].islower(): 1771 new_name += '_' 1772 elif c_fun_str[i - 1].isdigit(): 1773 new_name += '_' 1774 new_name += c 1775 return new_name.lstrip('_').upper() 1776 1777 1778def c_enum_const(type_name, const_name, prefix=None): 1779 if prefix is not None: 1780 type_name = prefix 1781 return camel_to_upper(type_name) + '_' + c_name(const_name, False).upper() 1782 1783if hasattr(str, 'maketrans'): 1784 c_name_trans = str.maketrans('.-', '__') 1785else: 1786 c_name_trans = string.maketrans('.-', '__') 1787 1788 1789# Map @name to a valid C identifier. 1790# If @protect, avoid returning certain ticklish identifiers (like 1791# C keywords) by prepending 'q_'. 1792# 1793# Used for converting 'name' from a 'name':'type' qapi definition 1794# into a generated struct member, as well as converting type names 1795# into substrings of a generated C function name. 1796# '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo' 1797# protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int' 1798def c_name(name, protect=True): 1799 # ANSI X3J11/88-090, 3.1.1 1800 c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue', 1801 'default', 'do', 'double', 'else', 'enum', 'extern', 1802 'float', 'for', 'goto', 'if', 'int', 'long', 'register', 1803 'return', 'short', 'signed', 'sizeof', 'static', 1804 'struct', 'switch', 'typedef', 'union', 'unsigned', 1805 'void', 'volatile', 'while']) 1806 # ISO/IEC 9899:1999, 6.4.1 1807 c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary']) 1808 # ISO/IEC 9899:2011, 6.4.1 1809 c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic', 1810 '_Noreturn', '_Static_assert', '_Thread_local']) 1811 # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html 1812 # excluding _.* 1813 gcc_words = set(['asm', 'typeof']) 1814 # C++ ISO/IEC 14882:2003 2.11 1815 cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete', 1816 'dynamic_cast', 'explicit', 'false', 'friend', 'mutable', 1817 'namespace', 'new', 'operator', 'private', 'protected', 1818 'public', 'reinterpret_cast', 'static_cast', 'template', 1819 'this', 'throw', 'true', 'try', 'typeid', 'typename', 1820 'using', 'virtual', 'wchar_t', 1821 # alternative representations 1822 'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not', 1823 'not_eq', 'or', 'or_eq', 'xor', 'xor_eq']) 1824 # namespace pollution: 1825 polluted_words = set(['unix', 'errno', 'mips', 'sparc', 'i386']) 1826 name = name.translate(c_name_trans) 1827 if protect and (name in c89_words | c99_words | c11_words | gcc_words 1828 | cpp_words | polluted_words): 1829 return 'q_' + name 1830 return name 1831 1832eatspace = '\033EATSPACE.' 1833pointer_suffix = ' *' + eatspace 1834 1835 1836def genindent(count): 1837 ret = '' 1838 for _ in range(count): 1839 ret += ' ' 1840 return ret 1841 1842indent_level = 0 1843 1844 1845def push_indent(indent_amount=4): 1846 global indent_level 1847 indent_level += indent_amount 1848 1849 1850def pop_indent(indent_amount=4): 1851 global indent_level 1852 indent_level -= indent_amount 1853 1854 1855# Generate @code with @kwds interpolated. 1856# Obey indent_level, and strip eatspace. 1857def cgen(code, **kwds): 1858 raw = code % kwds 1859 if indent_level: 1860 indent = genindent(indent_level) 1861 # re.subn() lacks flags support before Python 2.7, use re.compile() 1862 raw = re.subn(re.compile(r'^.', re.MULTILINE), 1863 indent + r'\g<0>', raw) 1864 raw = raw[0] 1865 return re.sub(re.escape(eatspace) + r' *', '', raw) 1866 1867 1868def mcgen(code, **kwds): 1869 if code[0] == '\n': 1870 code = code[1:] 1871 return cgen(code, **kwds) 1872 1873 1874def guardname(filename): 1875 return re.sub(r'[^A-Za-z0-9_]', '_', filename).upper() 1876 1877 1878def guardstart(name): 1879 return mcgen(''' 1880#ifndef %(name)s 1881#define %(name)s 1882 1883''', 1884 name=guardname(name)) 1885 1886 1887def guardend(name): 1888 return mcgen(''' 1889 1890#endif /* %(name)s */ 1891''', 1892 name=guardname(name)) 1893 1894 1895def gen_enum_lookup(name, values, prefix=None): 1896 ret = mcgen(''' 1897 1898const QEnumLookup %(c_name)s_lookup = { 1899 .array = (const char *const[]) { 1900''', 1901 c_name=c_name(name)) 1902 for value in values: 1903 index = c_enum_const(name, value, prefix) 1904 ret += mcgen(''' 1905 [%(index)s] = "%(value)s", 1906''', 1907 index=index, value=value) 1908 1909 ret += mcgen(''' 1910 }, 1911 .size = %(max_index)s 1912}; 1913''', 1914 max_index=c_enum_const(name, '_MAX', prefix)) 1915 return ret 1916 1917 1918def gen_enum(name, values, prefix=None): 1919 # append automatically generated _MAX value 1920 enum_values = values + ['_MAX'] 1921 1922 ret = mcgen(''' 1923 1924typedef enum %(c_name)s { 1925''', 1926 c_name=c_name(name)) 1927 1928 i = 0 1929 for value in enum_values: 1930 ret += mcgen(''' 1931 %(c_enum)s = %(i)d, 1932''', 1933 c_enum=c_enum_const(name, value, prefix), 1934 i=i) 1935 i += 1 1936 1937 ret += mcgen(''' 1938} %(c_name)s; 1939''', 1940 c_name=c_name(name)) 1941 1942 ret += mcgen(''' 1943 1944#define %(c_name)s_str(val) \\ 1945 qapi_enum_lookup(&%(c_name)s_lookup, (val)) 1946 1947extern const QEnumLookup %(c_name)s_lookup; 1948''', 1949 c_name=c_name(name)) 1950 return ret 1951 1952 1953def build_params(arg_type, boxed, extra): 1954 if not arg_type: 1955 assert not boxed 1956 return extra 1957 ret = '' 1958 sep = '' 1959 if boxed: 1960 ret += '%s arg' % arg_type.c_param_type() 1961 sep = ', ' 1962 else: 1963 assert not arg_type.variants 1964 for memb in arg_type.members: 1965 ret += sep 1966 sep = ', ' 1967 if memb.optional: 1968 ret += 'bool has_%s, ' % c_name(memb.name) 1969 ret += '%s %s' % (memb.type.c_param_type(), 1970 c_name(memb.name)) 1971 if extra: 1972 ret += sep + extra 1973 return ret 1974 1975 1976# 1977# Accumulate and write output 1978# 1979 1980class QAPIGen(object): 1981 1982 def __init__(self): 1983 self._preamble = '' 1984 self._body = '' 1985 1986 def preamble_add(self, text): 1987 self._preamble += text 1988 1989 def add(self, text): 1990 self._body += text 1991 1992 def _top(self, fname): 1993 return '' 1994 1995 def _bottom(self, fname): 1996 return '' 1997 1998 def write(self, output_dir, fname): 1999 pathname = os.path.join(output_dir, fname) 2000 dir = os.path.dirname(pathname) 2001 if dir: 2002 try: 2003 os.makedirs(dir) 2004 except os.error as e: 2005 if e.errno != errno.EEXIST: 2006 raise 2007 fd = os.open(pathname, os.O_RDWR | os.O_CREAT, 0o666) 2008 f = os.fdopen(fd, 'r+') 2009 text = (self._top(fname) + self._preamble + self._body 2010 + self._bottom(fname)) 2011 oldtext = f.read(len(text) + 1) 2012 if text != oldtext: 2013 f.seek(0) 2014 f.truncate(0) 2015 f.write(text) 2016 f.close() 2017 2018 2019class QAPIGenC(QAPIGen): 2020 2021 def __init__(self, blurb, pydoc): 2022 QAPIGen.__init__(self) 2023 self._blurb = blurb 2024 self._copyright = '\n * '.join(re.findall(r'^Copyright .*', pydoc, 2025 re.MULTILINE)) 2026 2027 def _top(self, fname): 2028 return mcgen(''' 2029/* AUTOMATICALLY GENERATED, DO NOT MODIFY */ 2030 2031/* 2032%(blurb)s 2033 * 2034 * %(copyright)s 2035 * 2036 * This work is licensed under the terms of the GNU LGPL, version 2.1 or later. 2037 * See the COPYING.LIB file in the top-level directory. 2038 */ 2039 2040''', 2041 blurb=self._blurb, copyright=self._copyright) 2042 2043 def _bottom(self, fname): 2044 return mcgen(''' 2045/* Dummy declaration to prevent empty .o file */ 2046char dummy_%(name)s; 2047''', 2048 name=c_name(fname)) 2049 2050 2051class QAPIGenH(QAPIGenC): 2052 2053 def _top(self, fname): 2054 return QAPIGenC._top(self, fname) + guardstart(fname) 2055 2056 def _bottom(self, fname): 2057 return guardend(fname) 2058 2059 2060class QAPIGenDoc(QAPIGen): 2061 2062 def _top(self, fname): 2063 return (QAPIGen._top(self, fname) 2064 + '@c AUTOMATICALLY GENERATED, DO NOT MODIFY\n\n') 2065 2066 2067class QAPISchemaMonolithicCVisitor(QAPISchemaVisitor): 2068 2069 def __init__(self, prefix, what, blurb, pydoc): 2070 self._prefix = prefix 2071 self._what = what 2072 self._genc = QAPIGenC(blurb, pydoc) 2073 self._genh = QAPIGenH(blurb, pydoc) 2074 2075 def write(self, output_dir): 2076 self._genc.write(output_dir, self._prefix + self._what + '.c') 2077 self._genh.write(output_dir, self._prefix + self._what + '.h') 2078 2079 2080class QAPISchemaModularCVisitor(QAPISchemaVisitor): 2081 2082 def __init__(self, prefix, what, blurb, pydoc): 2083 self._prefix = prefix 2084 self._what = what 2085 self._blurb = blurb 2086 self._pydoc = pydoc 2087 self._module = {} 2088 self._main_module = None 2089 2090 def _module_basename(self, what, name): 2091 if name is None: 2092 return re.sub(r'-', '-builtin-', what) 2093 basename = os.path.join(os.path.dirname(name), 2094 self._prefix + what) 2095 if name == self._main_module: 2096 return basename 2097 return basename + '-' + os.path.splitext(os.path.basename(name))[0] 2098 2099 def _add_module(self, name, blurb): 2100 if self._main_module is None and name is not None: 2101 self._main_module = name 2102 genc = QAPIGenC(blurb, self._pydoc) 2103 genh = QAPIGenH(blurb, self._pydoc) 2104 self._module[name] = (genc, genh) 2105 self._set_module(name) 2106 2107 def _set_module(self, name): 2108 self._genc, self._genh = self._module[name] 2109 2110 def write(self, output_dir, opt_builtins=False): 2111 for name in self._module: 2112 if name is None and not opt_builtins: 2113 continue 2114 basename = self._module_basename(self._what, name) 2115 (genc, genh) = self._module[name] 2116 genc.write(output_dir, basename + '.c') 2117 genh.write(output_dir, basename + '.h') 2118 2119 def _begin_module(self, name): 2120 pass 2121 2122 def visit_module(self, name): 2123 if name in self._module: 2124 self._set_module(name) 2125 return 2126 self._add_module(name, self._blurb) 2127 self._begin_module(name) 2128 2129 def visit_include(self, name, info): 2130 basename = self._module_basename(self._what, name) 2131 self._genh.preamble_add(mcgen(''' 2132#include "%(basename)s.h" 2133''', 2134 basename=basename)) 2135