2019-10-18 09:43:44 +02:00
|
|
|
# -*- coding: utf-8 -*-
|
|
|
|
#
|
|
|
|
# Check (context-free) QAPI schema expression structure
|
|
|
|
#
|
|
|
|
# Copyright IBM, Corp. 2011
|
|
|
|
# Copyright (c) 2013-2019 Red Hat Inc.
|
|
|
|
#
|
|
|
|
# Authors:
|
|
|
|
# Anthony Liguori <aliguori@us.ibm.com>
|
|
|
|
# Markus Armbruster <armbru@redhat.com>
|
|
|
|
# Eric Blake <eblake@redhat.com>
|
|
|
|
# Marc-André Lureau <marcandre.lureau@redhat.com>
|
|
|
|
#
|
|
|
|
# This work is licensed under the terms of the GNU GPL, version 2.
|
|
|
|
# See the COPYING file in the top-level directory.
|
|
|
|
|
|
|
|
from collections import OrderedDict
|
2020-10-09 18:15:29 +02:00
|
|
|
import re
|
|
|
|
|
qapi: Prefer explicit relative imports
All of the QAPI include statements are changed to be package-aware, as
explicit relative imports.
A quirk of Python packages is that the name of the package exists only
*outside* of the package. This means that to a module inside of the qapi
folder, there is inherently no such thing as the "qapi" package. The
reason these imports work is because the "qapi" package exists in the
context of the caller -- the execution shim, where sys.path includes a
directory that has a 'qapi' folder in it.
When we write "from qapi import sibling", we are NOT referencing the folder
'qapi', but rather "any package named qapi in sys.path". If you should
so happen to have a 'qapi' package in your path, it will use *that*
package.
When we write "from .sibling import foo", we always reference explicitly
our sibling module; guaranteeing consistency in *where* we are importing
these modules from.
This can be useful when working with virtual environments and packages
in development mode. In development mode, a package is installed as a
series of symlinks that forwards to your same source files. The problem
arises because code quality checkers will follow "import qapi.x" to the
"installed" version instead of the sibling file and -- even though they
are the same file -- they have different module paths, and this causes
cyclic import problems, false positive type mismatch errors, and more.
It can also be useful when dealing with hierarchical packages, e.g. if
we allow qemu.core.qmp, qemu.qapi.parser, etc.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Eduardo Habkost <ehabkost@redhat.com>
Reviewed-by: Cleber Rosa <crosa@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
Message-Id: <20201009161558.107041-6-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-10-09 18:15:27 +02:00
|
|
|
from .common import c_name
|
|
|
|
from .error import QAPISemError
|
2019-10-18 09:43:44 +02:00
|
|
|
|
|
|
|
|
2021-03-23 10:40:07 +01:00
|
|
|
# Names consist of letters, digits, -, and _, starting with a letter.
|
|
|
|
# An experimental name is prefixed with x-. A name of a downstream
|
|
|
|
# extension is prefixed with __RFQDN_. The latter prefix goes first.
|
|
|
|
valid_name = re.compile(r'(__[a-z0-9.-]+_)?'
|
|
|
|
r'(x-)?'
|
|
|
|
r'([a-z][a-z0-9_-]*)$', re.IGNORECASE)
|
2019-10-18 09:43:44 +02:00
|
|
|
|
|
|
|
|
|
|
|
def check_name_is_str(name, info, source):
|
|
|
|
if not isinstance(name, str):
|
|
|
|
raise QAPISemError(info, "%s requires a string name" % source)
|
|
|
|
|
|
|
|
|
2021-03-23 10:40:08 +01:00
|
|
|
def check_name_str(name, info, source):
|
2019-10-18 09:43:44 +02:00
|
|
|
# Reserve the entire 'q_' namespace for c_name(), and for 'q_empty'
|
|
|
|
# and 'q_obj_*' implicit type names.
|
2021-03-23 10:40:07 +01:00
|
|
|
match = valid_name.match(name)
|
|
|
|
if not match or c_name(name, False).startswith('q_'):
|
2019-10-18 09:43:44 +02:00
|
|
|
raise QAPISemError(info, "%s has an invalid name" % source)
|
2021-03-23 10:40:07 +01:00
|
|
|
return match.group(3)
|
|
|
|
|
|
|
|
|
|
|
|
def check_name_upper(name, info, source):
|
2021-03-23 10:40:08 +01:00
|
|
|
stem = check_name_str(name, info, source)
|
2021-03-23 10:40:10 +01:00
|
|
|
if re.search(r'[a-z-]', stem):
|
|
|
|
raise QAPISemError(
|
|
|
|
info, "name of %s must not use lowercase or '-'" % source)
|
2021-03-23 10:40:07 +01:00
|
|
|
|
|
|
|
|
|
|
|
def check_name_lower(name, info, source,
|
|
|
|
permit_upper=False):
|
2021-03-23 10:40:08 +01:00
|
|
|
stem = check_name_str(name, info, source)
|
2021-03-23 10:40:09 +01:00
|
|
|
if not permit_upper and re.search(r'[A-Z]', stem):
|
2021-03-23 10:40:08 +01:00
|
|
|
raise QAPISemError(
|
|
|
|
info, "%s uses uppercase in name" % source)
|
2021-03-23 10:40:07 +01:00
|
|
|
# TODO reject '_' in stem
|
|
|
|
|
|
|
|
|
|
|
|
def check_name_camel(name, info, source):
|
2021-03-23 10:40:08 +01:00
|
|
|
stem = check_name_str(name, info, source)
|
2021-03-23 10:40:11 +01:00
|
|
|
if not re.match(r'[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$', stem):
|
|
|
|
raise QAPISemError(info, "name of %s must use CamelCase" % source)
|
2019-10-18 09:43:44 +02:00
|
|
|
|
|
|
|
|
|
|
|
def check_defn_name_str(name, info, meta):
|
2021-03-23 10:40:07 +01:00
|
|
|
if meta == 'event':
|
|
|
|
check_name_upper(name, info, meta)
|
|
|
|
elif meta == 'command':
|
|
|
|
check_name_lower(name, info, meta, permit_upper=True)
|
|
|
|
else:
|
|
|
|
check_name_camel(name, info, meta)
|
2019-10-18 09:43:44 +02:00
|
|
|
if name.endswith('Kind') or name.endswith('List'):
|
|
|
|
raise QAPISemError(
|
|
|
|
info, "%s name should not end in '%s'" % (meta, name[-4:]))
|
|
|
|
|
|
|
|
|
|
|
|
def check_keys(value, info, source, required, optional):
|
|
|
|
|
|
|
|
def pprint(elems):
|
|
|
|
return ', '.join("'" + e + "'" for e in sorted(elems))
|
|
|
|
|
|
|
|
missing = set(required) - set(value)
|
|
|
|
if missing:
|
|
|
|
raise QAPISemError(
|
|
|
|
info,
|
|
|
|
"%s misses key%s %s"
|
|
|
|
% (source, 's' if len(missing) > 1 else '',
|
|
|
|
pprint(missing)))
|
|
|
|
allowed = set(required + optional)
|
|
|
|
unknown = set(value) - allowed
|
|
|
|
if unknown:
|
|
|
|
raise QAPISemError(
|
|
|
|
info,
|
|
|
|
"%s has unknown key%s %s\nValid keys are %s."
|
|
|
|
% (source, 's' if len(unknown) > 1 else '',
|
|
|
|
pprint(unknown), pprint(allowed)))
|
|
|
|
|
|
|
|
|
|
|
|
def check_flags(expr, info):
|
|
|
|
for key in ['gen', 'success-response']:
|
|
|
|
if key in expr and expr[key] is not False:
|
|
|
|
raise QAPISemError(
|
|
|
|
info, "flag '%s' may only use false value" % key)
|
2020-10-05 17:58:49 +02:00
|
|
|
for key in ['boxed', 'allow-oob', 'allow-preconfig', 'coroutine']:
|
2019-10-18 09:43:44 +02:00
|
|
|
if key in expr and expr[key] is not True:
|
|
|
|
raise QAPISemError(
|
|
|
|
info, "flag '%s' may only use true value" % key)
|
2020-10-05 17:58:49 +02:00
|
|
|
if 'allow-oob' in expr and 'coroutine' in expr:
|
|
|
|
# This is not necessarily a fundamental incompatibility, but
|
|
|
|
# we don't have a use case and the desired semantics isn't
|
|
|
|
# obvious. The simplest solution is to forbid it until we get
|
|
|
|
# a use case for it.
|
|
|
|
raise QAPISemError(info, "flags 'allow-oob' and 'coroutine' "
|
|
|
|
"are incompatible")
|
2019-10-18 09:43:44 +02:00
|
|
|
|
|
|
|
|
|
|
|
def check_if(expr, info, source):
|
|
|
|
|
|
|
|
def check_if_str(ifcond, info):
|
|
|
|
if not isinstance(ifcond, str):
|
|
|
|
raise QAPISemError(
|
|
|
|
info,
|
|
|
|
"'if' condition of %s must be a string or a list of strings"
|
|
|
|
% source)
|
|
|
|
if ifcond.strip() == '':
|
|
|
|
raise QAPISemError(
|
|
|
|
info,
|
|
|
|
"'if' condition '%s' of %s makes no sense"
|
|
|
|
% (ifcond, source))
|
|
|
|
|
|
|
|
ifcond = expr.get('if')
|
|
|
|
if ifcond is None:
|
|
|
|
return
|
|
|
|
if isinstance(ifcond, list):
|
|
|
|
if ifcond == []:
|
|
|
|
raise QAPISemError(
|
|
|
|
info, "'if' condition [] of %s is useless" % source)
|
|
|
|
for elt in ifcond:
|
|
|
|
check_if_str(elt, info)
|
|
|
|
else:
|
|
|
|
check_if_str(ifcond, info)
|
2019-10-24 13:02:32 +02:00
|
|
|
expr['if'] = [ifcond]
|
2019-10-18 09:43:44 +02:00
|
|
|
|
|
|
|
|
|
|
|
def normalize_members(members):
|
|
|
|
if isinstance(members, OrderedDict):
|
|
|
|
for key, arg in members.items():
|
|
|
|
if isinstance(arg, dict):
|
|
|
|
continue
|
|
|
|
members[key] = {'type': arg}
|
|
|
|
|
|
|
|
|
|
|
|
def check_type(value, info, source,
|
|
|
|
allow_array=False, allow_dict=False):
|
|
|
|
if value is None:
|
|
|
|
return
|
|
|
|
|
|
|
|
# Array type
|
|
|
|
if isinstance(value, list):
|
|
|
|
if not allow_array:
|
|
|
|
raise QAPISemError(info, "%s cannot be an array" % source)
|
|
|
|
if len(value) != 1 or not isinstance(value[0], str):
|
|
|
|
raise QAPISemError(info,
|
|
|
|
"%s: array type must contain single type name" %
|
|
|
|
source)
|
|
|
|
return
|
|
|
|
|
|
|
|
# Type name
|
|
|
|
if isinstance(value, str):
|
|
|
|
return
|
|
|
|
|
|
|
|
# Anonymous type
|
|
|
|
|
|
|
|
if not allow_dict:
|
|
|
|
raise QAPISemError(info, "%s should be a type name" % source)
|
|
|
|
|
|
|
|
if not isinstance(value, OrderedDict):
|
|
|
|
raise QAPISemError(info,
|
|
|
|
"%s should be an object or type name" % source)
|
|
|
|
|
2021-03-23 10:40:16 +01:00
|
|
|
permit_upper = allow_dict in info.pragma.member_name_exceptions
|
2019-10-18 09:43:44 +02:00
|
|
|
|
|
|
|
# value is a dictionary, check that each member is okay
|
|
|
|
for (key, arg) in value.items():
|
|
|
|
key_source = "%s member '%s'" % (source, key)
|
2021-03-23 10:40:04 +01:00
|
|
|
if key.startswith('*'):
|
|
|
|
key = key[1:]
|
2021-03-23 10:40:07 +01:00
|
|
|
check_name_lower(key, info, key_source, permit_upper)
|
2019-10-18 09:43:44 +02:00
|
|
|
if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'):
|
|
|
|
raise QAPISemError(info, "%s uses reserved name" % key_source)
|
2020-03-17 12:54:45 +01:00
|
|
|
check_keys(arg, info, key_source, ['type'], ['if', 'features'])
|
2019-10-18 09:43:44 +02:00
|
|
|
check_if(arg, info, key_source)
|
2020-03-17 12:54:45 +01:00
|
|
|
check_features(arg.get('features'), info)
|
2019-10-18 09:43:44 +02:00
|
|
|
check_type(arg['type'], info, key_source, allow_array=True)
|
|
|
|
|
|
|
|
|
2019-10-18 10:14:51 +02:00
|
|
|
def check_features(features, info):
|
|
|
|
if features is None:
|
|
|
|
return
|
|
|
|
if not isinstance(features, list):
|
|
|
|
raise QAPISemError(info, "'features' must be an array")
|
2019-10-24 13:02:33 +02:00
|
|
|
features[:] = [f if isinstance(f, dict) else {'name': f}
|
|
|
|
for f in features]
|
2019-10-18 10:14:51 +02:00
|
|
|
for f in features:
|
|
|
|
source = "'features' member"
|
|
|
|
assert isinstance(f, dict)
|
|
|
|
check_keys(f, info, source, ['name'], ['if'])
|
|
|
|
check_name_is_str(f['name'], info, source)
|
|
|
|
source = "%s '%s'" % (source, f['name'])
|
2021-03-23 10:40:07 +01:00
|
|
|
check_name_lower(f['name'], info, source)
|
2019-10-18 10:14:51 +02:00
|
|
|
check_if(f, info, source)
|
|
|
|
|
|
|
|
|
2019-10-18 09:43:44 +02:00
|
|
|
def check_enum(expr, info):
|
|
|
|
name = expr['enum']
|
|
|
|
members = expr['data']
|
|
|
|
prefix = expr.get('prefix')
|
|
|
|
|
|
|
|
if not isinstance(members, list):
|
|
|
|
raise QAPISemError(info, "'data' must be an array")
|
|
|
|
if prefix is not None and not isinstance(prefix, str):
|
|
|
|
raise QAPISemError(info, "'prefix' must be a string")
|
|
|
|
|
2021-03-23 10:40:16 +01:00
|
|
|
permit_upper = name in info.pragma.member_name_exceptions
|
2019-10-18 09:43:44 +02:00
|
|
|
|
2019-10-24 13:02:34 +02:00
|
|
|
members[:] = [m if isinstance(m, dict) else {'name': m}
|
|
|
|
for m in members]
|
2019-10-18 09:43:44 +02:00
|
|
|
for member in members:
|
|
|
|
source = "'data' member"
|
2021-03-23 10:40:06 +01:00
|
|
|
member_name = member['name']
|
2019-10-18 09:43:44 +02:00
|
|
|
check_keys(member, info, source, ['name'], ['if'])
|
2021-03-23 10:40:06 +01:00
|
|
|
check_name_is_str(member_name, info, source)
|
|
|
|
source = "%s '%s'" % (source, member_name)
|
|
|
|
# Enum members may start with a digit
|
|
|
|
if member_name[0].isdigit():
|
|
|
|
member_name = 'd' + member_name # Hack: hide the digit
|
2021-03-23 10:40:07 +01:00
|
|
|
check_name_lower(member_name, info, source, permit_upper)
|
2019-10-18 09:43:44 +02:00
|
|
|
check_if(member, info, source)
|
|
|
|
|
|
|
|
|
|
|
|
def check_struct(expr, info):
|
|
|
|
name = expr['struct']
|
|
|
|
members = expr['data']
|
|
|
|
|
|
|
|
check_type(members, info, "'data'", allow_dict=name)
|
|
|
|
check_type(expr.get('base'), info, "'base'")
|
|
|
|
|
|
|
|
|
|
|
|
def check_union(expr, info):
|
|
|
|
name = expr['union']
|
|
|
|
base = expr.get('base')
|
|
|
|
discriminator = expr.get('discriminator')
|
|
|
|
members = expr['data']
|
|
|
|
|
|
|
|
if discriminator is None: # simple union
|
|
|
|
if base is not None:
|
|
|
|
raise QAPISemError(info, "'base' requires 'discriminator'")
|
|
|
|
else: # flat union
|
|
|
|
check_type(base, info, "'base'", allow_dict=name)
|
|
|
|
if not base:
|
|
|
|
raise QAPISemError(info, "'discriminator' requires 'base'")
|
|
|
|
check_name_is_str(discriminator, info, "'discriminator'")
|
|
|
|
|
|
|
|
for (key, value) in members.items():
|
|
|
|
source = "'data' member '%s'" % key
|
2021-03-23 10:40:05 +01:00
|
|
|
if discriminator is None:
|
2021-03-23 10:40:07 +01:00
|
|
|
check_name_lower(key, info, source)
|
2021-03-23 10:40:05 +01:00
|
|
|
# else: name is in discriminator enum, which gets checked
|
2019-10-18 09:43:44 +02:00
|
|
|
check_keys(value, info, source, ['type'], ['if'])
|
|
|
|
check_if(value, info, source)
|
|
|
|
check_type(value['type'], info, source, allow_array=not base)
|
|
|
|
|
|
|
|
|
|
|
|
def check_alternate(expr, info):
|
|
|
|
members = expr['data']
|
|
|
|
|
2020-03-04 16:59:32 +01:00
|
|
|
if not members:
|
2019-10-18 09:43:44 +02:00
|
|
|
raise QAPISemError(info, "'data' must not be empty")
|
|
|
|
for (key, value) in members.items():
|
|
|
|
source = "'data' member '%s'" % key
|
2021-03-23 10:40:07 +01:00
|
|
|
check_name_lower(key, info, source)
|
2019-10-18 09:43:44 +02:00
|
|
|
check_keys(value, info, source, ['type'], ['if'])
|
|
|
|
check_if(value, info, source)
|
|
|
|
check_type(value['type'], info, source)
|
|
|
|
|
|
|
|
|
|
|
|
def check_command(expr, info):
|
|
|
|
args = expr.get('data')
|
|
|
|
rets = expr.get('returns')
|
|
|
|
boxed = expr.get('boxed', False)
|
|
|
|
|
|
|
|
if boxed and args is None:
|
|
|
|
raise QAPISemError(info, "'boxed': true requires 'data'")
|
|
|
|
check_type(args, info, "'data'", allow_dict=not boxed)
|
|
|
|
check_type(rets, info, "'returns'", allow_array=True)
|
|
|
|
|
|
|
|
|
|
|
|
def check_event(expr, info):
|
|
|
|
args = expr.get('data')
|
|
|
|
boxed = expr.get('boxed', False)
|
|
|
|
|
|
|
|
if boxed and args is None:
|
|
|
|
raise QAPISemError(info, "'boxed': true requires 'data'")
|
|
|
|
check_type(args, info, "'data'", allow_dict=not boxed)
|
|
|
|
|
|
|
|
|
|
|
|
def check_exprs(exprs):
|
|
|
|
for expr_elem in exprs:
|
|
|
|
expr = expr_elem['expr']
|
|
|
|
info = expr_elem['info']
|
|
|
|
doc = expr_elem.get('doc')
|
|
|
|
|
|
|
|
if 'include' in expr:
|
|
|
|
continue
|
|
|
|
|
|
|
|
if 'enum' in expr:
|
|
|
|
meta = 'enum'
|
|
|
|
elif 'union' in expr:
|
|
|
|
meta = 'union'
|
|
|
|
elif 'alternate' in expr:
|
|
|
|
meta = 'alternate'
|
|
|
|
elif 'struct' in expr:
|
|
|
|
meta = 'struct'
|
|
|
|
elif 'command' in expr:
|
|
|
|
meta = 'command'
|
|
|
|
elif 'event' in expr:
|
|
|
|
meta = 'event'
|
|
|
|
else:
|
|
|
|
raise QAPISemError(info, "expression is missing metatype")
|
|
|
|
|
|
|
|
name = expr[meta]
|
|
|
|
check_name_is_str(name, info, "'%s'" % meta)
|
|
|
|
info.set_defn(meta, name)
|
|
|
|
check_defn_name_str(name, info, meta)
|
|
|
|
|
|
|
|
if doc:
|
|
|
|
if doc.symbol != name:
|
|
|
|
raise QAPISemError(
|
|
|
|
info, "documentation comment is for '%s'" % doc.symbol)
|
|
|
|
doc.check_expr(expr)
|
|
|
|
elif info.pragma.doc_required:
|
|
|
|
raise QAPISemError(info,
|
|
|
|
"documentation comment required")
|
|
|
|
|
|
|
|
if meta == 'enum':
|
|
|
|
check_keys(expr, info, meta,
|
2020-03-17 12:54:37 +01:00
|
|
|
['enum', 'data'], ['if', 'features', 'prefix'])
|
2019-10-18 09:43:44 +02:00
|
|
|
check_enum(expr, info)
|
|
|
|
elif meta == 'union':
|
|
|
|
check_keys(expr, info, meta,
|
|
|
|
['union', 'data'],
|
2020-03-17 12:54:37 +01:00
|
|
|
['base', 'discriminator', 'if', 'features'])
|
2019-10-18 09:43:44 +02:00
|
|
|
normalize_members(expr.get('base'))
|
|
|
|
normalize_members(expr['data'])
|
|
|
|
check_union(expr, info)
|
|
|
|
elif meta == 'alternate':
|
|
|
|
check_keys(expr, info, meta,
|
2020-03-17 12:54:37 +01:00
|
|
|
['alternate', 'data'], ['if', 'features'])
|
2019-10-18 09:43:44 +02:00
|
|
|
normalize_members(expr['data'])
|
|
|
|
check_alternate(expr, info)
|
|
|
|
elif meta == 'struct':
|
|
|
|
check_keys(expr, info, meta,
|
|
|
|
['struct', 'data'], ['base', 'if', 'features'])
|
|
|
|
normalize_members(expr['data'])
|
|
|
|
check_struct(expr, info)
|
|
|
|
elif meta == 'command':
|
|
|
|
check_keys(expr, info, meta,
|
|
|
|
['command'],
|
2019-10-18 10:14:51 +02:00
|
|
|
['data', 'returns', 'boxed', 'if', 'features',
|
2019-10-18 09:43:44 +02:00
|
|
|
'gen', 'success-response', 'allow-oob',
|
2020-10-05 17:58:49 +02:00
|
|
|
'allow-preconfig', 'coroutine'])
|
2019-10-18 09:43:44 +02:00
|
|
|
normalize_members(expr.get('data'))
|
|
|
|
check_command(expr, info)
|
|
|
|
elif meta == 'event':
|
|
|
|
check_keys(expr, info, meta,
|
2020-03-17 12:54:37 +01:00
|
|
|
['event'], ['data', 'boxed', 'if', 'features'])
|
2019-10-18 09:43:44 +02:00
|
|
|
normalize_members(expr.get('data'))
|
|
|
|
check_event(expr, info)
|
|
|
|
else:
|
|
|
|
assert False, 'unexpected meta type'
|
|
|
|
|
|
|
|
check_if(expr, info, meta)
|
2020-03-17 12:54:37 +01:00
|
|
|
check_features(expr.get('features'), info)
|
2019-10-18 09:43:44 +02:00
|
|
|
check_flags(expr, info)
|
|
|
|
|
|
|
|
return exprs
|