scripts/qapi/expr.py

   1 # -*- coding: utf-8 -*-
   2 #
   3 # Check (context-free) QAPI schema expression structure
   4 #
   5 # Copyright IBM, Corp. 2011
   6 # Copyright (c) 2013-2019 Red Hat Inc.
   7 #
   8 # Authors:
   9 #  Anthony Liguori <aliguori@us.ibm.com>
  10 #  Markus Armbruster <armbru@redhat.com>
  11 #  Eric Blake <eblake@redhat.com>
  12 #  Marc-André Lureau <marcandre.lureau@redhat.com>
  13 #
  14 # This work is licensed under the terms of the GNU GPL, version 2.
  15 # See the COPYING file in the top-level directory.
  16
  17 import re
  18 from collections import OrderedDict
  19 from qapi.common import c_name
  20 from qapi.error import QAPISemError
  21
  22
  23 # Names must be letters, numbers, -, and _.  They must start with letter,
  24 # except for downstream extensions which must start with __RFQDN_.
  25 # Dots are only valid in the downstream extension prefix.
  26 valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?'
  27                         '[a-zA-Z][a-zA-Z0-9_-]*$')
  28
  29
  30 def check_name_is_str(name, info, source):
  31     if not isinstance(name, str):
  32         raise QAPISemError(info, "%s requires a string name" % source)
  33
  34
  35 def check_name_str(name, info, source,
  36                    allow_optional=False, enum_member=False,
  37                    permit_upper=False):
  38     membername = name
  39
  40     if allow_optional and name.startswith('*'):
  41         membername = name[1:]
  42     # Enum members can start with a digit, because the generated C
  43     # code always prefixes it with the enum name
  44     if enum_member and membername[0].isdigit():
  45         membername = 'D' + membername
  46     # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
  47     # and 'q_obj_*' implicit type names.
  48     if not valid_name.match(membername) or \
  49        c_name(membername, False).startswith('q_'):
  50         raise QAPISemError(info, "%s has an invalid name" % source)
  51     if not permit_upper and name.lower() != name:
  52         raise QAPISemError(
  53             info, "%s uses uppercase in name" % source)
  54     assert not membername.startswith('*')
  55
  56
  57 def check_defn_name_str(name, info, meta):
  58     check_name_str(name, info, meta, permit_upper=True)
  59     if name.endswith('Kind') or name.endswith('List'):
  60         raise QAPISemError(
  61             info, "%s name should not end in '%s'" % (meta, name[-4:]))
  62
  63
  64 def check_keys(value, info, source, required, optional):
  65
  66     def pprint(elems):
  67         return ', '.join("'" + e + "'" for e in sorted(elems))
  68
  69     missing = set(required) - set(value)
  70     if missing:
  71         raise QAPISemError(
  72             info,
  73             "%s misses key%s %s"
  74             % (source, 's' if len(missing) > 1 else '',
  75                pprint(missing)))
  76     allowed = set(required + optional)
  77     unknown = set(value) - allowed
  78     if unknown:
  79         raise QAPISemError(
  80             info,
  81             "%s has unknown key%s %s\nValid keys are %s."
  82             % (source, 's' if len(unknown) > 1 else '',
  83                pprint(unknown), pprint(allowed)))
  84
  85
  86 def check_flags(expr, info):
  87     for key in ['gen', 'success-response']:
  88         if key in expr and expr[key] is not False:
  89             raise QAPISemError(
  90                 info, "flag '%s' may only use false value" % key)
  91     for key in ['boxed', 'allow-oob', 'allow-preconfig']:
  92         if key in expr and expr[key] is not True:
  93             raise QAPISemError(
  94                 info, "flag '%s' may only use true value" % key)
  95
  96
  97 def check_if(expr, info, source):
  98
  99     def check_if_str(ifcond, info):
 100         if not isinstance(ifcond, str):
 101             raise QAPISemError(
 102                 info,
 103                 "'if' condition of %s must be a string or a list of strings"
 104                 % source)
 105         if ifcond.strip() == '':
 106             raise QAPISemError(
 107                 info,
 108                 "'if' condition '%s' of %s makes no sense"
 109                 % (ifcond, source))
 110
 111     ifcond = expr.get('if')
 112     if ifcond is None:
 113         return
 114     if isinstance(ifcond, list):
 115         if ifcond == []:
 116             raise QAPISemError(
 117                 info, "'if' condition [] of %s is useless" % source)
 118         for elt in ifcond:
 119             check_if_str(elt, info)
 120     else:
 121         check_if_str(ifcond, info)
 122         expr['if'] = [ifcond]
 123
 124
 125 def normalize_members(members):
 126     if isinstance(members, OrderedDict):
 127         for key, arg in members.items():
 128             if isinstance(arg, dict):
 129                 continue
 130             members[key] = {'type': arg}
 131
 132
 133 def check_type(value, info, source,
 134                allow_array=False, allow_dict=False):
 135     if value is None:
 136         return
 137
 138     # Array type
 139     if isinstance(value, list):
 140         if not allow_array:
 141             raise QAPISemError(info, "%s cannot be an array" % source)
 142         if len(value) != 1 or not isinstance(value[0], str):
 143             raise QAPISemError(info,
 144                                "%s: array type must contain single type name" %
 145                                source)
 146         return
 147
 148     # Type name
 149     if isinstance(value, str):
 150         return
 151
 152     # Anonymous type
 153
 154     if not allow_dict:
 155         raise QAPISemError(info, "%s should be a type name" % source)
 156
 157     if not isinstance(value, OrderedDict):
 158         raise QAPISemError(info,
 159                            "%s should be an object or type name" % source)
 160
 161     permit_upper = allow_dict in info.pragma.name_case_whitelist
 162
 163     # value is a dictionary, check that each member is okay
 164     for (key, arg) in value.items():
 165         key_source = "%s member '%s'" % (source, key)
 166         check_name_str(key, info, key_source,
 167                        allow_optional=True, permit_upper=permit_upper)
 168         if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'):
 169             raise QAPISemError(info, "%s uses reserved name" % key_source)
 170         check_keys(arg, info, key_source, ['type'], ['if', 'features'])
 171         check_if(arg, info, key_source)
 172         check_features(arg.get('features'), info)
 173         check_type(arg['type'], info, key_source, allow_array=True)
 174
 175
 176 def check_features(features, info):
 177     if features is None:
 178         return
 179     if not isinstance(features, list):
 180         raise QAPISemError(info, "'features' must be an array")
 181     features[:] = [f if isinstance(f, dict) else {'name': f}
 182                    for f in features]
 183     for f in features:
 184         source = "'features' member"
 185         assert isinstance(f, dict)
 186         check_keys(f, info, source, ['name'], ['if'])
 187         check_name_is_str(f['name'], info, source)
 188         source = "%s '%s'" % (source, f['name'])
 189         check_name_str(f['name'], info, source)
 190         check_if(f, info, source)
 191
 192
 193 def check_enum(expr, info):
 194     name = expr['enum']
 195     members = expr['data']
 196     prefix = expr.get('prefix')
 197
 198     if not isinstance(members, list):
 199         raise QAPISemError(info, "'data' must be an array")
 200     if prefix is not None and not isinstance(prefix, str):
 201         raise QAPISemError(info, "'prefix' must be a string")
 202
 203     permit_upper = name in info.pragma.name_case_whitelist
 204
 205     members[:] = [m if isinstance(m, dict) else {'name': m}
 206                   for m in members]
 207     for member in members:
 208         source = "'data' member"
 209         check_keys(member, info, source, ['name'], ['if'])
 210         check_name_is_str(member['name'], info, source)
 211         source = "%s '%s'" % (source, member['name'])
 212         check_name_str(member['name'], info, source,
 213                        enum_member=True, permit_upper=permit_upper)
 214         check_if(member, info, source)
 215
 216
 217 def check_struct(expr, info):
 218     name = expr['struct']
 219     members = expr['data']
 220
 221     check_type(members, info, "'data'", allow_dict=name)
 222     check_type(expr.get('base'), info, "'base'")
 223
 224
 225 def check_union(expr, info):
 226     name = expr['union']
 227     base = expr.get('base')
 228     discriminator = expr.get('discriminator')
 229     members = expr['data']
 230
 231     if discriminator is None:   # simple union
 232         if base is not None:
 233             raise QAPISemError(info, "'base' requires 'discriminator'")
 234     else:                       # flat union
 235         check_type(base, info, "'base'", allow_dict=name)
 236         if not base:
 237             raise QAPISemError(info, "'discriminator' requires 'base'")
 238         check_name_is_str(discriminator, info, "'discriminator'")
 239
 240     for (key, value) in members.items():
 241         source = "'data' member '%s'" % key
 242         check_name_str(key, info, source)
 243         check_keys(value, info, source, ['type'], ['if'])
 244         check_if(value, info, source)
 245         check_type(value['type'], info, source, allow_array=not base)
 246
 247
 248 def check_alternate(expr, info):
 249     members = expr['data']
 250
 251     if not members:
 252         raise QAPISemError(info, "'data' must not be empty")
 253     for (key, value) in members.items():
 254         source = "'data' member '%s'" % key
 255         check_name_str(key, info, source)
 256         check_keys(value, info, source, ['type'], ['if'])
 257         check_if(value, info, source)
 258         check_type(value['type'], info, source)
 259
 260
 261 def check_command(expr, info):
 262     args = expr.get('data')
 263     rets = expr.get('returns')
 264     boxed = expr.get('boxed', False)
 265
 266     if boxed and args is None:
 267         raise QAPISemError(info, "'boxed': true requires 'data'")
 268     check_type(args, info, "'data'", allow_dict=not boxed)
 269     check_type(rets, info, "'returns'", allow_array=True)
 270
 271
 272 def check_event(expr, info):
 273     args = expr.get('data')
 274     boxed = expr.get('boxed', False)
 275
 276     if boxed and args is None:
 277         raise QAPISemError(info, "'boxed': true requires 'data'")
 278     check_type(args, info, "'data'", allow_dict=not boxed)
 279
 280
 281 def check_exprs(exprs):
 282     for expr_elem in exprs:
 283         expr = expr_elem['expr']
 284         info = expr_elem['info']
 285         doc = expr_elem.get('doc')
 286
 287         if 'include' in expr:
 288             continue
 289
 290         if 'enum' in expr:
 291             meta = 'enum'
 292         elif 'union' in expr:
 293             meta = 'union'
 294         elif 'alternate' in expr:
 295             meta = 'alternate'
 296         elif 'struct' in expr:
 297             meta = 'struct'
 298         elif 'command' in expr:
 299             meta = 'command'
 300         elif 'event' in expr:
 301             meta = 'event'
 302         else:
 303             raise QAPISemError(info, "expression is missing metatype")
 304
 305         name = expr[meta]
 306         check_name_is_str(name, info, "'%s'" % meta)
 307         info.set_defn(meta, name)
 308         check_defn_name_str(name, info, meta)
 309
 310         if doc:
 311             if doc.symbol != name:
 312                 raise QAPISemError(
 313                     info, "documentation comment is for '%s'" % doc.symbol)
 314             doc.check_expr(expr)
 315         elif info.pragma.doc_required:
 316             raise QAPISemError(info,
 317                                "documentation comment required")
 318
 319         if meta == 'enum':
 320             check_keys(expr, info, meta,
 321                        ['enum', 'data'], ['if', 'features', 'prefix'])
 322             check_enum(expr, info)
 323         elif meta == 'union':
 324             check_keys(expr, info, meta,
 325                        ['union', 'data'],
 326                        ['base', 'discriminator', 'if', 'features'])
 327             normalize_members(expr.get('base'))
 328             normalize_members(expr['data'])
 329             check_union(expr, info)
 330         elif meta == 'alternate':
 331             check_keys(expr, info, meta,
 332                        ['alternate', 'data'], ['if', 'features'])
 333             normalize_members(expr['data'])
 334             check_alternate(expr, info)
 335         elif meta == 'struct':
 336             check_keys(expr, info, meta,
 337                        ['struct', 'data'], ['base', 'if', 'features'])
 338             normalize_members(expr['data'])
 339             check_struct(expr, info)
 340         elif meta == 'command':
 341             check_keys(expr, info, meta,
 342                        ['command'],
 343                        ['data', 'returns', 'boxed', 'if', 'features',
 344                         'gen', 'success-response', 'allow-oob',
 345                         'allow-preconfig'])
 346             normalize_members(expr.get('data'))
 347             check_command(expr, info)
 348         elif meta == 'event':
 349             check_keys(expr, info, meta,
 350                        ['event'], ['data', 'boxed', 'if', 'features'])
 351             normalize_members(expr.get('data'))
 352             check_event(expr, info)
 353         else:
 354             assert False, 'unexpected meta type'
 355
 356         check_if(expr, info, meta)
 357         check_features(expr.get('features'), info)
 358         check_flags(expr, info)
 359
 360     return exprs