| 1 |
#!/usr/bin/python3 -i |
| 2 |
# |
| 3 |
# Copyright 2013-2023 The Khronos Group Inc. |
| 4 |
# Copyright 2023-2024 Google Inc. |
| 5 |
# |
| 6 |
# SPDX-License-Identifier: Apache-2.0 |
| 7 |
|
| 8 |
"""Types and classes for manipulating an API registry.""" |
| 9 |
|
| 10 |
import copy |
| 11 |
import re |
| 12 |
import sys |
| 13 |
import xml.etree.ElementTree as etree |
| 14 |
from collections import defaultdict, deque, namedtuple |
| 15 |
|
| 16 |
from generator import GeneratorOptions, OutputGenerator, noneStr, write |
| 17 |
|
| 18 |
def apiNameMatch(str, supported): |
| 19 |
"""Return whether a required api name matches a pattern specified for an |
| 20 |
XML <feature> 'api' attribute or <extension> 'supported' attribute. |
| 21 |
|
| 22 |
- str - API name such as 'vulkan' or 'openxr'. May be None, in which |
| 23 |
case it never matches (this should not happen). |
| 24 |
- supported - comma-separated list of XML API names. May be None, in |
| 25 |
which case str always matches (this is the usual case).""" |
| 26 |
|
| 27 |
if str is not None: |
| 28 |
return supported is None or str in supported.split(',') |
| 29 |
|
| 30 |
# Fallthrough case - either str is None or the test failed |
| 31 |
return False |
| 32 |
|
| 33 |
def matchAPIProfile(api, elem): |
| 34 |
"""Return whether an API and profile |
| 35 |
like `"gl(core)|gles1(common-lite)"`.""" |
| 36 |
# Match 'api', if present |
| 37 |
elem_api = elem.get('api') |
| 38 |
if elem_api: |
| 39 |
if api is None: |
| 40 |
raise UserWarning("No API requested, but 'api' attribute is present with value '" |
| 41 |
+ elem_api + "'") |
| 42 |
elif api != elem_api: |
| 43 |
# Requested API does not match attribute |
| 44 |
return False |
| 45 |
return True |
| 46 |
|
| 47 |
class BaseInfo: |
| 48 |
"""Base class for information about a registry feature |
| 49 |
(type/group/enum/command/API/extension). |
| 50 |
|
| 51 |
Represents the state of a registry feature, used during API generation. |
| 52 |
""" |
| 53 |
|
| 54 |
def __init__(self, elem): |
| 55 |
self.required = False |
| 56 |
"""should this feature be defined during header generation |
| 57 |
(has it been removed by a profile or version)?""" |
| 58 |
|
| 59 |
self.declared = False |
| 60 |
"has this feature been defined already?" |
| 61 |
|
| 62 |
self.elem = elem |
| 63 |
"etree Element for this feature" |
| 64 |
|
| 65 |
def resetState(self): |
| 66 |
"""Reset required/declared to initial values. Used |
| 67 |
prior to generating a new API interface.""" |
| 68 |
self.required = False |
| 69 |
self.declared = False |
| 70 |
|
| 71 |
def compareKeys(self, info, key, required = False): |
| 72 |
"""Return True if self.elem and info.elem have the same attribute |
| 73 |
value for key. |
| 74 |
If 'required' is not True, also returns True if neither element |
| 75 |
has an attribute value for key.""" |
| 76 |
|
| 77 |
if required and key not in self.elem.keys(): |
| 78 |
return False |
| 79 |
return self.elem.get(key) == info.elem.get(key) |
| 80 |
|
| 81 |
def compareElem(self, info, infoName): |
| 82 |
"""Return True if self.elem and info.elem have the same definition. |
| 83 |
info - the other object |
| 84 |
infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / |
| 85 |
'extension'""" |
| 86 |
|
| 87 |
if infoName == 'enum': |
| 88 |
if self.compareKeys(info, 'extends'): |
| 89 |
# Either both extend the same type, or no type |
| 90 |
if (self.compareKeys(info, 'value', required = True) or |
| 91 |
self.compareKeys(info, 'bitpos', required = True)): |
| 92 |
# If both specify the same value or bit position, |
| 93 |
# they are equal |
| 94 |
return True |
| 95 |
elif (self.compareKeys(info, 'extnumber') and |
| 96 |
self.compareKeys(info, 'offset') and |
| 97 |
self.compareKeys(info, 'dir')): |
| 98 |
# If both specify the same relative offset, they are equal |
| 99 |
return True |
| 100 |
elif (self.compareKeys(info, 'alias')): |
| 101 |
# If both are aliases of the same value |
| 102 |
return True |
| 103 |
else: |
| 104 |
return False |
| 105 |
else: |
| 106 |
# The same enum cannot extend two different types |
| 107 |
return False |
| 108 |
else: |
| 109 |
# Non-<enum>s should never be redefined |
| 110 |
return False |
| 111 |
|
| 112 |
|
| 113 |
class TypeInfo(BaseInfo): |
| 114 |
"""Registry information about a type. No additional state |
| 115 |
beyond BaseInfo is required.""" |
| 116 |
|
| 117 |
def __init__(self, elem): |
| 118 |
BaseInfo.__init__(self, elem) |
| 119 |
self.additionalValidity = [] |
| 120 |
self.removedValidity = [] |
| 121 |
|
| 122 |
def getMembers(self): |
| 123 |
"""Get a collection of all member elements for this type, if any.""" |
| 124 |
return self.elem.findall('member') |
| 125 |
|
| 126 |
def resetState(self): |
| 127 |
BaseInfo.resetState(self) |
| 128 |
self.additionalValidity = [] |
| 129 |
self.removedValidity = [] |
| 130 |
|
| 131 |
|
| 132 |
class GroupInfo(BaseInfo): |
| 133 |
"""Registry information about a group of related enums |
| 134 |
in an <enums> block, generally corresponding to a C "enum" type.""" |
| 135 |
|
| 136 |
def __init__(self, elem): |
| 137 |
BaseInfo.__init__(self, elem) |
| 138 |
|
| 139 |
|
| 140 |
class EnumInfo(BaseInfo): |
| 141 |
"""Registry information about an enum""" |
| 142 |
|
| 143 |
def __init__(self, elem): |
| 144 |
BaseInfo.__init__(self, elem) |
| 145 |
self.type = elem.get('type') |
| 146 |
"""numeric type of the value of the <enum> tag |
| 147 |
( '' for GLint, 'u' for GLuint, 'ull' for GLuint64 )""" |
| 148 |
if self.type is None: |
| 149 |
self.type = '' |
| 150 |
|
| 151 |
|
| 152 |
class CmdInfo(BaseInfo): |
| 153 |
"""Registry information about a command""" |
| 154 |
|
| 155 |
def __init__(self, elem): |
| 156 |
BaseInfo.__init__(self, elem) |
| 157 |
self.additionalValidity = [] |
| 158 |
self.removedValidity = [] |
| 159 |
|
| 160 |
def getParams(self): |
| 161 |
"""Get a collection of all param elements for this command, if any.""" |
| 162 |
return self.elem.findall('param') |
| 163 |
|
| 164 |
def resetState(self): |
| 165 |
BaseInfo.resetState(self) |
| 166 |
self.additionalValidity = [] |
| 167 |
self.removedValidity = [] |
| 168 |
|
| 169 |
|
| 170 |
class FeatureInfo(BaseInfo): |
| 171 |
"""Registry information about an API <feature> |
| 172 |
or <extension>.""" |
| 173 |
|
| 174 |
def __init__(self, elem): |
| 175 |
BaseInfo.__init__(self, elem) |
| 176 |
self.name = elem.get('name') |
| 177 |
"feature name string (e.g. 'VK_KHR_surface')" |
| 178 |
|
| 179 |
self.emit = False |
| 180 |
"has this feature been defined already?" |
| 181 |
|
| 182 |
self.sortorder = int(elem.get('sortorder', 0)) |
| 183 |
"""explicit numeric sort key within feature and extension groups. |
| 184 |
Defaults to 0.""" |
| 185 |
|
| 186 |
# Determine element category (vendor). Only works |
| 187 |
# for <extension> elements. |
| 188 |
if elem.tag == 'feature': |
| 189 |
# Element category (vendor) is meaningless for <feature> |
| 190 |
self.category = 'VERSION' |
| 191 |
"""category, e.g. VERSION or khr/vendor tag""" |
| 192 |
|
| 193 |
self.version = elem.get('name') |
| 194 |
"""feature name string""" |
| 195 |
|
| 196 |
self.versionNumber = elem.get('number') |
| 197 |
"""versionNumber - API version number, taken from the 'number' |
| 198 |
attribute of <feature>. Extensions do not have API version |
| 199 |
numbers and are assigned number 0.""" |
| 200 |
|
| 201 |
self.number = 0 |
| 202 |
self.supported = None |
| 203 |
else: |
| 204 |
# Extract vendor portion of <APIprefix>_<vendor>_<name> |
| 205 |
self.category = self.name.split('_', 2)[1] |
| 206 |
self.version = "0" |
| 207 |
self.versionNumber = "0" |
| 208 |
|
| 209 |
self.number = int(elem.get('number','0')) |
| 210 |
"""extension number, used for ordering and for assigning |
| 211 |
enumerant offsets. <feature> features do not have extension |
| 212 |
numbers and are assigned number 0, as are extensions without |
| 213 |
numbers, so sorting works.""" |
| 214 |
|
| 215 |
self.supported = elem.get('supported', 'disabled') |
| 216 |
|
| 217 |
class Registry: |
| 218 |
"""Object representing an API registry, loaded from an XML file.""" |
| 219 |
|
| 220 |
def __init__(self, gen=None, genOpts=None): |
| 221 |
if gen is None: |
| 222 |
# If not specified, give a default object so messaging will work |
| 223 |
self.gen = OutputGenerator() |
| 224 |
else: |
| 225 |
self.gen = gen |
| 226 |
"Output generator used to write headers / messages" |
| 227 |
|
| 228 |
if genOpts is None: |
| 229 |
# If no generator is provided, we may still need the XML API name |
| 230 |
# (for example, in genRef.py). |
| 231 |
self.genOpts = GeneratorOptions(apiname = 'vulkan') |
| 232 |
else: |
| 233 |
self.genOpts = genOpts |
| 234 |
"Options controlling features to write and how to format them" |
| 235 |
|
| 236 |
self.gen.registry = self |
| 237 |
self.gen.genOpts = self.genOpts |
| 238 |
self.gen.genOpts.registry = self |
| 239 |
|
| 240 |
self.tree = None |
| 241 |
"ElementTree containing the root `<registry>`" |
| 242 |
|
| 243 |
self.typedict = {} |
| 244 |
"dictionary of TypeInfo objects keyed by type name" |
| 245 |
|
| 246 |
self.groupdict = {} |
| 247 |
"dictionary of GroupInfo objects keyed by group name" |
| 248 |
|
| 249 |
self.enumdict = {} |
| 250 |
"dictionary of EnumInfo objects keyed by enum name" |
| 251 |
|
| 252 |
self.cmddict = {} |
| 253 |
"dictionary of CmdInfo objects keyed by command name" |
| 254 |
|
| 255 |
self.apidict = {} |
| 256 |
"dictionary of FeatureInfo objects for `<feature>` elements keyed by API name" |
| 257 |
|
| 258 |
self.extensions = [] |
| 259 |
"list of `<extension>` Elements" |
| 260 |
|
| 261 |
self.extdict = {} |
| 262 |
"dictionary of FeatureInfo objects for `<extension>` elements keyed by extension name" |
| 263 |
|
| 264 |
self.emitFeatures = False |
| 265 |
"""True to actually emit features for a version / extension, |
| 266 |
or False to just treat them as emitted""" |
| 267 |
|
| 268 |
self.filename = None |
| 269 |
|
| 270 |
def loadElementTree(self, tree): |
| 271 |
"""Load ElementTree into a Registry object and parse it.""" |
| 272 |
self.tree = tree |
| 273 |
self.parseTree() |
| 274 |
|
| 275 |
def loadFile(self, file): |
| 276 |
"""Load an API registry XML file into a Registry object and parse it""" |
| 277 |
self.filename = file |
| 278 |
self.tree = etree.parse(file) |
| 279 |
self.parseTree() |
| 280 |
|
| 281 |
def setGenerator(self, gen): |
| 282 |
"""Specify output generator object. |
| 283 |
|
| 284 |
`None` restores the default generator.""" |
| 285 |
self.gen = gen |
| 286 |
self.gen.setRegistry(self) |
| 287 |
|
| 288 |
def addElementInfo(self, elem, info, infoName, dictionary): |
| 289 |
"""Add information about an element to the corresponding dictionary. |
| 290 |
|
| 291 |
Intended for internal use only. |
| 292 |
|
| 293 |
- elem - `<type>`/`<enums>`/`<enum>`/`<command>`/`<feature>`/`<extension>`/`<spirvextension>`/`<spirvcapability>`/`<format>`/`<syncstage>`/`<syncaccess>`/`<syncpipeline>` Element |
| 294 |
- info - corresponding {Type|Group|Enum|Cmd|Feature|Spirv|Format|SyncStage|SyncAccess|SyncPipeline}Info object |
| 295 |
- infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension' / 'spirvextension' / 'spirvcapability' / 'format' / 'syncstage' / 'syncaccess' / 'syncpipeline' |
| 296 |
- dictionary - self.{type|group|enum|cmd|api|ext|format|spirvext|spirvcap|sync}dict |
| 297 |
|
| 298 |
The dictionary key is the element 'name' attribute.""" |
| 299 |
|
| 300 |
key = elem.get('name') |
| 301 |
if key in dictionary: |
| 302 |
if not dictionary[key].compareElem(info, infoName): |
| 303 |
return |
| 304 |
else: |
| 305 |
dictionary[key] = info |
| 306 |
|
| 307 |
def lookupElementInfo(self, fname, dictionary): |
| 308 |
"""Find a {Type|Enum|Cmd}Info object by name. |
| 309 |
|
| 310 |
Intended for internal use only. |
| 311 |
|
| 312 |
If an object qualified by API name exists, use that. |
| 313 |
|
| 314 |
- fname - name of type / enum / command |
| 315 |
- dictionary - self.{type|enum|cmd}dict""" |
| 316 |
key = (fname, 'vulkan') |
| 317 |
if key in dictionary: |
| 318 |
return dictionary[key] |
| 319 |
if fname in dictionary: |
| 320 |
return dictionary[fname] |
| 321 |
|
| 322 |
return None |
| 323 |
|
| 324 |
def parseTree(self): |
| 325 |
"""Parse the registry Element, once created""" |
| 326 |
# This must be the Element for the root <registry> |
| 327 |
if self.tree is None: |
| 328 |
raise RuntimeError("Tree not initialized!") |
| 329 |
self.reg = self.tree.getroot() |
| 330 |
|
| 331 |
# There is usually one <types> block; more are OK |
| 332 |
# Required <type> attributes: 'name' or nested <name> tag contents |
| 333 |
self.typedict = {} |
| 334 |
for type_elem in self.reg.findall('types/type'): |
| 335 |
# If the <type> does not already have a 'name' attribute, set |
| 336 |
# it from contents of its <name> tag, or from the contents of |
| 337 |
# its <proto><name> tag for funcpointer types. |
| 338 |
name = type_elem.get('name') |
| 339 |
if name is None: |
| 340 |
if type_elem.get('category') == 'funcpointer': |
| 341 |
name_elem = type_elem.find('proto/name') |
| 342 |
if name_elem is None: |
| 343 |
name_elem = type_elem.find('name') |
| 344 |
else: |
| 345 |
name_elem = type_elem.find('name') |
| 346 |
if name_elem is None or not name_elem.text: |
| 347 |
raise RuntimeError("Type without a name!") |
| 348 |
name = name_elem.text |
| 349 |
type_elem.set('name', name) |
| 350 |
self.addElementInfo(type_elem, TypeInfo(type_elem), 'type', self.typedict) |
| 351 |
|
| 352 |
# Create dictionary of registry enum groups from <enums> tags. |
| 353 |
# |
| 354 |
# Required <enums> attributes: 'name'. If no name is given, one is |
| 355 |
# generated, but that group cannot be identified and turned into an |
| 356 |
# enum type definition - it is just a container for <enum> tags. |
| 357 |
self.groupdict = {} |
| 358 |
for group in self.reg.findall('enums'): |
| 359 |
self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict) |
| 360 |
|
| 361 |
# Create dictionary of registry enums from <enum> tags |
| 362 |
# |
| 363 |
# <enums> tags usually define different namespaces for the values |
| 364 |
# defined in those tags, but the actual names all share the |
| 365 |
# same dictionary. |
| 366 |
# Required <enum> attributes: 'name', 'value' |
| 367 |
# For containing <enums> which have type="enum" or type="bitmask", |
| 368 |
# tag all contained <enum>s are required. This is a stopgap until |
| 369 |
# a better scheme for tagging core and extension enums is created. |
| 370 |
self.enumdict = {} |
| 371 |
for enums in self.reg.findall('enums'): |
| 372 |
required = (enums.get('type') is not None) |
| 373 |
for enum in enums.findall('enum'): |
| 374 |
enumInfo = EnumInfo(enum) |
| 375 |
enumInfo.required = required |
| 376 |
self.addElementInfo(enum, enumInfo, 'enum', self.enumdict) |
| 377 |
|
| 378 |
# Create dictionary of registry commands from <command> tags |
| 379 |
# and add 'name' attribute to each <command> tag (where missing) |
| 380 |
# based on its <proto><name> element. |
| 381 |
# |
| 382 |
# There is usually only one <commands> block; more are OK. |
| 383 |
# Required <command> attributes: 'name' or <proto><name> tag contents |
| 384 |
self.cmddict = {} |
| 385 |
# List of commands which alias others. Contains |
| 386 |
# [ aliasName, element ] |
| 387 |
# for each alias |
| 388 |
cmdAlias = [] |
| 389 |
for cmd in self.reg.findall('commands/command'): |
| 390 |
# If the <command> does not already have a 'name' attribute, set |
| 391 |
# it from contents of its <proto><name> tag. |
| 392 |
name = cmd.get('name') |
| 393 |
if name is None: |
| 394 |
name_elem = cmd.find('proto/name') |
| 395 |
if name_elem is None or not name_elem.text: |
| 396 |
raise RuntimeError("Command without a name!") |
| 397 |
name = cmd.set('name', name_elem.text) |
| 398 |
ci = CmdInfo(cmd) |
| 399 |
self.addElementInfo(cmd, ci, 'command', self.cmddict) |
| 400 |
alias = cmd.get('alias') |
| 401 |
if alias: |
| 402 |
cmdAlias.append([name, alias, cmd]) |
| 403 |
|
| 404 |
# Now loop over aliases, injecting a copy of the aliased command's |
| 405 |
# Element with the aliased prototype name replaced with the command |
| 406 |
# name - if it exists. |
| 407 |
for (name, alias, cmd) in cmdAlias: |
| 408 |
if alias in self.cmddict: |
| 409 |
aliasInfo = self.cmddict[alias] |
| 410 |
cmdElem = copy.deepcopy(aliasInfo.elem) |
| 411 |
cmdElem.find('proto/name').text = name |
| 412 |
cmdElem.set('name', name) |
| 413 |
cmdElem.set('alias', alias) |
| 414 |
ci = CmdInfo(cmdElem) |
| 415 |
# Replace the dictionary entry for the CmdInfo element |
| 416 |
self.cmddict[name] = ci |
| 417 |
|
| 418 |
# Create dictionaries of API and extension interfaces |
| 419 |
# from toplevel <api> and <extension> tags. |
| 420 |
self.apidict = {} |
| 421 |
for feature in self.reg.findall('feature'): |
| 422 |
featureInfo = FeatureInfo(feature) |
| 423 |
self.addElementInfo(feature, featureInfo, 'feature', self.apidict) |
| 424 |
|
| 425 |
# Add additional enums defined only in <feature> tags |
| 426 |
# to the corresponding enumerated type. |
| 427 |
# When seen here, the <enum> element, processed to contain the |
| 428 |
# numeric enum value, is added to the corresponding <enums> |
| 429 |
# element, as well as adding to the enum dictionary. It is no |
| 430 |
# longer removed from the <require> element it is introduced in. |
| 431 |
# Instead, generateRequiredInterface ignores <enum> elements |
| 432 |
# that extend enumerated types. |
| 433 |
# |
| 434 |
# For <enum> tags which are actually just constants, if there is |
| 435 |
# no 'extends' tag but there is a 'value' or 'bitpos' tag, just |
| 436 |
# add an EnumInfo record to the dictionary. That works because |
| 437 |
# output generation of constants is purely dependency-based, and |
| 438 |
# does not need to iterate through the XML tags. |
| 439 |
for elem in feature.findall('require'): |
| 440 |
for enum in elem.findall('enum'): |
| 441 |
addEnumInfo = False |
| 442 |
groupName = enum.get('extends') |
| 443 |
if groupName is not None: |
| 444 |
# Add version number attribute to the <enum> element |
| 445 |
enum.set('version', featureInfo.version) |
| 446 |
# Look up the GroupInfo with matching groupName |
| 447 |
if groupName in self.groupdict: |
| 448 |
gi = self.groupdict[groupName] |
| 449 |
gi.elem.append(copy.deepcopy(enum)) |
| 450 |
addEnumInfo = True |
| 451 |
elif enum.get('value') or enum.get('bitpos') or enum.get('alias'): |
| 452 |
addEnumInfo = True |
| 453 |
if addEnumInfo: |
| 454 |
enumInfo = EnumInfo(enum) |
| 455 |
self.addElementInfo(enum, enumInfo, 'enum', self.enumdict) |
| 456 |
|
| 457 |
self.extensions = self.reg.findall('extensions/extension') |
| 458 |
self.extdict = {} |
| 459 |
for feature in self.extensions: |
| 460 |
featureInfo = FeatureInfo(feature) |
| 461 |
self.addElementInfo(feature, featureInfo, 'extension', self.extdict) |
| 462 |
|
| 463 |
# Add additional enums defined only in <extension> tags |
| 464 |
# to the corresponding core type. |
| 465 |
# Algorithm matches that of enums in a "feature" tag as above. |
| 466 |
# |
| 467 |
# This code also adds a 'extnumber' attribute containing the |
| 468 |
# extension number, used for enumerant value calculation. |
| 469 |
for elem in feature.findall('require'): |
| 470 |
for enum in elem.findall('enum'): |
| 471 |
addEnumInfo = False |
| 472 |
groupName = enum.get('extends') |
| 473 |
if groupName is not None: |
| 474 |
|
| 475 |
# Add <extension> block's extension number attribute to |
| 476 |
# the <enum> element unless specified explicitly, such |
| 477 |
# as when redefining an enum in another extension. |
| 478 |
extnumber = enum.get('extnumber') |
| 479 |
if not extnumber: |
| 480 |
enum.set('extnumber', str(featureInfo.number)) |
| 481 |
|
| 482 |
enum.set('extname', featureInfo.name) |
| 483 |
enum.set('supported', noneStr(featureInfo.supported)) |
| 484 |
# Look up the GroupInfo with matching groupName |
| 485 |
if groupName in self.groupdict: |
| 486 |
gi = self.groupdict[groupName] |
| 487 |
gi.elem.append(copy.deepcopy(enum)) |
| 488 |
|
| 489 |
addEnumInfo = True |
| 490 |
elif enum.get('value') or enum.get('bitpos') or enum.get('alias'): |
| 491 |
addEnumInfo = True |
| 492 |
if addEnumInfo: |
| 493 |
enumInfo = EnumInfo(enum) |
| 494 |
self.addElementInfo(enum, enumInfo, 'enum', self.enumdict) |
| 495 |
|
| 496 |
def markTypeRequired(self, typename, required): |
| 497 |
"""Require (along with its dependencies) or remove (but not its dependencies) a type. |
| 498 |
|
| 499 |
- typename - name of type |
| 500 |
- required - boolean (to tag features as required or not) |
| 501 |
""" |
| 502 |
# Get TypeInfo object for <type> tag corresponding to typename |
| 503 |
typeinfo = self.lookupElementInfo(typename, self.typedict) |
| 504 |
if typeinfo is not None: |
| 505 |
if required: |
| 506 |
# Tag type dependencies in 'alias' and 'required' attributes as |
| 507 |
# required. This does not un-tag dependencies in a <remove> |
| 508 |
# tag. See comments in markRequired() below for the reason. |
| 509 |
for attrib_name in ['requires', 'alias']: |
| 510 |
depname = typeinfo.elem.get(attrib_name) |
| 511 |
if depname: |
| 512 |
# Do not recurse on self-referential structures. |
| 513 |
if typename != depname: |
| 514 |
self.markTypeRequired(depname, required) |
| 515 |
# Tag types used in defining this type (e.g. in nested |
| 516 |
# <type> tags) |
| 517 |
# Look for <type> in entire <command> tree, |
| 518 |
# not just immediate children |
| 519 |
for subtype in typeinfo.elem.findall('.//type'): |
| 520 |
if typename != subtype.text: |
| 521 |
self.markTypeRequired(subtype.text, required) |
| 522 |
# Tag enums used in defining this type, for example in |
| 523 |
# <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member> |
| 524 |
for subenum in typeinfo.elem.findall('.//enum'): |
| 525 |
self.markEnumRequired(subenum.text, required) |
| 526 |
# Tag type dependency in 'bitvalues' attributes as |
| 527 |
# required. This ensures that the bit values for a flag |
| 528 |
# are emitted |
| 529 |
depType = typeinfo.elem.get('bitvalues') |
| 530 |
if depType: |
| 531 |
self.markTypeRequired(depType, required) |
| 532 |
group = self.lookupElementInfo(depType, self.groupdict) |
| 533 |
if group is not None: |
| 534 |
group.flagType = typeinfo |
| 535 |
|
| 536 |
typeinfo.required = required |
| 537 |
|
| 538 |
def markEnumRequired(self, enumname, required): |
| 539 |
"""Mark an enum as required or not. |
| 540 |
|
| 541 |
- enumname - name of enum |
| 542 |
- required - boolean (to tag features as required or not)""" |
| 543 |
|
| 544 |
enum = self.lookupElementInfo(enumname, self.enumdict) |
| 545 |
if enum is not None: |
| 546 |
# If the enum is part of a group, and is being removed, then |
| 547 |
# look it up in that <enums> tag and remove the Element there, |
| 548 |
# so that it is not visible to generators (which traverse the |
| 549 |
# <enums> tag elements rather than using the dictionaries). |
| 550 |
if not required: |
| 551 |
groupName = enum.elem.get('extends') |
| 552 |
if groupName is not None: |
| 553 |
|
| 554 |
# Look up the Info with matching groupName |
| 555 |
if groupName in self.groupdict: |
| 556 |
gi = self.groupdict[groupName] |
| 557 |
gienum = gi.elem.find("enum[@name='" + enumname + "']") |
| 558 |
if gienum is not None: |
| 559 |
# Remove copy of this enum from the group |
| 560 |
gi.elem.remove(gienum) |
| 561 |
else: |
| 562 |
# This enum is not an extending enum. |
| 563 |
# The XML tree must be searched for all <enums> that |
| 564 |
# might have it, so we know the parent to delete from. |
| 565 |
|
| 566 |
enumName = enum.elem.get('name') |
| 567 |
count = 0 |
| 568 |
for enums in self.reg.findall('enums'): |
| 569 |
for thisEnum in enums.findall('enum'): |
| 570 |
if thisEnum.get('name') == enumName: |
| 571 |
# Actually remove it |
| 572 |
count = count + 1 |
| 573 |
enums.remove(thisEnum) |
| 574 |
|
| 575 |
enum.required = required |
| 576 |
# Tag enum dependencies in 'alias' attribute as required |
| 577 |
depname = enum.elem.get('alias') |
| 578 |
if depname: |
| 579 |
self.markEnumRequired(depname, required) |
| 580 |
|
| 581 |
def markCmdRequired(self, cmdname, required): |
| 582 |
"""Mark a command as required or not. |
| 583 |
|
| 584 |
- cmdname - name of command |
| 585 |
- required - boolean (to tag features as required or not)""" |
| 586 |
cmd = self.lookupElementInfo(cmdname, self.cmddict) |
| 587 |
if cmd is not None: |
| 588 |
cmd.required = required |
| 589 |
# Tag all parameter types of this command as required. |
| 590 |
# This does not remove types of commands in a <remove> |
| 591 |
# tag, because many other commands may use the same type. |
| 592 |
# We could be more clever and reference count types, |
| 593 |
# instead of using a boolean. |
| 594 |
if required: |
| 595 |
# Look for <type> in entire <command> tree, |
| 596 |
# not just immediate children |
| 597 |
for type_elem in cmd.elem.findall('.//type'): |
| 598 |
self.markTypeRequired(type_elem.text, required) |
| 599 |
|
| 600 |
def markRequired(self, featurename, feature, required): |
| 601 |
"""Require or remove features specified in the Element. |
| 602 |
|
| 603 |
- featurename - name of the feature |
| 604 |
- feature - Element for `<require>` or `<remove>` tag |
| 605 |
- required - boolean (to tag features as required or not)""" |
| 606 |
# Loop over types, enums, and commands in the tag |
| 607 |
# @@ It would be possible to respect 'api' and 'profile' attributes |
| 608 |
# in individual features, but that is not done yet. |
| 609 |
for typeElem in feature.findall('type'): |
| 610 |
self.markTypeRequired(typeElem.get('name'), required) |
| 611 |
for enumElem in feature.findall('enum'): |
| 612 |
self.markEnumRequired(enumElem.get('name'), required) |
| 613 |
|
| 614 |
for cmdElem in feature.findall('command'): |
| 615 |
self.markCmdRequired(cmdElem.get('name'), required) |
| 616 |
|
| 617 |
def fillFeatureDictionary(self, interface, featurename, api): |
| 618 |
"""Capture added interfaces for a `<version>` or `<extension>`. |
| 619 |
|
| 620 |
- interface - Element for `<version>` or `<extension>`, containing |
| 621 |
`<require>` and `<remove>` tags |
| 622 |
- featurename - name of the feature |
| 623 |
- api - string specifying API name being generated |
| 624 |
""" |
| 625 |
|
| 626 |
# Explicitly initialize known types - errors for unhandled categories |
| 627 |
self.gen.featureDictionary[featurename] = { |
| 628 |
"enumconstant": {}, |
| 629 |
"command": {}, |
| 630 |
"enum": {}, |
| 631 |
"struct": {}, |
| 632 |
"handle": {}, |
| 633 |
"basetype": {}, |
| 634 |
"include": {}, |
| 635 |
"define": {}, |
| 636 |
"bitmask": {}, |
| 637 |
"union": {}, |
| 638 |
"funcpointer": {}, |
| 639 |
} |
| 640 |
|
| 641 |
def requireFeatures(self, interface, featurename, api): |
| 642 |
"""Process `<require>` tags for a `<version>` or `<extension>`. |
| 643 |
|
| 644 |
- interface - Element for `<version>` or `<extension>`, containing |
| 645 |
`<require>` tags |
| 646 |
- featurename - name of the feature |
| 647 |
- api - string specifying API name being generated |
| 648 |
- profile - string specifying API profile being generated""" |
| 649 |
|
| 650 |
# <require> marks things that are required by this version/profile |
| 651 |
for feature in interface.findall('require'): |
| 652 |
if matchAPIProfile(api, feature): |
| 653 |
self.markRequired(featurename, feature, True) |
| 654 |
|
| 655 |
def generateFeature(self, fname, ftype, dictionary, explicit=False): |
| 656 |
"""Generate a single type / enum group / enum / command, |
| 657 |
and all its dependencies as needed. |
| 658 |
|
| 659 |
- fname - name of feature (`<type>`/`<enum>`/`<command>`) |
| 660 |
- ftype - type of feature, 'type' | 'enum' | 'command' |
| 661 |
- dictionary - of *Info objects - self.{type|enum|cmd}dict |
| 662 |
- explicit - True if this is explicitly required by the top-level |
| 663 |
XML <require> tag, False if it is a dependency of an explicit |
| 664 |
requirement.""" |
| 665 |
|
| 666 |
f = self.lookupElementInfo(fname, dictionary) |
| 667 |
if f is None: |
| 668 |
return |
| 669 |
|
| 670 |
if not f.required: |
| 671 |
return |
| 672 |
|
| 673 |
# If feature is not required, or has already been declared, return |
| 674 |
if f.declared: |
| 675 |
return |
| 676 |
# Always mark feature declared, as though actually emitted |
| 677 |
f.declared = True |
| 678 |
|
| 679 |
# Determine if this is an alias, and of what, if so |
| 680 |
alias = f.elem.get('alias') |
| 681 |
# Pull in dependent declaration(s) of the feature. |
| 682 |
# For types, there may be one type in the 'requires' attribute of |
| 683 |
# the element, one in the 'alias' attribute, and many in |
| 684 |
# embedded <type> and <enum> tags within the element. |
| 685 |
# For commands, there may be many in <type> tags within the element. |
| 686 |
# For enums, no dependencies are allowed (though perhaps if you |
| 687 |
# have a uint64 enum, it should require that type). |
| 688 |
genProc = None |
| 689 |
followupFeature = None |
| 690 |
if ftype == 'type': |
| 691 |
genProc = self.gen.genType |
| 692 |
|
| 693 |
# Generate type dependencies in 'alias' and 'requires' attributes |
| 694 |
if alias: |
| 695 |
self.generateFeature(alias, 'type', self.typedict) |
| 696 |
requires = f.elem.get('requires') |
| 697 |
if requires: |
| 698 |
self.generateFeature(requires, 'type', self.typedict) |
| 699 |
|
| 700 |
# Generate types used in defining this type (e.g. in nested |
| 701 |
# <type> tags) |
| 702 |
# Look for <type> in entire <command> tree, |
| 703 |
# not just immediate children |
| 704 |
for subtype in f.elem.findall('.//type'): |
| 705 |
self.generateFeature(subtype.text, 'type', self.typedict) |
| 706 |
|
| 707 |
# Generate enums used in defining this type, for example in |
| 708 |
# <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member> |
| 709 |
for subtype in f.elem.findall('.//enum'): |
| 710 |
self.generateFeature(subtype.text, 'enum', self.enumdict) |
| 711 |
|
| 712 |
# If the type is an enum group, look up the corresponding |
| 713 |
# group in the group dictionary and generate that instead. |
| 714 |
if f.elem.get('category') == 'enum': |
| 715 |
group = self.lookupElementInfo(fname, self.groupdict) |
| 716 |
if alias is not None: |
| 717 |
# Now, pass the *aliased* GroupInfo to the genGroup, but |
| 718 |
# with an additional parameter which is the alias name. |
| 719 |
genProc = self.gen.genGroup |
| 720 |
f = self.lookupElementInfo(alias, self.groupdict) |
| 721 |
elif group is None: |
| 722 |
return |
| 723 |
else: |
| 724 |
genProc = self.gen.genGroup |
| 725 |
f = group |
| 726 |
|
| 727 |
# @ The enum group is not ready for generation. At this |
| 728 |
# @ point, it contains all <enum> tags injected by |
| 729 |
# @ <extension> tags without any verification of whether |
| 730 |
# @ they are required or not. It may also contain |
| 731 |
# @ duplicates injected by multiple consistent |
| 732 |
# @ definitions of an <enum>. |
| 733 |
|
| 734 |
# @ Pass over each enum, marking its enumdict[] entry as |
| 735 |
# @ required or not. Mark aliases of enums as required, |
| 736 |
# @ too. |
| 737 |
|
| 738 |
enums = group.elem.findall('enum') |
| 739 |
# Check for required enums, including aliases |
| 740 |
# LATER - Check for, report, and remove duplicates? |
| 741 |
enumAliases = [] |
| 742 |
for elem in enums: |
| 743 |
name = elem.get('name') |
| 744 |
|
| 745 |
required = False |
| 746 |
|
| 747 |
extname = elem.get('extname') |
| 748 |
version = elem.get('version') |
| 749 |
if extname is not None: |
| 750 |
# 'supported' attribute was injected when the <enum> element was |
| 751 |
# moved into the <enums> group in Registry.parseTree() |
| 752 |
supported_list = elem.get('supported').split(",") |
| 753 |
if 'vulkan' in supported_list: |
| 754 |
required = True |
| 755 |
elif re.match(self.genOpts.addExtensions, extname) is not None: |
| 756 |
required = True |
| 757 |
elif version is not None: |
| 758 |
required = re.match(self.genOpts.emitversions, version) is not None |
| 759 |
else: |
| 760 |
required = True |
| 761 |
|
| 762 |
if required: |
| 763 |
# Mark this element as required (in the element, not the EnumInfo) |
| 764 |
elem.set('required', 'true') |
| 765 |
# If it is an alias, track that for later use |
| 766 |
enumAlias = elem.get('alias') |
| 767 |
if enumAlias: |
| 768 |
enumAliases.append(enumAlias) |
| 769 |
for elem in enums: |
| 770 |
name = elem.get('name') |
| 771 |
if name in enumAliases: |
| 772 |
elem.set('required', 'true') |
| 773 |
if f is None: |
| 774 |
raise RuntimeError("Should not get here") |
| 775 |
if f.elem.get('category') == 'bitmask': |
| 776 |
followupFeature = f.elem.get('bitvalues') |
| 777 |
elif ftype == 'command': |
| 778 |
# Generate command dependencies in 'alias' attribute |
| 779 |
if alias: |
| 780 |
self.generateFeature(alias, 'command', self.cmddict) |
| 781 |
|
| 782 |
genProc = self.gen.genCmd |
| 783 |
for type_elem in f.elem.findall('.//type'): |
| 784 |
depname = type_elem.text |
| 785 |
self.generateFeature(depname, 'type', self.typedict) |
| 786 |
elif ftype == 'enum': |
| 787 |
# Generate enum dependencies in 'alias' attribute |
| 788 |
if alias: |
| 789 |
self.generateFeature(alias, 'enum', self.enumdict) |
| 790 |
genProc = self.gen.genEnum |
| 791 |
|
| 792 |
# Actually generate the type only if emitting declarations |
| 793 |
if self.emitFeatures: |
| 794 |
if genProc is None: |
| 795 |
raise RuntimeError("genProc is None when we should be emitting") |
| 796 |
genProc(f, fname, alias) |
| 797 |
|
| 798 |
if followupFeature: |
| 799 |
self.generateFeature(followupFeature, "type", self.typedict) |
| 800 |
|
| 801 |
def generateRequiredInterface(self, interface): |
| 802 |
"""Generate all interfaces required by an API version or extension. |
| 803 |
|
| 804 |
- interface - Element for `<version>` or `<extension>`""" |
| 805 |
|
| 806 |
# Loop over all features inside all <require> tags. |
| 807 |
for features in interface.findall('require'): |
| 808 |
for t in features.findall('type'): |
| 809 |
self.generateFeature(t.get('name'), 'type', self.typedict, explicit=True) |
| 810 |
for e in features.findall('enum'): |
| 811 |
# If this is an enum extending an enumerated type, do not |
| 812 |
# generate it - this has already been done in reg.parseTree, |
| 813 |
# by copying this element into the enumerated type. |
| 814 |
enumextends = e.get('extends') |
| 815 |
if not enumextends: |
| 816 |
self.generateFeature(e.get('name'), 'enum', self.enumdict, explicit=True) |
| 817 |
for c in features.findall('command'): |
| 818 |
self.generateFeature(c.get('name'), 'command', self.cmddict, explicit=True) |
| 819 |
|
| 820 |
def apiGen(self): |
| 821 |
"""Generate interface for specified versions using the current |
| 822 |
generator and generator options""" |
| 823 |
|
| 824 |
# Could reset required/declared flags for all features here. |
| 825 |
# This has been removed as never used. The initial motivation was |
| 826 |
# the idea of calling apiGen() repeatedly for different targets, but |
| 827 |
# this has never been done. The 20% or so build-time speedup that |
| 828 |
# might result is not worth the effort to make it actually work. |
| 829 |
# |
| 830 |
# self.apiReset() |
| 831 |
|
| 832 |
# Compile regexps used to select versions & extensions |
| 833 |
regVersions = re.compile(self.genOpts.versions) |
| 834 |
regEmitVersions = re.compile(self.genOpts.emitversions) |
| 835 |
regAddExtensions = re.compile(self.genOpts.addExtensions) |
| 836 |
regEmitExtensions = re.compile(self.genOpts.emitExtensions) |
| 837 |
|
| 838 |
# Get all matching API feature names & add to list of FeatureInfo |
| 839 |
# Note we used to select on feature version attributes, not names. |
| 840 |
features = [] |
| 841 |
apiMatch = False |
| 842 |
for key in self.apidict: |
| 843 |
fi = self.apidict[key] |
| 844 |
api = fi.elem.get('api') |
| 845 |
if apiNameMatch('vulkan', api): |
| 846 |
apiMatch = True |
| 847 |
if regVersions.match(fi.name): |
| 848 |
# Matches API & version #s being generated. Mark for |
| 849 |
# emission and add to the features[] list . |
| 850 |
# @@ Could use 'declared' instead of 'emit'? |
| 851 |
fi.emit = (regEmitVersions.match(fi.name) is not None) |
| 852 |
features.append(fi) |
| 853 |
|
| 854 |
# Get all matching extensions, in order by their extension number, |
| 855 |
# and add to the list of features. |
| 856 |
# Start with extensions whose 'supported' attributes match the API |
| 857 |
# being generated. Add extensions matching the pattern specified in |
| 858 |
# regExtensions, then remove extensions matching the pattern |
| 859 |
# specified in regRemoveExtensions |
| 860 |
for (extName, ei) in sorted(self.extdict.items(), key=lambda x: x[1].number if x[1].number is not None else '0'): |
| 861 |
extName = ei.name |
| 862 |
include = False |
| 863 |
|
| 864 |
# Include extension if defaultExtensions is not None and is |
| 865 |
# exactly matched by the 'supported' attribute. |
| 866 |
if apiNameMatch('vulkan', ei.elem.get('supported')): |
| 867 |
include = True |
| 868 |
|
| 869 |
# Include additional extensions if the extension name matches |
| 870 |
# the regexp specified in the generator options. This allows |
| 871 |
# forcing extensions into an interface even if they are not |
| 872 |
# tagged appropriately in the registry. |
| 873 |
# However, we still respect the 'supported' attribute. |
| 874 |
if regAddExtensions.match(extName) is not None: |
| 875 |
if not apiNameMatch('vulkan', ei.elem.get('supported')): |
| 876 |
include = False |
| 877 |
else: |
| 878 |
include = True |
| 879 |
# If the extension is to be included, add it to the |
| 880 |
# extension features list. |
| 881 |
if include: |
| 882 |
ei.emit = (regEmitExtensions.match(extName) is not None) |
| 883 |
features.append(ei) |
| 884 |
|
| 885 |
# Sort the features list, if a sort procedure is defined |
| 886 |
if self.genOpts.sortProcedure: |
| 887 |
self.genOpts.sortProcedure(features) |
| 888 |
|
| 889 |
# Passes 1+2: loop over requested API versions and extensions tagging |
| 890 |
# types/commands/features as required (in an <require> block) or no |
| 891 |
# longer required (in an <remove> block). <remove>s are processed |
| 892 |
# after all <require>s, so removals win. |
| 893 |
# If a profile other than 'None' is being generated, it must |
| 894 |
# match the profile attribute (if any) of the <require> and |
| 895 |
# <remove> tags. |
| 896 |
for f in features: |
| 897 |
self.fillFeatureDictionary(f.elem, f.name, 'vulkan') |
| 898 |
self.requireFeatures(f.elem, f.name, 'vulkan') |
| 899 |
|
| 900 |
# @@May need to strip <spirvcapability> / <spirvextension> <enable> |
| 901 |
# tags of these forms: |
| 902 |
# <enable version="VK_API_VERSION_1_0"/> |
| 903 |
# <enable struct="VkPhysicalDeviceFeatures" feature="geometryShader" requires="VK_VERSION_1_0"/> |
| 904 |
# <enable extension="VK_KHR_shader_draw_parameters"/> |
| 905 |
# <enable property="VkPhysicalDeviceVulkan12Properties" member="shaderDenormPreserveFloat16" value="VK_TRUE" requires="VK_VERSION_1_2,VK_KHR_shader_float_controls"/> |
| 906 |
|
| 907 |
# Pass 3: loop over specified API versions and extensions printing |
| 908 |
# declarations for required things which have not already been |
| 909 |
# generated. |
| 910 |
self.gen.beginFile(self.genOpts) |
| 911 |
for f in features: |
| 912 |
emit = self.emitFeatures = f.emit |
| 913 |
# Generate the interface (or just tag its elements as having been |
| 914 |
# emitted, if they have not been). |
| 915 |
self.gen.beginFeature(f.elem, emit) |
| 916 |
self.generateRequiredInterface(f.elem) |
| 917 |
self.gen.endFeature() |
| 918 |
self.gen.endFile() |