path: root/registry/reg.py

#!/usr/bin/python3 -i
#
# Copyright 2013-2023 The Khronos Group Inc.
#
# SPDX-License-Identifier: Apache-2.0

"""Types and classes for manipulating an API registry."""

import copy
import re
import sys
import xml.etree.ElementTree as etree
from collections import defaultdict, deque, namedtuple

from generator import GeneratorOptions, OutputGenerator, noneStr, write
from apiconventions import APIConventions

def apiNameMatch(str, supported):
    """Return whether a required api name matches a pattern specified for an
    XML <feature> 'api' attribute or <extension> 'supported' attribute.

    - str - API name such as 'vulkan' or 'openxr'. May be None, in which
        case it never matches (this should not happen).
    - supported - comma-separated list of XML API names. May be None, in
        which case str always matches (this is the usual case)."""

    if str is not None:
        return supported is None or str in supported.split(',')

    # Fallthrough case - either str is None or the test failed
    return False

def matchAPIProfile(api, profile, elem):
    """Return whether an API and profile
    being generated matches an element's profile

    - api - string naming the API to match
    - profile - string naming the profile to match
    - elem - Element which (may) have 'api' and 'profile'
      attributes to match to.

    If a tag is not present in the Element, the corresponding API
      or profile always matches.

    Otherwise, the tag must exactly match the API or profile.

    Thus, if 'profile' = core:

    - `<remove>`  with no attribute will match
    - `<remove profile="core">` will match
    - `<remove profile="compatibility">` will not match

    Possible match conditions:

    ```
      Requested   Element
      Profile     Profile
      ---------   --------
      None        None        Always matches
      'string'    None        Always matches
      None        'string'    Does not match. Cannot generate multiple APIs
                              or profiles, so if an API/profile constraint
                              is present, it must be asked for explicitly.
      'string'    'string'    Strings must match
    ```

    ** In the future, we will allow regexes for the attributes,
    not just strings, so that `api="^(gl|gles2)"` will match. Even
    this is not really quite enough, we might prefer something
    like `"gl(core)|gles1(common-lite)"`."""
    # Match 'api', if present
    elem_api = elem.get('api')
    if elem_api:
        if api is None:
            raise UserWarning("No API requested, but 'api' attribute is present with value '"
                              + elem_api + "'")
        elif api != elem_api:
            # Requested API does not match attribute
            return False
    elem_profile = elem.get('profile')
    if elem_profile:
        if profile is None:
            raise UserWarning("No profile requested, but 'profile' attribute is present with value '"
                              + elem_profile + "'")
        elif profile != elem_profile:
            # Requested profile does not match attribute
            return False
    return True


def mergeAPIs(tree, fromApiNames, toApiName):
    """Merge multiple APIs using the precedence order specified in apiNames.
    Also deletes <remove> elements.

        tree - Element at the root of the hierarchy to merge.
        apiNames - list of strings of API names."""

    stack = deque()
    stack.append(tree)

    while len(stack) > 0:
        parent = stack.pop()

        for child in parent.findall('*'):
            if child.tag == 'remove':
                # Remove <remove> elements
                parent.remove(child)
            else:
                stack.append(child)

            supportedList = child.get('supported')
            if supportedList:
                supportedList = supportedList.split(',')
                for apiName in [toApiName] + fromApiNames:
                    if apiName in supportedList:
                        child.set('supported', toApiName)

            if child.get('api'):
                definitionName = None
                definitionVariants = []

                # Keep only one definition with the same name if there are multiple definitions
                if child.tag in ['type']:
                    if child.get('name') is not None:
                        definitionName = child.get('name')
                        definitionVariants = parent.findall(f"{child.tag}[@name='{definitionName}']")
                    else:
                        definitionName = child.find('name').text
                        definitionVariants = parent.findall(f"{child.tag}/name[.='{definitionName}']/..")
                elif child.tag in ['member', 'param']:
                    definitionName = child.find('name').text
                    definitionVariants = parent.findall(f"{child.tag}/name[.='{definitionName}']/..")
                elif child.tag in ['enum', 'feature']:
                    definitionName = child.get('name')
                    definitionVariants = parent.findall(f"{child.tag}[@name='{definitionName}']")
                elif child.tag in ['require']:
                    definitionName = child.get('feature')
                    definitionVariants = parent.findall(f"{child.tag}[@feature='{definitionName}']")
                elif child.tag in ['command']:
                    definitionName = child.find('proto/name').text
                    definitionVariants = parent.findall(f"{child.tag}/proto/name[.='{definitionName}']/../..")

                if definitionName:
                    bestMatchApi = None
                    requires = None
                    for apiName in [toApiName] + fromApiNames:
                        for variant in definitionVariants:
                            # Keep any requires attributes from the target API
                            if variant.get('requires') and variant.get('api') == apiName:
                                requires = variant.get('requires')
                            # Find the best matching definition
                            if apiName in variant.get('api').split(',') and bestMatchApi is None:
                                bestMatchApi = variant.get('api')

                    if bestMatchApi:
                        for variant in definitionVariants:
                            if variant.get('api') != bestMatchApi:
                                # Only keep best matching definition
                                parent.remove(variant)
                            else:
                                # Add requires attribute from the target API if it is not overridden
                                if requires is not None and variant.get('requires') is None:
                                    variant.set('requires', requires)
                                variant.set('api', toApiName)


def stripNonmatchingAPIs(tree, apiName, actuallyDelete = True):
    """Remove tree Elements with 'api' attributes matching apiName.

        tree - Element at the root of the hierarchy to strip. Only its
            children can actually be removed, not the tree itself.
        apiName - string which much match a command-separated component of
            the 'api' attribute.
        actuallyDelete - only delete matching elements if True."""

    stack = deque()
    stack.append(tree)

    while len(stack) > 0:
        parent = stack.pop()

        for child in parent.findall('*'):
            api = child.get('api')

            if apiNameMatch(apiName, api):
                # Add child to the queue
                stack.append(child)
            elif not apiNameMatch(apiName, api):
                # Child does not match requested api. Remove it.
                if actuallyDelete:
                    parent.remove(child)


class BaseInfo:
    """Base class for information about a registry feature
    (type/group/enum/command/API/extension).

    Represents the state of a registry feature, used during API generation.
    """

    def __init__(self, elem):
        self.required = False
        """should this feature be defined during header generation
        (has it been removed by a profile or version)?"""

        self.declared = False
        "has this feature been defined already?"

        self.elem = elem
        "etree Element for this feature"

    def resetState(self):
        """Reset required/declared to initial values. Used
        prior to generating a new API interface."""
        self.required = False
        self.declared = False

    def compareKeys(self, info, key, required = False):
        """Return True if self.elem and info.elem have the same attribute
           value for key.
           If 'required' is not True, also returns True if neither element
           has an attribute value for key."""

        if required and key not in self.elem.keys():
            return False
        return self.elem.get(key) == info.elem.get(key)

    def compareElem(self, info, infoName):
        """Return True if self.elem and info.elem have the same definition.
        info - the other object
        infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' /
                   'extension'"""

        if infoName == 'enum':
            if self.compareKeys(info, 'extends'):
                # Either both extend the same type, or no type
                if (self.compareKeys(info, 'value', required = True) or
                    self.compareKeys(info, 'bitpos', required = True)):
                    # If both specify the same value or bit position,
                    # they are equal
                    return True
                elif (self.compareKeys(info, 'extnumber') and
                      self.compareKeys(info, 'offset') and
                      self.compareKeys(info, 'dir')):
                    # If both specify the same relative offset, they are equal
                    return True
                elif (self.compareKeys(info, 'alias')):
                    # If both are aliases of the same value
                    return True
                else:
                    return False
            else:
                # The same enum cannot extend two different types
                return False
        else:
            # Non-<enum>s should never be redefined
            return False


class TypeInfo(BaseInfo):
    """Registry information about a type. No additional state
      beyond BaseInfo is required."""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)
        self.additionalValidity = []
        self.removedValidity = []

    def getMembers(self):
        """Get a collection of all member elements for this type, if any."""
        return self.elem.findall('member')

    def resetState(self):
        BaseInfo.resetState(self)
        self.additionalValidity = []
        self.removedValidity = []


class GroupInfo(BaseInfo):
    """Registry information about a group of related enums
    in an <enums> block, generally corresponding to a C "enum" type."""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)


class EnumInfo(BaseInfo):
    """Registry information about an enum"""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)
        self.type = elem.get('type')
        """numeric type of the value of the <enum> tag
        ( '' for GLint, 'u' for GLuint, 'ull' for GLuint64 )"""
        if self.type is None:
            self.type = ''


class CmdInfo(BaseInfo):
    """Registry information about a command"""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)
        self.additionalValidity = []
        self.removedValidity = []

    def getParams(self):
        """Get a collection of all param elements for this command, if any."""
        return self.elem.findall('param')

    def resetState(self):
        BaseInfo.resetState(self)
        self.additionalValidity = []
        self.removedValidity = []


class FeatureInfo(BaseInfo):
    """Registry information about an API <feature>
    or <extension>."""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)
        self.name = elem.get('name')
        "feature name string (e.g. 'VK_KHR_surface')"

        self.emit = False
        "has this feature been defined already?"

        self.sortorder = int(elem.get('sortorder', 0))
        """explicit numeric sort key within feature and extension groups.
        Defaults to 0."""

        # Determine element category (vendor). Only works
        # for <extension> elements.
        if elem.tag == 'feature':
            # Element category (vendor) is meaningless for <feature>
            self.category = 'VERSION'
            """category, e.g. VERSION or khr/vendor tag"""

            self.version = elem.get('name')
            """feature name string"""

            self.versionNumber = elem.get('number')
            """versionNumber - API version number, taken from the 'number'
               attribute of <feature>. Extensions do not have API version
               numbers and are assigned number 0."""

            self.number = 0
            self.supported = None
        else:
            # Extract vendor portion of <APIprefix>_<vendor>_<name>
            self.category = self.name.split('_', 2)[1]
            self.version = "0"
            self.versionNumber = "0"

            self.number = int(elem.get('number','0'))
            """extension number, used for ordering and for assigning
            enumerant offsets. <feature> features do not have extension
            numbers and are assigned number 0, as are extensions without
            numbers, so sorting works."""

            self.supported = elem.get('supported', 'disabled')

class SpirvInfo(BaseInfo):
    """Registry information about an API <spirvextensions>
    or <spirvcapability>."""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)

class FormatInfo(BaseInfo):
    """Registry information about an API <format>."""

    def __init__(self, elem, condition):
        BaseInfo.__init__(self, elem)
        # Need to save the condition here when it is known
        self.condition = condition

class SyncStageInfo(BaseInfo):
    """Registry information about <syncstage>."""

    def __init__(self, elem, condition):
        BaseInfo.__init__(self, elem)
        # Need to save the condition here when it is known
        self.condition = condition

class SyncAccessInfo(BaseInfo):
    """Registry information about <syncaccess>."""

    def __init__(self, elem, condition):
        BaseInfo.__init__(self, elem)
        # Need to save the condition here when it is known
        self.condition = condition

class SyncPipelineInfo(BaseInfo):
    """Registry information about <syncpipeline>."""

    def __init__(self, elem):
        BaseInfo.__init__(self, elem)

class Registry:
    """Object representing an API registry, loaded from an XML file."""

    def __init__(self, gen=None, genOpts=None):
        if gen is None:
            # If not specified, give a default object so messaging will work
            self.gen = OutputGenerator()
        else:
            self.gen = gen
        "Output generator used to write headers / messages"

        if genOpts is None:
            # If no generator is provided, we may still need the XML API name
            # (for example, in genRef.py).
            self.genOpts = GeneratorOptions(apiname = APIConventions().xml_api_name)
        else:
            self.genOpts = genOpts
        "Options controlling features to write and how to format them"

        self.gen.registry = self
        self.gen.genOpts = self.genOpts
        self.gen.genOpts.registry = self

        self.tree = None
        "ElementTree containing the root `<registry>`"

        self.typedict = {}
        "dictionary of TypeInfo objects keyed by type name"

        self.groupdict = {}
        "dictionary of GroupInfo objects keyed by group name"

        self.enumdict = {}
        "dictionary of EnumInfo objects keyed by enum name"

        self.cmddict = {}
        "dictionary of CmdInfo objects keyed by command name"

        self.apidict = {}
        "dictionary of FeatureInfo objects for `<feature>` elements keyed by API name"

        self.extensions = []
        "list of `<extension>` Elements"

        self.extdict = {}
        "dictionary of FeatureInfo objects for `<extension>` elements keyed by extension name"

        self.spirvextdict = {}
        "dictionary of FeatureInfo objects for `<spirvextension>` elements keyed by spirv extension name"

        self.spirvcapdict = {}
        "dictionary of FeatureInfo objects for `<spirvcapability>` elements keyed by spirv capability name"

        self.formatsdict = {}
        "dictionary of FeatureInfo objects for `<format>` elements keyed by VkFormat name"

        self.syncstagedict = {}
        "dictionary of Sync*Info objects for `<syncstage>` elements keyed by VkPipelineStageFlagBits2 name"

        self.syncaccessdict = {}
        "dictionary of Sync*Info objects for `<syncaccess>` elements keyed by VkAccessFlagBits2 name"

        self.syncpipelinedict = {}
        "dictionary of Sync*Info objects for `<syncpipeline>` elements keyed by pipeline type name"

        self.emitFeatures = False
        """True to actually emit features for a version / extension,
        or False to just treat them as emitted"""

        self.breakPat = None
        "regexp pattern to break on when generating names"
        # self.breakPat     = re.compile('VkFenceImportFlagBits.*')

        self.requiredextensions = []  # Hack - can remove it after validity generator goes away

        # ** Global types for automatic source generation **
        # Length Member data
        self.commandextensiontuple = namedtuple('commandextensiontuple',
                                                ['command',        # The name of the command being modified
                                                 'value',          # The value to append to the command
                                                 'extension'])     # The name of the extension that added it
        self.validextensionstructs = defaultdict(list)
        self.commandextensionsuccesses = []
        self.commandextensionerrors = []

        self.filename     = None

    def loadElementTree(self, tree):
        """Load ElementTree into a Registry object and parse it."""
        self.tree = tree
        self.parseTree()

    def loadFile(self, file):
        """Load an API registry XML file into a Registry object and parse it"""
        self.filename = file
        self.tree = etree.parse(file)
        self.parseTree()

    def setGenerator(self, gen):
        """Specify output generator object.

        `None` restores the default generator."""
        self.gen = gen
        self.gen.setRegistry(self)

    def addElementInfo(self, elem, info, infoName, dictionary):
        """Add information about an element to the corresponding dictionary.

        Intended for internal use only.

        - elem - `<type>`/`<enums>`/`<enum>`/`<command>`/`<feature>`/`<extension>`/`<spirvextension>`/`<spirvcapability>`/`<format>`/`<syncstage>`/`<syncaccess>`/`<syncpipeline>` Element
        - info - corresponding {Type|Group|Enum|Cmd|Feature|Spirv|Format|SyncStage|SyncAccess|SyncPipeline}Info object
        - infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension' / 'spirvextension' / 'spirvcapability' / 'format' / 'syncstage' / 'syncaccess' / 'syncpipeline'
        - dictionary - self.{type|group|enum|cmd|api|ext|format|spirvext|spirvcap|sync}dict

        The dictionary key is the element 'name' attribute."""

        # self.gen.logMsg('diag', 'Adding ElementInfo.required =',
        #     info.required, 'name =', elem.get('name'))
        key = elem.get('name')
        if key in dictionary:
            if not dictionary[key].compareElem(info, infoName):
                self.gen.logMsg('warn', 'Attempt to redefine', key,
                                '(this should not happen)')
        else:
            dictionary[key] = info

    def lookupElementInfo(self, fname, dictionary):
        """Find a {Type|Enum|Cmd}Info object by name.

        Intended for internal use only.

        If an object qualified by API name exists, use that.

        - fname - name of type / enum / command
        - dictionary - self.{type|enum|cmd}dict"""
        key = (fname, self.genOpts.apiname)
        if key in dictionary:
            # self.gen.logMsg('diag', 'Found API-specific element for feature', fname)
            return dictionary[key]
        if fname in dictionary:
            # self.gen.logMsg('diag', 'Found generic element for feature', fname)
            return dictionary[fname]

        return None

    def breakOnName(self, regexp):
        """Specify a feature name regexp to break on when generating features."""
        self.breakPat = re.compile(regexp)

    def parseTree(self):
        """Parse the registry Element, once created"""
        # This must be the Element for the root <registry>
        if self.tree is None:
            raise RuntimeError("Tree not initialized!")
        self.reg = self.tree.getroot()

        # Preprocess the tree in one of the following ways:
        # - either merge a set of APIs to another API based on their 'api' attributes
        # - or remove all elements with non-matching 'api' attributes
        # The preprocessing happens through a breath-first tree traversal.
        # This is a blunt hammer, but eliminates the need to track and test
        # the apis deeper in processing to select the correct elements and
        # avoid duplicates.
        # Schema validation should prevent duplicate elements with
        # overlapping api attributes, or where one element has an api
        # attribute and the other does not.

        if self.genOpts.mergeApiNames:
            mergeAPIs(self.reg, self.genOpts.mergeApiNames.split(','), self.genOpts.apiname)
        else:
            stripNonmatchingAPIs(self.reg, self.genOpts.apiname, actuallyDelete = True)

        # Create dictionary of registry types from toplevel <types> tags
        # and add 'name' attribute to each <type> tag (where missing)
        # based on its <name> element.
        #
        # There is usually one <types> block; more are OK
        # Required <type> attributes: 'name' or nested <name> tag contents
        self.typedict = {}
        for type_elem in self.reg.findall('types/type'):
            # If the <type> does not already have a 'name' attribute, set
            # it from contents of its <name> tag.
            if type_elem.get('name') is None:
                name_elem = type_elem.find('name')
                if name_elem is None or not name_elem.text:
                    raise RuntimeError("Type without a name!")
                type_elem.set('name', name_elem.text)
            self.addElementInfo(type_elem, TypeInfo(type_elem), 'type', self.typedict)

        # Create dictionary of registry enum groups from <enums> tags.
        #
        # Required <enums> attributes: 'name'. If no name is given, one is
        # generated, but that group cannot be identified and turned into an
        # enum type definition - it is just a container for <enum> tags.
        self.groupdict = {}
        for group in self.reg.findall('enums'):
            self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict)

        # Create dictionary of registry enums from <enum> tags
        #
        # <enums> tags usually define different namespaces for the values
        #   defined in those tags, but the actual names all share the
        #   same dictionary.
        # Required <enum> attributes: 'name', 'value'
        # For containing <enums> which have type="enum" or type="bitmask",
        # tag all contained <enum>s are required. This is a stopgap until
        # a better scheme for tagging core and extension enums is created.
        self.enumdict = {}
        for enums in self.reg.findall('enums'):
            required = (enums.get('type') is not None)
            for enum in enums.findall('enum'):
                enumInfo = EnumInfo(enum)
                enumInfo.required = required
                self.addElementInfo(enum, enumInfo, 'enum', self.enumdict)

        # Create dictionary of registry commands from <command> tags
        # and add 'name' attribute to each <command> tag (where missing)
        # based on its <proto><name> element.
        #
        # There is usually only one <commands> block; more are OK.
        # Required <command> attributes: 'name' or <proto><name> tag contents
        self.cmddict = {}
        # List of commands which alias others. Contains
        #   [ aliasName, element ]
        # for each alias
        cmdAlias = []
        for cmd in self.reg.findall('commands/command'):
            # If the <command> does not already have a 'name' attribute, set
            # it from contents of its <proto><name> tag.
            name = cmd.get('name')
            if name is None:
                name_elem = cmd.find('proto/name')
                if name_elem is None or not name_elem.text:
                    raise RuntimeError("Command without a name!")
                name = cmd.set('name', name_elem.text)
            ci = CmdInfo(cmd)
            self.addElementInfo(cmd, ci, 'command', self.cmddict)
            alias = cmd.get('alias')
            if alias:
                cmdAlias.append([name, alias, cmd])

        # Now loop over aliases, injecting a copy of the aliased command's
        # Element with the aliased prototype name replaced with the command
        # name - if it exists.
        for (name, alias, cmd) in cmdAlias:
            if alias in self.cmddict:
                aliasInfo = self.cmddict[alias]
                cmdElem = copy.deepcopy(aliasInfo.elem)
                cmdElem.find('proto/name').text = name
                cmdElem.set('name', name)
                cmdElem.set('alias', alias)
                ci = CmdInfo(cmdElem)
                # Replace the dictionary entry for the CmdInfo element
                self.cmddict[name] = ci

                # @  newString = etree.tostring(base, encoding="unicode").replace(aliasValue, aliasName)
                # @elem.append(etree.fromstring(replacement))
            else:
                self.gen.logMsg('warn', 'No matching <command> found for command',
                                cmd.get('name'), 'alias', alias)

        # Create dictionaries of API and extension interfaces
        #   from toplevel <api> and <extension> tags.
        self.apidict = {}
        format_condition = dict()
        for feature in self.reg.findall('feature'):
            featureInfo = FeatureInfo(feature)
            self.addElementInfo(feature, featureInfo, 'feature', self.apidict)

            # Add additional enums defined only in <feature> tags
            # to the corresponding enumerated type.
            # When seen here, the <enum> element, processed to contain the
            # numeric enum value, is added to the corresponding <enums>
            # element, as well as adding to the enum dictionary. It is no
            # longer removed from the <require> element it is introduced in.
            # Instead, generateRequiredInterface ignores <enum> elements
            # that extend enumerated types.
            #
            # For <enum> tags which are actually just constants, if there is
            # no 'extends' tag but there is a 'value' or 'bitpos' tag, just
            # add an EnumInfo record to the dictionary. That works because
            # output generation of constants is purely dependency-based, and
            # does not need to iterate through the XML tags.
            for elem in feature.findall('require'):
                for enum in elem.findall('enum'):
                    addEnumInfo = False
                    groupName = enum.get('extends')
                    if groupName is not None:
                        # self.gen.logMsg('diag', 'Found extension enum',
                        #     enum.get('name'))
                        # Add version number attribute to the <enum> element
                        enum.set('version', featureInfo.version)
                        # Look up the GroupInfo with matching groupName
                        if groupName in self.groupdict:
                            # self.gen.logMsg('diag', 'Matching group',
                            #     groupName, 'found, adding element...')
                            gi = self.groupdict[groupName]
                            gi.elem.append(copy.deepcopy(enum))
                        else:
                            self.gen.logMsg('warn', 'NO matching group',
                                            groupName, 'for enum', enum.get('name'), 'found.')
                        if groupName == "VkFormat":
                            format_name = enum.get('name')
                            if enum.get('alias'):
                                format_name = enum.get('alias')
                            format_condition[format_name] = featureInfo.name
                        addEnumInfo = True
                    elif enum.get('value') or enum.get('bitpos') or enum.get('alias'):
                        # self.gen.logMsg('diag', 'Adding extension constant "enum"',
                        #     enum.get('name'))
                        addEnumInfo = True
                    if addEnumInfo:
                        enumInfo = EnumInfo(enum)
                        self.addElementInfo(enum, enumInfo, 'enum', self.enumdict)

        sync_pipeline_stage_condition = dict()
        sync_access_condition = dict()

        self.extensions = self.reg.findall('extensions/extension')
        self.extdict = {}
        for feature in self.extensions:
            featureInfo = FeatureInfo(feature)
            self.addElementInfo(feature, featureInfo, 'extension', self.extdict)

            # Add additional enums defined only in <extension> tags
            # to the corresponding core type.
            # Algorithm matches that of enums in a "feature" tag as above.
            #
            # This code also adds a 'extnumber' attribute containing the
            # extension number, used for enumerant value calculation.
            for elem in feature.findall('require'):
                for enum in elem.findall('enum'):
                    addEnumInfo = False
                    groupName = enum.get('extends')
                    if groupName is not None:
                        # self.gen.logMsg('diag', 'Found extension enum',
                        #     enum.get('name'))

                        # Add <extension> block's extension number attribute to
                        # the <enum> element unless specified explicitly, such
                        # as when redefining an enum in another extension.
                        extnumber = enum.get('extnumber')
                        if not extnumber:
                            enum.set('extnumber', str(featureInfo.number))

                        enum.set('extname', featureInfo.name)
                        enum.set('supported', noneStr(featureInfo.supported))
                        # Look up the GroupInfo with matching groupName
                        if groupName in self.groupdict:
                            # self.gen.logMsg('diag', 'Matching group',
                            #     groupName, 'found, adding element...')
                            gi = self.groupdict[groupName]
                            gi.elem.append(copy.deepcopy(enum))
                        else:
                            self.gen.logMsg('warn', 'NO matching group',
                                            groupName, 'for enum', enum.get('name'), 'found.')
                        # This is Vulkan-specific
                        if groupName == "VkFormat":
                            format_name = enum.get('name')
                            if enum.get('alias'):
                                format_name = enum.get('alias')
                            if format_name in format_condition:
                                format_condition[format_name] += "," + featureInfo.name
                            else:
                                format_condition[format_name] = featureInfo.name
                        elif groupName == "VkPipelineStageFlagBits2":
                            stage_flag = enum.get('name')
                            if enum.get('alias'):
                                stage_flag = enum.get('alias')
                            featureName = elem.get('depends') if elem.get('depends') is not None else featureInfo.name
                            if stage_flag in sync_pipeline_stage_condition:
                                sync_pipeline_stage_condition[stage_flag] += "," + featureName
                            else:
                                sync_pipeline_stage_condition[stage_flag] = featureName
                        elif groupName == "VkAccessFlagBits2":
                            access_flag = enum.get('name')
                            if enum.get('alias'):
                                access_flag = enum.get('alias')
                            featureName = elem.get('depends') if elem.get('depends') is not None else featureInfo.name
                            if access_flag in sync_access_condition:
                                sync_access_condition[access_flag] += "," + featureName
                            else:
                                sync_access_condition[access_flag] = featureName

                        addEnumInfo = True
                    elif enum.get('value') or enum.get('bitpos') or enum.get('alias'):
                        # self.gen.logMsg('diag', 'Adding extension constant "enum"',
                        #     enum.get('name'))
                        addEnumInfo = True
                    if addEnumInfo:
                        enumInfo = EnumInfo(enum)
                        self.addElementInfo(enum, enumInfo, 'enum', self.enumdict)

        # Parse out all spirv tags in dictionaries
        # Use addElementInfo to catch duplicates
        for spirv in self.reg.findall('spirvextensions/spirvextension'):
            spirvInfo = SpirvInfo(spirv)
            self.addElementInfo(spirv, spirvInfo, 'spirvextension', self.spirvextdict)
        for spirv in self.reg.findall('spirvcapabilities/spirvcapability'):
            spirvInfo = SpirvInfo(spirv)
            self.addElementInfo(spirv, spirvInfo, 'spirvcapability', self.spirvcapdict)

        for format in self.reg.findall('formats/format'):
            condition = None
            format_name = format.get('name')
            if format_name in format_condition:
                condition = format_condition[format_name]
            formatInfo = FormatInfo(format, condition)
            self.addElementInfo(format, formatInfo, 'format', self.formatsdict)

        for stage in self.reg.findall('sync/syncstage'):
            condition = None
            stage_flag = stage.get('name')
            if stage_flag in sync_pipeline_stage_condition:
                condition = sync_pipeline_stage_condition[stage_flag]
            syncInfo = SyncStageInfo(stage, condition)
            self.addElementInfo(stage, syncInfo, 'syncstage', self.syncstagedict)

        for access in self.reg.findall('sync/syncaccess'):
            condition = None
            access_flag = access.get('name')
            if access_flag in sync_access_condition:
                condition = sync_access_condition[access_flag]
            syncInfo = SyncAccessInfo(access, condition)
            self.addElementInfo(access, syncInfo, 'syncaccess', self.syncaccessdict)

        for pipeline in self.reg.findall('sync/syncpipeline'):
            syncInfo = SyncPipelineInfo(pipeline)
            self.addElementInfo(pipeline, syncInfo, 'syncpipeline', self.syncpipelinedict)

    def dumpReg(self, maxlen=120, filehandle=sys.stdout):
        """Dump all the dictionaries constructed from the Registry object.

        Diagnostic to dump the dictionaries to specified file handle (default stdout).
        Truncates type / enum / command elements to maxlen characters (default 120)"""
        write('***************************************', file=filehandle)
        write('    ** Dumping Registry contents **',     file=filehandle)
        write('***************************************', file=filehandle)
        write('// Types', file=filehandle)
        for name in self.typedict:
            tobj = self.typedict[name]
            write('    Type', name, '->', etree.tostring(tobj.elem)[0:maxlen], file=filehandle)
        write('// Groups', file=filehandle)
        for name in self.groupdict:
            gobj = self.groupdict[name]
            write('    Group', name, '->', etree.tostring(gobj.elem)[0:maxlen], file=filehandle)
        write('// Enums', file=filehandle)
        for name in self.enumdict:
            eobj = self.enumdict[name]
            write('    Enum', name, '->', etree.tostring(eobj.elem)[0:maxlen], file=filehandle)
        write('// Commands', file=filehandle)
        for name in self.cmddict:
            cobj = self.cmddict[name]
            write('    Command', name, '->', etree.tostring(cobj.elem)[0:maxlen], file=filehandle)
        write('// APIs', file=filehandle)
        for key in self.apidict:
            write('    API Version ', key, '->',
                  etree.tostring(self.apidict[key].elem)[0:maxlen], file=filehandle)
        write('// Extensions', file=filehandle)
        for key in self.extdict:
            write('    Extension', key, '->',
                  etree.tostring(self.extdict[key].elem)[0:maxlen], file=filehandle)
        write('// SPIR-V', file=filehandle)
        for key in self.spirvextdict:
            write('    SPIR-V Extension', key, '->',
                  etree.tostring(self.spirvextdict[key].elem)[0:maxlen], file=filehandle)
        for key in self.spirvcapdict:
            write('    SPIR-V Capability', key, '->',
                  etree.tostring(self.spirvcapdict[key].elem)[0:maxlen], file=filehandle)
        write('// VkFormat', file=filehandle)
        for key in self.formatsdict:
            write('    VkFormat', key, '->',
                  etree.tostring(self.formatsdict[key].elem)[0:maxlen], file=filehandle)

    def markTypeRequired(self, typename, required):
        """Require (along with its dependencies) or remove (but not its dependencies) a type.

        - typename - name of type
        - required - boolean (to tag features as required or not)
        """
        self.gen.logMsg('diag', 'tagging type:', typename, '-> required =', required)

        # Get TypeInfo object for <type> tag corresponding to typename
        typeinfo = self.lookupElementInfo(typename, self.typedict)
        if typeinfo is not None:
            if required:
                # Tag type dependencies in 'alias' and 'required' attributes as
                # required. This does not un-tag dependencies in a <remove>
                # tag. See comments in markRequired() below for the reason.
                for attrib_name in ['requires', 'alias']:
                    depname = typeinfo.elem.get(attrib_name)
                    if depname:
                        self.gen.logMsg('diag', 'Generating dependent type',
                                        depname, 'for', attrib_name, 'type', typename)
                        # Do not recurse on self-referential structures.
                        if typename != depname:
                            self.markTypeRequired(depname, required)
                        else:
                            self.gen.logMsg('diag', 'type', typename, 'is self-referential')
                # Tag types used in defining this type (e.g. in nested
                # <type> tags)
                # Look for <type> in entire <command> tree,
                # not just immediate children
                for subtype in typeinfo.elem.findall('.//type'):
                    self.gen.logMsg('diag', 'markRequired: type requires dependent <type>', subtype.text)
                    if typename != subtype.text:
                        self.markTypeRequired(subtype.text, required)
                    else:
                        self.gen.logMsg('diag', 'type', typename, 'is self-referential')
                # Tag enums used in defining this type, for example in
                #   <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member>
                for subenum in typeinfo.elem.findall('.//enum'):
                    self.gen.logMsg('diag', 'markRequired: type requires dependent <enum>', subenum.text)
                    self.markEnumRequired(subenum.text, required)
                # Tag type dependency in 'bitvalues' attributes as
                # required. This ensures that the bit values for a flag
                # are emitted
                depType = typeinfo.elem.get('bitvalues')
                if depType:
                    self.gen.logMsg('diag', 'Generating bitflag type',
                                    depType, 'for type', typename)
                    self.markTypeRequired(depType, required)
                    group = self.lookupElementInfo(depType, self.groupdict)
                    if group is not None:
                        group.flagType = typeinfo

            typeinfo.required = required
        elif '.h' not in typename:
            self.gen.logMsg('warn', 'type:', typename, 'IS NOT DEFINED')

    def markEnumRequired(self, enumname, required):
        """Mark an enum as required or not.

        - enumname - name of enum
        - required - boolean (to tag features as required or not)"""

        self.gen.logMsg('diag', 'markEnumRequired: tagging enum:', enumname, '-> required =', required)
        enum = self.lookupElementInfo(enumname, self.enumdict)
        if enum is not None:
            # If the enum is part of a group, and is being removed, then
            # look it up in that <enums> tag and remove the Element there,
            # so that it is not visible to generators (which traverse the
            # <enums> tag elements rather than using the dictionaries).
            if not required:
                groupName = enum.elem.get('extends')
                if groupName is not None:
                    self.gen.logMsg('diag', f'markEnumRequired: Removing extending enum {enum.elem.get("name")}')

                    # Look up the Info with matching groupName
                    if groupName in self.groupdict:
                        gi = self.groupdict[groupName]
                        gienum = gi.elem.find("enum[@name='" + enumname + "']")
                        if gienum is not None:
                            # Remove copy of this enum from the group
                            gi.elem.remove(gienum)
                        else:
                            self.gen.logMsg('warn', 'markEnumRequired: Cannot remove enum',
                                            enumname, 'not found in group',
                                            groupName)
                    else:
                        self.gen.logMsg('warn', 'markEnumRequired: Cannot remove enum',
                                        enumname, 'from nonexistent group',
                                        groupName)
                else:
                    # This enum is not an extending enum.
                    # The XML tree must be searched for all <enums> that
                    # might have it, so we know the parent to delete from.

                    enumName = enum.elem.get('name')

                    self.gen.logMsg('diag', f'markEnumRequired: Removing non-extending enum {enumName}')

                    count = 0
                    for enums in self.reg.findall('enums'):
                        for thisEnum in enums.findall('enum'):
                            if thisEnum.get('name') == enumName:
                                # Actually remove it
                                count = count + 1
                                enums.remove(thisEnum)

                    if count == 0:
                        self.gen.logMsg('warn', f'markEnumRequired: {enumName}) not found in any <enums> tag')

            enum.required = required
            # Tag enum dependencies in 'alias' attribute as required
            depname = enum.elem.get('alias')
            if depname:
                self.gen.logMsg('diag', 'markEnumRequired: Generating dependent enum',
                                depname, 'for alias', enumname, 'required =', enum.required)
                self.markEnumRequired(depname, required)
        else:
            self.gen.logMsg('warn', f'markEnumRequired: {enumname} IS NOT DEFINED')

    def markCmdRequired(self, cmdname, required):
        """Mark a command as required or not.

        - cmdname - name of command
        - required - boolean (to tag features as required or not)"""
        self.gen.logMsg('diag', 'tagging command:', cmdname, '-> required =', required)
        cmd = self.lookupElementInfo(cmdname, self.cmddict)
        if cmd is not None:
            cmd.required = required

            # Tag command dependencies in 'alias' attribute as required
            #
            # This is usually not done, because command 'aliases' are not
            # actual C language aliases like type and enum aliases. Instead
            # they are just duplicates of the function signature of the
            # alias. This means that there is no dependency of a command
            # alias on what it aliases. One exception is validity includes,
            # where the spec markup needs the promoted-to validity include
            # even if only the promoted-from command is being built.
            if self.genOpts.requireCommandAliases:
                depname = cmd.elem.get('alias')
                if depname:
                    self.gen.logMsg('diag', 'Generating dependent command',
                                    depname, 'for alias', cmdname)
                    self.markCmdRequired(depname, required)

            # Tag all parameter types of this command as required.
            # This does not remove types of commands in a <remove>
            # tag, because many other commands may use the same type.
            # We could be more clever and reference count types,
            # instead of using a boolean.
            if required:
                # Look for <type> in entire <command> tree,
                # not just immediate children
                for type_elem in cmd.elem.findall('.//type'):
                    self.gen.logMsg('diag', 'markRequired: command implicitly requires dependent type', type_elem.text)
                    self.markTypeRequired(type_elem.text, required)
        else:
            self.gen.logMsg('warn', 'command:', cmdname, 'IS NOT DEFINED')

    def markRequired(self, featurename, feature, required):
        """Require or remove features specified in the Element.

        - featurename - name of the feature
        - feature - Element for `<require>` or `<remove>` tag
        - required - boolean (to tag features as required or not)"""
        self.gen.logMsg('diag', 'markRequired (feature = <too long to print>, required =', required, ')')

        # Loop over types, enums, and commands in the tag
        # @@ It would be possible to respect 'api' and 'profile' attributes
        #  in individual features, but that is not done yet.
        for typeElem in feature.findall('type'):
            self.markTypeRequired(typeElem.get('name'), required)
        for enumElem in feature.findall('enum'):
            self.markEnumRequired(enumElem.get('name'), required)

        for cmdElem in feature.findall('command'):
            self.markCmdRequired(cmdElem.get('name'), required)

        # Extensions may need to extend existing commands or other items in the future.
        # So, look for extend tags.
        for extendElem in feature.findall('extend'):
            extendType = extendElem.get('type')
            if extendType == 'command':
                commandName = extendElem.get('name')
                successExtends = extendElem.get('successcodes')
                if successExtends is not None:
                    for success in successExtends.split(','):
                        self.commandextensionsuccesses.append(self.commandextensiontuple(command=commandName,
                                                                                         value=success,
                                                                                         extension=featurename))
                errorExtends = extendElem.get('errorcodes')
                if errorExtends is not None:
                    for error in errorExtends.split(','):
                        self.commandextensionerrors.append(self.commandextensiontuple(command=commandName,
                                                                                      value=error,
                                                                                      extension=featurename))
            else:
                self.gen.logMsg('warn', 'extend type:', extendType, 'IS NOT SUPPORTED')

    def getAlias(self, elem, dict):
        """Check for an alias in the same require block.

        - elem - Element to check for an alias"""

        # Try to find an alias
        alias = elem.get('alias')
        if alias is None:
            name = elem.get('name')
            typeinfo = self.lookupElementInfo(name, dict)
            if not typeinfo:
                self.gen.logMsg('error', name, 'is not a known name')
            alias = typeinfo.elem.get('alias')

        return alias

    def checkForCorrectionAliases(self, alias, require, tag):
        """Check for an alias in the same require block.

        - alias - String name of the alias
        - require -  `<require>` block from the registry
        - tag - tag to look for in the require block"""

        # For the time being, the code below is bypassed. It has the effect
        # of excluding "spelling aliases" created to comply with the style
        # guide, but this leaves references out of the specification and
        # causes broken internal links.
        #
        # if alias and require.findall(tag + "[@name='" + alias + "']"):
        #     return True

        return False

    def fillFeatureDictionary(self, interface, featurename, api, profile):
        """Capture added interfaces for a `<version>` or `<extension>`.

        - interface - Element for `<version>` or `<extension>`, containing
          `<require>` and `<remove>` tags
        - featurename - name of the feature
        - api - string specifying API name being generated
        - profile - string specifying API profile being generated"""

        # Explicitly initialize known types - errors for unhandled categories
        self.gen.featureDictionary[featurename] = {
            "enumconstant": {},
            "command": {},
            "enum": {},
            "struct": {},
            "handle": {},
            "basetype": {},
            "include": {},
            "define": {},
            "bitmask": {},
            "union": {},
            "funcpointer": {},
        }

        # <require> marks things that are required by this version/profile
        for require in interface.findall('require'):
            if matchAPIProfile(api, profile, require):

                # Determine the required extension or version needed for a require block
                # Assumes that only one of these is specified
                # 'extension', and therefore 'required_key', may be a boolean
                # expression of extension names.
                # 'required_key' is used only as a dictionary key at
                # present, and passed through to the script generators, so
                # they must be prepared to parse that boolean expression.
                required_key = require.get('depends')

                # Loop over types, enums, and commands in the tag
                for typeElem in require.findall('type'):
                    typename = typeElem.get('name')
                    typeinfo = self.lookupElementInfo(typename, self.typedict)

                    if typeinfo:
                        # Remove aliases in the same extension/feature; these are always added as a correction. Do not need the original to be visible.
                        alias = self.getAlias(typeElem, self.typedict)
                        if not self.checkForCorrectionAliases(alias, require, 'type'):
                            # Resolve the type info to the actual type, so we get an accurate read for 'structextends'
                            while alias:
                                typeinfo = self.lookupElementInfo(alias, self.typedict)
                                alias = typeinfo.elem.get('alias')

                            typecat = typeinfo.elem.get('category')
                            typeextends = typeinfo.elem.get('structextends')
                            if not required_key in self.gen.featureDictionary[featurename][typecat]:
                                self.gen.featureDictionary[featurename][typecat][required_key] = {}
                            if not typeextends in self.gen.featureDictionary[featurename][typecat][required_key]:
                                self.gen.featureDictionary[featurename][typecat][required_key][typeextends] = []
                            self.gen.featureDictionary[featurename][typecat][required_key][typeextends].append(typename)
                        else:
                            self.gen.logMsg('warn', 'fillFeatureDictionary: NOT filling for {}'.format(typename))


                for enumElem in require.findall('enum'):
                    enumname = enumElem.get('name')
                    typeinfo = self.lookupElementInfo(enumname, self.enumdict)

                    # Remove aliases in the same extension/feature; these are always added as a correction. Do not need the original to be visible.
                    alias = self.getAlias(enumElem, self.enumdict)
                    if not self.checkForCorrectionAliases(alias, require, 'enum'):
                        enumextends = enumElem.get('extends')
                        if not required_key in self.gen.featureDictionary[featurename]['enumconstant']:
                            self.gen.featureDictionary[featurename]['enumconstant'][required_key] = {}
                        if not enumextends in self.gen.featureDictionary[featurename]['enumconstant'][required_key]:
                            self.gen.featureDictionary[featurename]['enumconstant'][required_key][enumextends] = []
                        self.gen.featureDictionary[featurename]['enumconstant'][required_key][enumextends].append(enumname)
                    else:
                        self.gen.logMsg('warn', 'fillFeatureDictionary: NOT filling for {}'.format(typename))

                for cmdElem in require.findall('command'):
                    # Remove aliases in the same extension/feature; these are always added as a correction. Do not need the original to be visible.
                    alias = self.getAlias(cmdElem, self.cmddict)
                    if not self.checkForCorrectionAliases(alias, require, 'command'):
                        if not required_key in self.gen.featureDictionary[featurename]['command']:
                            self.gen.featureDictionary[featurename]['command'][required_key] = []
                        self.gen.featureDictionary[featurename]['command'][required_key].append(cmdElem.get('name'))
                    else:
                        self.gen.logMsg('warn', 'fillFeatureDictionary: NOT filling for {}'.format(typename))

    def requireFeatures(self, interface, featurename, api, profile):
        """Process `<require>` tags for a `<version>` or `<extension>`.

        - interface - Element for `<version>` or `<extension>`, containing
          `<require>` tags
        - featurename - name of the feature
        - api - string specifying API name being generated
        - profile - string specifying API profile being generated"""

        # <require> marks things that are required by this version/profile
        for feature in interface.findall('require'):
            if matchAPIProfile(api, profile, feature):
                self.markRequired(featurename, feature, True)

    def removeFeatures(self, interface, featurename, api, profile):
        """Process `<remove>` tags for a `<version>` or `<extension>`.

        - interface - Element for `<version>` or `<extension>`, containing
          `<remove>` tags
        - featurename - name of the feature
        - api - string specifying API name being generated
        - profile - string specifying API profile being generated"""

        # <remove> marks things that are removed by this version/profile
        for feature in interface.findall('remove'):
            if matchAPIProfile(api, profile, feature):
                self.markRequired(featurename, feature, False)

    def assignAdditionalValidity(self, interface, api, profile):
        # Loop over all usage inside all <require> tags.
        for feature in interface.findall('require'):
            if matchAPIProfile(api, profile, feature):
                for v in feature.findall('usage'):
                    if v.get('command'):
                        self.cmddict[v.get('command')].additionalValidity.append(copy.deepcopy(v))
                    if v.get('struct'):
                        self.typedict[v.get('struct')].additionalValidity.append(copy.deepcopy(v))

    def removeAdditionalValidity(self, interface, api, profile):
        # Loop over all usage inside all <remove> tags.
        for feature in interface.findall('remove'):
            if matchAPIProfile(api, profile, feature):
                for v in feature.findall('usage'):
                    if v.get('command'):
                        self.cmddict[v.get('command')].removedValidity.append(copy.deepcopy(v))
                    if v.get('struct'):
                        self.typedict[v.get('struct')].removedValidity.append(copy.deepcopy(v))

    def generateFeature(self, fname, ftype, dictionary, explicit=False):
        """Generate a single type / enum group / enum / command,
        and all its dependencies as needed.

        - fname - name of feature (`<type>`/`<enum>`/`<command>`)
        - ftype - type of feature, 'type' | 'enum' | 'command'
        - dictionary - of *Info objects - self.{type|enum|cmd}dict
        - explicit - True if this is explicitly required by the top-level
          XML <require> tag, False if it is a dependency of an explicit
          requirement."""

        self.gen.logMsg('diag', 'generateFeature: generating', ftype, fname)

        if not (explicit or self.genOpts.requireDepends):
            self.gen.logMsg('diag', 'generateFeature: NOT generating', ftype, fname, 'because generator does not require dependencies')
            return

        f = self.lookupElementInfo(fname, dictionary)
        if f is None:
            # No such feature. This is an error, but reported earlier
            self.gen.logMsg('diag', 'No entry found for feature', fname,
                            'returning!')
            return

        # If feature is not required, or has already been declared, return
        if not f.required:
            self.gen.logMsg('diag', 'Skipping', ftype, fname, '(not required)')
            return
        if f.declared:
            self.gen.logMsg('diag', 'Skipping', ftype, fname, '(already declared)')
            return
        # Always mark feature declared, as though actually emitted
        f.declared = True

        # Determine if this is an alias, and of what, if so
        alias = f.elem.get('alias')
        if alias:
            self.gen.logMsg('diag', fname, 'is an alias of', alias)

        # Pull in dependent declaration(s) of the feature.
        # For types, there may be one type in the 'requires' attribute of
        #   the element, one in the 'alias' attribute, and many in
        #   embedded <type> and <enum> tags within the element.
        # For commands, there may be many in <type> tags within the element.
        # For enums, no dependencies are allowed (though perhaps if you
        #   have a uint64 enum, it should require that type).
        genProc = None
        followupFeature = None
        if ftype == 'type':
            genProc = self.gen.genType

            # Generate type dependencies in 'alias' and 'requires' attributes
            if alias:
                self.generateFeature(alias, 'type', self.typedict)
            requires = f.elem.get('requires')
            if requires:
                self.gen.logMsg('diag', 'Generating required dependent type',
                                requires)
                self.generateFeature(requires, 'type', self.typedict)

            # Generate types used in defining this type (e.g. in nested
            # <type> tags)
            # Look for <type> in entire <command> tree,
            # not just immediate children
            for subtype in f.elem.findall('.//type'):
                self.gen.logMsg('diag', 'Generating required dependent <type>',
                                subtype.text)
                self.generateFeature(subtype.text, 'type', self.typedict)

            # Generate enums used in defining this type, for example in
            #   <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member>
            for subtype in f.elem.findall('.//enum'):
                self.gen.logMsg('diag', 'Generating required dependent <enum>',
                                subtype.text)
                self.generateFeature(subtype.text, 'enum', self.enumdict)

            # If the type is an enum group, look up the corresponding
            # group in the group dictionary and generate that instead.
            if f.elem.get('category') == 'enum':
                self.gen.logMsg('diag', 'Type', fname, 'is an enum group, so generate that instead')
                group = self.lookupElementInfo(fname, self.groupdict)
                if alias is not None:
                    # An alias of another group name.
                    # Pass to genGroup with 'alias' parameter = aliased name
                    self.gen.logMsg('diag', 'Generating alias', fname,
                                    'for enumerated type', alias)
                    # Now, pass the *aliased* GroupInfo to the genGroup, but
                    # with an additional parameter which is the alias name.
                    genProc = self.gen.genGroup
                    f = self.lookupElementInfo(alias, self.groupdict)
                elif group is None:
                    self.gen.logMsg('warn', 'Skipping enum type', fname,
                                    ': No matching enumerant group')
                    return
                else:
                    genProc = self.gen.genGroup
                    f = group

                    # @ The enum group is not ready for generation. At this
                    # @   point, it contains all <enum> tags injected by
                    # @   <extension> tags without any verification of whether
                    # @   they are required or not. It may also contain
                    # @   duplicates injected by multiple consistent
                    # @   definitions of an <enum>.

                    # @ Pass over each enum, marking its enumdict[] entry as
                    # @ required or not. Mark aliases of enums as required,
                    # @ too.

                    enums = group.elem.findall('enum')

                    self.gen.logMsg('diag', 'generateFeature: checking enums for group', fname)

                    # Check for required enums, including aliases
                    # LATER - Check for, report, and remove duplicates?
                    enumAliases = []
                    for elem in enums:
                        name = elem.get('name')

                        required = False

                        extname = elem.get('extname')
                        version = elem.get('version')
                        if extname is not None:
                            # 'supported' attribute was injected when the <enum> element was
                            # moved into the <enums> group in Registry.parseTree()
                            supported_list = elem.get('supported').split(",")
                            if self.genOpts.defaultExtensions in supported_list:
                                required = True
                            elif re.match(self.genOpts.addExtensions, extname) is not None:
                                required = True
                        elif version is not None:
                            required = re.match(self.genOpts.emitversions, version) is not None
                        else:
                            required = True

                        self.gen.logMsg('diag', '* required =', required, 'for', name)
                        if required:
                            # Mark this element as required (in the element, not the EnumInfo)
                            elem.set('required', 'true')
                            # If it is an alias, track that for later use
                            enumAlias = elem.get('alias')
                            if enumAlias:
                                enumAliases.append(enumAlias)
                    for elem in enums:
                        name = elem.get('name')
                        if name in enumAliases:
                            elem.set('required', 'true')
                            self.gen.logMsg('diag', '* also need to require alias', name)
            if f is None:
                raise RuntimeError("Should not get here")
            if f.elem.get('category') == 'bitmask':
                followupFeature = f.elem.get('bitvalues')
        elif ftype == 'command':
            # Generate command dependencies in 'alias' attribute
            if alias:
                self.generateFeature(alias, 'command', self.cmddict)

            genProc = self.gen.genCmd
            for type_elem in f.elem.findall('.//type'):
                depname = type_elem.text
                self.gen.logMsg('diag', 'Generating required parameter type',
                                depname)
                self.generateFeature(depname, 'type', self.typedict)
        elif ftype == 'enum':
            # Generate enum dependencies in 'alias' attribute
            if alias:
                self.generateFeature(alias, 'enum', self.enumdict)
            genProc = self.gen.genEnum

        # Actually generate the type only if emitting declarations
        if self.emitFeatures:
            self.gen.logMsg('diag', 'Emitting', ftype, 'decl for', fname)
            if genProc is None:
                raise RuntimeError("genProc is None when we should be emitting")
            genProc(f, fname, alias)
        else:
            self.gen.logMsg('diag', 'Skipping', ftype, fname,
                            '(should not be emitted)')

        if followupFeature:
            self.gen.logMsg('diag', 'Generating required bitvalues <enum>',
                            followupFeature)
            self.generateFeature(followupFeature, "type", self.typedict)

    def generateRequiredInterface(self, interface):
        """Generate all interfaces required by an API version or extension.

        - interface - Element for `<version>` or `<extension>`"""

        # Loop over all features inside all <require> tags.
        for features in interface.findall('require'):
            for t in features.findall('type'):
                self.generateFeature(t.get('name'), 'type', self.typedict, explicit=True)
            for e in features.findall('enum'):
                # If this is an enum extending an enumerated type, do not
                # generate it - this has already been done in reg.parseTree,
                # by copying this element into the enumerated type.
                enumextends = e.get('extends')
                if not enumextends:
                    self.generateFeature(e.get('name'), 'enum', self.enumdict, explicit=True)
            for c in features.findall('command'):
                self.generateFeature(c.get('name'), 'command', self.cmddict, explicit=True)

    def generateSpirv(self, spirv, dictionary):
        if spirv is None:
            self.gen.logMsg('diag', 'No entry found for element', name,
                            'returning!')
            return

        name = spirv.elem.get('name')
        # No known alias for spirv elements
        alias = None
        if spirv.emit:
            genProc = self.gen.genSpirv
            genProc(spirv, name, alias)

    def stripUnsupportedAPIs(self, dictionary, attribute, supportedDictionary):
        """Strip unsupported APIs from attributes of APIs.
           dictionary - *Info dictionary of APIs to be updated
           attribute - attribute name to look for in each API
           supportedDictionary - dictionary in which to look for supported
            API elements in the attribute"""

        for key in dictionary:
            eleminfo = dictionary[key]
            attribstring = eleminfo.elem.get(attribute)
            if attribstring is not None:
                apis = []
                stripped = False
                for api in attribstring.split(','):
                    ##print('Checking API {} referenced by {}'.format(api, key))
                    if api in supportedDictionary and supportedDictionary[api].required:
                        apis.append(api)
                    else:
                        stripped = True
                        ##print('\t**STRIPPING API {} from {}'.format(api, key))

                # Update the attribute after stripping stuff.
                # Could sort apis before joining, but it is not a clear win
                if stripped:
                    eleminfo.elem.set(attribute, ','.join(apis))

    def stripUnsupportedAPIsFromList(self, dictionary, supportedDictionary):
        """Strip unsupported APIs from attributes of APIs.
           dictionary - dictionary of list of structure name strings
           supportedDictionary - dictionary in which to look for supported
            API elements in the attribute"""

        for key in dictionary:
            attribstring = dictionary[key]
            if attribstring is not None:
                apis = []
                stripped = False
                for api in attribstring:
                    ##print('Checking API {} referenced by {}'.format(api, key))
                    if supportedDictionary[api].required:
                        apis.append(api)
                    else:
                        stripped = True
                        ##print('\t**STRIPPING API {} from {}'.format(api, key))

                # Update the attribute after stripping stuff.
                # Could sort apis before joining, but it is not a clear win
                if stripped:
                    dictionary[key] = apis

    def generateFormat(self, format, dictionary):
        if format is None:
            self.gen.logMsg('diag', 'No entry found for format element',
                            'returning!')
            return

        name = format.elem.get('name')
        # No known alias for VkFormat elements
        alias = None
        if format.emit:
            genProc = self.gen.genFormat
            genProc(format, name, alias)

    def generateSyncStage(self, sync):
        genProc = self.gen.genSyncStage
        genProc(sync)

    def generateSyncAccess(self, sync):
        genProc = self.gen.genSyncAccess
        genProc(sync)

    def generateSyncPipeline(self, sync):
        genProc = self.gen.genSyncPipeline
        genProc(sync)

    def tagValidExtensionStructs(self):
        """Construct a "validextensionstructs" list for parent structures
           based on "structextends" tags in child structures.
           Only do this for structures tagged as required."""

        for typeinfo in self.typedict.values():
            type_elem = typeinfo.elem
            if typeinfo.required and type_elem.get('category') == 'struct':
                struct_extends = type_elem.get('structextends')
                if struct_extends is not None:
                    for parent in struct_extends.split(','):
                        # self.gen.logMsg('diag', type_elem.get('name'), 'extends', parent)
                        self.validextensionstructs[parent].append(type_elem.get('name'))

        # Sort the lists so they do not depend on the XML order
        for parent in self.validextensionstructs:
            self.validextensionstructs[parent].sort()

    def apiGen(self):
        """Generate interface for specified versions using the current
        generator and generator options"""

        self.gen.logMsg('diag', '*******************************************')
        self.gen.logMsg('diag', '  Registry.apiGen file:', self.genOpts.filename,
                        'api:', self.genOpts.apiname,
                        'profile:', self.genOpts.profile)
        self.gen.logMsg('diag', '*******************************************')

        # Could reset required/declared flags for all features here.
        # This has been removed as never used. The initial motivation was
        # the idea of calling apiGen() repeatedly for different targets, but
        # this has never been done. The 20% or so build-time speedup that
        # might result is not worth the effort to make it actually work.
        #
        # self.apiReset()

        # Compile regexps used to select versions & extensions
        regVersions = re.compile(self.genOpts.versions)
        regEmitVersions = re.compile(self.genOpts.emitversions)
        regAddExtensions = re.compile(self.genOpts.addExtensions)
        regRemoveExtensions = re.compile(self.genOpts.removeExtensions)
        regEmitExtensions = re.compile(self.genOpts.emitExtensions)
        regEmitSpirv = re.compile(self.genOpts.emitSpirv)
        regEmitFormats = re.compile(self.genOpts.emitFormats)

        # Get all matching API feature names & add to list of FeatureInfo
        # Note we used to select on feature version attributes, not names.
        features = []
        apiMatch = False
        for key in self.apidict:
            fi = self.apidict[key]
            api = fi.elem.get('api')
            if apiNameMatch(self.genOpts.apiname, api):
                apiMatch = True
                if regVersions.match(fi.name):
                    # Matches API & version #s being generated. Mark for
                    # emission and add to the features[] list .
                    # @@ Could use 'declared' instead of 'emit'?
                    fi.emit = (regEmitVersions.match(fi.name) is not None)
                    features.append(fi)
                    if not fi.emit:
                        self.gen.logMsg('diag', 'NOT tagging feature api =', api,
                                        'name =', fi.name, 'version =', fi.version,
                                        'for emission (does not match emitversions pattern)')
                    else:
                        self.gen.logMsg('diag', 'Including feature api =', api,
                                        'name =', fi.name, 'version =', fi.version,
                                        'for emission (matches emitversions pattern)')
                else:
                    self.gen.logMsg('diag', 'NOT including feature api =', api,
                                    'name =', fi.name, 'version =', fi.version,
                                    '(does not match requested versions)')
            else:
                self.gen.logMsg('diag', 'NOT including feature api =', api,
                                'name =', fi.name,
                                '(does not match requested API)')
        if not apiMatch:
            self.gen.logMsg('warn', 'No matching API versions found!')

        # Get all matching extensions, in order by their extension number,
        # and add to the list of features.
        # Start with extensions whose 'supported' attributes match the API
        # being generated. Add extensions matching the pattern specified in
        # regExtensions, then remove extensions matching the pattern
        # specified in regRemoveExtensions
        for (extName, ei) in sorted(self.extdict.items(), key=lambda x: x[1].number if x[1].number is not None else '0'):
            extName = ei.name
            include = False

            # Include extension if defaultExtensions is not None and is
            # exactly matched by the 'supported' attribute.
            if apiNameMatch(self.genOpts.defaultExtensions,
                            ei.elem.get('supported')):
                self.gen.logMsg('diag', 'Including extension',
                                extName, "(defaultExtensions matches the 'supported' attribute)")
                include = True

            # Include additional extensions if the extension name matches
            # the regexp specified in the generator options. This allows
            # forcing extensions into an interface even if they are not
            # tagged appropriately in the registry.
            # However, we still respect the 'supported' attribute.
            if regAddExtensions.match(extName) is not None:
                if not apiNameMatch(self.genOpts.apiname, ei.elem.get('supported')):
                    self.gen.logMsg('diag', 'NOT including extension',
                                    extName, '(matches explicitly requested, but does not match the \'supported\' attribute)')
                    include = False
                else:
                    self.gen.logMsg('diag', 'Including extension',
                                    extName, '(matches explicitly requested extensions to add)')
                    include = True
            # Remove extensions if the name matches the regexp specified
            # in generator options. This allows forcing removal of
            # extensions from an interface even if they are tagged that
            # way in the registry.
            if regRemoveExtensions.match(extName) is not None:
                self.gen.logMsg('diag', 'Removing extension',
                                extName, '(matches explicitly requested extensions to remove)')
                include = False

            # If the extension is to be included, add it to the
            # extension features list.
            if include:
                ei.emit = (regEmitExtensions.match(extName) is not None)
                features.append(ei)
                if not ei.emit:
                    self.gen.logMsg('diag', 'NOT tagging extension',
                                    extName,
                                    'for emission (does not match emitextensions pattern)')

                # Hack - can be removed when validity generator goes away
                # (Jon) I am not sure what this does, or if it should
                # respect the ei.emit flag above.
                self.requiredextensions.append(extName)
            else:
                self.gen.logMsg('diag', 'NOT including extension',
                                extName, '(does not match api attribute or explicitly requested extensions)')

        # Add all spirv elements to list
        # generators decide to emit them all or not
        # Currently no filtering as no client of these elements needs filtering
        spirvexts = []
        for key in self.spirvextdict:
            si = self.spirvextdict[key]
            si.emit = (regEmitSpirv.match(key) is not None)
            spirvexts.append(si)
        spirvcaps = []
        for key in self.spirvcapdict:
            si = self.spirvcapdict[key]
            si.emit = (regEmitSpirv.match(key) is not None)
            spirvcaps.append(si)

        formats = []
        for key in self.formatsdict:
            si = self.formatsdict[key]
            si.emit = (regEmitFormats.match(key) is not None)
            formats.append(si)

        # Sort the features list, if a sort procedure is defined
        if self.genOpts.sortProcedure:
            self.genOpts.sortProcedure(features)

        # Passes 1+2: loop over requested API versions and extensions tagging
        #   types/commands/features as required (in an <require> block) or no
        #   longer required (in an <remove> block). <remove>s are processed
        #   after all <require>s, so removals win.
        # If a profile other than 'None' is being generated, it must
        #   match the profile attribute (if any) of the <require> and
        #   <remove> tags.
        self.gen.logMsg('diag', 'PASS 1: TAG FEATURES')
        for f in features:
            self.gen.logMsg('diag', 'PASS 1: Tagging required and features for', f.name)
            self.fillFeatureDictionary(f.elem, f.name, self.genOpts.apiname, self.genOpts.profile)
            self.requireFeatures(f.elem, f.name, self.genOpts.apiname, self.genOpts.profile)
            self.assignAdditionalValidity(f.elem, self.genOpts.apiname, self.genOpts.profile)

        for f in features:
            self.gen.logMsg('diag', 'PASS 2: Tagging removed features for', f.name)
            self.removeFeatures(f.elem, f.name, self.genOpts.apiname, self.genOpts.profile)
            self.removeAdditionalValidity(f.elem, self.genOpts.apiname, self.genOpts.profile)

        # Now, strip references to APIs that are not required.
        # At present such references may occur in:
        #   Structs in <type category="struct"> 'structextends' attributes
        #   Enums in <command> 'successcodes' and 'errorcodes' attributes
        self.stripUnsupportedAPIs(self.typedict, 'structextends', self.typedict)
        self.stripUnsupportedAPIs(self.cmddict, 'successcodes', self.enumdict)
        self.stripUnsupportedAPIs(self.cmddict, 'errorcodes', self.enumdict)
        self.stripUnsupportedAPIsFromList(self.validextensionstructs, self.typedict)

        # Construct lists of valid extension structures
        self.tagValidExtensionStructs()

        # @@May need to strip <spirvcapability> / <spirvextension> <enable>
        # tags of these forms:
        #   <enable version="VK_API_VERSION_1_0"/>
        #   <enable struct="VkPhysicalDeviceFeatures" feature="geometryShader" requires="VK_VERSION_1_0"/>
        #   <enable extension="VK_KHR_shader_draw_parameters"/>
        #   <enable property="VkPhysicalDeviceVulkan12Properties" member="shaderDenormPreserveFloat16" value="VK_TRUE" requires="VK_VERSION_1_2,VK_KHR_shader_float_controls"/>

        # Pass 3: loop over specified API versions and extensions printing
        #   declarations for required things which have not already been
        #   generated.
        self.gen.logMsg('diag', 'PASS 3: GENERATE INTERFACES FOR FEATURES')
        self.gen.beginFile(self.genOpts)
        for f in features:
            self.gen.logMsg('diag', 'PASS 3: Generating interface for',
                            f.name)
            emit = self.emitFeatures = f.emit
            if not emit:
                self.gen.logMsg('diag', 'PASS 3: NOT declaring feature',
                                f.elem.get('name'), 'because it is not tagged for emission')
            # Generate the interface (or just tag its elements as having been
            # emitted, if they have not been).
            self.gen.beginFeature(f.elem, emit)
            self.generateRequiredInterface(f.elem)
            self.gen.endFeature()
        # Generate spirv elements
        for s in spirvexts:
            self.generateSpirv(s, self.spirvextdict)
        for s in spirvcaps:
            self.generateSpirv(s, self.spirvcapdict)
        for s in formats:
            self.generateFormat(s, self.formatsdict)
        for s in self.syncstagedict:
            self.generateSyncStage(self.syncstagedict[s])
        for s in self.syncaccessdict:
            self.generateSyncAccess(self.syncaccessdict[s])
        for s in self.syncpipelinedict:
            self.generateSyncPipeline(self.syncpipelinedict[s])
        self.gen.endFile()

    def apiReset(self):
        """Reset type/enum/command dictionaries before generating another API.

        Use between apiGen() calls to reset internal state."""
        for datatype in self.typedict:
            self.typedict[datatype].resetState()
        for enum in self.enumdict:
            self.enumdict[enum].resetState()
        for cmd in self.cmddict:
            self.cmddict[cmd].resetState()
        for cmd in self.apidict:
            self.apidict[cmd].resetState()