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 17from collections import OrderedDict 18import re 19 20from .common import c_name 21from .error import QAPISemError 22 23 24# Names consist of letters, digits, -, and _, starting with a letter. 25# An experimental name is prefixed with x-. A name of a downstream 26# extension is prefixed with __RFQDN_. The latter prefix goes first. 27valid_name = re.compile(r'(__[a-z0-9.-]+_)?' 28 r'(x-)?' 29 r'([a-z][a-z0-9_-]*)$', re.IGNORECASE) 30 31 32def check_name_is_str(name, info, source): 33 if not isinstance(name, str): 34 raise QAPISemError(info, "%s requires a string name" % source) 35 36 37def check_name_str(name, info, source): 38 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty' 39 # and 'q_obj_*' implicit type names. 40 match = valid_name.match(name) 41 if not match or c_name(name, False).startswith('q_'): 42 raise QAPISemError(info, "%s has an invalid name" % source) 43 return match.group(3) 44 45 46def check_name_upper(name, info, source): 47 stem = check_name_str(name, info, source) 48 if re.search(r'[a-z-]', stem): 49 raise QAPISemError( 50 info, "name of %s must not use lowercase or '-'" % source) 51 52 53def check_name_lower(name, info, source, 54 permit_upper=False, 55 permit_underscore=False): 56 stem = check_name_str(name, info, source) 57 if ((not permit_upper and re.search(r'[A-Z]', stem)) 58 or (not permit_underscore and '_' in stem)): 59 raise QAPISemError( 60 info, "name of %s must not use uppercase or '_'" % source) 61 62 63def check_name_camel(name, info, source): 64 stem = check_name_str(name, info, source) 65 if not re.match(r'[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$', stem): 66 raise QAPISemError(info, "name of %s must use CamelCase" % source) 67 68 69def check_defn_name_str(name, info, meta): 70 if meta == 'event': 71 check_name_upper(name, info, meta) 72 elif meta == 'command': 73 check_name_lower( 74 name, info, meta, 75 permit_underscore=name in info.pragma.command_name_exceptions) 76 else: 77 check_name_camel(name, info, meta) 78 if name.endswith('Kind') or name.endswith('List'): 79 raise QAPISemError( 80 info, "%s name should not end in '%s'" % (meta, name[-4:])) 81 82 83def check_keys(value, info, source, required, optional): 84 85 def pprint(elems): 86 return ', '.join("'" + e + "'" for e in sorted(elems)) 87 88 missing = set(required) - set(value) 89 if missing: 90 raise QAPISemError( 91 info, 92 "%s misses key%s %s" 93 % (source, 's' if len(missing) > 1 else '', 94 pprint(missing))) 95 allowed = set(required + optional) 96 unknown = set(value) - allowed 97 if unknown: 98 raise QAPISemError( 99 info, 100 "%s has unknown key%s %s\nValid keys are %s." 101 % (source, 's' if len(unknown) > 1 else '', 102 pprint(unknown), pprint(allowed))) 103 104 105def check_flags(expr, info): 106 for key in ['gen', 'success-response']: 107 if key in expr and expr[key] is not False: 108 raise QAPISemError( 109 info, "flag '%s' may only use false value" % key) 110 for key in ['boxed', 'allow-oob', 'allow-preconfig', 'coroutine']: 111 if key in expr and expr[key] is not True: 112 raise QAPISemError( 113 info, "flag '%s' may only use true value" % key) 114 if 'allow-oob' in expr and 'coroutine' in expr: 115 # This is not necessarily a fundamental incompatibility, but 116 # we don't have a use case and the desired semantics isn't 117 # obvious. The simplest solution is to forbid it until we get 118 # a use case for it. 119 raise QAPISemError(info, "flags 'allow-oob' and 'coroutine' " 120 "are incompatible") 121 122 123def check_if(expr, info, source): 124 125 def check_if_str(ifcond, info): 126 if not isinstance(ifcond, str): 127 raise QAPISemError( 128 info, 129 "'if' condition of %s must be a string or a list of strings" 130 % source) 131 if ifcond.strip() == '': 132 raise QAPISemError( 133 info, 134 "'if' condition '%s' of %s makes no sense" 135 % (ifcond, source)) 136 137 ifcond = expr.get('if') 138 if ifcond is None: 139 return 140 if isinstance(ifcond, list): 141 if ifcond == []: 142 raise QAPISemError( 143 info, "'if' condition [] of %s is useless" % source) 144 for elt in ifcond: 145 check_if_str(elt, info) 146 else: 147 check_if_str(ifcond, info) 148 expr['if'] = [ifcond] 149 150 151def normalize_members(members): 152 if isinstance(members, OrderedDict): 153 for key, arg in members.items(): 154 if isinstance(arg, dict): 155 continue 156 members[key] = {'type': arg} 157 158 159def check_type(value, info, source, 160 allow_array=False, allow_dict=False): 161 if value is None: 162 return 163 164 # Array type 165 if isinstance(value, list): 166 if not allow_array: 167 raise QAPISemError(info, "%s cannot be an array" % source) 168 if len(value) != 1 or not isinstance(value[0], str): 169 raise QAPISemError(info, 170 "%s: array type must contain single type name" % 171 source) 172 return 173 174 # Type name 175 if isinstance(value, str): 176 return 177 178 # Anonymous type 179 180 if not allow_dict: 181 raise QAPISemError(info, "%s should be a type name" % source) 182 183 if not isinstance(value, OrderedDict): 184 raise QAPISemError(info, 185 "%s should be an object or type name" % source) 186 187 permit_upper = allow_dict in info.pragma.member_name_exceptions 188 189 # value is a dictionary, check that each member is okay 190 for (key, arg) in value.items(): 191 key_source = "%s member '%s'" % (source, key) 192 if key.startswith('*'): 193 key = key[1:] 194 check_name_lower(key, info, key_source, 195 permit_upper, permit_underscore=True) 196 if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'): 197 raise QAPISemError(info, "%s uses reserved name" % key_source) 198 check_keys(arg, info, key_source, ['type'], ['if', 'features']) 199 check_if(arg, info, key_source) 200 check_features(arg.get('features'), info) 201 check_type(arg['type'], info, key_source, allow_array=True) 202 203 204def check_features(features, info): 205 if features is None: 206 return 207 if not isinstance(features, list): 208 raise QAPISemError(info, "'features' must be an array") 209 features[:] = [f if isinstance(f, dict) else {'name': f} 210 for f in features] 211 for f in features: 212 source = "'features' member" 213 assert isinstance(f, dict) 214 check_keys(f, info, source, ['name'], ['if']) 215 check_name_is_str(f['name'], info, source) 216 source = "%s '%s'" % (source, f['name']) 217 check_name_lower(f['name'], info, source) 218 check_if(f, info, source) 219 220 221def check_enum(expr, info): 222 name = expr['enum'] 223 members = expr['data'] 224 prefix = expr.get('prefix') 225 226 if not isinstance(members, list): 227 raise QAPISemError(info, "'data' must be an array") 228 if prefix is not None and not isinstance(prefix, str): 229 raise QAPISemError(info, "'prefix' must be a string") 230 231 permit_upper = name in info.pragma.member_name_exceptions 232 233 members[:] = [m if isinstance(m, dict) else {'name': m} 234 for m in members] 235 for member in members: 236 source = "'data' member" 237 member_name = member['name'] 238 check_keys(member, info, source, ['name'], ['if']) 239 check_name_is_str(member_name, info, source) 240 source = "%s '%s'" % (source, member_name) 241 # Enum members may start with a digit 242 if member_name[0].isdigit(): 243 member_name = 'd' + member_name # Hack: hide the digit 244 check_name_lower(member_name, info, source, 245 permit_upper, permit_underscore=True) 246 check_if(member, info, source) 247 248 249def check_struct(expr, info): 250 name = expr['struct'] 251 members = expr['data'] 252 253 check_type(members, info, "'data'", allow_dict=name) 254 check_type(expr.get('base'), info, "'base'") 255 256 257def check_union(expr, info): 258 name = expr['union'] 259 base = expr.get('base') 260 discriminator = expr.get('discriminator') 261 members = expr['data'] 262 263 if discriminator is None: # simple union 264 if base is not None: 265 raise QAPISemError(info, "'base' requires 'discriminator'") 266 else: # flat union 267 check_type(base, info, "'base'", allow_dict=name) 268 if not base: 269 raise QAPISemError(info, "'discriminator' requires 'base'") 270 check_name_is_str(discriminator, info, "'discriminator'") 271 272 for (key, value) in members.items(): 273 source = "'data' member '%s'" % key 274 if discriminator is None: 275 check_name_lower(key, info, source, permit_underscore=True) 276 # else: name is in discriminator enum, which gets checked 277 check_keys(value, info, source, ['type'], ['if']) 278 check_if(value, info, source) 279 check_type(value['type'], info, source, allow_array=not base) 280 281 282def check_alternate(expr, info): 283 members = expr['data'] 284 285 if not members: 286 raise QAPISemError(info, "'data' must not be empty") 287 for (key, value) in members.items(): 288 source = "'data' member '%s'" % key 289 check_name_lower(key, info, source, permit_underscore=True) 290 check_keys(value, info, source, ['type'], ['if']) 291 check_if(value, info, source) 292 check_type(value['type'], info, source) 293 294 295def check_command(expr, info): 296 args = expr.get('data') 297 rets = expr.get('returns') 298 boxed = expr.get('boxed', False) 299 300 if boxed and args is None: 301 raise QAPISemError(info, "'boxed': true requires 'data'") 302 check_type(args, info, "'data'", allow_dict=not boxed) 303 check_type(rets, info, "'returns'", allow_array=True) 304 305 306def check_event(expr, info): 307 args = expr.get('data') 308 boxed = expr.get('boxed', False) 309 310 if boxed and args is None: 311 raise QAPISemError(info, "'boxed': true requires 'data'") 312 check_type(args, info, "'data'", allow_dict=not boxed) 313 314 315def check_exprs(exprs): 316 for expr_elem in exprs: 317 expr = expr_elem['expr'] 318 info = expr_elem['info'] 319 doc = expr_elem.get('doc') 320 321 if 'include' in expr: 322 continue 323 324 if 'enum' in expr: 325 meta = 'enum' 326 elif 'union' in expr: 327 meta = 'union' 328 elif 'alternate' in expr: 329 meta = 'alternate' 330 elif 'struct' in expr: 331 meta = 'struct' 332 elif 'command' in expr: 333 meta = 'command' 334 elif 'event' in expr: 335 meta = 'event' 336 else: 337 raise QAPISemError(info, "expression is missing metatype") 338 339 name = expr[meta] 340 check_name_is_str(name, info, "'%s'" % meta) 341 info.set_defn(meta, name) 342 check_defn_name_str(name, info, meta) 343 344 if doc: 345 if doc.symbol != name: 346 raise QAPISemError( 347 info, "documentation comment is for '%s'" % doc.symbol) 348 doc.check_expr(expr) 349 elif info.pragma.doc_required: 350 raise QAPISemError(info, 351 "documentation comment required") 352 353 if meta == 'enum': 354 check_keys(expr, info, meta, 355 ['enum', 'data'], ['if', 'features', 'prefix']) 356 check_enum(expr, info) 357 elif meta == 'union': 358 check_keys(expr, info, meta, 359 ['union', 'data'], 360 ['base', 'discriminator', 'if', 'features']) 361 normalize_members(expr.get('base')) 362 normalize_members(expr['data']) 363 check_union(expr, info) 364 elif meta == 'alternate': 365 check_keys(expr, info, meta, 366 ['alternate', 'data'], ['if', 'features']) 367 normalize_members(expr['data']) 368 check_alternate(expr, info) 369 elif meta == 'struct': 370 check_keys(expr, info, meta, 371 ['struct', 'data'], ['base', 'if', 'features']) 372 normalize_members(expr['data']) 373 check_struct(expr, info) 374 elif meta == 'command': 375 check_keys(expr, info, meta, 376 ['command'], 377 ['data', 'returns', 'boxed', 'if', 'features', 378 'gen', 'success-response', 'allow-oob', 379 'allow-preconfig', 'coroutine']) 380 normalize_members(expr.get('data')) 381 check_command(expr, info) 382 elif meta == 'event': 383 check_keys(expr, info, meta, 384 ['event'], ['data', 'boxed', 'if', 'features']) 385 normalize_members(expr.get('data')) 386 check_event(expr, info) 387 else: 388 assert False, 'unexpected meta type' 389 390 check_if(expr, info, meta) 391 check_features(expr.get('features'), info) 392 check_flags(expr, info) 393 394 return exprs 395