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