expr.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360
  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. import re
  17. from collections import OrderedDict
  18. from qapi.common import c_name
  19. from qapi.error import QAPISemError
  20. # Names must be letters, numbers, -, and _. They must start with letter,
  21. # except for downstream extensions which must start with __RFQDN_.
  22. # Dots are only valid in the downstream extension prefix.
  23. valid_name = re.compile(r'^(__[a-zA-Z0-9.-]+_)?'
  24. '[a-zA-Z][a-zA-Z0-9_-]*$')
  25. def check_name_is_str(name, info, source):
  26. if not isinstance(name, str):
  27. raise QAPISemError(info, "%s requires a string name" % source)
  28. def check_name_str(name, info, source,
  29. allow_optional=False, enum_member=False,
  30. permit_upper=False):
  31. membername = name
  32. if allow_optional and name.startswith('*'):
  33. membername = name[1:]
  34. # Enum members can start with a digit, because the generated C
  35. # code always prefixes it with the enum name
  36. if enum_member and membername[0].isdigit():
  37. membername = 'D' + membername
  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(membername) or \
  41. c_name(membername, 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. assert not membername.startswith('*')
  47. def check_defn_name_str(name, info, meta):
  48. check_name_str(name, info, meta, permit_upper=True)
  49. if name.endswith('Kind') or name.endswith('List'):
  50. raise QAPISemError(
  51. info, "%s name should not end in '%s'" % (meta, name[-4:]))
  52. def check_keys(value, info, source, required, optional):
  53. def pprint(elems):
  54. return ', '.join("'" + e + "'" for e in sorted(elems))
  55. missing = set(required) - set(value)
  56. if missing:
  57. raise QAPISemError(
  58. info,
  59. "%s misses key%s %s"
  60. % (source, 's' if len(missing) > 1 else '',
  61. pprint(missing)))
  62. allowed = set(required + optional)
  63. unknown = set(value) - allowed
  64. if unknown:
  65. raise QAPISemError(
  66. info,
  67. "%s has unknown key%s %s\nValid keys are %s."
  68. % (source, 's' if len(unknown) > 1 else '',
  69. pprint(unknown), pprint(allowed)))
  70. def check_flags(expr, info):
  71. for key in ['gen', 'success-response']:
  72. if key in expr and expr[key] is not False:
  73. raise QAPISemError(
  74. info, "flag '%s' may only use false value" % key)
  75. for key in ['boxed', 'allow-oob', 'allow-preconfig']:
  76. if key in expr and expr[key] is not True:
  77. raise QAPISemError(
  78. info, "flag '%s' may only use true value" % key)
  79. def check_if(expr, info, source):
  80. def check_if_str(ifcond, info):
  81. if not isinstance(ifcond, str):
  82. raise QAPISemError(
  83. info,
  84. "'if' condition of %s must be a string or a list of strings"
  85. % source)
  86. if ifcond.strip() == '':
  87. raise QAPISemError(
  88. info,
  89. "'if' condition '%s' of %s makes no sense"
  90. % (ifcond, source))
  91. ifcond = expr.get('if')
  92. if ifcond is None:
  93. return
  94. if isinstance(ifcond, list):
  95. if ifcond == []:
  96. raise QAPISemError(
  97. info, "'if' condition [] of %s is useless" % source)
  98. for elt in ifcond:
  99. check_if_str(elt, info)
  100. else:
  101. check_if_str(ifcond, info)
  102. expr['if'] = [ifcond]
  103. def normalize_members(members):
  104. if isinstance(members, OrderedDict):
  105. for key, arg in members.items():
  106. if isinstance(arg, dict):
  107. continue
  108. members[key] = {'type': arg}
  109. def check_type(value, info, source,
  110. allow_array=False, allow_dict=False):
  111. if value is None:
  112. return
  113. # Array type
  114. if isinstance(value, list):
  115. if not allow_array:
  116. raise QAPISemError(info, "%s cannot be an array" % source)
  117. if len(value) != 1 or not isinstance(value[0], str):
  118. raise QAPISemError(info,
  119. "%s: array type must contain single type name" %
  120. source)
  121. return
  122. # Type name
  123. if isinstance(value, str):
  124. return
  125. # Anonymous type
  126. if not allow_dict:
  127. raise QAPISemError(info, "%s should be a type name" % source)
  128. if not isinstance(value, OrderedDict):
  129. raise QAPISemError(info,
  130. "%s should be an object or type name" % source)
  131. permit_upper = allow_dict in info.pragma.name_case_whitelist
  132. # value is a dictionary, check that each member is okay
  133. for (key, arg) in value.items():
  134. key_source = "%s member '%s'" % (source, key)
  135. check_name_str(key, info, key_source,
  136. allow_optional=True, permit_upper=permit_upper)
  137. if c_name(key, False) == 'u' or c_name(key, False).startswith('has_'):
  138. raise QAPISemError(info, "%s uses reserved name" % key_source)
  139. check_keys(arg, info, key_source, ['type'], ['if', 'features'])
  140. check_if(arg, info, key_source)
  141. check_features(arg.get('features'), info)
  142. check_type(arg['type'], info, key_source, allow_array=True)
  143. def check_features(features, info):
  144. if features is None:
  145. return
  146. if not isinstance(features, list):
  147. raise QAPISemError(info, "'features' must be an array")
  148. features[:] = [f if isinstance(f, dict) else {'name': f}
  149. for f in features]
  150. for f in features:
  151. source = "'features' member"
  152. assert isinstance(f, dict)
  153. check_keys(f, info, source, ['name'], ['if'])
  154. check_name_is_str(f['name'], info, source)
  155. source = "%s '%s'" % (source, f['name'])
  156. check_name_str(f['name'], info, source)
  157. check_if(f, info, source)
  158. def check_enum(expr, info):
  159. name = expr['enum']
  160. members = expr['data']
  161. prefix = expr.get('prefix')
  162. if not isinstance(members, list):
  163. raise QAPISemError(info, "'data' must be an array")
  164. if prefix is not None and not isinstance(prefix, str):
  165. raise QAPISemError(info, "'prefix' must be a string")
  166. permit_upper = name in info.pragma.name_case_whitelist
  167. members[:] = [m if isinstance(m, dict) else {'name': m}
  168. for m in members]
  169. for member in members:
  170. source = "'data' member"
  171. check_keys(member, info, source, ['name'], ['if'])
  172. check_name_is_str(member['name'], info, source)
  173. source = "%s '%s'" % (source, member['name'])
  174. check_name_str(member['name'], info, source,
  175. enum_member=True, permit_upper=permit_upper)
  176. check_if(member, info, source)
  177. def check_struct(expr, info):
  178. name = expr['struct']
  179. members = expr['data']
  180. check_type(members, info, "'data'", allow_dict=name)
  181. check_type(expr.get('base'), info, "'base'")
  182. def check_union(expr, info):
  183. name = expr['union']
  184. base = expr.get('base')
  185. discriminator = expr.get('discriminator')
  186. members = expr['data']
  187. if discriminator is None: # simple union
  188. if base is not None:
  189. raise QAPISemError(info, "'base' requires 'discriminator'")
  190. else: # flat union
  191. check_type(base, info, "'base'", allow_dict=name)
  192. if not base:
  193. raise QAPISemError(info, "'discriminator' requires 'base'")
  194. check_name_is_str(discriminator, info, "'discriminator'")
  195. for (key, value) in members.items():
  196. source = "'data' member '%s'" % key
  197. check_name_str(key, info, source)
  198. check_keys(value, info, source, ['type'], ['if'])
  199. check_if(value, info, source)
  200. check_type(value['type'], info, source, allow_array=not base)
  201. def check_alternate(expr, info):
  202. members = expr['data']
  203. if not members:
  204. raise QAPISemError(info, "'data' must not be empty")
  205. for (key, value) in members.items():
  206. source = "'data' member '%s'" % key
  207. check_name_str(key, info, source)
  208. check_keys(value, info, source, ['type'], ['if'])
  209. check_if(value, info, source)
  210. check_type(value['type'], info, source)
  211. def check_command(expr, info):
  212. args = expr.get('data')
  213. rets = expr.get('returns')
  214. boxed = expr.get('boxed', False)
  215. if boxed and args is None:
  216. raise QAPISemError(info, "'boxed': true requires 'data'")
  217. check_type(args, info, "'data'", allow_dict=not boxed)
  218. check_type(rets, info, "'returns'", allow_array=True)
  219. def check_event(expr, info):
  220. args = expr.get('data')
  221. boxed = expr.get('boxed', False)
  222. if boxed and args is None:
  223. raise QAPISemError(info, "'boxed': true requires 'data'")
  224. check_type(args, info, "'data'", allow_dict=not boxed)
  225. def check_exprs(exprs):
  226. for expr_elem in exprs:
  227. expr = expr_elem['expr']
  228. info = expr_elem['info']
  229. doc = expr_elem.get('doc')
  230. if 'include' in expr:
  231. continue
  232. if 'enum' in expr:
  233. meta = 'enum'
  234. elif 'union' in expr:
  235. meta = 'union'
  236. elif 'alternate' in expr:
  237. meta = 'alternate'
  238. elif 'struct' in expr:
  239. meta = 'struct'
  240. elif 'command' in expr:
  241. meta = 'command'
  242. elif 'event' in expr:
  243. meta = 'event'
  244. else:
  245. raise QAPISemError(info, "expression is missing metatype")
  246. name = expr[meta]
  247. check_name_is_str(name, info, "'%s'" % meta)
  248. info.set_defn(meta, name)
  249. check_defn_name_str(name, info, meta)
  250. if doc:
  251. if doc.symbol != name:
  252. raise QAPISemError(
  253. info, "documentation comment is for '%s'" % doc.symbol)
  254. doc.check_expr(expr)
  255. elif info.pragma.doc_required:
  256. raise QAPISemError(info,
  257. "documentation comment required")
  258. if meta == 'enum':
  259. check_keys(expr, info, meta,
  260. ['enum', 'data'], ['if', 'features', 'prefix'])
  261. check_enum(expr, info)
  262. elif meta == 'union':
  263. check_keys(expr, info, meta,
  264. ['union', 'data'],
  265. ['base', 'discriminator', 'if', 'features'])
  266. normalize_members(expr.get('base'))
  267. normalize_members(expr['data'])
  268. check_union(expr, info)
  269. elif meta == 'alternate':
  270. check_keys(expr, info, meta,
  271. ['alternate', 'data'], ['if', 'features'])
  272. normalize_members(expr['data'])
  273. check_alternate(expr, info)
  274. elif meta == 'struct':
  275. check_keys(expr, info, meta,
  276. ['struct', 'data'], ['base', 'if', 'features'])
  277. normalize_members(expr['data'])
  278. check_struct(expr, info)
  279. elif meta == 'command':
  280. check_keys(expr, info, meta,
  281. ['command'],
  282. ['data', 'returns', 'boxed', 'if', 'features',
  283. 'gen', 'success-response', 'allow-oob',
  284. 'allow-preconfig'])
  285. normalize_members(expr.get('data'))
  286. check_command(expr, info)
  287. elif meta == 'event':
  288. check_keys(expr, info, meta,
  289. ['event'], ['data', 'boxed', 'if', 'features'])
  290. normalize_members(expr.get('data'))
  291. check_event(expr, info)
  292. else:
  293. assert False, 'unexpected meta type'
  294. check_if(expr, info, meta)
  295. check_features(expr.get('features'), info)
  296. check_flags(expr, info)
  297. return exprs