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 17import re 18from collections import OrderedDict 19from qapi.common import c_name 20from 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. 26valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?' 27 '[a-zA-Z][a-zA-Z0-9_-]*$') 28 29 30def 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 35def 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 57def 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 64def 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 86def 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 97def 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 125def 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 133def 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 176def 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 193def 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 217def 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 225def 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 248def 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 261def 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 272def 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 281def 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 361