1 # -*- coding: utf-8 -*-
3 # Check (context-free) QAPI schema expression structure
5 # Copyright IBM, Corp. 2011
6 # Copyright (c) 2013-2019 Red Hat Inc.
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>
14 # This work is licensed under the terms of the GNU GPL, version 2.
15 # See the COPYING file in the top-level directory.
18 from collections
import OrderedDict
19 from qapi
.common
import c_name
20 from qapi
.error
import QAPISemError
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_-]*$')
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
)
35 def check_name_str(name
, info
, source
,
36 allow_optional
=False, enum_member
=False,
40 if allow_optional
and name
.startswith('*'):
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
:
53 info
, "%s uses uppercase in name" % source
)
54 assert not membername
.startswith('*')
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'):
61 info
, "%s name should not end in '%s'" % (meta
, name
[-4:]))
64 def check_keys(value
, info
, source
, required
, optional
):
67 return ', '.join("'" + e
+ "'" for e
in sorted(elems
))
69 missing
= set(required
) - set(value
)
74 % (source
, 's' if len(missing
) > 1 else '',
76 allowed
= set(required
+ optional
)
77 unknown
= set(value
) - allowed
81 "%s has unknown key%s %s\nValid keys are %s."
82 % (source
, 's' if len(unknown
) > 1 else '',
83 pprint(unknown
), pprint(allowed
)))
86 def check_flags(expr
, info
):
87 for key
in ['gen', 'success-response']:
88 if key
in expr
and expr
[key
] is not False:
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:
94 info
, "flag '%s' may only use true value" % key
)
97 def check_if(expr
, info
, source
):
99 def check_if_str(ifcond
, info
):
100 if not isinstance(ifcond
, str):
103 "'if' condition of %s must be a string or a list of strings"
105 if ifcond
.strip() == '':
108 "'if' condition '%s' of %s makes no sense"
111 ifcond
= expr
.get('if')
114 if isinstance(ifcond
, list):
117 info
, "'if' condition [] of %s is useless" % source
)
119 check_if_str(elt
, info
)
121 check_if_str(ifcond
, info
)
122 expr
['if'] = [ifcond
]
125 def normalize_members(members
):
126 if isinstance(members
, OrderedDict
):
127 for key
, arg
in members
.items():
128 if isinstance(arg
, dict):
130 members
[key
] = {'type': arg
}
133 def check_type(value
, info
, source
,
134 allow_array
=False, allow_dict
=False):
139 if isinstance(value
, list):
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" %
149 if isinstance(value
, str):
155 raise QAPISemError(info
, "%s should be a type name" % source
)
157 if not isinstance(value
, OrderedDict
):
158 raise QAPISemError(info
,
159 "%s should be an object or type name" % source
)
161 permit_upper
= allow_dict
in info
.pragma
.name_case_whitelist
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'])
171 check_if(arg
, info
, key_source
)
172 check_type(arg
['type'], info
, key_source
, allow_array
=True)
175 def check_features(features
, info
):
178 if not isinstance(features
, list):
179 raise QAPISemError(info
, "'features' must be an array")
180 features
[:] = [f
if isinstance(f
, dict) else {'name': f
}
183 source
= "'features' member"
184 assert isinstance(f
, dict)
185 check_keys(f
, info
, source
, ['name'], ['if'])
186 check_name_is_str(f
['name'], info
, source
)
187 source
= "%s '%s'" % (source
, f
['name'])
188 check_name_str(f
['name'], info
, source
)
189 check_if(f
, info
, source
)
192 def check_enum(expr
, info
):
194 members
= expr
['data']
195 prefix
= expr
.get('prefix')
197 if not isinstance(members
, list):
198 raise QAPISemError(info
, "'data' must be an array")
199 if prefix
is not None and not isinstance(prefix
, str):
200 raise QAPISemError(info
, "'prefix' must be a string")
202 permit_upper
= name
in info
.pragma
.name_case_whitelist
204 members
[:] = [m
if isinstance(m
, dict) else {'name': m
}
206 for member
in members
:
207 source
= "'data' member"
208 check_keys(member
, info
, source
, ['name'], ['if'])
209 check_name_is_str(member
['name'], info
, source
)
210 source
= "%s '%s'" % (source
, member
['name'])
211 check_name_str(member
['name'], info
, source
,
212 enum_member
=True, permit_upper
=permit_upper
)
213 check_if(member
, info
, source
)
216 def check_struct(expr
, info
):
217 name
= expr
['struct']
218 members
= expr
['data']
220 check_type(members
, info
, "'data'", allow_dict
=name
)
221 check_type(expr
.get('base'), info
, "'base'")
222 check_features(expr
.get('features'), info
)
225 def check_union(expr
, info
):
227 base
= expr
.get('base')
228 discriminator
= expr
.get('discriminator')
229 members
= expr
['data']
231 if discriminator
is None: # simple union
233 raise QAPISemError(info
, "'base' requires 'discriminator'")
235 check_type(base
, info
, "'base'", allow_dict
=name
)
237 raise QAPISemError(info
, "'discriminator' requires 'base'")
238 check_name_is_str(discriminator
, info
, "'discriminator'")
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
)
248 def check_alternate(expr
, info
):
249 members
= expr
['data']
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
)
261 def check_command(expr
, info
):
262 args
= expr
.get('data')
263 rets
= expr
.get('returns')
264 boxed
= expr
.get('boxed', False)
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 check_features(expr
.get('features'), info
)
273 def check_event(expr
, info
):
274 args
= expr
.get('data')
275 boxed
= expr
.get('boxed', False)
277 if boxed
and args
is None:
278 raise QAPISemError(info
, "'boxed': true requires 'data'")
279 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
282 def check_exprs(exprs
):
283 for expr_elem
in exprs
:
284 expr
= expr_elem
['expr']
285 info
= expr_elem
['info']
286 doc
= expr_elem
.get('doc')
288 if 'include' in expr
:
293 elif 'union' in expr
:
295 elif 'alternate' in expr
:
297 elif 'struct' in expr
:
299 elif 'command' in expr
:
301 elif 'event' in expr
:
304 raise QAPISemError(info
, "expression is missing metatype")
307 check_name_is_str(name
, info
, "'%s'" % meta
)
308 info
.set_defn(meta
, name
)
309 check_defn_name_str(name
, info
, meta
)
312 if doc
.symbol
!= name
:
314 info
, "documentation comment is for '%s'" % doc
.symbol
)
316 elif info
.pragma
.doc_required
:
317 raise QAPISemError(info
,
318 "documentation comment required")
321 check_keys(expr
, info
, meta
,
322 ['enum', 'data'], ['if', 'prefix'])
323 check_enum(expr
, info
)
324 elif meta
== 'union':
325 check_keys(expr
, info
, meta
,
327 ['base', 'discriminator', 'if'])
328 normalize_members(expr
.get('base'))
329 normalize_members(expr
['data'])
330 check_union(expr
, info
)
331 elif meta
== 'alternate':
332 check_keys(expr
, info
, meta
,
333 ['alternate', 'data'], ['if'])
334 normalize_members(expr
['data'])
335 check_alternate(expr
, info
)
336 elif meta
== 'struct':
337 check_keys(expr
, info
, meta
,
338 ['struct', 'data'], ['base', 'if', 'features'])
339 normalize_members(expr
['data'])
340 check_struct(expr
, info
)
341 elif meta
== 'command':
342 check_keys(expr
, info
, meta
,
344 ['data', 'returns', 'boxed', 'if', 'features',
345 'gen', 'success-response', 'allow-oob',
347 normalize_members(expr
.get('data'))
348 check_command(expr
, info
)
349 elif meta
== 'event':
350 check_keys(expr
, info
, meta
,
351 ['event'], ['data', 'boxed', 'if'])
352 normalize_members(expr
.get('data'))
353 check_event(expr
, info
)
355 assert False, 'unexpected meta type'
357 check_if(expr
, info
, meta
)
358 check_flags(expr
, info
)