scripts/qapi/common.py

   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
  14 from __future__ import print_function
  15 import errno
  16 import os
  17 import re
  18 import string
  19 try:
  20     from collections import OrderedDict
  21 except:
  22     from ordereddict import OrderedDict
  23
  24 builtin_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?
  44 doc_required = False
  45
  46 # Whitelist of commands allowed to return a non-dictionary
  47 returns_whitelist = []
  48
  49 # Whitelist of entities allowed to violate case conventions
  50 name_case_whitelist = []
  51
  52 enum_types = {}
  53 struct_types = {}
  54 union_types = {}
  55 all_names = {}
  56
  57 #
  58 # Parsing the schema into expressions
  59 #
  60
  61
  62 def 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
  71 class 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
  87 class 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
  99 class QAPISemError(QAPIError):
 100     def __init__(self, info, msg):
 101         QAPIError.__init__(self, info['file'], info['line'], None,
 102                            info['parent'], msg)
 103
 104
 105 class 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
 258 class 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
 554 def 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.
 564 def 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.
 578 def 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.
 599 valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?'
 600                         '[a-zA-Z][a-zA-Z0-9_-]*$')
 601
 602
 603 def 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
 626 def 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
 640 def 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
 690 def 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
 708 def 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
 720 def 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
 793 def 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
 834 def 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
 850 def 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
 860 def 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
 885 def 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
 986 class 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
1012 class 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
1055 class 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
1065 class 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
1099 class 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
1129 class 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
1164 class 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
1194 class 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
1277 class 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
1322 class 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
1337 class 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
1379 class QAPISchemaObjectTypeVariant(QAPISchemaObjectTypeMember):
1380     role = 'branch'
1381
1382     def __init__(self, name, typ):
1383         QAPISchemaObjectTypeMember.__init__(self, name, typ, False)
1384
1385
1386 class 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
1423 class 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
1464 class 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
1492 class 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
1742 def 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
1759 def 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
1778 def 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
1783 if hasattr(str, 'maketrans'):
1784     c_name_trans = str.maketrans('.-', '__')
1785 else:
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'
1798 def 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
1832 eatspace = '\033EATSPACE.'
1833 pointer_suffix = ' *' + eatspace
1834
1835
1836 def genindent(count):
1837     ret = ''
1838     for _ in range(count):
1839         ret += ' '
1840     return ret
1841
1842 indent_level = 0
1843
1844
1845 def push_indent(indent_amount=4):
1846     global indent_level
1847     indent_level += indent_amount
1848
1849
1850 def 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.
1857 def 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
1868 def mcgen(code, **kwds):
1869     if code[0] == '\n':
1870         code = code[1:]
1871     return cgen(code, **kwds)
1872
1873
1874 def guardname(filename):
1875     return re.sub(r'[^A-Za-z0-9_]', '_', filename).upper()
1876
1877
1878 def guardstart(name):
1879     return mcgen('''
1880 #ifndef %(name)s
1881 #define %(name)s
1882
1883 ''',
1884                  name=guardname(name))
1885
1886
1887 def guardend(name):
1888     return mcgen('''
1889
1890 #endif /* %(name)s */
1891 ''',
1892                  name=guardname(name))
1893
1894
1895 def gen_enum_lookup(name, values, prefix=None):
1896     ret = mcgen('''
1897
1898 const 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
1918 def gen_enum(name, values, prefix=None):
1919     # append automatically generated _MAX value
1920     enum_values = values + ['_MAX']
1921
1922     ret = mcgen('''
1923
1924 typedef 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
1947 extern const QEnumLookup %(c_name)s_lookup;
1948 ''',
1949                  c_name=c_name(name))
1950     return ret
1951
1952
1953 def 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
1980 class 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
2019 class 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 */
2046 char dummy_%(name)s;
2047 ''',
2048                      name=c_name(fname))
2049
2050
2051 class 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
2060 class 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
2067 class 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
2080 class 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))