Debian Codegraph @

src/gfxstream/codegen/scripts/reg.py

raw
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()