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