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