scripts/qapi.py

   1 #
   2 # QAPI helper library
   3 #
   4 # Copyright IBM, Corp. 2011
   5 # Copyright (c) 2013-2015 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 import re
  15 from ordereddict import OrderedDict
  16 import getopt
  17 import os
  18 import sys
  19 import string
  20
  21 builtin_types = {
  22     'str':      'QTYPE_QSTRING',
  23     'int':      'QTYPE_QINT',
  24     'number':   'QTYPE_QFLOAT',
  25     'bool':     'QTYPE_QBOOL',
  26     'int8':     'QTYPE_QINT',
  27     'int16':    'QTYPE_QINT',
  28     'int32':    'QTYPE_QINT',
  29     'int64':    'QTYPE_QINT',
  30     'uint8':    'QTYPE_QINT',
  31     'uint16':   'QTYPE_QINT',
  32     'uint32':   'QTYPE_QINT',
  33     'uint64':   'QTYPE_QINT',
  34     'size':     'QTYPE_QINT',
  35 }
  36
  37 # Whitelist of commands allowed to return a non-dictionary
  38 returns_whitelist = [
  39     # From QMP:
  40     'human-monitor-command',
  41     'query-migrate-cache-size',
  42     'query-tpm-models',
  43     'query-tpm-types',
  44     'ringbuf-read',
  45
  46     # From QGA:
  47     'guest-file-open',
  48     'guest-fsfreeze-freeze',
  49     'guest-fsfreeze-freeze-list',
  50     'guest-fsfreeze-status',
  51     'guest-fsfreeze-thaw',
  52     'guest-get-time',
  53     'guest-set-vcpus',
  54     'guest-sync',
  55     'guest-sync-delimited',
  56
  57     # From qapi-schema-test:
  58     'user_def_cmd3',
  59 ]
  60
  61 enum_types = []
  62 struct_types = []
  63 union_types = []
  64 events = []
  65 all_names = {}
  66
  67 def error_path(parent):
  68     res = ""
  69     while parent:
  70         res = ("In file included from %s:%d:\n" % (parent['file'],
  71                                                    parent['line'])) + res
  72         parent = parent['parent']
  73     return res
  74
  75 class QAPISchemaError(Exception):
  76     def __init__(self, schema, msg):
  77         self.input_file = schema.input_file
  78         self.msg = msg
  79         self.col = 1
  80         self.line = schema.line
  81         for ch in schema.src[schema.line_pos:schema.pos]:
  82             if ch == '\t':
  83                 self.col = (self.col + 7) % 8 + 1
  84             else:
  85                 self.col += 1
  86         self.info = schema.parent_info
  87
  88     def __str__(self):
  89         return error_path(self.info) + \
  90             "%s:%d:%d: %s" % (self.input_file, self.line, self.col, self.msg)
  91
  92 class QAPIExprError(Exception):
  93     def __init__(self, expr_info, msg):
  94         self.info = expr_info
  95         self.msg = msg
  96
  97     def __str__(self):
  98         return error_path(self.info['parent']) + \
  99             "%s:%d: %s" % (self.info['file'], self.info['line'], self.msg)
 100
 101 class QAPISchema:
 102
 103     def __init__(self, fp, input_relname=None, include_hist=[],
 104                  previously_included=[], parent_info=None):
 105         """ include_hist is a stack used to detect inclusion cycles
 106             previously_included is a global state used to avoid multiple
 107                                 inclusions of the same file"""
 108         input_fname = os.path.abspath(fp.name)
 109         if input_relname is None:
 110             input_relname = fp.name
 111         self.input_dir = os.path.dirname(input_fname)
 112         self.input_file = input_relname
 113         self.include_hist = include_hist + [(input_relname, input_fname)]
 114         previously_included.append(input_fname)
 115         self.parent_info = parent_info
 116         self.src = fp.read()
 117         if self.src == '' or self.src[-1] != '\n':
 118             self.src += '\n'
 119         self.cursor = 0
 120         self.line = 1
 121         self.line_pos = 0
 122         self.exprs = []
 123         self.accept()
 124
 125         while self.tok != None:
 126             expr_info = {'file': input_relname, 'line': self.line, 'parent': self.parent_info}
 127             expr = self.get_expr(False)
 128             if isinstance(expr, dict) and "include" in expr:
 129                 if len(expr) != 1:
 130                     raise QAPIExprError(expr_info, "Invalid 'include' directive")
 131                 include = expr["include"]
 132                 if not isinstance(include, str):
 133                     raise QAPIExprError(expr_info,
 134                                         'Expected a file name (string), got: %s'
 135                                         % include)
 136                 include_path = os.path.join(self.input_dir, include)
 137                 for elem in self.include_hist:
 138                     if include_path == elem[1]:
 139                         raise QAPIExprError(expr_info, "Inclusion loop for %s"
 140                                             % include)
 141                 # skip multiple include of the same file
 142                 if include_path in previously_included:
 143                     continue
 144                 try:
 145                     fobj = open(include_path, 'r')
 146                 except IOError, e:
 147                     raise QAPIExprError(expr_info,
 148                                         '%s: %s' % (e.strerror, include))
 149                 exprs_include = QAPISchema(fobj, include, self.include_hist,
 150                                            previously_included, expr_info)
 151                 self.exprs.extend(exprs_include.exprs)
 152             else:
 153                 expr_elem = {'expr': expr,
 154                              'info': expr_info}
 155                 self.exprs.append(expr_elem)
 156
 157     def accept(self):
 158         while True:
 159             self.tok = self.src[self.cursor]
 160             self.pos = self.cursor
 161             self.cursor += 1
 162             self.val = None
 163
 164             if self.tok == '#':
 165                 self.cursor = self.src.find('\n', self.cursor)
 166             elif self.tok in ['{', '}', ':', ',', '[', ']']:
 167                 return
 168             elif self.tok == "'":
 169                 string = ''
 170                 esc = False
 171                 while True:
 172                     ch = self.src[self.cursor]
 173                     self.cursor += 1
 174                     if ch == '\n':
 175                         raise QAPISchemaError(self,
 176                                               'Missing terminating "\'"')
 177                     if esc:
 178                         if ch == 'b':
 179                             string += '\b'
 180                         elif ch == 'f':
 181                             string += '\f'
 182                         elif ch == 'n':
 183                             string += '\n'
 184                         elif ch == 'r':
 185                             string += '\r'
 186                         elif ch == 't':
 187                             string += '\t'
 188                         elif ch == 'u':
 189                             value = 0
 190                             for x in range(0, 4):
 191                                 ch = self.src[self.cursor]
 192                                 self.cursor += 1
 193                                 if ch not in "0123456789abcdefABCDEF":
 194                                     raise QAPISchemaError(self,
 195                                                           '\\u escape needs 4 '
 196                                                           'hex digits')
 197                                 value = (value << 4) + int(ch, 16)
 198                             # If Python 2 and 3 didn't disagree so much on
 199                             # how to handle Unicode, then we could allow
 200                             # Unicode string defaults.  But most of QAPI is
 201                             # ASCII-only, so we aren't losing much for now.
 202                             if not value or value > 0x7f:
 203                                 raise QAPISchemaError(self,
 204                                                       'For now, \\u escape '
 205                                                       'only supports non-zero '
 206                                                       'values up to \\u007f')
 207                             string += chr(value)
 208                         elif ch in "\\/'\"":
 209                             string += ch
 210                         else:
 211                             raise QAPISchemaError(self,
 212                                                   "Unknown escape \\%s" %ch)
 213                         esc = False
 214                     elif ch == "\\":
 215                         esc = True
 216                     elif ch == "'":
 217                         self.val = string
 218                         return
 219                     else:
 220                         string += ch
 221             elif self.tok in "tfn":
 222                 val = self.src[self.cursor - 1:]
 223                 if val.startswith("true"):
 224                     self.val = True
 225                     self.cursor += 3
 226                     return
 227                 elif val.startswith("false"):
 228                     self.val = False
 229                     self.cursor += 4
 230                     return
 231                 elif val.startswith("null"):
 232                     self.val = None
 233                     self.cursor += 3
 234                     return
 235             elif self.tok == '\n':
 236                 if self.cursor == len(self.src):
 237                     self.tok = None
 238                     return
 239                 self.line += 1
 240                 self.line_pos = self.cursor
 241             elif not self.tok.isspace():
 242                 raise QAPISchemaError(self, 'Stray "%s"' % self.tok)
 243
 244     def get_members(self):
 245         expr = OrderedDict()
 246         if self.tok == '}':
 247             self.accept()
 248             return expr
 249         if self.tok != "'":
 250             raise QAPISchemaError(self, 'Expected string or "}"')
 251         while True:
 252             key = self.val
 253             self.accept()
 254             if self.tok != ':':
 255                 raise QAPISchemaError(self, 'Expected ":"')
 256             self.accept()
 257             if key in expr:
 258                 raise QAPISchemaError(self, 'Duplicate key "%s"' % key)
 259             expr[key] = self.get_expr(True)
 260             if self.tok == '}':
 261                 self.accept()
 262                 return expr
 263             if self.tok != ',':
 264                 raise QAPISchemaError(self, 'Expected "," or "}"')
 265             self.accept()
 266             if self.tok != "'":
 267                 raise QAPISchemaError(self, 'Expected string')
 268
 269     def get_values(self):
 270         expr = []
 271         if self.tok == ']':
 272             self.accept()
 273             return expr
 274         if not self.tok in "{['tfn":
 275             raise QAPISchemaError(self, 'Expected "{", "[", "]", string, '
 276                                   'boolean or "null"')
 277         while True:
 278             expr.append(self.get_expr(True))
 279             if self.tok == ']':
 280                 self.accept()
 281                 return expr
 282             if self.tok != ',':
 283                 raise QAPISchemaError(self, 'Expected "," or "]"')
 284             self.accept()
 285
 286     def get_expr(self, nested):
 287         if self.tok != '{' and not nested:
 288             raise QAPISchemaError(self, 'Expected "{"')
 289         if self.tok == '{':
 290             self.accept()
 291             expr = self.get_members()
 292         elif self.tok == '[':
 293             self.accept()
 294             expr = self.get_values()
 295         elif self.tok in "'tfn":
 296             expr = self.val
 297             self.accept()
 298         else:
 299             raise QAPISchemaError(self, 'Expected "{", "[" or string')
 300         return expr
 301
 302 def find_base_fields(base):
 303     base_struct_define = find_struct(base)
 304     if not base_struct_define:
 305         return None
 306     return base_struct_define['data']
 307
 308 # Return the qtype of an alternate branch, or None on error.
 309 def find_alternate_member_qtype(qapi_type):
 310     if builtin_types.has_key(qapi_type):
 311         return builtin_types[qapi_type]
 312     elif find_struct(qapi_type):
 313         return "QTYPE_QDICT"
 314     elif find_enum(qapi_type):
 315         return "QTYPE_QSTRING"
 316     elif find_union(qapi_type):
 317         return "QTYPE_QDICT"
 318     return None
 319
 320 # Return the discriminator enum define if discriminator is specified as an
 321 # enum type, otherwise return None.
 322 def discriminator_find_enum_define(expr):
 323     base = expr.get('base')
 324     discriminator = expr.get('discriminator')
 325
 326     if not (discriminator and base):
 327         return None
 328
 329     base_fields = find_base_fields(base)
 330     if not base_fields:
 331         return None
 332
 333     discriminator_type = base_fields.get(discriminator)
 334     if not discriminator_type:
 335         return None
 336
 337     return find_enum(discriminator_type)
 338
 339 valid_name = re.compile('^[a-zA-Z_][a-zA-Z0-9_.-]*$')
 340 def check_name(expr_info, source, name, allow_optional = False,
 341                enum_member = False):
 342     global valid_name
 343     membername = name
 344
 345     if not isinstance(name, str):
 346         raise QAPIExprError(expr_info,
 347                             "%s requires a string name" % source)
 348     if name.startswith('*'):
 349         membername = name[1:]
 350         if not allow_optional:
 351             raise QAPIExprError(expr_info,
 352                                 "%s does not allow optional name '%s'"
 353                                 % (source, name))
 354     # Enum members can start with a digit, because the generated C
 355     # code always prefixes it with the enum name
 356     if enum_member:
 357         membername = '_' + membername
 358     if not valid_name.match(membername):
 359         raise QAPIExprError(expr_info,
 360                             "%s uses invalid name '%s'" % (source, name))
 361
 362 def check_type(expr_info, source, value, allow_array = False,
 363                allow_dict = False, allow_optional = False,
 364                allow_star = False, allow_metas = []):
 365     global all_names
 366     orig_value = value
 367
 368     if value is None:
 369         return
 370
 371     if allow_star and value == '**':
 372         return
 373
 374     # Check if array type for value is okay
 375     if isinstance(value, list):
 376         if not allow_array:
 377             raise QAPIExprError(expr_info,
 378                                 "%s cannot be an array" % source)
 379         if len(value) != 1 or not isinstance(value[0], str):
 380             raise QAPIExprError(expr_info,
 381                                 "%s: array type must contain single type name"
 382                                 % source)
 383         value = value[0]
 384         orig_value = "array of %s" %value
 385
 386     # Check if type name for value is okay
 387     if isinstance(value, str):
 388         if value == '**':
 389             raise QAPIExprError(expr_info,
 390                                 "%s uses '**' but did not request 'gen':false"
 391                                 % source)
 392         if not value in all_names:
 393             raise QAPIExprError(expr_info,
 394                                 "%s uses unknown type '%s'"
 395                                 % (source, orig_value))
 396         if not all_names[value] in allow_metas:
 397             raise QAPIExprError(expr_info,
 398                                 "%s cannot use %s type '%s'"
 399                                 % (source, all_names[value], orig_value))
 400         return
 401
 402     # value is a dictionary, check that each member is okay
 403     if not isinstance(value, OrderedDict):
 404         raise QAPIExprError(expr_info,
 405                             "%s should be a dictionary" % source)
 406     if not allow_dict:
 407         raise QAPIExprError(expr_info,
 408                             "%s should be a type name" % source)
 409     for (key, arg) in value.items():
 410         check_name(expr_info, "Member of %s" % source, key,
 411                    allow_optional=allow_optional)
 412         # Todo: allow dictionaries to represent default values of
 413         # an optional argument.
 414         check_type(expr_info, "Member '%s' of %s" % (key, source), arg,
 415                    allow_array=True, allow_star=allow_star,
 416                    allow_metas=['built-in', 'union', 'alternate', 'struct',
 417                                 'enum'])
 418
 419 def check_member_clash(expr_info, base_name, data, source = ""):
 420     base = find_struct(base_name)
 421     assert base
 422     base_members = base['data']
 423     for key in data.keys():
 424         if key.startswith('*'):
 425             key = key[1:]
 426         if key in base_members or "*" + key in base_members:
 427             raise QAPIExprError(expr_info,
 428                                 "Member name '%s'%s clashes with base '%s'"
 429                                 % (key, source, base_name))
 430     if base.get('base'):
 431         check_member_clash(expr_info, base['base'], data, source)
 432
 433 def check_command(expr, expr_info):
 434     name = expr['command']
 435     allow_star = expr.has_key('gen')
 436
 437     check_type(expr_info, "'data' for command '%s'" % name,
 438                expr.get('data'), allow_dict=True, allow_optional=True,
 439                allow_metas=['union', 'struct'], allow_star=allow_star)
 440     returns_meta = ['union', 'struct']
 441     if name in returns_whitelist:
 442         returns_meta += ['built-in', 'alternate', 'enum']
 443     check_type(expr_info, "'returns' for command '%s'" % name,
 444                expr.get('returns'), allow_array=True, allow_dict=True,
 445                allow_optional=True, allow_metas=returns_meta,
 446                allow_star=allow_star)
 447
 448 def check_event(expr, expr_info):
 449     global events
 450     name = expr['event']
 451     params = expr.get('data')
 452
 453     if name.upper() == 'MAX':
 454         raise QAPIExprError(expr_info, "Event name 'MAX' cannot be created")
 455     events.append(name)
 456     check_type(expr_info, "'data' for event '%s'" % name,
 457                expr.get('data'), allow_dict=True, allow_optional=True,
 458                allow_metas=['union', 'struct'])
 459
 460 def check_union(expr, expr_info):
 461     name = expr['union']
 462     base = expr.get('base')
 463     discriminator = expr.get('discriminator')
 464     members = expr['data']
 465     values = { 'MAX': '(automatic)' }
 466
 467     # If the object has a member 'base', its value must name a struct,
 468     # and there must be a discriminator.
 469     if base is not None:
 470         if discriminator is None:
 471             raise QAPIExprError(expr_info,
 472                                 "Union '%s' requires a discriminator to go "
 473                                 "along with base" %name)
 474
 475     # Two types of unions, determined by discriminator.
 476
 477     # With no discriminator it is a simple union.
 478     if discriminator is None:
 479         enum_define = None
 480         allow_metas=['built-in', 'union', 'alternate', 'struct', 'enum']
 481         if base is not None:
 482             raise QAPIExprError(expr_info,
 483                                 "Simple union '%s' must not have a base"
 484                                 % name)
 485
 486     # Else, it's a flat union.
 487     else:
 488         # The object must have a string member 'base'.
 489         if not isinstance(base, str):
 490             raise QAPIExprError(expr_info,
 491                                 "Flat union '%s' must have a string base field"
 492                                 % name)
 493         base_fields = find_base_fields(base)
 494         if not base_fields:
 495             raise QAPIExprError(expr_info,
 496                                 "Base '%s' is not a valid struct"
 497                                 % base)
 498
 499         # The value of member 'discriminator' must name a non-optional
 500         # member of the base struct.
 501         check_name(expr_info, "Discriminator of flat union '%s'" % name,
 502                    discriminator)
 503         discriminator_type = base_fields.get(discriminator)
 504         if not discriminator_type:
 505             raise QAPIExprError(expr_info,
 506                                 "Discriminator '%s' is not a member of base "
 507                                 "struct '%s'"
 508                                 % (discriminator, base))
 509         enum_define = find_enum(discriminator_type)
 510         allow_metas=['struct']
 511         # Do not allow string discriminator
 512         if not enum_define:
 513             raise QAPIExprError(expr_info,
 514                                 "Discriminator '%s' must be of enumeration "
 515                                 "type" % discriminator)
 516
 517     # Check every branch
 518     for (key, value) in members.items():
 519         check_name(expr_info, "Member of union '%s'" % name, key)
 520
 521         # Each value must name a known type; furthermore, in flat unions,
 522         # branches must be a struct with no overlapping member names
 523         check_type(expr_info, "Member '%s' of union '%s'" % (key, name),
 524                    value, allow_array=True, allow_metas=allow_metas)
 525         if base:
 526             branch_struct = find_struct(value)
 527             assert branch_struct
 528             check_member_clash(expr_info, base, branch_struct['data'],
 529                                " of branch '%s'" % key)
 530
 531         # If the discriminator names an enum type, then all members
 532         # of 'data' must also be members of the enum type.
 533         if enum_define:
 534             if not key in enum_define['enum_values']:
 535                 raise QAPIExprError(expr_info,
 536                                     "Discriminator value '%s' is not found in "
 537                                     "enum '%s'" %
 538                                     (key, enum_define["enum_name"]))
 539
 540         # Otherwise, check for conflicts in the generated enum
 541         else:
 542             c_key = camel_to_upper(key)
 543             if c_key in values:
 544                 raise QAPIExprError(expr_info,
 545                                     "Union '%s' member '%s' clashes with '%s'"
 546                                     % (name, key, values[c_key]))
 547             values[c_key] = key
 548
 549 def check_alternate(expr, expr_info):
 550     name = expr['alternate']
 551     members = expr['data']
 552     values = { 'MAX': '(automatic)' }
 553     types_seen = {}
 554
 555     # Check every branch
 556     for (key, value) in members.items():
 557         check_name(expr_info, "Member of alternate '%s'" % name, key)
 558
 559         # Check for conflicts in the generated enum
 560         c_key = camel_to_upper(key)
 561         if c_key in values:
 562             raise QAPIExprError(expr_info,
 563                                 "Alternate '%s' member '%s' clashes with '%s'"
 564                                 % (name, key, values[c_key]))
 565         values[c_key] = key
 566
 567         # Ensure alternates have no type conflicts.
 568         check_type(expr_info, "Member '%s' of alternate '%s'" % (key, name),
 569                    value,
 570                    allow_metas=['built-in', 'union', 'struct', 'enum'])
 571         qtype = find_alternate_member_qtype(value)
 572         assert qtype
 573         if qtype in types_seen:
 574             raise QAPIExprError(expr_info,
 575                                 "Alternate '%s' member '%s' can't "
 576                                 "be distinguished from member '%s'"
 577                                 % (name, key, types_seen[qtype]))
 578         types_seen[qtype] = key
 579
 580 def check_enum(expr, expr_info):
 581     name = expr['enum']
 582     members = expr.get('data')
 583     values = { 'MAX': '(automatic)' }
 584
 585     if not isinstance(members, list):
 586         raise QAPIExprError(expr_info,
 587                             "Enum '%s' requires an array for 'data'" % name)
 588     for member in members:
 589         check_name(expr_info, "Member of enum '%s'" %name, member,
 590                    enum_member=True)
 591         key = camel_to_upper(member)
 592         if key in values:
 593             raise QAPIExprError(expr_info,
 594                                 "Enum '%s' member '%s' clashes with '%s'"
 595                                 % (name, member, values[key]))
 596         values[key] = member
 597
 598 def check_struct(expr, expr_info):
 599     name = expr['struct']
 600     members = expr['data']
 601
 602     check_type(expr_info, "'data' for struct '%s'" % name, members,
 603                allow_dict=True, allow_optional=True)
 604     check_type(expr_info, "'base' for struct '%s'" % name, expr.get('base'),
 605                allow_metas=['struct'])
 606     if expr.get('base'):
 607         check_member_clash(expr_info, expr['base'], expr['data'])
 608
 609 def check_exprs(schema):
 610     for expr_elem in schema.exprs:
 611         expr = expr_elem['expr']
 612         info = expr_elem['info']
 613
 614         if expr.has_key('enum'):
 615             check_enum(expr, info)
 616         elif expr.has_key('union'):
 617             check_union(expr, info)
 618         elif expr.has_key('alternate'):
 619             check_alternate(expr, info)
 620         elif expr.has_key('struct'):
 621             check_struct(expr, info)
 622         elif expr.has_key('command'):
 623             check_command(expr, info)
 624         elif expr.has_key('event'):
 625             check_event(expr, info)
 626         else:
 627             assert False, 'unexpected meta type'
 628
 629 def check_keys(expr_elem, meta, required, optional=[]):
 630     expr = expr_elem['expr']
 631     info = expr_elem['info']
 632     name = expr[meta]
 633     if not isinstance(name, str):
 634         raise QAPIExprError(info,
 635                             "'%s' key must have a string value" % meta)
 636     required = required + [ meta ]
 637     for (key, value) in expr.items():
 638         if not key in required and not key in optional:
 639             raise QAPIExprError(info,
 640                                 "Unknown key '%s' in %s '%s'"
 641                                 % (key, meta, name))
 642         if (key == 'gen' or key == 'success-response') and value != False:
 643             raise QAPIExprError(info,
 644                                 "'%s' of %s '%s' should only use false value"
 645                                 % (key, meta, name))
 646     for key in required:
 647         if not expr.has_key(key):
 648             raise QAPIExprError(info,
 649                                 "Key '%s' is missing from %s '%s'"
 650                                 % (key, meta, name))
 651
 652
 653 def parse_schema(input_file):
 654     global all_names
 655     exprs = []
 656
 657     # First pass: read entire file into memory
 658     try:
 659         schema = QAPISchema(open(input_file, "r"))
 660     except (QAPISchemaError, QAPIExprError), e:
 661         print >>sys.stderr, e
 662         exit(1)
 663
 664     try:
 665         # Next pass: learn the types and check for valid expression keys. At
 666         # this point, top-level 'include' has already been flattened.
 667         for builtin in builtin_types.keys():
 668             all_names[builtin] = 'built-in'
 669         for expr_elem in schema.exprs:
 670             expr = expr_elem['expr']
 671             info = expr_elem['info']
 672             if expr.has_key('enum'):
 673                 check_keys(expr_elem, 'enum', ['data'])
 674                 add_enum(expr['enum'], info, expr['data'])
 675             elif expr.has_key('union'):
 676                 check_keys(expr_elem, 'union', ['data'],
 677                            ['base', 'discriminator'])
 678                 add_union(expr, info)
 679             elif expr.has_key('alternate'):
 680                 check_keys(expr_elem, 'alternate', ['data'])
 681                 add_name(expr['alternate'], info, 'alternate')
 682             elif expr.has_key('struct'):
 683                 check_keys(expr_elem, 'struct', ['data'], ['base'])
 684                 add_struct(expr, info)
 685             elif expr.has_key('command'):
 686                 check_keys(expr_elem, 'command', [],
 687                            ['data', 'returns', 'gen', 'success-response'])
 688                 add_name(expr['command'], info, 'command')
 689             elif expr.has_key('event'):
 690                 check_keys(expr_elem, 'event', [], ['data'])
 691                 add_name(expr['event'], info, 'event')
 692             else:
 693                 raise QAPIExprError(expr_elem['info'],
 694                                     "Expression is missing metatype")
 695             exprs.append(expr)
 696
 697         # Try again for hidden UnionKind enum
 698         for expr_elem in schema.exprs:
 699             expr = expr_elem['expr']
 700             if expr.has_key('union'):
 701                 if not discriminator_find_enum_define(expr):
 702                     add_enum('%sKind' % expr['union'], expr_elem['info'],
 703                              implicit=True)
 704             elif expr.has_key('alternate'):
 705                 add_enum('%sKind' % expr['alternate'], expr_elem['info'],
 706                          implicit=True)
 707
 708         # Final pass - validate that exprs make sense
 709         check_exprs(schema)
 710     except QAPIExprError, e:
 711         print >>sys.stderr, e
 712         exit(1)
 713
 714     return exprs
 715
 716 def parse_args(typeinfo):
 717     if isinstance(typeinfo, str):
 718         struct = find_struct(typeinfo)
 719         assert struct != None
 720         typeinfo = struct['data']
 721
 722     for member in typeinfo:
 723         argname = member
 724         argentry = typeinfo[member]
 725         optional = False
 726         if member.startswith('*'):
 727             argname = member[1:]
 728             optional = True
 729         # Todo: allow argentry to be OrderedDict, for providing the
 730         # value of an optional argument.
 731         yield (argname, argentry, optional)
 732
 733 def camel_case(name):
 734     new_name = ''
 735     first = True
 736     for ch in name:
 737         if ch in ['_', '-']:
 738             first = True
 739         elif first:
 740             new_name += ch.upper()
 741             first = False
 742         else:
 743             new_name += ch.lower()
 744     return new_name
 745
 746 # ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1
 747 # ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2
 748 # ENUM24_Name -> ENUM24_NAME
 749 def camel_to_upper(value):
 750     c_fun_str = c_name(value, False)
 751     if value.isupper():
 752         return c_fun_str
 753
 754     new_name = ''
 755     l = len(c_fun_str)
 756     for i in range(l):
 757         c = c_fun_str[i]
 758         # When c is upper and no "_" appears before, do more checks
 759         if c.isupper() and (i > 0) and c_fun_str[i - 1] != "_":
 760             # Case 1: next string is lower
 761             # Case 2: previous string is digit
 762             if (i < (l - 1) and c_fun_str[i + 1].islower()) or \
 763             c_fun_str[i - 1].isdigit():
 764                 new_name += '_'
 765         new_name += c
 766     return new_name.lstrip('_').upper()
 767
 768 def c_enum_const(type_name, const_name):
 769     return camel_to_upper(type_name + '_' + const_name)
 770
 771 c_name_trans = string.maketrans('.-', '__')
 772
 773 # Map @name to a valid C identifier.
 774 # If @protect, avoid returning certain ticklish identifiers (like
 775 # C keywords) by prepending "q_".
 776 #
 777 # Used for converting 'name' from a 'name':'type' qapi definition
 778 # into a generated struct member, as well as converting type names
 779 # into substrings of a generated C function name.
 780 # '__a.b_c' -> '__a_b_c', 'x-foo' -> 'x_foo'
 781 # protect=True: 'int' -> 'q_int'; protect=False: 'int' -> 'int'
 782 def c_name(name, protect=True):
 783     # ANSI X3J11/88-090, 3.1.1
 784     c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
 785                      'default', 'do', 'double', 'else', 'enum', 'extern', 'float',
 786                      'for', 'goto', 'if', 'int', 'long', 'register', 'return',
 787                      'short', 'signed', 'sizeof', 'static', 'struct', 'switch',
 788                      'typedef', 'union', 'unsigned', 'void', 'volatile', 'while'])
 789     # ISO/IEC 9899:1999, 6.4.1
 790     c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary'])
 791     # ISO/IEC 9899:2011, 6.4.1
 792     c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic', '_Noreturn',
 793                      '_Static_assert', '_Thread_local'])
 794     # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html
 795     # excluding _.*
 796     gcc_words = set(['asm', 'typeof'])
 797     # C++ ISO/IEC 14882:2003 2.11
 798     cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete',
 799                      'dynamic_cast', 'explicit', 'false', 'friend', 'mutable',
 800                      'namespace', 'new', 'operator', 'private', 'protected',
 801                      'public', 'reinterpret_cast', 'static_cast', 'template',
 802                      'this', 'throw', 'true', 'try', 'typeid', 'typename',
 803                      'using', 'virtual', 'wchar_t',
 804                      # alternative representations
 805                      'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not',
 806                      'not_eq', 'or', 'or_eq', 'xor', 'xor_eq'])
 807     # namespace pollution:
 808     polluted_words = set(['unix', 'errno'])
 809     if protect and (name in c89_words | c99_words | c11_words | gcc_words | cpp_words | polluted_words):
 810         return "q_" + name
 811     return name.translate(c_name_trans)
 812
 813 # Map type @name to the C typedef name for the list form.
 814 #
 815 # ['Name'] -> 'NameList', ['x-Foo'] -> 'x_FooList', ['int'] -> 'intList'
 816 def c_list_type(name):
 817     return type_name(name) + 'List'
 818
 819 # Map type @value to the C typedef form.
 820 #
 821 # Used for converting 'type' from a 'member':'type' qapi definition
 822 # into the alphanumeric portion of the type for a generated C parameter,
 823 # as well as generated C function names.  See c_type() for the rest of
 824 # the conversion such as adding '*' on pointer types.
 825 # 'int' -> 'int', '[x-Foo]' -> 'x_FooList', '__a.b_c' -> '__a_b_c'
 826 def type_name(value):
 827     if type(value) == list:
 828         return c_list_type(value[0])
 829     if value in builtin_types.keys():
 830         return value
 831     return c_name(value)
 832
 833 def add_name(name, info, meta, implicit = False):
 834     global all_names
 835     check_name(info, "'%s'" % meta, name)
 836     if name in all_names:
 837         raise QAPIExprError(info,
 838                             "%s '%s' is already defined"
 839                             % (all_names[name], name))
 840     if not implicit and name[-4:] == 'Kind':
 841         raise QAPIExprError(info,
 842                             "%s '%s' should not end in 'Kind'"
 843                             % (meta, name))
 844     all_names[name] = meta
 845
 846 def add_struct(definition, info):
 847     global struct_types
 848     name = definition['struct']
 849     add_name(name, info, 'struct')
 850     struct_types.append(definition)
 851
 852 def find_struct(name):
 853     global struct_types
 854     for struct in struct_types:
 855         if struct['struct'] == name:
 856             return struct
 857     return None
 858
 859 def add_union(definition, info):
 860     global union_types
 861     name = definition['union']
 862     add_name(name, info, 'union')
 863     union_types.append(definition)
 864
 865 def find_union(name):
 866     global union_types
 867     for union in union_types:
 868         if union['union'] == name:
 869             return union
 870     return None
 871
 872 def add_enum(name, info, enum_values = None, implicit = False):
 873     global enum_types
 874     add_name(name, info, 'enum', implicit)
 875     enum_types.append({"enum_name": name, "enum_values": enum_values})
 876
 877 def find_enum(name):
 878     global enum_types
 879     for enum in enum_types:
 880         if enum['enum_name'] == name:
 881             return enum
 882     return None
 883
 884 def is_enum(name):
 885     return find_enum(name) != None
 886
 887 eatspace = '\033EATSPACE.'
 888 pointer_suffix = ' *' + eatspace
 889
 890 # Map type @name to its C type expression.
 891 # If @is_param, const-qualify the string type.
 892 #
 893 # This function is used for computing the full C type of 'member':'name'.
 894 # A special suffix is added in c_type() for pointer types, and it's
 895 # stripped in mcgen(). So please notice this when you check the return
 896 # value of c_type() outside mcgen().
 897 def c_type(value, is_param=False):
 898     if value == 'str':
 899         if is_param:
 900             return 'const char' + pointer_suffix
 901         return 'char' + pointer_suffix
 902
 903     elif value == 'int':
 904         return 'int64_t'
 905     elif (value == 'int8' or value == 'int16' or value == 'int32' or
 906           value == 'int64' or value == 'uint8' or value == 'uint16' or
 907           value == 'uint32' or value == 'uint64'):
 908         return value + '_t'
 909     elif value == 'size':
 910         return 'uint64_t'
 911     elif value == 'bool':
 912         return 'bool'
 913     elif value == 'number':
 914         return 'double'
 915     elif type(value) == list:
 916         return c_list_type(value[0]) + pointer_suffix
 917     elif is_enum(value):
 918         return c_name(value)
 919     elif value == None:
 920         return 'void'
 921     elif value in events:
 922         return camel_case(value) + 'Event' + pointer_suffix
 923     else:
 924         # complex type name
 925         assert isinstance(value, str) and value != ""
 926         return c_name(value) + pointer_suffix
 927
 928 def is_c_ptr(value):
 929     return c_type(value).endswith(pointer_suffix)
 930
 931 def genindent(count):
 932     ret = ""
 933     for i in range(count):
 934         ret += " "
 935     return ret
 936
 937 indent_level = 0
 938
 939 def push_indent(indent_amount=4):
 940     global indent_level
 941     indent_level += indent_amount
 942
 943 def pop_indent(indent_amount=4):
 944     global indent_level
 945     indent_level -= indent_amount
 946
 947 def cgen(code, **kwds):
 948     indent = genindent(indent_level)
 949     lines = code.split('\n')
 950     lines = map(lambda x: indent + x, lines)
 951     return '\n'.join(lines) % kwds + '\n'
 952
 953 def mcgen(code, **kwds):
 954     raw = cgen('\n'.join(code.split('\n')[1:-1]), **kwds)
 955     return re.sub(re.escape(eatspace) + ' *', '', raw)
 956
 957 def basename(filename):
 958     return filename.split("/")[-1]
 959
 960 def guardname(filename):
 961     guard = basename(filename).rsplit(".", 1)[0]
 962     for substr in [".", " ", "-"]:
 963         guard = guard.replace(substr, "_")
 964     return guard.upper() + '_H'
 965
 966 def guardstart(name):
 967     return mcgen('''
 968
 969 #ifndef %(name)s
 970 #define %(name)s
 971
 972 ''',
 973                  name=guardname(name))
 974
 975 def guardend(name):
 976     return mcgen('''
 977
 978 #endif /* %(name)s */
 979
 980 ''',
 981                  name=guardname(name))
 982
 983 def parse_command_line(extra_options = "", extra_long_options = []):
 984
 985     try:
 986         opts, args = getopt.gnu_getopt(sys.argv[1:],
 987                                        "chp:i:o:" + extra_options,
 988                                        ["source", "header", "prefix=",
 989                                         "input-file=", "output-dir="]
 990                                        + extra_long_options)
 991     except getopt.GetoptError, err:
 992         print str(err)
 993         sys.exit(1)
 994
 995     output_dir = ""
 996     prefix = ""
 997     do_c = False
 998     do_h = False
 999     extra_opts = []
1000
1001     for oa in opts:
1002         o, a = oa
1003         if o in ("-p", "--prefix"):
1004             prefix = a
1005         elif o in ("-i", "--input-file"):
1006             input_file = a
1007         elif o in ("-o", "--output-dir"):
1008             output_dir = a + "/"
1009         elif o in ("-c", "--source"):
1010             do_c = True
1011         elif o in ("-h", "--header"):
1012             do_h = True
1013         else:
1014             extra_opts.append(oa)
1015
1016     if not do_c and not do_h:
1017         do_c = True
1018         do_h = True
1019
1020     return (input_file, output_dir, do_c, do_h, prefix, extra_opts)