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,
41 if allow_optional
and name
.startswith('*'):
43 # Enum members can start with a digit, because the generated C
44 # code always prefixes it with the enum name
45 if enum_member
and membername
[0].isdigit():
46 membername
= 'D' + membername
47 # Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
48 # and 'q_obj_*' implicit type names.
49 if not valid_name
.match(membername
) or \
50 c_name(membername
, False).startswith('q_'):
51 raise QAPISemError(info
, "%s has an invalid name" % source
)
52 if not permit_upper
and name
.lower() != name
:
54 info
, "%s uses uppercase in name" % source
)
55 assert not membername
.startswith('*')
58 def check_defn_name_str(name
, info
, meta
):
59 check_name_str(name
, info
, meta
, permit_upper
=True)
60 if name
.endswith('Kind') or name
.endswith('List'):
62 info
, "%s name should not end in '%s'" % (meta
, name
[-4:]))
65 def check_keys(value
, info
, source
, required
, optional
):
68 return ', '.join("'" + e
+ "'" for e
in sorted(elems
))
70 missing
= set(required
) - set(value
)
75 % (source
, 's' if len(missing
) > 1 else '',
77 allowed
= set(required
+ optional
)
78 unknown
= set(value
) - allowed
82 "%s has unknown key%s %s\nValid keys are %s."
83 % (source
, 's' if len(unknown
) > 1 else '',
84 pprint(unknown
), pprint(allowed
)))
87 def check_flags(expr
, info
):
88 for key
in ['gen', 'success-response']:
89 if key
in expr
and expr
[key
] is not False:
91 info
, "flag '%s' may only use false value" % key
)
92 for key
in ['boxed', 'allow-oob', 'allow-preconfig']:
93 if key
in expr
and expr
[key
] is not True:
95 info
, "flag '%s' may only use true value" % key
)
98 def check_if(expr
, info
, source
):
100 def check_if_str(ifcond
, info
):
101 if not isinstance(ifcond
, str):
104 "'if' condition of %s must be a string or a list of strings"
106 if ifcond
.strip() == '':
109 "'if' condition '%s' of %s makes no sense"
112 ifcond
= expr
.get('if')
115 if isinstance(ifcond
, list):
118 info
, "'if' condition [] of %s is useless" % source
)
120 check_if_str(elt
, info
)
122 check_if_str(ifcond
, info
)
123 expr
['if'] = [ifcond
]
126 def normalize_members(members
):
127 if isinstance(members
, OrderedDict
):
128 for key
, arg
in members
.items():
129 if isinstance(arg
, dict):
131 members
[key
] = {'type': arg
}
134 def check_type(value
, info
, source
,
135 allow_array
=False, allow_dict
=False):
140 if isinstance(value
, list):
142 raise QAPISemError(info
, "%s cannot be an array" % source
)
143 if len(value
) != 1 or not isinstance(value
[0], str):
144 raise QAPISemError(info
,
145 "%s: array type must contain single type name" %
150 if isinstance(value
, str):
156 raise QAPISemError(info
, "%s should be a type name" % source
)
158 if not isinstance(value
, OrderedDict
):
159 raise QAPISemError(info
,
160 "%s should be an object or type name" % source
)
162 permit_upper
= allow_dict
in info
.pragma
.name_case_whitelist
164 # value is a dictionary, check that each member is okay
165 for (key
, arg
) in value
.items():
166 key_source
= "%s member '%s'" % (source
, key
)
167 check_name_str(key
, info
, key_source
,
168 allow_optional
=True, permit_upper
=permit_upper
)
169 if c_name(key
, False) == 'u' or c_name(key
, False).startswith('has_'):
170 raise QAPISemError(info
, "%s uses reserved name" % key_source
)
171 check_keys(arg
, info
, key_source
, ['type'], ['if'])
172 check_if(arg
, info
, key_source
)
173 check_type(arg
['type'], info
, key_source
, allow_array
=True)
176 def check_features(features
, info
):
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
}
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
)
193 def check_enum(expr
, info
):
195 members
= expr
['data']
196 prefix
= expr
.get('prefix')
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")
203 permit_upper
= name
in info
.pragma
.name_case_whitelist
205 members
[:] = [m
if isinstance(m
, dict) else {'name': m
}
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
)
217 def check_struct(expr
, info
):
218 name
= expr
['struct']
219 members
= expr
['data']
221 check_type(members
, info
, "'data'", allow_dict
=name
)
222 check_type(expr
.get('base'), info
, "'base'")
223 check_features(expr
.get('features'), info
)
226 def check_union(expr
, info
):
228 base
= expr
.get('base')
229 discriminator
= expr
.get('discriminator')
230 members
= expr
['data']
232 if discriminator
is None: # simple union
234 raise QAPISemError(info
, "'base' requires 'discriminator'")
236 check_type(base
, info
, "'base'", allow_dict
=name
)
238 raise QAPISemError(info
, "'discriminator' requires 'base'")
239 check_name_is_str(discriminator
, info
, "'discriminator'")
241 for (key
, value
) in members
.items():
242 source
= "'data' member '%s'" % key
243 check_name_str(key
, info
, source
)
244 check_keys(value
, info
, source
, ['type'], ['if'])
245 check_if(value
, info
, source
)
246 check_type(value
['type'], info
, source
, allow_array
=not base
)
249 def check_alternate(expr
, info
):
250 members
= expr
['data']
252 if len(members
) == 0:
253 raise QAPISemError(info
, "'data' must not be empty")
254 for (key
, value
) in members
.items():
255 source
= "'data' member '%s'" % key
256 check_name_str(key
, info
, source
)
257 check_keys(value
, info
, source
, ['type'], ['if'])
258 check_if(value
, info
, source
)
259 check_type(value
['type'], info
, source
)
262 def check_command(expr
, info
):
263 args
= expr
.get('data')
264 rets
= expr
.get('returns')
265 boxed
= expr
.get('boxed', False)
267 if boxed
and args
is None:
268 raise QAPISemError(info
, "'boxed': true requires 'data'")
269 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
270 check_type(rets
, info
, "'returns'", allow_array
=True)
271 check_features(expr
.get('features'), info
)
274 def check_event(expr
, info
):
275 args
= expr
.get('data')
276 boxed
= expr
.get('boxed', False)
278 if boxed
and args
is None:
279 raise QAPISemError(info
, "'boxed': true requires 'data'")
280 check_type(args
, info
, "'data'", allow_dict
=not boxed
)
283 def check_exprs(exprs
):
284 for expr_elem
in exprs
:
285 expr
= expr_elem
['expr']
286 info
= expr_elem
['info']
287 doc
= expr_elem
.get('doc')
289 if 'include' in expr
:
294 elif 'union' in expr
:
296 elif 'alternate' in expr
:
298 elif 'struct' in expr
:
300 elif 'command' in expr
:
302 elif 'event' in expr
:
305 raise QAPISemError(info
, "expression is missing metatype")
308 check_name_is_str(name
, info
, "'%s'" % meta
)
309 info
.set_defn(meta
, name
)
310 check_defn_name_str(name
, info
, meta
)
313 if doc
.symbol
!= name
:
315 info
, "documentation comment is for '%s'" % doc
.symbol
)
317 elif info
.pragma
.doc_required
:
318 raise QAPISemError(info
,
319 "documentation comment required")
322 check_keys(expr
, info
, meta
,
323 ['enum', 'data'], ['if', 'prefix'])
324 check_enum(expr
, info
)
325 elif meta
== 'union':
326 check_keys(expr
, info
, meta
,
328 ['base', 'discriminator', 'if'])
329 normalize_members(expr
.get('base'))
330 normalize_members(expr
['data'])
331 check_union(expr
, info
)
332 elif meta
== 'alternate':
333 check_keys(expr
, info
, meta
,
334 ['alternate', 'data'], ['if'])
335 normalize_members(expr
['data'])
336 check_alternate(expr
, info
)
337 elif meta
== 'struct':
338 check_keys(expr
, info
, meta
,
339 ['struct', 'data'], ['base', 'if', 'features'])
340 normalize_members(expr
['data'])
341 check_struct(expr
, info
)
342 elif meta
== 'command':
343 check_keys(expr
, info
, meta
,
345 ['data', 'returns', 'boxed', 'if', 'features',
346 'gen', 'success-response', 'allow-oob',
348 normalize_members(expr
.get('data'))
349 check_command(expr
, info
)
350 elif meta
== 'event':
351 check_keys(expr
, info
, meta
,
352 ['event'], ['data', 'boxed', 'if'])
353 normalize_members(expr
.get('data'))
354 check_event(expr
, info
)
356 assert False, 'unexpected meta type'
358 check_if(expr
, info
, meta
)
359 check_flags(expr
, info
)