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 os
  17 import sys
  18
  19 builtin_types = {
  20     'str':      'QTYPE_QSTRING',
  21     'int':      'QTYPE_QINT',
  22     'number':   'QTYPE_QFLOAT',
  23     'bool':     'QTYPE_QBOOL',
  24     'int8':     'QTYPE_QINT',
  25     'int16':    'QTYPE_QINT',
  26     'int32':    'QTYPE_QINT',
  27     'int64':    'QTYPE_QINT',
  28     'uint8':    'QTYPE_QINT',
  29     'uint16':   'QTYPE_QINT',
  30     'uint32':   'QTYPE_QINT',
  31     'uint64':   'QTYPE_QINT',
  32     'size':     'QTYPE_QINT',
  33 }
  34
  35 def error_path(parent):
  36     res = ""
  37     while parent:
  38         res = ("In file included from %s:%d:\n" % (parent['file'],
  39                                                    parent['line'])) + res
  40         parent = parent['parent']
  41     return res
  42
  43 class QAPISchemaError(Exception):
  44     def __init__(self, schema, msg):
  45         self.input_file = schema.input_file
  46         self.msg = msg
  47         self.col = 1
  48         self.line = schema.line
  49         for ch in schema.src[schema.line_pos:schema.pos]:
  50             if ch == '\t':
  51                 self.col = (self.col + 7) % 8 + 1
  52             else:
  53                 self.col += 1
  54         self.info = schema.parent_info
  55
  56     def __str__(self):
  57         return error_path(self.info) + \
  58             "%s:%d:%d: %s" % (self.input_file, self.line, self.col, self.msg)
  59
  60 class QAPIExprError(Exception):
  61     def __init__(self, expr_info, msg):
  62         self.info = expr_info
  63         self.msg = msg
  64
  65     def __str__(self):
  66         return error_path(self.info['parent']) + \
  67             "%s:%d: %s" % (self.info['file'], self.info['line'], self.msg)
  68
  69 class QAPISchema:
  70
  71     def __init__(self, fp, input_relname=None, include_hist=[],
  72                  previously_included=[], parent_info=None):
  73         """ include_hist is a stack used to detect inclusion cycles
  74             previously_included is a global state used to avoid multiple
  75                                 inclusions of the same file"""
  76         input_fname = os.path.abspath(fp.name)
  77         if input_relname is None:
  78             input_relname = fp.name
  79         self.input_dir = os.path.dirname(input_fname)
  80         self.input_file = input_relname
  81         self.include_hist = include_hist + [(input_relname, input_fname)]
  82         previously_included.append(input_fname)
  83         self.parent_info = parent_info
  84         self.src = fp.read()
  85         if self.src == '' or self.src[-1] != '\n':
  86             self.src += '\n'
  87         self.cursor = 0
  88         self.line = 1
  89         self.line_pos = 0
  90         self.exprs = []
  91         self.accept()
  92
  93         while self.tok != None:
  94             expr_info = {'file': input_relname, 'line': self.line, 'parent': self.parent_info}
  95             expr = self.get_expr(False)
  96             if isinstance(expr, dict) and "include" in expr:
  97                 if len(expr) != 1:
  98                     raise QAPIExprError(expr_info, "Invalid 'include' directive")
  99                 include = expr["include"]
 100                 if not isinstance(include, str):
 101                     raise QAPIExprError(expr_info,
 102                                         'Expected a file name (string), got: %s'
 103                                         % include)
 104                 include_path = os.path.join(self.input_dir, include)
 105                 for elem in self.include_hist:
 106                     if include_path == elem[1]:
 107                         raise QAPIExprError(expr_info, "Inclusion loop for %s"
 108                                             % include)
 109                 # skip multiple include of the same file
 110                 if include_path in previously_included:
 111                     continue
 112                 try:
 113                     fobj = open(include_path, 'r')
 114                 except IOError, e:
 115                     raise QAPIExprError(expr_info,
 116                                         '%s: %s' % (e.strerror, include))
 117                 exprs_include = QAPISchema(fobj, include, self.include_hist,
 118                                            previously_included, expr_info)
 119                 self.exprs.extend(exprs_include.exprs)
 120             else:
 121                 expr_elem = {'expr': expr,
 122                              'info': expr_info}
 123                 self.exprs.append(expr_elem)
 124
 125     def accept(self):
 126         while True:
 127             self.tok = self.src[self.cursor]
 128             self.pos = self.cursor
 129             self.cursor += 1
 130             self.val = None
 131
 132             if self.tok == '#':
 133                 self.cursor = self.src.find('\n', self.cursor)
 134             elif self.tok in ['{', '}', ':', ',', '[', ']']:
 135                 return
 136             elif self.tok == "'":
 137                 string = ''
 138                 esc = False
 139                 while True:
 140                     ch = self.src[self.cursor]
 141                     self.cursor += 1
 142                     if ch == '\n':
 143                         raise QAPISchemaError(self,
 144                                               'Missing terminating "\'"')
 145                     if esc:
 146                         string += ch
 147                         esc = False
 148                     elif ch == "\\":
 149                         esc = True
 150                     elif ch == "'":
 151                         self.val = string
 152                         return
 153                     else:
 154                         string += ch
 155             elif self.tok == '\n':
 156                 if self.cursor == len(self.src):
 157                     self.tok = None
 158                     return
 159                 self.line += 1
 160                 self.line_pos = self.cursor
 161             elif not self.tok.isspace():
 162                 raise QAPISchemaError(self, 'Stray "%s"' % self.tok)
 163
 164     def get_members(self):
 165         expr = OrderedDict()
 166         if self.tok == '}':
 167             self.accept()
 168             return expr
 169         if self.tok != "'":
 170             raise QAPISchemaError(self, 'Expected string or "}"')
 171         while True:
 172             key = self.val
 173             self.accept()
 174             if self.tok != ':':
 175                 raise QAPISchemaError(self, 'Expected ":"')
 176             self.accept()
 177             if key in expr:
 178                 raise QAPISchemaError(self, 'Duplicate key "%s"' % key)
 179             expr[key] = self.get_expr(True)
 180             if self.tok == '}':
 181                 self.accept()
 182                 return expr
 183             if self.tok != ',':
 184                 raise QAPISchemaError(self, 'Expected "," or "}"')
 185             self.accept()
 186             if self.tok != "'":
 187                 raise QAPISchemaError(self, 'Expected string')
 188
 189     def get_values(self):
 190         expr = []
 191         if self.tok == ']':
 192             self.accept()
 193             return expr
 194         if not self.tok in [ '{', '[', "'" ]:
 195             raise QAPISchemaError(self, 'Expected "{", "[", "]" or string')
 196         while True:
 197             expr.append(self.get_expr(True))
 198             if self.tok == ']':
 199                 self.accept()
 200                 return expr
 201             if self.tok != ',':
 202                 raise QAPISchemaError(self, 'Expected "," or "]"')
 203             self.accept()
 204
 205     def get_expr(self, nested):
 206         if self.tok != '{' and not nested:
 207             raise QAPISchemaError(self, 'Expected "{"')
 208         if self.tok == '{':
 209             self.accept()
 210             expr = self.get_members()
 211         elif self.tok == '[':
 212             self.accept()
 213             expr = self.get_values()
 214         elif self.tok == "'":
 215             expr = self.val
 216             self.accept()
 217         else:
 218             raise QAPISchemaError(self, 'Expected "{", "[" or string')
 219         return expr
 220
 221 def find_base_fields(base):
 222     base_struct_define = find_struct(base)
 223     if not base_struct_define:
 224         return None
 225     return base_struct_define['data']
 226
 227 # Return the discriminator enum define if discriminator is specified as an
 228 # enum type, otherwise return None.
 229 def discriminator_find_enum_define(expr):
 230     base = expr.get('base')
 231     discriminator = expr.get('discriminator')
 232
 233     if not (discriminator and base):
 234         return None
 235
 236     base_fields = find_base_fields(base)
 237     if not base_fields:
 238         return None
 239
 240     discriminator_type = base_fields.get(discriminator)
 241     if not discriminator_type:
 242         return None
 243
 244     return find_enum(discriminator_type)
 245
 246 def check_event(expr, expr_info):
 247     params = expr.get('data')
 248     if params:
 249         for argname, argentry, optional, structured in parse_args(params):
 250             if structured:
 251                 raise QAPIExprError(expr_info,
 252                                     "Nested structure define in event is not "
 253                                     "supported, event '%s', argname '%s'"
 254                                     % (expr['event'], argname))
 255
 256 def check_union(expr, expr_info):
 257     name = expr['union']
 258     base = expr.get('base')
 259     discriminator = expr.get('discriminator')
 260     members = expr['data']
 261
 262     # If the object has a member 'base', its value must name a complex type.
 263     if base:
 264         base_fields = find_base_fields(base)
 265         if not base_fields:
 266             raise QAPIExprError(expr_info,
 267                                 "Base '%s' is not a valid type"
 268                                 % base)
 269
 270     # If the union object has no member 'discriminator', it's an
 271     # ordinary union.
 272     if not discriminator:
 273         enum_define = None
 274
 275     # Else if the value of member 'discriminator' is {}, it's an
 276     # anonymous union.
 277     elif discriminator == {}:
 278         enum_define = None
 279
 280     # Else, it's a flat union.
 281     else:
 282         # The object must have a member 'base'.
 283         if not base:
 284             raise QAPIExprError(expr_info,
 285                                 "Flat union '%s' must have a base field"
 286                                 % name)
 287         # The value of member 'discriminator' must name a member of the
 288         # base type.
 289         discriminator_type = base_fields.get(discriminator)
 290         if not discriminator_type:
 291             raise QAPIExprError(expr_info,
 292                                 "Discriminator '%s' is not a member of base "
 293                                 "type '%s'"
 294                                 % (discriminator, base))
 295         enum_define = find_enum(discriminator_type)
 296         # Do not allow string discriminator
 297         if not enum_define:
 298             raise QAPIExprError(expr_info,
 299                                 "Discriminator '%s' must be of enumeration "
 300                                 "type" % discriminator)
 301
 302     # Check every branch
 303     for (key, value) in members.items():
 304         # If this named member's value names an enum type, then all members
 305         # of 'data' must also be members of the enum type.
 306         if enum_define and not key in enum_define['enum_values']:
 307             raise QAPIExprError(expr_info,
 308                                 "Discriminator value '%s' is not found in "
 309                                 "enum '%s'" %
 310                                 (key, enum_define["enum_name"]))
 311         # Todo: add checking for values. Key is checked as above, value can be
 312         # also checked here, but we need more functions to handle array case.
 313
 314 def check_enum(expr, expr_info):
 315     name = expr['enum']
 316     members = expr.get('data')
 317     values = { 'MAX': '(automatic)' }
 318
 319     if not isinstance(members, list):
 320         raise QAPIExprError(expr_info,
 321                             "Enum '%s' requires an array for 'data'" % name)
 322     for member in members:
 323         if not isinstance(member, str):
 324             raise QAPIExprError(expr_info,
 325                                 "Enum '%s' member '%s' is not a string"
 326                                 % (name, member))
 327         key = _generate_enum_string(member)
 328         if key in values:
 329             raise QAPIExprError(expr_info,
 330                                 "Enum '%s' member '%s' clashes with '%s'"
 331                                 % (name, member, values[key]))
 332         values[key] = member
 333
 334 def check_exprs(schema):
 335     for expr_elem in schema.exprs:
 336         expr = expr_elem['expr']
 337         info = expr_elem['info']
 338
 339         if expr.has_key('enum'):
 340             check_enum(expr, info)
 341         elif expr.has_key('union'):
 342             check_union(expr, info)
 343         elif expr.has_key('event'):
 344             check_event(expr, info)
 345
 346 def parse_schema(input_file):
 347     try:
 348         schema = QAPISchema(open(input_file, "r"))
 349     except (QAPISchemaError, QAPIExprError), e:
 350         print >>sys.stderr, e
 351         exit(1)
 352
 353     exprs = []
 354
 355     for expr_elem in schema.exprs:
 356         expr = expr_elem['expr']
 357         if expr.has_key('enum'):
 358             add_enum(expr['enum'], expr.get('data'))
 359         elif expr.has_key('union'):
 360             add_union(expr)
 361         elif expr.has_key('type'):
 362             add_struct(expr)
 363         exprs.append(expr)
 364
 365     # Try again for hidden UnionKind enum
 366     for expr_elem in schema.exprs:
 367         expr = expr_elem['expr']
 368         if expr.has_key('union'):
 369             if not discriminator_find_enum_define(expr):
 370                 add_enum('%sKind' % expr['union'])
 371
 372     try:
 373         check_exprs(schema)
 374     except QAPIExprError, e:
 375         print >>sys.stderr, e
 376         exit(1)
 377
 378     return exprs
 379
 380 def parse_args(typeinfo):
 381     if isinstance(typeinfo, str):
 382         struct = find_struct(typeinfo)
 383         assert struct != None
 384         typeinfo = struct['data']
 385
 386     for member in typeinfo:
 387         argname = member
 388         argentry = typeinfo[member]
 389         optional = False
 390         structured = False
 391         if member.startswith('*'):
 392             argname = member[1:]
 393             optional = True
 394         if isinstance(argentry, OrderedDict):
 395             structured = True
 396         yield (argname, argentry, optional, structured)
 397
 398 def de_camel_case(name):
 399     new_name = ''
 400     for ch in name:
 401         if ch.isupper() and new_name:
 402             new_name += '_'
 403         if ch == '-':
 404             new_name += '_'
 405         else:
 406             new_name += ch.lower()
 407     return new_name
 408
 409 def camel_case(name):
 410     new_name = ''
 411     first = True
 412     for ch in name:
 413         if ch in ['_', '-']:
 414             first = True
 415         elif first:
 416             new_name += ch.upper()
 417             first = False
 418         else:
 419             new_name += ch.lower()
 420     return new_name
 421
 422 def c_var(name, protect=True):
 423     # ANSI X3J11/88-090, 3.1.1
 424     c89_words = set(['auto', 'break', 'case', 'char', 'const', 'continue',
 425                      'default', 'do', 'double', 'else', 'enum', 'extern', 'float',
 426                      'for', 'goto', 'if', 'int', 'long', 'register', 'return',
 427                      'short', 'signed', 'sizeof', 'static', 'struct', 'switch',
 428                      'typedef', 'union', 'unsigned', 'void', 'volatile', 'while'])
 429     # ISO/IEC 9899:1999, 6.4.1
 430     c99_words = set(['inline', 'restrict', '_Bool', '_Complex', '_Imaginary'])
 431     # ISO/IEC 9899:2011, 6.4.1
 432     c11_words = set(['_Alignas', '_Alignof', '_Atomic', '_Generic', '_Noreturn',
 433                      '_Static_assert', '_Thread_local'])
 434     # GCC http://gcc.gnu.org/onlinedocs/gcc-4.7.1/gcc/C-Extensions.html
 435     # excluding _.*
 436     gcc_words = set(['asm', 'typeof'])
 437     # C++ ISO/IEC 14882:2003 2.11
 438     cpp_words = set(['bool', 'catch', 'class', 'const_cast', 'delete',
 439                      'dynamic_cast', 'explicit', 'false', 'friend', 'mutable',
 440                      'namespace', 'new', 'operator', 'private', 'protected',
 441                      'public', 'reinterpret_cast', 'static_cast', 'template',
 442                      'this', 'throw', 'true', 'try', 'typeid', 'typename',
 443                      'using', 'virtual', 'wchar_t',
 444                      # alternative representations
 445                      'and', 'and_eq', 'bitand', 'bitor', 'compl', 'not',
 446                      'not_eq', 'or', 'or_eq', 'xor', 'xor_eq'])
 447     # namespace pollution:
 448     polluted_words = set(['unix', 'errno'])
 449     if protect and (name in c89_words | c99_words | c11_words | gcc_words | cpp_words | polluted_words):
 450         return "q_" + name
 451     return name.replace('-', '_').lstrip("*")
 452
 453 def c_fun(name, protect=True):
 454     return c_var(name, protect).replace('.', '_')
 455
 456 def c_list_type(name):
 457     return '%sList' % name
 458
 459 def type_name(name):
 460     if type(name) == list:
 461         return c_list_type(name[0])
 462     return name
 463
 464 enum_types = []
 465 struct_types = []
 466 union_types = []
 467
 468 def add_struct(definition):
 469     global struct_types
 470     struct_types.append(definition)
 471
 472 def find_struct(name):
 473     global struct_types
 474     for struct in struct_types:
 475         if struct['type'] == name:
 476             return struct
 477     return None
 478
 479 def add_union(definition):
 480     global union_types
 481     union_types.append(definition)
 482
 483 def find_union(name):
 484     global union_types
 485     for union in union_types:
 486         if union['union'] == name:
 487             return union
 488     return None
 489
 490 def add_enum(name, enum_values = None):
 491     global enum_types
 492     enum_types.append({"enum_name": name, "enum_values": enum_values})
 493
 494 def find_enum(name):
 495     global enum_types
 496     for enum in enum_types:
 497         if enum['enum_name'] == name:
 498             return enum
 499     return None
 500
 501 def is_enum(name):
 502     return find_enum(name) != None
 503
 504 eatspace = '\033EATSPACE.'
 505
 506 # A special suffix is added in c_type() for pointer types, and it's
 507 # stripped in mcgen(). So please notice this when you check the return
 508 # value of c_type() outside mcgen().
 509 def c_type(name, is_param=False):
 510     if name == 'str':
 511         if is_param:
 512             return 'const char *' + eatspace
 513         return 'char *' + eatspace
 514
 515     elif name == 'int':
 516         return 'int64_t'
 517     elif (name == 'int8' or name == 'int16' or name == 'int32' or
 518           name == 'int64' or name == 'uint8' or name == 'uint16' or
 519           name == 'uint32' or name == 'uint64'):
 520         return name + '_t'
 521     elif name == 'size':
 522         return 'uint64_t'
 523     elif name == 'bool':
 524         return 'bool'
 525     elif name == 'number':
 526         return 'double'
 527     elif type(name) == list:
 528         return '%s *%s' % (c_list_type(name[0]), eatspace)
 529     elif is_enum(name):
 530         return name
 531     elif name == None or len(name) == 0:
 532         return 'void'
 533     elif name == name.upper():
 534         return '%sEvent *%s' % (camel_case(name), eatspace)
 535     else:
 536         return '%s *%s' % (name, eatspace)
 537
 538 def is_c_ptr(name):
 539     suffix = "*" + eatspace
 540     return c_type(name).endswith(suffix)
 541
 542 def genindent(count):
 543     ret = ""
 544     for i in range(count):
 545         ret += " "
 546     return ret
 547
 548 indent_level = 0
 549
 550 def push_indent(indent_amount=4):
 551     global indent_level
 552     indent_level += indent_amount
 553
 554 def pop_indent(indent_amount=4):
 555     global indent_level
 556     indent_level -= indent_amount
 557
 558 def cgen(code, **kwds):
 559     indent = genindent(indent_level)
 560     lines = code.split('\n')
 561     lines = map(lambda x: indent + x, lines)
 562     return '\n'.join(lines) % kwds + '\n'
 563
 564 def mcgen(code, **kwds):
 565     raw = cgen('\n'.join(code.split('\n')[1:-1]), **kwds)
 566     return re.sub(re.escape(eatspace) + ' *', '', raw)
 567
 568 def basename(filename):
 569     return filename.split("/")[-1]
 570
 571 def guardname(filename):
 572     guard = basename(filename).rsplit(".", 1)[0]
 573     for substr in [".", " ", "-"]:
 574         guard = guard.replace(substr, "_")
 575     return guard.upper() + '_H'
 576
 577 def guardstart(name):
 578     return mcgen('''
 579
 580 #ifndef %(name)s
 581 #define %(name)s
 582
 583 ''',
 584                  name=guardname(name))
 585
 586 def guardend(name):
 587     return mcgen('''
 588
 589 #endif /* %(name)s */
 590
 591 ''',
 592                  name=guardname(name))
 593
 594 # ENUMName -> ENUM_NAME, EnumName1 -> ENUM_NAME1
 595 # ENUM_NAME -> ENUM_NAME, ENUM_NAME1 -> ENUM_NAME1, ENUM_Name2 -> ENUM_NAME2
 596 # ENUM24_Name -> ENUM24_NAME
 597 def _generate_enum_string(value):
 598     c_fun_str = c_fun(value, False)
 599     if value.isupper():
 600         return c_fun_str
 601
 602     new_name = ''
 603     l = len(c_fun_str)
 604     for i in range(l):
 605         c = c_fun_str[i]
 606         # When c is upper and no "_" appears before, do more checks
 607         if c.isupper() and (i > 0) and c_fun_str[i - 1] != "_":
 608             # Case 1: next string is lower
 609             # Case 2: previous string is digit
 610             if (i < (l - 1) and c_fun_str[i + 1].islower()) or \
 611             c_fun_str[i - 1].isdigit():
 612                 new_name += '_'
 613         new_name += c
 614     return new_name.lstrip('_').upper()
 615
 616 def generate_enum_full_value(enum_name, enum_value):
 617     abbrev_string = _generate_enum_string(enum_name)
 618     value_string = _generate_enum_string(enum_value)
 619     return "%s_%s" % (abbrev_string, value_string)