1474 lines
60 KiB
Python
1474 lines
60 KiB
Python
#!/usr/bin/python3 -i
|
|
#
|
|
# Copyright (c) 2013-2019 The Khronos Group Inc.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
import re
|
|
import sys
|
|
from collections import OrderedDict, namedtuple
|
|
from functools import reduce
|
|
|
|
from generator import OutputGenerator, write
|
|
|
|
class UnhandledCaseError(RuntimeError):
|
|
def __init__(self):
|
|
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 what container type you'd like,
|
|
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 LengthEntry:
|
|
"""An entry in a (comma-separated) len attribute"""
|
|
|
|
def __init__(self, val):
|
|
self.other_param_name = None
|
|
self.null_terminated = False
|
|
self.number = None
|
|
if val == 'null-terminated':
|
|
self.null_terminated = True
|
|
return
|
|
|
|
if val.isdigit():
|
|
self.number = int(val)
|
|
return
|
|
|
|
# Must be another param name.
|
|
self.other_param_name = val
|
|
|
|
@staticmethod
|
|
def parse_len_from_param(param):
|
|
"""Get a list of LengthEntry."""
|
|
return [LengthEntry(elt) for elt in param.get('len').split(',')]
|
|
|
|
|
|
def _getElemName(elem, default=None):
|
|
"""Get the name associated with an element, either a name child or name attribute."""
|
|
name_elem = elem.find('name')
|
|
if name_elem is not None:
|
|
return name_elem.text
|
|
# Fallback if there is no child.
|
|
return elem.get('name', default)
|
|
|
|
def _getElemType(elem, default=None):
|
|
"""Get the type associated with an element, either a type child or type attribute."""
|
|
type_elem = elem.find('type')
|
|
if type_elem is not None:
|
|
return type_elem.text
|
|
# Fallback if there is no child.
|
|
return elem.get('type', default)
|
|
|
|
def _findNamedElem(elems, name):
|
|
"""Traverse a collection of elements with 'name' nodes or attributes, looking for and returning one with the right name.
|
|
|
|
NOTE: Many places where this is used might be better served by changing to a dictionary.
|
|
"""
|
|
for elem in elems:
|
|
if _getElemName(elem) == name:
|
|
return elem
|
|
return None
|
|
|
|
|
|
def _findNamedObject(collection, name):
|
|
"""Traverse a collection of elements with 'name' attributes, looking for and returning one with the right name.
|
|
|
|
NOTE: Many places where this is used might be better served by changing to a dictionary.
|
|
"""
|
|
for elt in collection:
|
|
if elt.name == name:
|
|
return elt
|
|
return None
|
|
|
|
|
|
class ValidityCollection:
|
|
"""Combines validity for a single entity."""
|
|
|
|
def __init__(self, entity, conventions):
|
|
self.entity = entity
|
|
self.conventions = conventions
|
|
self.lines = []
|
|
|
|
def possiblyAddExtensionRequirement(self, entity_data, entity_preface):
|
|
"""Add an extension-related validity statement if required.
|
|
|
|
entity_preface is a string that goes between "must be enabled prior to "
|
|
and the name of the entity, and normally ends in a macro.
|
|
For instance, might be "calling flink:" for a function.
|
|
"""
|
|
if entity_data.extensionname:
|
|
msg = 'The {} extension must: be enabled prior to {}{}'.format(
|
|
self.conventions.formatExtension(entity_data.extensionname), entity_preface, self.entity)
|
|
self.addValidityEntry(msg, 'extension', 'notenabled')
|
|
|
|
def addValidityEntry(self, msg, *args):
|
|
"""Add a validity entry, optionally with a VUID anchor.
|
|
|
|
If any trailing arguments are supplied,
|
|
an anchor is generated by concatenating them with dashes
|
|
at the end of the VUID anchor name.
|
|
"""
|
|
parts = ['*']
|
|
if args:
|
|
parts.append('[[{}]]'.format(
|
|
'-'.join(['VUID', self.entity] + list(args))))
|
|
parts.append(msg)
|
|
self.lines.append(' '.join(parts))
|
|
|
|
def addText(self, msg):
|
|
"""Add already formatted validity text."""
|
|
if not msg:
|
|
return
|
|
msg = msg.rstrip()
|
|
if not msg:
|
|
return
|
|
self.lines.append(msg)
|
|
|
|
@property
|
|
def text(self):
|
|
"""Access validity statements as a single string."""
|
|
if not self.lines:
|
|
return None
|
|
return '\n'.join(self.lines) + '\n'
|
|
|
|
|
|
class ValidityOutputGenerator(OutputGenerator):
|
|
"""ValidityOutputGenerator - subclass of OutputGenerator.
|
|
|
|
Generates AsciiDoc includes of valid usage information, for reference
|
|
pages and the Vulkan 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,
|
|
errFile = sys.stderr,
|
|
warnFile = sys.stderr,
|
|
diagFile = sys.stdout):
|
|
OutputGenerator.__init__(self, errFile, warnFile, diagFile)
|
|
|
|
@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, connective='and'):
|
|
"""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.
|
|
|
|
Delegates to the object implementing ConventionsBase.
|
|
"""
|
|
return self.conventions.makeProseList(elements, connective)
|
|
|
|
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((self.conventions.valid_pointer_prefix, 'pointer'))
|
|
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 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 makeAnchor(self, blockname, pname, category):
|
|
"""Create a unique namespaced Valid Usage anchor name.
|
|
|
|
blockname - command or structure
|
|
pname - parameter or member (may be None)
|
|
category - distinct implicit VU type
|
|
"""
|
|
# For debugging
|
|
# return '* '
|
|
if pname is not None:
|
|
return '* [[VUID-%s-%s-%s]] ' % (blockname, pname, category)
|
|
|
|
return '* [[VUID-%s-%s]] ' % (blockname, category)
|
|
|
|
def writeInclude(self, directory, basename, validity, threadsafety, commandpropertiesentry, successcodes, errorcodes):
|
|
"""Generate an include file.
|
|
|
|
directory - subdirectory to put file in (relative pathname)
|
|
basename - base name of the file
|
|
contents - contents of the file (Asciidoc boilerplate aside)
|
|
"""
|
|
# Create subdirectory, if needed
|
|
directory = self.genOpts.directory + '/' + directory
|
|
self.makeDir(directory)
|
|
|
|
# Create validity file
|
|
filename = directory + '/' + basename + '.txt'
|
|
self.logMsg('diag', '# Generating include file:', filename)
|
|
|
|
fp = open(filename, 'w', encoding='utf-8')
|
|
# Asciidoc anchor
|
|
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:
|
|
write('.Host Synchronization', 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('|<<VkCommandBufferLevel,Command Buffer Levels>>|<<vkCmdBeginRenderPass,Render Pass Scope>>|<<VkQueueFlagBits,Supported Queue Types>>|<<synchronization-pipeline-stages-types,Pipeline Type>>', 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
|
|
has_success = (successcodes is not None and len(successcodes) > 0)
|
|
has_errors = (errorcodes is not None and len(errorcodes) > 0)
|
|
if has_success or has_errors:
|
|
write('.Return Codes', file=fp)
|
|
write('****', file=fp)
|
|
if has_success:
|
|
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 has_errors:
|
|
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)
|
|
|
|
fp.close()
|
|
|
|
def paramIsPointer(self, param):
|
|
"""Check if the parameter passed in is a pointer."""
|
|
tail = param.find('type').tail
|
|
return tail is not None and '*' in tail
|
|
|
|
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 staticArrayLength(self, param):
|
|
"""Get the length of a parameter that's been identified as a static array."""
|
|
paramenumsize = param.find('enum')
|
|
if paramenumsize is not None:
|
|
return paramenumsize.text
|
|
|
|
return param.find('name').tail[1:-1]
|
|
|
|
def paramIsArray(self, param):
|
|
"""Check if the parameter passed in is a pointer to an array."""
|
|
return param.get('len') is not None
|
|
|
|
def getHandleParent(self, typename):
|
|
"""Get the parent of a handle object."""
|
|
types = self.registry.tree.findall("types/type")
|
|
elem = _findNamedElem(types, typename)
|
|
if elem:
|
|
return elem.get('parent')
|
|
|
|
return None
|
|
|
|
def iterateHandleAncestors(self, typename):
|
|
"""Iterate through the ancestors of a handle type."""
|
|
current = self.getHandleParent(typename)
|
|
while current is not None:
|
|
yield current
|
|
current = self.getHandleParent(current)
|
|
|
|
def getHandleAncestors(self, typename):
|
|
"""Get the ancestors of a handle object."""
|
|
ancestors = []
|
|
current = typename
|
|
while True:
|
|
current = self.getHandleParent(current)
|
|
if current is None:
|
|
return ancestors
|
|
ancestors.append(current)
|
|
|
|
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's 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 let's say yes.
|
|
if param.get('noautovalidity') is not None:
|
|
return True
|
|
|
|
# If the parameter is an array and we haven't 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:
|
|
# don't 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 getTypeCategory(self, typename):
|
|
"""Get the category of a type."""
|
|
types = self.registry.tree.findall("types/type")
|
|
elem = _findNamedElem(types, typename)
|
|
if elem is not None:
|
|
return elem.get('category')
|
|
return None
|
|
|
|
def makeAsciiDocPreChunk(self, blockname, param, params):
|
|
"""Make a chunk of text for the end of a parameter if it is an array."""
|
|
param_name = _getElemName(param)
|
|
paramtype = _getElemType(param)
|
|
|
|
# General pre-amble. Check optionality and add stuff.
|
|
asciidoc = self.makeAnchor(blockname, param_name, 'parameter')
|
|
optionallengths = []
|
|
|
|
if self.paramIsStaticArray(param):
|
|
asciidoc += 'Any given element of '
|
|
|
|
elif self.paramIsArray(param):
|
|
# 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
|
|
lengths = LengthEntry.parse_len_from_param(param)
|
|
for length in lengths:
|
|
if not length.other_param_name:
|
|
# don't care about constants or "null-terminated"
|
|
continue
|
|
other_param = _findNamedElem(params, length.other_param_name)
|
|
if other_param is not None and other_param.get('optional') is not None:
|
|
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 param.get('optional') is not None:
|
|
asciidoc += 'If '
|
|
if optionallengths:
|
|
# TODO switch to commented line, but this introduces cosmetic changes.
|
|
#asciidoc += self.makeProseList(optionallengths, 'or')
|
|
asciidoc += ', or '.join(optionallengths)
|
|
if len(optionallengths) == 1:
|
|
asciidoc += ' is '
|
|
else:
|
|
asciidoc += ' are '
|
|
|
|
asciidoc += 'not `0`, '
|
|
|
|
|
|
if optionallengths and param.get('optional') is not None:
|
|
asciidoc += 'and '
|
|
if param.get('optional') is not None:
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' is not `NULL`, '
|
|
|
|
elif param.get('optional'):
|
|
# Don't generate this stub for bitflags
|
|
if self.getTypeCategory(paramtype) != 'bitmask':
|
|
if param.get('optional').split(',')[0] == 'true':
|
|
asciidoc += 'If '
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' is not '
|
|
if self.paramIsArray(param) or self.paramIsPointer(param) or self.isHandleTypeDispatchable(paramtype):
|
|
asciidoc += self.null
|
|
elif self.getTypeCategory(paramtype) == 'handle':
|
|
asciidoc += 'dlink:' + self.conventions.api_prefix + 'NULL_HANDLE'
|
|
else:
|
|
asciidoc += '`0`'
|
|
|
|
asciidoc += ', '
|
|
|
|
return asciidoc
|
|
|
|
def createValidationLineForParameterIntroChunk(self, blockname, param, params, typetext):
|
|
"""Make the generic asciidoc line chunk portion used for all parameters.
|
|
|
|
May return an empty string if nothing to validate.
|
|
"""
|
|
|
|
asciidoc = ''
|
|
param_name = _getElemName(param)
|
|
paramtype = _getElemType(param)
|
|
|
|
asciidoc += self.makeAsciiDocPreChunk(blockname, param, params)
|
|
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: be '
|
|
|
|
if self.paramIsArray(param):
|
|
# Arrays. These are hard to get right, apparently
|
|
|
|
lengths = param.get('len').split(',')
|
|
|
|
if lengths[0] == 'null-terminated':
|
|
asciidoc += 'a null-terminated '
|
|
elif lengths[0] == '1':
|
|
asciidoc += 'a ' + self.valid_pointer_text + ' to '
|
|
else:
|
|
asciidoc += 'a ' + self.valid_pointer_text + ' to an array of '
|
|
|
|
# Handle equations, which are currently denoted with latex
|
|
if 'latexmath:' in lengths[0]:
|
|
asciidoc += lengths[0]
|
|
else:
|
|
asciidoc += self.makeParameterName(lengths[0])
|
|
asciidoc += ' '
|
|
|
|
for length in lengths[1:]:
|
|
if length == 'null-terminated':
|
|
# This should always be the last thing.
|
|
# If it ever isn't for some bizarre reason, then this will need some massaging.
|
|
asciidoc += 'null-terminated '
|
|
elif length == '1':
|
|
asciidoc += self.valid_pointer_text + 's to '
|
|
else:
|
|
asciidoc += self.valid_pointer_text + 's to arrays of '
|
|
# Handle equations, which are currently denoted with latex
|
|
if 'latexmath:' in length:
|
|
asciidoc += length
|
|
else:
|
|
asciidoc += self.makeParameterName(length)
|
|
asciidoc += ' '
|
|
|
|
# Void pointers don't actually point at anything - remove the word "to"
|
|
if paramtype == 'void':
|
|
if lengths[-1] == '1':
|
|
if len(lengths) > 1:
|
|
asciidoc = asciidoc[:-5] # Take care of the extra s added by the post array chunk function. #HACK#
|
|
else:
|
|
asciidoc = asciidoc[:-4]
|
|
else:
|
|
# An array of void values is a byte array.
|
|
asciidoc += 'byte'
|
|
|
|
elif paramtype == 'char':
|
|
# A null terminated array of chars is a string
|
|
if lengths[-1] == 'null-terminated':
|
|
asciidoc += 'UTF-8 string'
|
|
else:
|
|
# Else it's just a bunch of chars
|
|
asciidoc += 'char value'
|
|
elif param.text is not None:
|
|
# If a value is "const" that means it won't get modified, so it must be valid going into the function.
|
|
if 'const' in param.text:
|
|
typecategory = self.getTypeCategory(paramtype)
|
|
if (typecategory not in ('struct', 'union', 'basetype') and typecategory is not None) \
|
|
or not self.isStructAlwaysValid(blockname, paramtype):
|
|
asciidoc += 'valid '
|
|
|
|
asciidoc += typetext
|
|
|
|
# pluralize
|
|
if len(lengths) > 1 or (lengths[0] != '1' and lengths[0] != 'null-terminated'):
|
|
asciidoc += 's'
|
|
|
|
elif self.paramIsPointer(param):
|
|
# Handle pointers - which are really special case arrays (i.e. they don't 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':
|
|
pointercount -= 1
|
|
|
|
# Could be multi-level pointers (e.g. ppData - pointer to a pointer). Handle that.
|
|
asciidoc += 'a '
|
|
asciidoc += (self.valid_pointer_text + ' to a ') * pointercount
|
|
|
|
# Handle void* and pointers to it
|
|
if paramtype == 'void':
|
|
# If there is only void*, it is just optional int - we don't need any language.
|
|
if pointercount == 0 and param.get('optional') is not None:
|
|
return '' # early return
|
|
|
|
if param.get('optional') is None or param.get('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 won't get modified, so it must be valid going into the function.
|
|
if param.text is not None and paramtype != 'void':
|
|
if 'const' in param.text:
|
|
asciidoc += 'valid '
|
|
|
|
asciidoc += typetext
|
|
|
|
else:
|
|
# Non-pointer, non-optional things must be valid
|
|
asciidoc += 'a valid '
|
|
asciidoc += typetext
|
|
|
|
if asciidoc != '':
|
|
asciidoc += '\n'
|
|
|
|
# Add additional line for non-optional bitmasks
|
|
isOutputParam = self.paramIsPointer(param) and not (param.text and 'const' in param.text)
|
|
if self.getTypeCategory(paramtype) == 'bitmask' and not isOutputParam:
|
|
isMandatory = param.get('optional') is None #TODO does not really handle if someone tries something like optional="true,false"
|
|
if isMandatory:
|
|
asciidoc += self.makeAnchor(blockname, param_name, 'requiredbitmask')
|
|
if self.paramIsArray(param):
|
|
asciidoc += 'Each element of '
|
|
asciidoc += 'pname:'
|
|
asciidoc += param_name
|
|
asciidoc += ' must: not be `0`'
|
|
asciidoc += '\n'
|
|
|
|
return asciidoc
|
|
|
|
def makeAsciiDocLineForParameter(self, blockname, param, params, typetext):
|
|
if param.get('noautovalidity') is not None:
|
|
return ''
|
|
asciidoc = self.createValidationLineForParameterIntroChunk(blockname, param, params, typetext)
|
|
|
|
return asciidoc
|
|
|
|
def isStructAlwaysValid(self, blockname, structname):
|
|
"""Try to do check if a structure is always considered valid (i.e. there's no rules to its acceptance)."""
|
|
|
|
struct = self.registry.tree.find("types/type[@name='" + structname + "']")
|
|
|
|
if struct.get('returnedonly'):
|
|
return True
|
|
|
|
params = struct.findall('member')
|
|
|
|
for param in params:
|
|
param_name = _getElemName(param)
|
|
paramtype = _getElemType(param)
|
|
typecategory = self.getTypeCategory(paramtype)
|
|
|
|
if param_name in (self.structtype_member_name, self.nextpointer_member_name):
|
|
return False
|
|
|
|
if param.get('noautovalidity'):
|
|
return False
|
|
|
|
if paramtype in ('void', 'char') or self.paramIsArray(param) or self.paramIsPointer(param):
|
|
if self.makeAsciiDocLineForParameter(blockname, param, params, '') != '':
|
|
return False
|
|
elif typecategory in ('handle', 'enum', 'bitmask'):
|
|
return False
|
|
elif typecategory in ('struct', 'union'):
|
|
if self.isStructAlwaysValid(blockname, paramtype) is False:
|
|
return False
|
|
|
|
return True
|
|
|
|
def fix_an(self, text):
|
|
"""Fix 'a' vs 'an' in a string"""
|
|
return re.sub(r' a ([a-z]+:)?([aAeEiIoOxX]\w+\b)(?!:)', r' an \1\2', text)
|
|
|
|
def createValidationLineForParameter(self, blockname, param, params, typecategory):
|
|
"""Make an entire asciidoc line for a given parameter."""
|
|
asciidoc = ''
|
|
param_name = _getElemName(param)
|
|
paramtype = _getElemType(param)
|
|
type_name = paramtype
|
|
|
|
is_array = self.paramIsArray(param)
|
|
is_pointer = self.paramIsPointer(param)
|
|
needs_recursive_validity = (is_array or
|
|
is_pointer or
|
|
not self.isStructAlwaysValid(blockname, type_name))
|
|
typetext = None
|
|
if type_name in ('void', 'char'):
|
|
# Chars and void are special cases - needs care inside the generator functions
|
|
# A null-terminated char array is a string, else it's 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 = type_name.replace('Flags', 'FlagBits')
|
|
if self.registry.tree.find("enums[@name='" + bitsname + "']") is None:
|
|
# Empty bit mask: presumably just a placeholder (or only in an extension not enabled for this build)
|
|
asciidoc += self.makeAnchor(blockname,
|
|
param_name, 'zerobitmask')
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: be `0`'
|
|
asciidoc += '\n'
|
|
else:
|
|
const_in_text = param.text is not None and 'const' in param.text
|
|
|
|
if is_array:
|
|
if const_in_text:
|
|
# input an array of bitmask values
|
|
template = 'combinations of {bitsname} value'
|
|
else:
|
|
template = '{paramtype} value'
|
|
elif is_pointer:
|
|
if const_in_text:
|
|
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.makeEnumerationName(type_name))
|
|
|
|
elif typecategory == 'handle':
|
|
typetext = '{} handle'.format(self.makeStructName(type_name))
|
|
|
|
elif typecategory == 'enum':
|
|
typetext = '{} value'.format(self.makeEnumerationName(type_name))
|
|
|
|
elif typecategory == 'funcpointer':
|
|
typetext = '{} value'.format(self.makeFuncPointerName(type_name))
|
|
|
|
elif typecategory == 'struct':
|
|
if needs_recursive_validity:
|
|
typetext = '{} structure'.format(
|
|
self.makeStructName(type_name))
|
|
|
|
else:
|
|
# TODO right now just skipping generating a line here.
|
|
# I think this was intentional in general, but maybe not in that particular case.
|
|
#raise UnhandledCaseError()
|
|
pass
|
|
|
|
elif typecategory == 'union':
|
|
if needs_recursive_validity:
|
|
typetext = '{} union'.format(self.makeStructName(type_name))
|
|
else:
|
|
# TODO right now just skipping generating a line here.
|
|
# I think this was intentional in general:
|
|
# we do hit this in Vulkan.
|
|
pass
|
|
|
|
elif self.paramIsArray(param) or self.paramIsPointer(param):
|
|
typetext = '{} value'.format(self.makeBaseTypeName(paramtype))
|
|
|
|
elif typecategory is None:
|
|
# "a valid uint32_t value" doesn't make much sense.
|
|
pass
|
|
|
|
# If any of the above conditions matched and set typetext,
|
|
# we call using it.
|
|
if typetext is not None:
|
|
asciidoc += self.makeAsciiDocLineForParameter(
|
|
blockname, param, params, typetext)
|
|
return self.fix_an(asciidoc)
|
|
|
|
def makeAsciiDocHandleParent(self, blockname, param, params):
|
|
"""Make an asciidoc validity entry for a handle's parent object.
|
|
|
|
Creates 'parent' VUID.
|
|
"""
|
|
asciidoc = ''
|
|
param_name = _getElemName(param)
|
|
paramtype = _getElemType(param)
|
|
|
|
# Deal with handle parents
|
|
handleparent = self.getHandleParent(paramtype)
|
|
if handleparent is None:
|
|
return asciidoc
|
|
|
|
otherparam = None
|
|
for p in params:
|
|
if _getElemType(p) == handleparent:
|
|
otherparam = p
|
|
break
|
|
if otherparam is None:
|
|
return asciidoc
|
|
|
|
parentreference = _getElemName(otherparam)
|
|
asciidoc += self.makeAnchor(blockname, param_name, 'parent')
|
|
|
|
if self.isHandleOptional(param, params):
|
|
if self.paramIsArray(param):
|
|
asciidoc += 'Each element of '
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' that is a valid handle'
|
|
else:
|
|
asciidoc += 'If '
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' is a valid handle, it'
|
|
else:
|
|
if self.paramIsArray(param):
|
|
asciidoc += 'Each element of '
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: have been created, allocated, or retrieved from '
|
|
asciidoc += self.makeParameterName(parentreference)
|
|
|
|
asciidoc += '\n'
|
|
return asciidoc
|
|
|
|
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.
|
|
"""
|
|
asciidoc = ''
|
|
|
|
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:
|
|
|
|
asciidoc += self.makeAnchor(blockname, None, '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:
|
|
asciidoc += 'Each of '
|
|
else:
|
|
asciidoc += 'Both of '
|
|
|
|
asciidoc += ", ".join(parametertexts[:-1])
|
|
asciidoc += ', and '
|
|
asciidoc += parametertexts[-1]
|
|
if anyoptional is True:
|
|
asciidoc += ' that are valid handles'
|
|
asciidoc += ' must: have been created, allocated, or retrieved from the same '
|
|
asciidoc += self.makeStructName(commonancestor)
|
|
asciidoc += '\n'
|
|
|
|
return asciidoc
|
|
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 makeStructureType(self, structname, param):
|
|
"""Generate an asciidoc validity line for the type value of a struct."""
|
|
param_name = _getElemName(param)
|
|
|
|
asciidoc = self.makeAnchor(structname, param_name, self.structtype_member_name)
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: be '
|
|
|
|
values = param.get('values')
|
|
if values:
|
|
# Extract each enumerant value. They could be validated in the
|
|
# same fashion as validextensionstructs in
|
|
# makeStructureExtensionPointer, although that's not relevant in
|
|
# the current extension struct model.
|
|
asciidoc += self.makeProseList(( self.makeEnumerantName(v) for v in values.split(',')), 'or')
|
|
elif 'Base' in structname:
|
|
# This type doesn't even have any values for its type,
|
|
# and it seems like it might be a base struct that we'd expect to lack its own type,
|
|
# so omit the entire statement
|
|
return ''
|
|
else:
|
|
self.logMsg('warn', 'No values were marked-up for the structure type member of', structname, 'so making one up!')
|
|
asciidoc += self.makeStructureTypeFromName(structname)
|
|
|
|
asciidoc += '\n'
|
|
|
|
return asciidoc
|
|
|
|
def makeStructureExtensionPointer(self, blockname, param):
|
|
"""Generate an asciidoc 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')
|
|
|
|
asciidoc = self.makeAnchor(blockname, param_name, self.nextpointer_member_name)
|
|
validextensionstructs = self.registry.validextensionstructs.get(blockname)
|
|
extensionstructs = []
|
|
|
|
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.
|
|
for struct in validextensionstructs:
|
|
# Unpleasantly breaks encapsulation. Should be a method in the registry class
|
|
type = self.registry.lookupElementInfo(struct, self.registry.typedict)
|
|
if type is None:
|
|
self.logMsg('warn', 'makeStructureExtensionPointer: struct', struct, 'is in a validextensionstructs= attribute but is not in the registry')
|
|
elif type.required:
|
|
extensionstructs.append('slink:' + struct)
|
|
else:
|
|
self.logMsg('diag', 'makeStructureExtensionPointer: struct', struct, 'IS NOT required')
|
|
|
|
if not extensionstructs:
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: be '
|
|
asciidoc += self.null
|
|
elif len(extensionstructs) == 1:
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: be '
|
|
asciidoc += self.null
|
|
asciidoc +=' or a pointer to a valid instance of '
|
|
asciidoc += extensionstructs[0]
|
|
else:
|
|
asciidoc += 'Each '
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' member of any structure (including this one) in the '
|
|
asciidoc += 'pname:' + self.nextpointer_member_name
|
|
asciidoc += ' chain must: be either '
|
|
asciidoc += self.null
|
|
asciidoc += ' or a pointer to a valid instance of '
|
|
|
|
asciidoc += self.makeProseList(extensionstructs, 'or')
|
|
asciidoc += '\n'
|
|
|
|
asciidoc += self.makeAnchor(blockname, self.structtype_member_name, 'unique')
|
|
asciidoc += 'Each pname:' + self.structtype_member_name + ' member in the '
|
|
asciidoc += 'pname:' + self.nextpointer_member_name
|
|
asciidoc += ' chain must: be unique'
|
|
|
|
asciidoc += '\n'
|
|
|
|
return asciidoc
|
|
|
|
def makeValidUsageStatementsReturnedOnly(self, cmd, blockname, params):
|
|
"""Generate all the valid usage information for a given struct
|
|
that's only ever filled out by the implementation other than the
|
|
structure type and pointer chain members.
|
|
"""
|
|
|
|
# Start the asciidoc block for this
|
|
asciidoc = ''
|
|
|
|
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.
|
|
|
|
if param.get('noautovalidity') is None:
|
|
# Generate language to independently validate a parameter
|
|
if self.conventions.is_structure_type_member(paramtype, param_name):
|
|
asciidoc += self.makeStructureType(blockname, param)
|
|
elif self.conventions.is_nextpointer_member(paramtype, param_name) and cmd.get('structextends') is None:
|
|
asciidoc += self.makeStructureExtensionPointer(blockname, param)
|
|
|
|
# In case there's nothing to report, return None
|
|
if asciidoc == '':
|
|
return None
|
|
|
|
return asciidoc
|
|
|
|
def makeValidUsageStatements(self, cmd, blockname, params):
|
|
"""Generate all the valid usage information for a given struct or command."""
|
|
# Start the asciidoc block for this
|
|
asciidoc = ''
|
|
|
|
handles = []
|
|
arraylengths = set()
|
|
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 param.get('noautovalidity') is None:
|
|
# Generate language to independently validate a parameter
|
|
if self.conventions.is_structure_type_member(paramtype, param_name):
|
|
asciidoc += self.makeStructureType(blockname, param)
|
|
elif self.conventions.is_nextpointer_member(paramtype, param_name):
|
|
if cmd.get('structextends') is None:
|
|
asciidoc += self.makeStructureExtensionPointer(blockname, param)
|
|
else:
|
|
asciidoc += self.createValidationLineForParameter(blockname, param, params, typecategory)
|
|
|
|
# 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
|
|
arraylength = param.get('len')
|
|
if arraylength is not None:
|
|
arraylengths.update(set(arraylength.split(',')))
|
|
|
|
# For any vkQueue* functions, there might be queue type data
|
|
if 'vkQueue' in blockname:
|
|
# The queue type must be valid
|
|
queuetypes = cmd.get('queues')
|
|
if queuetypes:
|
|
queuebits = []
|
|
for queuetype in re.findall(r'([^,]+)', queuetypes):
|
|
queuebits.append(queuetype.replace('_',' '))
|
|
|
|
asciidoc += self.makeAnchor(blockname, None, 'queuetype')
|
|
asciidoc += 'The pname:queue must: support '
|
|
if len(queuebits) == 1:
|
|
asciidoc += queuebits[0]
|
|
else:
|
|
asciidoc += (', ').join(queuebits[:-1])
|
|
asciidoc += ', or '
|
|
asciidoc += queuebits[-1]
|
|
asciidoc += ' operations'
|
|
asciidoc += '\n'
|
|
|
|
if 'vkCmd' in blockname:
|
|
# The commandBuffer parameter must be being recorded
|
|
asciidoc += self.makeAnchor(blockname, 'commandBuffer', 'recording')
|
|
asciidoc += 'pname:commandBuffer must: be in the <<commandbuffers-lifecycle, recording state>>'
|
|
asciidoc += '\n'
|
|
|
|
#
|
|
# Start of valid queue type validation - command pool must have been
|
|
# allocated against a queue with at least one of the valid queue types
|
|
asciidoc += self.makeAnchor(blockname, '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':
|
|
if 'VK_KHR_maintenance1' in self.registry.requiredextensions:
|
|
asciidoc += 'The sname:VkCommandPool that pname:commandBuffer was allocated from must: support transfer, graphics or compute operations\n'
|
|
else:
|
|
asciidoc += 'The sname:VkCommandPool that pname:commandBuffer was allocated from must: support graphics or compute operations\n'
|
|
else:
|
|
# The queue type must be valid
|
|
queuetypes = cmd.get('queues')
|
|
queuebits = []
|
|
for queuetype in re.findall(r'([^,]+)', queuetypes):
|
|
queuebits.append(queuetype.replace('_',' '))
|
|
|
|
asciidoc += 'The sname:VkCommandPool that pname:commandBuffer was allocated from must: support '
|
|
if len(queuebits) == 1:
|
|
asciidoc += queuebits[0]
|
|
else:
|
|
asciidoc += (', ').join(queuebits[:-1])
|
|
asciidoc += ', or '
|
|
asciidoc += queuebits[-1]
|
|
asciidoc += ' operations'
|
|
asciidoc += '\n'
|
|
|
|
# Must be called inside/outside a renderpass appropriately
|
|
renderpass = cmd.get('renderpass')
|
|
|
|
if renderpass != 'both':
|
|
asciidoc += self.makeAnchor(blockname, None, 'renderpass')
|
|
asciidoc += 'This command must: only be called '
|
|
asciidoc += renderpass
|
|
asciidoc += ' of a render pass instance'
|
|
asciidoc += '\n'
|
|
|
|
# Must be in the right level command buffer
|
|
cmdbufferlevel = cmd.get('cmdbufferlevel')
|
|
|
|
if cmdbufferlevel != 'primary,secondary':
|
|
asciidoc += self.makeAnchor(blockname, None, 'bufferlevel')
|
|
asciidoc += 'pname:commandBuffer must: be a '
|
|
asciidoc += cmdbufferlevel
|
|
asciidoc += ' sname:VkCommandBuffer'
|
|
asciidoc += '\n'
|
|
|
|
# Any non-optional arraylengths should specify they must be greater than 0
|
|
non_optional_array_lengths = ((param, _getElemName(param))
|
|
for param in params
|
|
if _getElemName(param) in arraylengths and not param.get('optional'))
|
|
|
|
for param, param_name in non_optional_array_lengths:
|
|
# Get all the array dependencies
|
|
arrays = cmd.findall(
|
|
"param/[@len='{}'][@optional='true']".format(param_name))
|
|
|
|
# Get all the optional array dependencies, including those not generating validity for some reason
|
|
optionalarrays = arrays + \
|
|
cmd.findall(
|
|
"param/[@len='{}'][@noautovalidity='true']".format(param_name))
|
|
|
|
# If arraylength can ever be not a legal part of an
|
|
# asciidoc anchor name, this will need to be altered.
|
|
asciidoc += self.makeAnchor(blockname, param_name, 'arraylength')
|
|
|
|
# Allow lengths to be arbitrary if all their dependents are optional
|
|
if optionalarrays and len(optionalarrays) == len(arrays):
|
|
asciidoc += 'If '
|
|
if len(optionalarrays) > 1:
|
|
asciidoc += 'any of '
|
|
|
|
# TODO uncomment following statement once cosmetic changes OK
|
|
# asciidoc += self.makeProseList((self.makeParameterName(_getElemName(array))
|
|
# for array in optionalarrays),
|
|
# 'or')
|
|
|
|
if len(optionalarrays) > 1:
|
|
# TODO remove following statement once cosmetic changes OK
|
|
asciidoc += self.makeProseList((self.makeParameterName(_getElemName(array))
|
|
for array in optionalarrays),
|
|
'or')
|
|
asciidoc += ' are '
|
|
else:
|
|
# TODO remove following statement once cosmetic changes OK
|
|
asciidoc += ', '.join((self.makeParameterName(_getElemName(array))
|
|
for array in optionalarrays))
|
|
asciidoc += ' is '
|
|
|
|
asciidoc += 'not ' + self.null + ', '
|
|
|
|
if self.paramIsPointer(param):
|
|
asciidoc += 'the value referenced by '
|
|
|
|
elif self.paramIsPointer(param):
|
|
asciidoc += 'The value referenced by '
|
|
|
|
asciidoc += self.makeParameterName(param_name)
|
|
asciidoc += ' must: be greater than `0`'
|
|
asciidoc += '\n'
|
|
|
|
# Find the parents of all objects referenced in this command
|
|
for param in handles:
|
|
paramtype = _getElemType(param)
|
|
# Don't detect a parent for return values!
|
|
if not self.paramIsPointer(param) or (param.text is not None and 'const' in param.text):
|
|
|
|
parent = self.getHandleParent(paramtype)
|
|
|
|
if parent is not None:
|
|
asciidoc += self.makeAsciiDocHandleParent(blockname, param, params)
|
|
|
|
# Find the common ancestor of all objects referenced in this command
|
|
asciidoc += self.makeAsciiDocHandlesCommonAncestor(blockname, handles, params)
|
|
|
|
# In case there's nothing to report, return None
|
|
if asciidoc == '':
|
|
return None
|
|
# Delimit the asciidoc block
|
|
return asciidoc
|
|
|
|
def makeThreadSafetyBlock(self, cmd, paramtext):
|
|
"""Generate C function pointer typedef for <command> Element"""
|
|
paramdecl = ''
|
|
|
|
# Find and add any parameters that are thread unsafe
|
|
explicitexternsyncparams = cmd.findall(paramtext + "[@externsync]")
|
|
if explicitexternsyncparams is not None:
|
|
for param in explicitexternsyncparams:
|
|
externsyncattribs = param.get('externsync')
|
|
param_name = _getElemName(param)
|
|
for externsyncattrib in externsyncattribs.split(','):
|
|
paramdecl += '* '
|
|
paramdecl += 'Host access to '
|
|
if externsyncattrib == 'true':
|
|
if self.paramIsArray(param):
|
|
paramdecl += 'each member of ' + \
|
|
self.makeParameterName(param_name)
|
|
elif self.paramIsPointer(param):
|
|
paramdecl += 'the object referenced by ' + \
|
|
self.makeParameterName(param_name)
|
|
else:
|
|
paramdecl += self.makeParameterName(param_name)
|
|
else:
|
|
paramdecl += 'pname:'
|
|
paramdecl += externsyncattrib
|
|
paramdecl += ' must: be externally synchronized\n'
|
|
|
|
# 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:
|
|
paramdecl += '* '
|
|
paramdecl += 'Host access to the sname:VkCommandPool that pname:commandBuffer was allocated from must: be externally synchronized'
|
|
paramdecl += '\n'
|
|
|
|
# Find and add any "implicit" parameters that are thread unsafe
|
|
implicitexternsyncparams = cmd.find('implicitexternsyncparams')
|
|
if implicitexternsyncparams is not None:
|
|
for elem in implicitexternsyncparams:
|
|
paramdecl += '* '
|
|
paramdecl += 'Host access to '
|
|
paramdecl += elem.text
|
|
paramdecl += ' must: be externally synchronized\n'
|
|
|
|
if not paramdecl:
|
|
return None
|
|
return paramdecl
|
|
|
|
def makeCommandPropertiesTableEntry(self, cmd, name):
|
|
|
|
if 'vkCmd' in name:
|
|
# Must be called inside/outside a renderpass appropriately
|
|
cmdbufferlevel = cmd.get('cmdbufferlevel')
|
|
cmdbufferlevel = (' + \n').join(cmdbufferlevel.title().split(','))
|
|
|
|
renderpass = cmd.get('renderpass')
|
|
renderpass = renderpass.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 'VK_KHR_maintenance1' in self.registry.requiredextensions:
|
|
queues = 'Transfer + \nGraphics + \nCompute'
|
|
else:
|
|
queues = 'Graphics + \nCompute'
|
|
else:
|
|
queues = cmd.get('queues')
|
|
queues = (' + \n').join(queues.title().split(','))
|
|
|
|
pipeline = cmd.get('pipeline')
|
|
if pipeline:
|
|
pipeline = pipeline.capitalize()
|
|
else:
|
|
pipeline = ''
|
|
|
|
return '|' + cmdbufferlevel + '|' + renderpass + '|' + queues + '|' + pipeline
|
|
elif 'vkQueue' in name:
|
|
# Must be called inside/outside a renderpass appropriately
|
|
|
|
queues = cmd.get('queues')
|
|
if queues is None:
|
|
queues = 'Any'
|
|
else:
|
|
queues = (' + \n').join(queues.upper().split(','))
|
|
|
|
return '|-|-|' + queues + '|-'
|
|
|
|
return None
|
|
|
|
# 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.
|
|
def findRequiredEnums(self, enums):
|
|
out = []
|
|
for enum in enums:
|
|
# Unpleasantly breaks encapsulation. Should be a method in the registry class
|
|
ei = self.registry.lookupElementInfo(enum, self.registry.enumdict)
|
|
if ei is None:
|
|
self.logMsg('warn', 'findRequiredEnums: enum', enum,
|
|
'is in an attribute list but is not in the registry')
|
|
elif ei.required:
|
|
out.append(enum)
|
|
else:
|
|
self.logMsg('diag', 'findRequiredEnums: enum', enum, 'IS NOT required, skipping')
|
|
return out
|
|
|
|
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
|
|
|
|
# Get all the parameters
|
|
params = cmdinfo.elem.findall('param')
|
|
|
|
validity = self.makeValidUsageStatements(cmdinfo.elem, name, params)
|
|
|
|
threadsafety = self.makeThreadSafetyBlock(cmdinfo.elem, 'param')
|
|
# Vulkan-specific
|
|
commandpropertiesentry = self.makeCommandPropertiesTableEntry(cmdinfo.elem, name)
|
|
successcodes = self.makeSuccessCodes(cmdinfo.elem, name)
|
|
errorcodes = self.makeErrorCodes(cmdinfo.elem, name)
|
|
# OpenXR-specific
|
|
# beginsstate = self.makeBeginState(cmdinfo.elem, name)
|
|
# endsstate = self.makeEndState(cmdinfo.elem, name)
|
|
# checksstatedata = self.makeCheckState(cmdinfo.elem, 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's only ever returned can't be set by the user, so shouldn't have any validity information.
|
|
params = []
|
|
validity = ''
|
|
threadsafety = []
|
|
|
|
if typeinfo.elem.get('returnedonly') is None:
|
|
params = typeinfo.elem.findall('member')
|
|
|
|
generalvalidity = self.makeValidUsageStatements(typeinfo.elem, typeName, params)
|
|
if generalvalidity:
|
|
validity += generalvalidity
|
|
threadsafety = self.makeThreadSafetyBlock(typeinfo.elem, 'member')
|
|
|
|
self.writeInclude('structs', typeName, validity, threadsafety, None, None, None)
|
|
else:
|
|
# Need to generate structure type and next pointer chain member validation
|
|
params = typeinfo.elem.findall('member')
|
|
|
|
retvalidity = self.makeValidUsageStatementsReturnedOnly(typeinfo.elem, typeName, params)
|
|
if retvalidity:
|
|
validity += retvalidity
|
|
|
|
self.writeInclude('structs', typeName, validity, None, 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)
|
|
|
|
# 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)
|