xref: /third_party/vk-gl-cts/external/vulkan-docs/src/scripts/validitygenerator.py

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

import re
from collections import OrderedDict, namedtuple
from functools import reduce
from pathlib import Path

from spec_tools.conventions import ProseListFormats as plf
from generator import OutputGenerator, write
from spec_tools.attributes import ExternSyncEntry, LengthEntry
from spec_tools.util import (findNamedElem, findNamedObject, findTypedElem,
                             getElemName, getElemType)
from spec_tools.validity import ValidityCollection, ValidityEntry


class UnhandledCaseError(RuntimeError):
    def __init__(self, msg=None):
        if msg:
            super().__init__('Got a case in the validity generator that we have not explicitly handled: ' + msg)
        else:
            super().__init__('Got a case in the validity generator that we have not explicitly handled.')


def _genericIterateIntersection(a, b):
    """Iterate through all elements in a that are also in b.

    Somewhat like a set's intersection(),
    but not type-specific so it can work with OrderedDicts, etc.
    It also returns a generator instead of a set,
    so you can pick a preferred container type,
    if any.
    """
    return (x for x in a if x in b)


def _make_ordered_dict(gen):
    """Make an ordered dict (with None as the values) from a generator."""
    return OrderedDict(((x, None) for x in gen))


def _orderedDictIntersection(a, b):
    return _make_ordered_dict(_genericIterateIntersection(a, b))


def _genericIsDisjoint(a, b):
    """Return true if nothing in a is also in b.

    Like a set's is_disjoint(),
    but not type-specific so it can work with OrderedDicts, etc.
    """
    for _ in _genericIterateIntersection(a, b):
        return False
    # if we never enter the loop...
    return True


class ValidityOutputGenerator(OutputGenerator):
    """ValidityOutputGenerator - subclass of OutputGenerator.

    Generates AsciiDoc includes of valid usage information, for reference
    pages and the specification. Similar to DocOutputGenerator.

    ---- methods ----
    ValidityOutputGenerator(errFile, warnFile, diagFile) - args as for
    OutputGenerator. Defines additional internal state.
    ---- methods overriding base class ----
    beginFile(genOpts)
    endFile()
    beginFeature(interface, emit)
    endFeature()
    genCmd(cmdinfo)
    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.currentExtension = ''

        # Tracks whether we are tracing operations
        self.trace = False

    @property
    def null(self):
        """Preferred spelling of NULL.

        Delegates to the object implementing ConventionsBase.
        """
        return self.conventions.null

    @property
    def structtype_member_name(self):
        """Return name of the structure type member.

        Delegates to the object implementing ConventionsBase.
        """
        return self.conventions.structtype_member_name

    @property
    def nextpointer_member_name(self):
        """Return name of the structure pointer chain member.

        Delegates to the object implementing ConventionsBase.
        """
        return self.conventions.nextpointer_member_name

    def makeProseList(self, elements, fmt=plf.AND,
                      comma_for_two_elts=False, *args, **kwargs):
        """Make a (comma-separated) list for use in prose.

        Adds a connective (by default, 'and')
        before the last element if there are more than 1.

        Optionally adds a quantifier (like 'any') before a list of 2 or more,
        if specified by fmt.

        Delegates to the object implementing ConventionsBase.
        """
        if not elements:
            raise ValueError(
                'Cannot pass an empty list if you are trying to make a prose list.')
        return self.conventions.makeProseList(elements,
                                              fmt,
                                              with_verb=False,
                                              comma_for_two_elts=comma_for_two_elts,
                                              *args, **kwargs)

    def makeProseListIs(self, elements, fmt=plf.AND,
                        comma_for_two_elts=False, *args, **kwargs):
        """Make a (comma-separated) list for use in prose, followed by either 'is' or 'are' as appropriate.

        Adds a connective (by default, 'and')
        before the last element if there are more than 1.

        Optionally adds a quantifier (like 'any') before a list of 2 or more,
        if specified by fmt.

        Delegates to the object implementing ConventionsBase.
        """
        if not elements:
            raise ValueError(
                'Cannot pass an empty list if you are trying to make a prose list.')
        return self.conventions.makeProseList(elements,
                                              fmt,
                                              with_verb=True,
                                              comma_for_two_elts=comma_for_two_elts,
                                              *args, **kwargs)

    def makeValidityCollection(self, entity_name):
        """Create a ValidityCollection object, passing along our Conventions."""
        return ValidityCollection(entity_name, self.conventions)

    def beginFile(self, genOpts):
        if not genOpts.conventions:
            raise RuntimeError(
                'Must specify conventions object to generator options')
        self.conventions = genOpts.conventions
        # Vulkan says 'must: be a valid pointer' a lot, OpenXR just says
        # 'must: be a pointer'.
        self.valid_pointer_text = ' '.join(
            (x for x in (self.conventions.valid_pointer_prefix, 'pointer') if x))
        OutputGenerator.beginFile(self, genOpts)

    def endFile(self):
        OutputGenerator.endFile(self)

    def beginFeature(self, interface, emit):
        # Start processing in superclass
        OutputGenerator.beginFeature(self, interface, emit)
        self.currentExtension = interface.get('name')

    def endFeature(self):
        # Finish processing in superclass
        OutputGenerator.endFeature(self)

    @property
    def struct_macro(self):
        """Get the appropriate format macro for a structure."""
        # delegate to conventions
        return self.conventions.struct_macro

    def makeStructName(self, name):
        """Prepend the appropriate format macro for a structure to a structure type name."""
        # delegate to conventions
        return self.conventions.makeStructName(name)

    def makeParameterName(self, name):
        """Prepend the appropriate format macro for a parameter/member to a parameter name."""
        return 'pname:' + name

    def makeBaseTypeName(self, name):
        """Prepend the appropriate format macro for a 'base type' to a type name."""
        return 'basetype:' + name

    def makeEnumerationName(self, name):
        """Prepend the appropriate format macro for an enumeration type to a enum type name."""
        return 'elink:' + name

    def makeFlagsName(self, name):
        """Prepend the appropriate format macro for a flags type to a flags type name."""
        return 'tlink:' + name

    def makeFuncPointerName(self, name):
        """Prepend the appropriate format macro for a function pointer type to a type name."""
        return 'tlink:' + name

    def makeExternalTypeName(self, name):
        """Prepend the appropriate format macro for an external type like uint32_t to a type name."""
        # delegate to conventions
        return self.conventions.makeExternalTypeName(name)

    def makeEnumerantName(self, name):
        """Prepend the appropriate format macro for an enumerate (value) to a enum value name."""
        return 'ename:' + name

    def writeInclude(self, directory, basename, validity: ValidityCollection,
                     threadsafety, commandpropertiesentry=None,
                     successcodes=None, errorcodes=None):
        """Generate an include file.

        directory - subdirectory to put file in (absolute or relative pathname)
        basename - base name of the file
        validity - ValidityCollection to write.
        threadsafety - List (may be empty) of thread safety statements to write.
        successcodes - Optional success codes to document.
        errorcodes - Optional error codes to document.
        """
        # Create subdirectory, if needed
        directory = Path(directory)
        if not directory.is_absolute():
            directory = Path(self.genOpts.directory) / directory
        self.makeDir(str(directory))

        # Create validity file
        filename = str(directory / f'{basename}{self.file_suffix}')
        self.logMsg('diag', '# Generating include file:', filename)

        with open(filename, 'w', encoding='utf-8') as fp:
            write(self.conventions.warning_comment, file=fp)

            # Valid Usage
            if validity:
                write('.Valid Usage (Implicit)', file=fp)
                write('****', file=fp)
                write(validity, file=fp, end='')
                write('****', file=fp)
                write('', file=fp)

            # Host Synchronization
            if threadsafety:
                # The heading of this block differs between projects, so an Asciidoc attribute is used.
                write('.{externsynctitle}', file=fp)
                write('****', file=fp)
                write(threadsafety, file=fp, end='')
                write('****', file=fp)
                write('', file=fp)

            # Command Properties - contained within a block, to avoid table numbering
            if commandpropertiesentry:
                write('.Command Properties', file=fp)
                write('****', file=fp)
                write('[options="header", width="100%"]', file=fp)
                write('|====', file=fp)
                write(self.makeCommandPropertiesTableHeader(), file=fp)
                write(commandpropertiesentry, file=fp)
                write('|====', file=fp)
                write('****', file=fp)
                write('', file=fp)

            # Success Codes - contained within a block, to avoid table numbering
            if successcodes or errorcodes:
                write('.Return Codes', file=fp)
                write('****', file=fp)
                if successcodes:
                    write('ifndef::doctype-manpage[]', file=fp)
                    write('<<fundamentals-successcodes,Success>>::', file=fp)
                    write('endif::doctype-manpage[]', file=fp)
                    write('ifdef::doctype-manpage[]', file=fp)
                    write('On success, this command returns::', file=fp)
                    write('endif::doctype-manpage[]', file=fp)
                    write(successcodes, file=fp)
                if errorcodes:
                    write('ifndef::doctype-manpage[]', file=fp)
                    write('<<fundamentals-errorcodes,Failure>>::', file=fp)
                    write('endif::doctype-manpage[]', file=fp)
                    write('ifdef::doctype-manpage[]', file=fp)
                    write('On failure, this command returns::', file=fp)
                    write('endif::doctype-manpage[]', file=fp)
                    write(errorcodes, file=fp)
                write('****', file=fp)
                write('', file=fp)

    def paramIsStaticArray(self, param):
        """Check if the parameter passed in is a static array."""
        tail = param.find('name').tail
        return tail and tail[0] == '['

    def paramIsConst(self, param):
        """Check if the parameter passed in has a type that mentions const."""
        return param.text is not None and 'const' in param.text

    def staticArrayLength(self, param):
        """Get the length of a parameter that has been identified as a static array."""
        paramenumsize = param.find('enum')
        if paramenumsize is not None:
            return paramenumsize.text
            # TODO switch to below when cosmetic changes OK
            # return self.makeEnumerantName(paramenumsize.text)

        return param.find('name').tail[1:-1]

    def getHandleDispatchableAncestors(self, typename):
        """Get the ancestors of a handle object."""
        ancestors = []
        current = typename
        while True:
            current = self.getHandleParent(current)
            if current is None:
                return ancestors
            if self.isHandleTypeDispatchable(current):
                ancestors.append(current)

    def isHandleTypeDispatchable(self, handlename):
        """Check if a parent object is dispatchable or not."""
        handle = self.registry.tree.find(
            "types/type/[name='" + handlename + "'][@category='handle']")
        if handle is not None and getElemType(handle) == 'VK_DEFINE_HANDLE':
            return True
        else:
            return False

    def isHandleOptional(self, param, params):
        # Simple, if it is optional, return true
        if param.get('optional') is not None:
            return True

        # If no validity is being generated, it usually means that validity is complex and not absolute, so say yes.
        if param.get('noautovalidity') is not None:
            return True

        # If the parameter is an array and we have not already returned, find out if any of the len parameters are optional
        if self.paramIsArray(param):
            for length in LengthEntry.parse_len_from_param(param):
                if not length.other_param_name:
                    # do not care about constants or "null-terminated"
                    continue

                other_param = findNamedElem(params, length.other_param_name)
                if other_param is None:
                    self.logMsg('warn', length.other_param_name,
                                'is listed as a length for parameter', param, 'but no such parameter exists')
                if other_param and other_param.get('optional'):
                    return True

        return False

    def makeOptionalPre(self, param):
        # Do not generate this stub for bitflags
        param_name = getElemName(param)
        paramtype = getElemType(param)
        type_category = self.getTypeCategory(paramtype)
        is_optional = param.get('optional').split(',')[0] == 'true'
        if type_category != 'bitmask' and is_optional:
            if self.paramIsArray(param) or self.paramIsPointer(param):
                optional_val = self.null
            elif type_category == 'handle':
                if self.isHandleTypeDispatchable(paramtype):
                    optional_val = self.null
                else:
                    optional_val = 'dlink:' + self.conventions.api_prefix + 'NULL_HANDLE'
            else:
                optional_val = self.conventions.zero
            return 'If {} is not {}, '.format(
                self.makeParameterName(param_name),
                optional_val)

        return ""

    def makeParamValidityPre(self, param, params, selector):
        """Make the start of an entry for a parameter's validity, including a chunk of text if it is an array."""
        param_name = getElemName(param)
        paramtype = getElemType(param)

        # General pre-amble. Check optionality and add stuff.
        entry = ValidityEntry(anchor=(param_name, 'parameter'))
        is_optional = param.get('optional') is not None and param.get('optional').split(',')[0] == 'true'

        # This is for a union member, and the valid member is chosen by an enum selection
        if selector:
            selection = param.get('selection')

            entry += 'If {} is {}, '.format(
                self.makeParameterName(selector),
                self.makeEnumerantName(selection))

            if is_optional:
                entry += "and "
                optionalpre = self.makeOptionalPre(param)
                entry += optionalpre[0].lower() + optionalpre[1:]

            return entry

        if self.paramIsStaticArray(param):
            if paramtype != 'char':
                entry += 'Each element of '
            return entry

        if self.paramIsArray(param) and param.get('len') != LengthEntry.NULL_TERMINATED_STRING:
            # Find all the parameters that are called out as optional,
            # so we can document that they might be zero, and the array may be ignored
            optionallengths = []
            for length in LengthEntry.parse_len_from_param(param):
                if not length.other_param_name:
                    # Only care about length entries that are parameter names
                    continue

                other_param = findNamedElem(params, length.other_param_name)
                other_param_optional = (other_param is not None) and (
                    other_param.get('optional') is not None)

                if other_param is None or not other_param_optional:
                    # Do not care about not-found params or non-optional params
                    continue

                if self.paramIsPointer(other_param):
                    optionallengths.append(
                        'the value referenced by ' + self.makeParameterName(length.other_param_name))
                else:
                    optionallengths.append(
                        self.makeParameterName(length.other_param_name))

            # Document that these arrays may be ignored if any of the length values are 0
            if optionallengths or is_optional:
                entry += 'If '
            if optionallengths:
                entry += self.makeProseListIs(optionallengths, fmt=plf.OR)
                entry += ' not %s, ' % self.conventions.zero
            # TODO enabling this in OpenXR, as used in Vulkan, causes nonsensical things like
            # "If pname:propertyCapacityInput is not `0`, and pname:properties is not `NULL`, pname:properties must: be a pointer to an array of pname:propertyCapacityInput slink:XrApiLayerProperties structures"
            if optionallengths and is_optional:
                entry += 'and '
            if is_optional:
                entry += self.makeParameterName(param_name)
                # TODO switch when cosmetic changes OK
                # entry += ' is not {}, '.format(self.null)
                entry += ' is not `NULL`, '
            return entry

        if param.get('optional'):
            entry += self.makeOptionalPre(param)
            return entry

        # If none of the early returns happened, we at least return an empty
        # entry with an anchor.
        return entry

    def createValidationLineForParameterImpl(self, blockname, param, params, typetext, selector, parentname):
        """Make the generic validity portion used for all parameters.

        May return None if nothing to validate.
        """
        if param.get('noautovalidity') is not None:
            return None

        validity = self.makeValidityCollection(blockname)
        param_name = getElemName(param)
        paramtype = getElemType(param)

        entry = self.makeParamValidityPre(param, params, selector)

        # pAllocator is not supported in VulkanSC and must always be NULL
        if self.conventions.xml_api_name == "vulkansc" and param_name == 'pAllocator' and paramtype == 'VkAllocationCallbacks':
            entry = ValidityEntry(anchor=(param_name, 'null'))
            entry += 'pname:pAllocator must: be `NULL`'
            return entry

        # This is for a child member of a union
        if selector:
            entry += 'the {} member of {} must: be '.format(self.makeParameterName(param_name), self.makeParameterName(parentname))
        else:
            entry += '{} must: be '.format(self.makeParameterName(param_name))

        if self.paramIsStaticArray(param) and paramtype == 'char':
            # TODO this is a minor hack to determine if this is a command parameter or a struct member
            if self.paramIsConst(param) or blockname.startswith(self.conventions.type_prefix):
                entry += 'a null-terminated UTF-8 string whose length is less than or equal to '
                entry += self.staticArrayLength(param)
            else:
                # This is a command's output parameter
                entry += 'a character array of length %s ' % self.staticArrayLength(param)
            validity += entry
            return validity

        elif self.paramIsArray(param):
            # Arrays. These are hard to get right, apparently

            lengths = LengthEntry.parse_len_from_param(param)

            for i, length in enumerate(LengthEntry.parse_len_from_param(param)):
                if i == 0:
                    # If the first index, make it singular.
                    entry += 'a '
                    array_text = 'an array'
                    pointer_text = self.valid_pointer_text
                else:
                    array_text = 'arrays'
                    pointer_text = self.valid_pointer_text + 's'

                if length.null_terminated:
                    # This should always be the last thing.
                    # If it ever is not for some bizarre reason, then this
                    # will need some massaging.
                    entry += 'null-terminated '
                elif length.number == 1:
                    entry += pointer_text
                    entry += ' to '
                else:
                    entry += pointer_text
                    entry += ' to '
                    entry += array_text
                    entry += ' of '
                    # Handle equations, which are currently denoted with latex
                    if length.math:
                        # Handle equations, which are currently denoted with latex
                        entry += str(length)
                    else:
                        entry += self.makeParameterName(str(length))
                    entry += ' '

            # Void pointers do not actually point at anything - remove the word "to"
            if paramtype == 'void':
                if lengths[-1].number == 1:
                    if len(lengths) > 1:
                        # Take care of the extra s added by the post array chunk function. #HACK#
                        entry.drop_end(5)
                    else:
                        entry.drop_end(4)

                    # This has not been hit, so this has not been tested recently.
                    raise UnhandledCaseError(
                        "Got void pointer param/member with last length 1")
                else:
                    # An array of void values is a byte array.
                    entry += 'byte'

            elif paramtype == 'char':
                # A null terminated array of chars is a string
                if lengths[-1].null_terminated:
                    entry += 'UTF-8 string'
                else:
                    # Else it is just a bunch of chars
                    entry += 'char value'

            elif self.paramIsConst(param):
                # If a value is "const" that means it will not get modified,
                # so it must be valid going into the function.
                if 'const' in param.text:

                    if not self.isStructAlwaysValid(paramtype):
                        entry += 'valid '

            # Check if the array elements are optional
            array_element_optional = param.get('optional') is not None    \
                      and len(param.get('optional').split(',')) == len(LengthEntry.parse_len_from_param(param)) + 1 \
                      and param.get('optional').split(',')[-1] == 'true'
            if array_element_optional and self.getTypeCategory(paramtype) != 'bitmask': # bitmask is handled later
                entry += 'or dlink:' + self.conventions.api_prefix + 'NULL_HANDLE '

            entry += typetext

            # pluralize
            if len(lengths) > 1 or (lengths[0] != 1 and not lengths[0].null_terminated):
                entry += 's'

            return self.handleRequiredBitmask(blockname, param, paramtype, entry, 'true' if array_element_optional else None)

        if self.paramIsPointer(param):
            # Handle pointers - which are really special case arrays (i.e.
            # they do not have a length)
            # TODO  should do something here if someone ever uses some intricate comma-separated `optional`
            pointercount = param.find('type').tail.count('*')

            # Treat void* as an int
            if paramtype == 'void':
                optional = param.get('optional')
                # If there is only void*, it is just optional int - we do not need any language.
                if pointercount == 1 and optional is not None:
                    return None  # early return
                # Treat the inner-most void* as an int
                pointercount -= 1

            # Could be multi-level pointers (e.g. ppData - pointer to a pointer). Handle that.
            entry += 'a '
            entry += (self.valid_pointer_text + ' to a ') * pointercount

            # Handle void* and pointers to it
            if paramtype == 'void':
                if optional is None or optional.split(',')[pointercount]:
                    # The last void* is just optional int (e.g. to be filled by the impl.)
                    typetext = 'pointer value'

            # If a value is "const" that means it will not get modified, so
            # it must be valid going into the function.
            elif self.paramIsConst(param) and paramtype != 'void':
                entry += 'valid '

            entry += typetext
            return self.handleRequiredBitmask(blockname, param, paramtype, entry, param.get('optional'))

        # Add additional line for non-optional bitmasks
        if self.getTypeCategory(paramtype) == 'bitmask':
            # TODO does not really handle if someone tries something like optional="true,false"
            # TODO OpenXR has 0 or a valid combination of flags, for optional things.
            # Vulkan does not...
            # isMandatory = param.get('optional') is None
            # if not isMandatory:
            #     entry += self.conventions.zero
            #     entry += ' or '
            # Non-pointer, non-optional things must be valid
            entry += 'a valid {}'.format(typetext)

            return self.handleRequiredBitmask(blockname, param, paramtype, entry, param.get('optional'))

        # Non-pointer, non-optional things must be valid
        entry += 'a valid {}'.format(typetext)
        return entry

    def handleRequiredBitmask(self, blockname, param, paramtype, entry, optional):
        # TODO does not really handle if someone tries something like optional="true,false"
        if self.getTypeCategory(paramtype) != 'bitmask' or optional == 'true':
            return entry
        if self.paramIsPointer(param) and not self.paramIsArray(param):
            # This is presumably an output parameter
            return entry

        param_name = getElemName(param)
        # If mandatory, then we need two entries instead of just one.
        validity = self.makeValidityCollection(blockname)
        validity += entry

        entry2 = ValidityEntry(anchor=(param_name, 'requiredbitmask'))
        if self.paramIsArray(param):
            entry2 += 'Each element of '
        entry2 += '{} must: not be {}'.format(
            self.makeParameterName(param_name), self.conventions.zero)
        validity += entry2
        return validity

    def createValidationLineForParameter(self, blockname, param, params, typecategory, selector, parentname):
        """Make an entire validation entry for a given parameter."""
        param_name = getElemName(param)
        paramtype = getElemType(param)

        is_array = self.paramIsArray(param)
        is_pointer = self.paramIsPointer(param)
        needs_recursive_validity = (is_array
                                    or is_pointer
                                    or not self.isStructAlwaysValid(paramtype))
        typetext = None
        if paramtype in ('void', 'char'):
            # Chars and void are special cases - we call the impl function,
            # but do not use the typetext.
            # A null-terminated char array is a string, else it is chars.
            # An array of void values is a byte array, a void pointer is just a pointer to nothing in particular
            typetext = ''

        elif typecategory == 'bitmask':
            bitsname = paramtype.replace('Flags', 'FlagBits')
            bitselem = self.registry.tree.find("enums[@name='" + bitsname + "']")

            # If bitsname is an alias, then use the alias to get bitselem.
            typeElem = self.registry.lookupElementInfo(bitsname, self.registry.typedict)
            if typeElem is not None:
                alias = self.registry.getAlias(typeElem.elem, self.registry.typedict)
                if alias is not None:
                    bitselem = self.registry.tree.find("enums[@name='" + alias + "']")

            if bitselem is None or len(bitselem.findall('enum[@required="true"]')) == 0:
                # Empty bit mask: presumably just a placeholder (or only in
                # an extension not enabled for this build)
                entry = ValidityEntry(
                    anchor=(param_name, 'zerobitmask'))
                entry += self.makeParameterName(param_name)
                entry += ' must: be '
                entry += self.conventions.zero
                # Early return
                return entry

            is_const = self.paramIsConst(param)

            if is_array:
                if is_const:
                    # input an array of bitmask values
                    template = 'combinations of {bitsname} value'
                else:
                    template = '{paramtype} value'
            elif is_pointer:
                if is_const:
                    template = 'combination of {bitsname} values'
                else:
                    template = '{paramtype} value'
            else:
                template = 'combination of {bitsname} values'

            # The above few cases all use makeEnumerationName, just with different context.
            typetext = template.format(
                bitsname=self.makeEnumerationName(bitsname),
                paramtype=self.makeFlagsName(paramtype))

        elif typecategory == 'handle':
            typetext = '{} handle'.format(self.makeStructName(paramtype))

        elif typecategory == 'enum':
            typetext = '{} value'.format(self.makeEnumerationName(paramtype))

        elif typecategory == 'funcpointer':
            typetext = '{} value'.format(self.makeFuncPointerName(paramtype))

        elif typecategory == 'struct':
            if needs_recursive_validity:
                typetext = '{} structure'.format(
                    self.makeStructName(paramtype))

        elif typecategory == 'union':
            if needs_recursive_validity:
                typetext = '{} union'.format(self.makeStructName(paramtype))

        elif self.paramIsArray(param) or self.paramIsPointer(param):
            # TODO sync cosmetic changes from OpenXR?
            if typecategory is None:
                typetext = f'code:{paramtype} value'
            else:
                typetext = '{} value'.format(self.makeBaseTypeName(paramtype))

        elif typecategory is None:
            if not self.isStructAlwaysValid(paramtype):
                typetext = '{} value'.format(
                    self.makeExternalTypeName(paramtype))

            # "a valid uint32_t value" does not make much sense.
            pass

        # If any of the above conditions matched and set typetext,
        # we call using it.
        if typetext is not None:
            return self.createValidationLineForParameterImpl(
                blockname, param, params, typetext, selector, parentname)
        return None

    def makeHandleValidityParent(self, param, params):
        """Make a validity entry for a handle's parent object.

        Creates 'parent' VUID.
        """
        param_name = getElemName(param)
        paramtype = getElemType(param)

        # Iterate up the handle parent hierarchy for the first parameter of
        # a parent type.
        # This enables cases where a more distant ancestor is present, such
        # as VkDevice and VkCommandBuffer (but no direct parent
        # VkCommandPool).

        while True:
            # If we run out of ancestors, give up
            handleparent = self.getHandleParent(paramtype)
            if handleparent is None:
                if self.trace:
                    print(f'makeHandleValidityParent:{param_name} has no handle parent, skipping')
                return None

            # Look for a parameter of the ancestor type
            otherparam = findTypedElem(params, handleparent)
            if otherparam is not None:
                break

            # Continue up the hierarchy
            paramtype = handleparent

        parent_name = getElemName(otherparam)
        entry = ValidityEntry(anchor=(param_name, 'parent'))

        is_optional = self.isHandleOptional(param, params)

        if self.paramIsArray(param):
            template = 'Each element of {}'
            if is_optional:
                template += ' that is a valid handle'
        elif is_optional:
            template = 'If {} is a valid handle, it'
        else:
            # not optional, not an array. Just say the parameter name.
            template = '{}'

        entry += template.format(self.makeParameterName(param_name))

        entry += ' must: have been created, allocated, or retrieved from {}'.format(
            self.makeParameterName(parent_name))

        return entry

    def makeAsciiDocHandlesCommonAncestor(self, blockname, handles, params):
        """Make an asciidoc validity entry for a common ancestors between handles.

        Only handles parent validity for signatures taking multiple handles
        any ancestors also being supplied to this function.
        (e.g. "Each of x, y, and z must: come from the same slink:ParentHandle")
        See self.makeAsciiDocHandleParent() for instances where the parent
        handle is named and also passed.

        Creates 'commonparent' VUID.
        """
        # TODO Replace with refactored code from OpenXR
        entry = None

        if len(handles) > 1:
            ancestormap = {}
            anyoptional = False
            # Find all the ancestors
            for param in handles:
                paramtype = getElemType(param)

                if not self.paramIsPointer(param) or (param.text and 'const' in param.text):
                    ancestors = self.getHandleDispatchableAncestors(paramtype)

                    ancestormap[param] = ancestors

                    anyoptional |= self.isHandleOptional(param, params)

            # Remove redundant ancestor lists
            for param in handles:
                paramtype = getElemType(param)

                removals = []
                for ancestors in ancestormap.items():
                    if paramtype in ancestors[1]:
                        removals.append(ancestors[0])

                if removals != []:
                    for removal in removals:
                        del(ancestormap[removal])

            # Intersect

            if len(ancestormap.values()) > 1:
                current = list(ancestormap.values())[0]
                for ancestors in list(ancestormap.values())[1:]:
                    current = [val for val in current if val in ancestors]

                if len(current) > 0:
                    commonancestor = current[0]

                    if len(ancestormap.keys()) > 1:

                        entry = ValidityEntry(anchor=('commonparent',))

                        parametertexts = []
                        for param in ancestormap.keys():
                            param_name = getElemName(param)
                            parametertext = self.makeParameterName(param_name)
                            if self.paramIsArray(param):
                                parametertext = 'the elements of ' + parametertext
                            parametertexts.append(parametertext)

                        parametertexts.sort()

                        if len(parametertexts) > 2:
                            entry += 'Each of '
                        else:
                            entry += 'Both of '

                        entry += self.makeProseList(parametertexts,
                                                    comma_for_two_elts=True)
                        if anyoptional is True:
                            entry += ' that are valid handles of non-ignored parameters'
                        entry += ' must: have been created, allocated, or retrieved from the same '
                        entry += self.makeStructName(commonancestor)

        return entry

    def makeStructureTypeFromName(self, structname):
        """Create text for a structure type name, like ename:VK_STRUCTURE_TYPE_CREATE_INSTANCE_INFO"""
        return self.makeEnumerantName(self.conventions.generate_structure_type_from_name(structname))

    def makeStructureTypeValidity(self, structname):
        """Generate an validity line for the type value of a struct.

        Creates VUID named like the member name.
        """
        info = self.registry.typedict.get(structname)
        assert(info is not None)

        # If this fails (meaning we have something other than a struct in here),
        # then the caller is wrong:
        # probably passing the wrong value for structname.
        members = info.getMembers()
        assert(members)

        # If this fails, see caller: this should only get called for a struct type with a type value.
        param = findNamedElem(members, self.structtype_member_name)
        # OpenXR gets some structs without a type field in here, so cannot assert
        assert(param is not None)
        # if param is None:
        #     return None

        entry = ValidityEntry(
            anchor=(self.structtype_member_name, self.structtype_member_name))
        entry += self.makeParameterName(self.structtype_member_name)
        entry += ' must: be '

        values = param.get('values', '').split(',')
        if values:
            # Extract each enumerant value. They could be validated in the
            # same fashion as validextensionstructs in
            # makeStructureExtensionPointer, although that is not relevant in
            # the current extension struct model.
            entry += self.makeProseList((self.makeEnumerantName(v)
                                         for v in values), 'or')
            return entry

        if 'Base' in structname:
            # This type does not even have any values for its type, and it
            # seems like it might be a base struct that we would expect to
            # lack its own type, so omit the entire statement
            return None

        self.logMsg('warn', 'No values were marked-up for the structure type member of',
                    structname, 'so making one up!')
        entry += self.makeStructureTypeFromName(structname)

        return entry

    def makeStructureExtensionPointer(self, blockname, param):
        """Generate an validity line for the pointer chain member value of a struct."""
        param_name = getElemName(param)

        if param.get('validextensionstructs') is not None:
            self.logMsg('warn', blockname,
                        'validextensionstructs is deprecated/removed', '\n')

        entry = ValidityEntry(
            anchor=(param_name, self.nextpointer_member_name))
        validextensionstructs = self.registry.validextensionstructs.get(
            blockname)
        extensionstructs = []
        duplicatestructs = []

        if validextensionstructs is not None:
            # Check each structure name and skip it if not required by the
            # generator. This allows tagging extension structs in the XML
            # that are only included in validity when needed for the spec
            # being targeted.
            # Track the required structures, and of the required structures,
            # those that allow duplicates in the pNext chain.
            for struct in validextensionstructs:
                # Unpleasantly breaks encapsulation. Should be a method in the registry class
                t = self.registry.lookupElementInfo(
                    struct, self.registry.typedict)
                if t is None:
                    self.logMsg('warn', 'makeStructureExtensionPointer: struct', struct,
                                'is in a validextensionstructs= attribute but is not in the registry')
                elif t.required:
                    extensionstructs.append('slink:' + struct)
                    if t.elem.get('allowduplicate') == 'true':
                        duplicatestructs.append('slink:' + struct)
                else:
                    self.logMsg(
                        'diag', 'makeStructureExtensionPointer: struct', struct, 'IS NOT required')

        if not extensionstructs:
            entry += '{} must: be {}'.format(
                self.makeParameterName(param_name), self.null)
            return entry

        if len(extensionstructs) == 1:
            entry += '{} must: be {} or a pointer to a valid instance of {}'.format(self.makeParameterName(param_name), self.null,
                                                                                    extensionstructs[0])
        else:
            # More than one extension struct.
            entry += 'Each {} member of any structure (including this one) in the pname:{} chain '.format(
                self.makeParameterName(param_name), self.nextpointer_member_name)
            entry += 'must: be either {} or a pointer to a valid instance of '.format(
                self.null)

            entry += self.makeProseList(extensionstructs, fmt=plf.OR)

        validity = self.makeValidityCollection(blockname)
        validity += entry

        # Generate VU statement requiring unique structures in the pNext
        # chain.
        # NOTE: OpenXR always allows non-unique type values. Instances other
        # than the first are just ignored

        vu = ('The pname:' +
              self.structtype_member_name +
              ' value of each struct in the pname:' +
              self.nextpointer_member_name +
              ' chain must: be unique')
        anchor = (self.conventions.member_used_for_unique_vuid, 'unique')

        # If duplicates of some structures are allowed, they are called out
        # explicitly.
        num = len(duplicatestructs)
        if num > 0:
            vu = (vu +
                  ', with the exception of structures of type ' +
                  self.makeProseList(duplicatestructs, fmt=plf.OR))

        validity.addValidityEntry(vu, anchor = anchor )

        return validity

    def addSharedStructMemberValidity(self, struct, blockname, param, validity):
        """Generate language to independently validate a parameter, for those validated even in output.

        Return value indicates whether it was handled internally (True) or if it may need more validity (False)."""
        param_name = getElemName(param)
        paramtype = getElemType(param)
        if param.get('noautovalidity') is None:

            if self.conventions.is_structure_type_member(paramtype, param_name):
                validity += self.makeStructureTypeValidity(blockname)
                return True

            if self.conventions.is_nextpointer_member(paramtype, param_name):
                # Vulkan: the addition of validity here is conditional unlike OpenXR.
                if struct.get('structextends') is None:
                    validity += self.makeStructureExtensionPointer(
                        blockname, param)
                return True
        return False

    def makeOutputOnlyStructValidity(self, cmd, blockname, params):
        """Generate all the valid usage information for a struct that is entirely output.

        That is, it is only ever filled out by the implementation other than
        the structure type and pointer chain members.
        Thus, we only create validity for the pointer chain member.
        """
        # Start the validity collection for this struct
        validity = self.makeValidityCollection(blockname)

        for param in params:
            self.addSharedStructMemberValidity(
                cmd, blockname, param, validity)

        return validity

    def isVKVersion11(self):
        """Returns true if VK_VERSION_1_1 is being emitted."""
        vk11 = re.match(self.registry.genOpts.emitversions, 'VK_VERSION_1_1') is not None
        return vk11

    def videocodingRequired(self):
        """Returns true if VK_KHR_video_queue is being emitted and thus validity
        with respect to the videocoding attribute should be generated."""
        return 'VK_KHR_video_queue' in self.registry.requiredextensions

    def getVideocoding(self, cmd):
        """Returns the value of the videocoding attribute, also considering the
        default value when the attribute is not present."""
        videocoding = cmd.get('videocoding')
        if videocoding is None:
            videocoding = 'outside'
        return videocoding

    def conditionallyRemoveQueueType(self, queues, queuetype, condition):
        """Removes a queue type from a queue list based on the specified condition."""
        if queuetype in queues and condition:
            queues.remove(queuetype)

    def getQueueList(self, cmd):
        """Returns the list of queue types a command is supported on."""
        queues = cmd.get('queues')
        if queues is None:
            return None
        queues = queues.split(',')

        # Filter queue types that have dependencies
        self.conditionallyRemoveQueueType(queues, 'sparse_binding', self.conventions.xml_api_name == "vulkansc")
        self.conditionallyRemoveQueueType(queues, 'decode',         'VK_KHR_video_decode_queue' not in self.registry.requiredextensions)
        self.conditionallyRemoveQueueType(queues, 'encode',         'VK_KHR_video_encode_queue' not in self.registry.requiredextensions)
        self.conditionallyRemoveQueueType(queues, 'opticalflow',    'VK_NV_optical_flow' not in self.registry.requiredextensions)

        # Verify that no new queue type is introduced accidentally
        for queue in queues:
            if queue not in [ 'transfer', 'compute', 'graphics', 'sparse_binding', 'decode', 'encode', 'opticalflow' ]:
                self.logMsg('error', f'Unknown queue type "{queue}".')

        return queues

    def getPrettyQueueList(self, cmd):
        """Returns a prettified version of the queue list which can be included in spec language text."""
        queues = self.getQueueList(cmd)
        if queues is None:
            return None

        replace = {
            'sparse_binding': 'sparse binding',
            'opticalflow': 'optical flow'
        }
        return [replace[queue] if queue in replace else queue for queue in queues]

    def makeStructOrCommandValidity(self, cmd, blockname, params):
        """Generate all the valid usage information for a given struct or command."""
        validity = self.makeValidityCollection(blockname)
        handles = []
        arraylengths = dict()
        for param in params:
            param_name = getElemName(param)
            paramtype = getElemType(param)

            # Valid usage ID tags (VUID) are generated for various
            # conditions based on the name of the block (structure or
            # command), name of the element (member or parameter), and type
            # of VU statement.

            # Get the type's category
            typecategory = self.getTypeCategory(paramtype)

            if not self.addSharedStructMemberValidity(
                    cmd, blockname, param, validity):
                if not param.get('selector'):
                    validity += self.createValidationLineForParameter(
                        blockname, param, params, typecategory, None, None)
                else:
                    selector = param.get('selector')
                    if typecategory != 'union':
                        self.logMsg('warn', 'selector attribute set on non-union parameter', param_name, 'in', blockname)

                    paraminfo = self.registry.lookupElementInfo(paramtype, self.registry.typedict)

                    for member in paraminfo.getMembers():
                        membertype = getElemType(member)
                        membertypecategory = self.getTypeCategory(membertype)

                        validity += self.createValidationLineForParameter(
                            blockname, member, paraminfo.getMembers(), membertypecategory, selector, param_name)

            # Ensure that any parenting is properly validated, and list that a handle was found
            if typecategory == 'handle':
                handles.append(param)

            # Get the array length for this parameter
            lengths = LengthEntry.parse_len_from_param(param)
            if lengths:
                arraylengths.update({length.other_param_name: length
                                     for length in lengths
                                     if length.other_param_name})

        # For any vkQueue* functions, there might be queue type data
        if 'vkQueue' in blockname:
            # The queue type must be valid
            queues = self.getPrettyQueueList(cmd)
            if queues:
                entry = ValidityEntry(anchor=('queuetype',))
                entry += 'The pname:queue must: support '
                entry += self.makeProseList(queues,
                                            fmt=plf.OR, comma_for_two_elts=True)
                entry += ' operations'
                validity += entry

        if 'vkCmd' in blockname:
            # The commandBuffer parameter must be being recorded
            entry = ValidityEntry(anchor=('commandBuffer', 'recording'))
            entry += 'pname:commandBuffer must: be in the <<commandbuffers-lifecycle, recording state>>'
            validity += entry

            #
            # Start of valid queue type validation - command pool must have been
            # allocated against a queue with at least one of the valid queue types
            entry = ValidityEntry(anchor=('commandBuffer', 'cmdpool'))

            #
            # This test for vkCmdFillBuffer is a hack, since we have no path
            # to conditionally have queues enabled or disabled by an extension.
            # As the VU stuff is all moving out (hopefully soon), this hack solves the issue for now
            if blockname == 'vkCmdFillBuffer':
                entry += 'The sname:VkCommandPool that pname:commandBuffer was allocated from must: support '
                if self.isVKVersion11() or 'VK_KHR_maintenance1' in self.registry.requiredextensions:
                    entry += 'transfer, graphics or compute operations'
                else:
                    entry += 'graphics or compute operations'
            else:
                # The queue type must be valid
                queues = self.getPrettyQueueList(cmd)
                assert(queues)
                entry += 'The sname:VkCommandPool that pname:commandBuffer was allocated from must: support '
                entry += self.makeProseList(queues,
                                            fmt=plf.OR, comma_for_two_elts=True)
                entry += ' operations'
            validity += entry

            # Must be called inside/outside a render pass appropriately
            renderpass = cmd.get('renderpass')

            if renderpass != 'both':
                entry = ValidityEntry(anchor=('renderpass',))
                entry += 'This command must: only be called '
                entry += renderpass
                entry += ' of a render pass instance'
                validity += entry

            # Must be called inside/outside a video coding scope appropriately
            if self.videocodingRequired():
                videocoding = self.getVideocoding(cmd)
                if videocoding != 'both':
                    entry = ValidityEntry(anchor=('videocoding',))
                    entry += 'This command must: only be called '
                    entry += videocoding
                    entry += ' of a video coding scope'
                    validity += entry

            # Must be in the right level command buffer
            cmdbufferlevel = cmd.get('cmdbufferlevel')

            if cmdbufferlevel != 'primary,secondary':
                entry = ValidityEntry(anchor=('bufferlevel',))
                entry += 'pname:commandBuffer must: be a '
                entry += cmdbufferlevel
                entry += ' sname:VkCommandBuffer'
                validity += entry

        # Any non-optional arraylengths should specify they must be greater than 0
        array_length_params = ((param, getElemName(param))
                               for param in params
                               if getElemName(param) in arraylengths)

        for param, param_name in array_length_params:
            if param.get('optional') is not None:
                continue

            length = arraylengths[param_name]
            full_length = length.full_reference

            # Is this just a name of a param? If false, then it is some kind
            # of qualified name (a member of a param for instance)
            simple_param_reference = (len(length.param_ref_parts) == 1)
            if not simple_param_reference:
                # Loop through to see if any parameters in the chain are optional
                array_length_parent = cmd
                array_length_optional = False
                for part in length.param_ref_parts:
                    # Overwrite the param so it ends up as the bottom level parameter for later checks
                    param = array_length_parent.find("*/[name='{}']".format(part))

                    # If any parameter in the chain is optional, skip the implicit length requirement
                    array_length_optional |= (param.get('optional') is not None)

                    # Lookup the type of the parameter for the next loop iteration
                    type = param.findtext('type')
                    array_length_parent = self.registry.tree.find("./types/type/[@name='{}']".format(type))

                if array_length_optional:
                    continue

            # Get all the array dependencies
            arrays = cmd.findall(
                "param/[@len='{}'][@optional='true']".format(full_length))

            # Get all the optional array dependencies, including those not generating validity for some reason
            optionalarrays = arrays + \
                cmd.findall(
                    "param/[@len='{}'][@noautovalidity='true']".format(full_length))

            entry = ValidityEntry(anchor=(full_length, 'arraylength'))
            # Allow lengths to be arbitrary if all their dependents are optional
            if optionalarrays and len(optionalarrays) == len(arrays):
                entry += 'If '
                # TODO sync this section from OpenXR once cosmetic changes OK

                optional_array_names = (self.makeParameterName(getElemName(array))
                                        for array in optionalarrays)
                entry += self.makeProseListIs(optional_array_names,
                                              plf.ANY_OR, comma_for_two_elts=True)

                entry += ' not {}, '.format(self.null)

            # TODO end needs sync cosmetic
            if self.paramIsPointer(param):
                entry += 'the value referenced by '

            # Split and re-join here to insert pname: around ::
            entry += '::'.join(self.makeParameterName(part)
                               for part in full_length.split('::'))
            # TODO replace the previous statement with the following when cosmetic changes OK
            # entry += length.get_human_readable(make_param_name=self.makeParameterName)

            entry += ' must: be greater than '
            entry += self.conventions.zero
            validity += entry

        # Find the parents of all objects referenced in this command
        for param in handles:
            # Do not detect a parent for return values!
            if not self.paramIsPointer(param) or self.paramIsConst(param):
                validity += self.makeHandleValidityParent(param, params)

        # Find the common ancestor of all objects referenced in this command
        validity += self.makeAsciiDocHandlesCommonAncestor(
            blockname, handles, params)

        return validity

    def makeThreadSafetyBlock(self, cmd, paramtext):
        """Generate thread-safety validity entries for cmd/structure"""
        # See also makeThreadSafetyBlock in validitygenerator.py
        validity = self.makeValidityCollection(getElemName(cmd))

        # This text varies between projects, so an Asciidoctor attribute is used.
        extsync_prefix = "{externsyncprefix} "

        # Find and add any parameters that are thread unsafe
        explicitexternsyncparams = cmd.findall(paramtext + "[@externsync]")
        if explicitexternsyncparams is not None:
            for param in explicitexternsyncparams:
                externsyncattribs = ExternSyncEntry.parse_externsync_from_param(
                    param)
                param_name = getElemName(param)

                for attrib in externsyncattribs:
                    entry = ValidityEntry()
                    entry += extsync_prefix
                    if attrib.entirely_extern_sync:
                        if self.paramIsArray(param):
                            entry += 'each member of '
                        elif self.paramIsPointer(param):
                            entry += 'the object referenced by '

                        entry += self.makeParameterName(param_name)

                        if attrib.children_extern_sync:
                            entry += ', and any child handles,'

                    else:
                        entry += 'pname:'
                        entry += str(attrib.full_reference)
                        # TODO switch to the following when cosmetic changes OK
                        # entry += attrib.get_human_readable(make_param_name=self.makeParameterName)
                    entry += ' must: be externally synchronized'
                    validity += entry

        # Vulkan-specific
        # For any vkCmd* functions, the command pool is externally synchronized
        if cmd.find('proto/name') is not None and 'vkCmd' in cmd.find('proto/name').text:
            entry = ValidityEntry()
            entry += extsync_prefix
            entry += 'the sname:VkCommandPool that pname:commandBuffer was allocated from must: be externally synchronized'
            validity += entry

        # Find and add any "implicit" parameters that are thread unsafe
        implicitexternsyncparams = cmd.find('implicitexternsyncparams')
        if implicitexternsyncparams is not None:
            for elem in implicitexternsyncparams:
                entry = ValidityEntry()
                entry += extsync_prefix
                entry += elem.text
                entry += ' must: be externally synchronized'
                validity += entry

        return validity

    def makeCommandPropertiesTableHeader(self):
        header  = '|<<VkCommandBufferLevel,Command Buffer Levels>>'
        header += '|<<vkCmdBeginRenderPass,Render Pass Scope>>'
        if self.videocodingRequired():
            header += '|<<vkCmdBeginVideoCodingKHR,Video Coding Scope>>'
        header += '|<<VkQueueFlagBits,Supported Queue Types>>'
        header += '|<<fundamentals-queueoperation-command-types,Command Type>>'
        return header

    def makeCommandPropertiesTableEntry(self, cmd, name):
        cmdbufferlevel, renderpass, videocoding, queues, tasks = None, None, None, None, None

        if 'vkCmd' in name:
            # Must be called in primary/secondary command buffers appropriately
            cmdbufferlevel = cmd.get('cmdbufferlevel')
            cmdbufferlevel = (' + \n').join(cmdbufferlevel.title().split(','))

            # Must be called inside/outside a render pass appropriately
            renderpass = cmd.get('renderpass')
            renderpass = renderpass.capitalize()

            # Must be called inside/outside a video coding scope appropriately
            if self.videocodingRequired():
                videocoding = self.getVideocoding(cmd).capitalize()

            #
            # This test for vkCmdFillBuffer is a hack, since we have no path
            # to conditionally have queues enabled or disabled by an extension.
            # As the VU stuff is all moving out (hopefully soon), this hack solves the issue for now
            if name == 'vkCmdFillBuffer':
                if self.isVKVersion11() or 'VK_KHR_maintenance1' in self.registry.requiredextensions:
                    queues = [ 'transfer', 'graphics', 'compute' ]
                else:
                    queues = [ 'graphics', 'compute' ]
            else:
                queues = self.getQueueList(cmd)
            queues = (' + \n').join([queue.title() for queue in queues])

            tasks = cmd.get('tasks')
            tasks = (' + \n').join(tasks.title().split(','))
        elif 'vkQueue' in name:
            # For queue commands there are no command buffer level, render
            # pass, or video coding scope specific restrictions,
            # or command type, but the queue types are considered
            cmdbufferlevel = '-'
            renderpass = '-'
            if self.videocodingRequired():
                videocoding = '-'

            queues = self.getQueueList(cmd)
            if queues is None:
                queues = 'Any'
            else:
                queues = (' + \n').join([queue.upper() for queue in queues])

            tasks = '-'

        table_items = (cmdbufferlevel, renderpass, videocoding, queues, tasks)
        entry = '|'.join(filter(None, table_items))

        return ('|' + entry) if entry else None


    def findRequiredEnums(self, enums):
        """Check each enumerant name in the enums list and remove it if not
        required by the generator. This allows specifying success and error
        codes for extensions that are only included in validity when needed
        for the spec being targeted."""
        return self.keepOnlyRequired(enums, self.registry.enumdict)

    def findRequiredCommands(self, commands):
        """Check each command name in the commands list and remove it if not
        required by the generator.

        This will allow some state operations to take place before endFile."""
        return self.keepOnlyRequired(commands, self.registry.cmddict)

    def keepOnlyRequired(self, names, info_dict):
        """Check each element name in the supplied dictionary and remove it if not
        required by the generator.

        This will allow some operations to take place before endFile no matter the order of generation."""
        # TODO Unpleasantly breaks encapsulation. Should be a method in the registry class

        def is_required(name):
            info = self.registry.lookupElementInfo(name, info_dict)
            if info is None:
                return False
            if not info.required:
                self.logMsg('diag', 'keepOnlyRequired: element',
                            name, 'IS NOT required, skipping')
            return info.required

        return [name
                for name in names
                if is_required(name)]

    def makeReturnCodeList(self, attrib, cmd, name):
        """Return a list of possible return codes for a function.

        attrib is either 'successcodes' or 'errorcodes'.
        """
        return_lines = []
        RETURN_CODE_FORMAT = '* ename:{}'

        codes_attr = cmd.get(attrib)
        if codes_attr:
            codes = self.findRequiredEnums(codes_attr.split(','))
            if codes:
                return_lines.extend((RETURN_CODE_FORMAT.format(code)
                                     for code in codes))

        applicable_ext_codes = (ext_code
                                for ext_code in self.registry.commandextensionsuccesses
                                if ext_code.command == name)
        for ext_code in applicable_ext_codes:
            line = RETURN_CODE_FORMAT.format(ext_code.value)
            if ext_code.extension:
                line += ' [only if {} is enabled]'.format(
                    self.conventions.formatExtension(ext_code.extension))

            return_lines.append(line)
        if return_lines:
            return '\n'.join(return_lines)

        return None

    def makeSuccessCodes(self, cmd, name):
        return self.makeReturnCodeList('successcodes', cmd, name)

    def makeErrorCodes(self, cmd, name):
        return self.makeReturnCodeList('errorcodes', cmd, name)

    def genCmd(self, cmdinfo, name, alias):
        """Command generation."""
        OutputGenerator.genCmd(self, cmdinfo, name, alias)

        # @@@ (Jon) something needs to be done here to handle aliases, probably

        validity = self.makeValidityCollection(name)

        # OpenXR-only: make sure extension is enabled
        # validity.possiblyAddExtensionRequirement(self.currentExtension, 'calling flink:')

        validity += self.makeStructOrCommandValidity(
            cmdinfo.elem, name, cmdinfo.getParams())

        threadsafety = self.makeThreadSafetyBlock(cmdinfo.elem, 'param')
        commandpropertiesentry = None

        # Vulkan-specific
        commandpropertiesentry = self.makeCommandPropertiesTableEntry(
            cmdinfo.elem, name)
        successcodes = self.makeSuccessCodes(cmdinfo.elem, name)
        errorcodes = self.makeErrorCodes(cmdinfo.elem, name)

        # OpenXR-specific
        # self.generateStateValidity(validity, name)

        self.writeInclude('protos', name, validity, threadsafety,
                          commandpropertiesentry, successcodes, errorcodes)

    def genStruct(self, typeinfo, typeName, alias):
        """Struct Generation."""
        OutputGenerator.genStruct(self, typeinfo, typeName, alias)

        # @@@ (Jon) something needs to be done here to handle aliases, probably

        # Anything that is only ever returned cannot be set by the user, so
        # should not have any validity information.
        validity = self.makeValidityCollection(typeName)
        threadsafety = []

        # OpenXR-only: make sure extension is enabled
        # validity.possiblyAddExtensionRequirement(self.currentExtension, 'using slink:')

        if typeinfo.elem.get('category') != 'union':
            if typeinfo.elem.get('returnedonly') is None:
                validity += self.makeStructOrCommandValidity(
                    typeinfo.elem, typeName, typeinfo.getMembers())
                threadsafety = self.makeThreadSafetyBlock(typeinfo.elem, 'member')

            else:
                # Need to generate structure type and next pointer chain member validation
                validity += self.makeOutputOnlyStructValidity(
                    typeinfo.elem, typeName, typeinfo.getMembers())

        self.writeInclude('structs', typeName, validity,
                          threadsafety, None, None, None)

    def genGroup(self, groupinfo, groupName, alias):
        """Group (e.g. C "enum" type) generation.
        For the validity generator, this just tags individual enumerants
        as required or not.
        """
        OutputGenerator.genGroup(self, groupinfo, groupName, alias)

        # @@@ (Jon) something needs to be done here to handle aliases, probably

        groupElem = groupinfo.elem

        # Loop over the nested 'enum' tags. Keep track of the minimum and
        # maximum numeric values, if they can be determined; but only for
        # core API enumerants, not extension enumerants. This is inferred
        # by looking for 'extends' attributes.
        for elem in groupElem.findall('enum'):
            name = elem.get('name')
            ei = self.registry.lookupElementInfo(name, self.registry.enumdict)

            if ei is None:
                self.logMsg('error',
                    f'genGroup({groupName}) - no element found for enum {name}')

            # Tag enumerant as required or not
            ei.required = self.isEnumRequired(elem)

    def genType(self, typeinfo, name, alias):
        """Type Generation."""
        OutputGenerator.genType(self, typeinfo, name, alias)

        # @@@ (Jon) something needs to be done here to handle aliases, probably

        category = typeinfo.elem.get('category')
        if category in ('struct', 'union'):
            self.genStruct(typeinfo, name, alias)