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