1#!/usr/bin/python3 -i 2# 3# Copyright (c) 2015-2017 The Khronos Group Inc. 4# Copyright (c) 2015-2017 Valve Corporation 5# Copyright (c) 2015-2017 LunarG, Inc. 6# Copyright (c) 2015-2017 Google Inc. 7# 8# Licensed under the Apache License, Version 2.0 (the "License"); 9# you may not use this file except in compliance with the License. 10# You may obtain a copy of the License at 11# 12# http://www.apache.org/licenses/LICENSE-2.0 13# 14# Unless required by applicable law or agreed to in writing, software 15# distributed under the License is distributed on an "AS IS" BASIS, 16# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17# See the License for the specific language governing permissions and 18# limitations under the License. 19# 20# Author: Mark Lobodzinski <mark@lunarg.com> 21# Author: Tobin Ehlis <tobine@google.com> 22# Author: John Zulauf <jzulauf@lunarg.com> 23 24import os,re,sys 25import xml.etree.ElementTree as etree 26from generator import * 27from collections import namedtuple 28from common_codegen import * 29 30# 31# HelperFileOutputGeneratorOptions - subclass of GeneratorOptions. 32class HelperFileOutputGeneratorOptions(GeneratorOptions): 33 def __init__(self, 34 conventions = None, 35 filename = None, 36 directory = '.', 37 genpath = None, 38 apiname = None, 39 profile = None, 40 versions = '.*', 41 emitversions = '.*', 42 defaultExtensions = None, 43 addExtensions = None, 44 removeExtensions = None, 45 emitExtensions = None, 46 sortProcedure = regSortFeatures, 47 prefixText = "", 48 genFuncPointers = True, 49 protectFile = True, 50 protectFeature = True, 51 apicall = '', 52 apientry = '', 53 apientryp = '', 54 alignFuncParam = 0, 55 library_name = '', 56 expandEnumerants = True, 57 helper_file_type = ''): 58 GeneratorOptions.__init__(self, 59 conventions = conventions, 60 filename = filename, 61 directory = directory, 62 genpath = genpath, 63 apiname = apiname, 64 profile = profile, 65 versions = versions, 66 emitversions = emitversions, 67 defaultExtensions = defaultExtensions, 68 addExtensions = addExtensions, 69 removeExtensions = removeExtensions, 70 emitExtensions = emitExtensions, 71 sortProcedure = sortProcedure) 72 self.prefixText = prefixText 73 self.genFuncPointers = genFuncPointers 74 self.protectFile = protectFile 75 self.protectFeature = protectFeature 76 self.apicall = apicall 77 self.apientry = apientry 78 self.apientryp = apientryp 79 self.alignFuncParam = alignFuncParam 80 self.library_name = library_name 81 self.helper_file_type = helper_file_type 82# 83# HelperFileOutputGenerator - subclass of OutputGenerator. Outputs Vulkan helper files 84class HelperFileOutputGenerator(OutputGenerator): 85 """Generate helper file based on XML element attributes""" 86 def __init__(self, 87 errFile = sys.stderr, 88 warnFile = sys.stderr, 89 diagFile = sys.stdout): 90 OutputGenerator.__init__(self, errFile, warnFile, diagFile) 91 # Internal state - accumulators for different inner block text 92 self.enum_output = '' # string built up of enum string routines 93 # Internal state - accumulators for different inner block text 94 self.structNames = [] # List of Vulkan struct typenames 95 self.structTypes = dict() # Map of Vulkan struct typename to required VkStructureType 96 self.structMembers = [] # List of StructMemberData records for all Vulkan structs 97 self.object_types = [] # List of all handle types 98 self.object_type_aliases = [] # Aliases to handles types (for handles that were extensions) 99 self.debug_report_object_types = [] # Handy copy of debug_report_object_type enum data 100 self.core_object_types = [] # Handy copy of core_object_type enum data 101 self.device_extension_info = dict() # Dict of device extension name defines and ifdef values 102 self.instance_extension_info = dict() # Dict of instance extension name defines and ifdef values 103 104 # Named tuples to store struct and command data 105 self.StructType = namedtuple('StructType', ['name', 'value']) 106 self.CommandParam = namedtuple('CommandParam', ['type', 'name', 'ispointer', 'isstaticarray', 'isconst', 'iscount', 'len', 'extstructs', 'cdecl']) 107 self.StructMemberData = namedtuple('StructMemberData', ['name', 'members', 'ifdef_protect']) 108 109 self.custom_construct_params = { 110 # safe_VkGraphicsPipelineCreateInfo needs to know if subpass has color and\or depth\stencil attachments to use its pointers 111 'VkGraphicsPipelineCreateInfo' : 112 ', const bool uses_color_attachment, const bool uses_depthstencil_attachment', 113 # safe_VkPipelineViewportStateCreateInfo needs to know if viewport and scissor is dynamic to use its pointers 114 'VkPipelineViewportStateCreateInfo' : 115 ', const bool is_dynamic_viewports, const bool is_dynamic_scissors', 116 } 117 # 118 # Called once at the beginning of each run 119 def beginFile(self, genOpts): 120 OutputGenerator.beginFile(self, genOpts) 121 # User-supplied prefix text, if any (list of strings) 122 self.helper_file_type = genOpts.helper_file_type 123 self.library_name = genOpts.library_name 124 125 write("// clang-format off", file=self.outFile) 126 127 # File Comment 128 file_comment = '// *** THIS FILE IS GENERATED - DO NOT EDIT ***\n' 129 file_comment += '// See helper_file_generator.py for modifications\n' 130 write(file_comment, file=self.outFile) 131 # Copyright Notice 132 copyright = '' 133 copyright += '\n' 134 copyright += '/***************************************************************************\n' 135 copyright += ' *\n' 136 copyright += ' * Copyright (c) 2015-2017 The Khronos Group Inc.\n' 137 copyright += ' * Copyright (c) 2015-2017 Valve Corporation\n' 138 copyright += ' * Copyright (c) 2015-2017 LunarG, Inc.\n' 139 copyright += ' * Copyright (c) 2015-2017 Google Inc.\n' 140 copyright += ' *\n' 141 copyright += ' * Licensed under the Apache License, Version 2.0 (the "License");\n' 142 copyright += ' * you may not use this file except in compliance with the License.\n' 143 copyright += ' * You may obtain a copy of the License at\n' 144 copyright += ' *\n' 145 copyright += ' * http://www.apache.org/licenses/LICENSE-2.0\n' 146 copyright += ' *\n' 147 copyright += ' * Unless required by applicable law or agreed to in writing, software\n' 148 copyright += ' * distributed under the License is distributed on an "AS IS" BASIS,\n' 149 copyright += ' * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n' 150 copyright += ' * See the License for the specific language governing permissions and\n' 151 copyright += ' * limitations under the License.\n' 152 copyright += ' *\n' 153 copyright += ' * Author: Mark Lobodzinski <mark@lunarg.com>\n' 154 copyright += ' * Author: Courtney Goeltzenleuchter <courtneygo@google.com>\n' 155 copyright += ' * Author: Tobin Ehlis <tobine@google.com>\n' 156 copyright += ' * Author: Chris Forbes <chrisforbes@google.com>\n' 157 copyright += ' * Author: John Zulauf<jzulauf@lunarg.com>\n' 158 copyright += ' *\n' 159 copyright += ' ****************************************************************************/\n' 160 write(copyright, file=self.outFile) 161 # 162 # Write generated file content to output file 163 def endFile(self): 164 dest_file = '' 165 dest_file += self.OutputDestFile() 166 # Remove blank lines at EOF 167 if dest_file.endswith('\n'): 168 dest_file = dest_file[:-1] 169 write(dest_file, file=self.outFile) 170 write("// clang-format on", file=self.outFile) 171 # Finish processing in superclass 172 OutputGenerator.endFile(self) 173 # 174 # Override parent class to be notified of the beginning of an extension 175 def beginFeature(self, interface, emit): 176 # Start processing in superclass 177 OutputGenerator.beginFeature(self, interface, emit) 178 self.featureExtraProtect = GetFeatureProtect(interface) 179 180 if interface.tag != 'extension': 181 return 182 name = self.featureName 183 name_define = next(enum.get('name') for enum in interface.findall('require/enum') if enum.get('name').endswith('_EXTENSION_NAME')) 184 requires = interface.get('requires') 185 if requires is not None: 186 required_extensions = requires.split(',') 187 else: 188 required_extensions = list() 189 info = { 'define': name_define, 'ifdef':self.featureExtraProtect, 'reqs':required_extensions } 190 if interface.get('type') == 'instance': 191 self.instance_extension_info[name] = info 192 else: 193 self.device_extension_info[name] = info 194 195 # 196 # Override parent class to be notified of the end of an extension 197 def endFeature(self): 198 # Finish processing in superclass 199 OutputGenerator.endFeature(self) 200 # 201 # Grab group (e.g. C "enum" type) info to output for enum-string conversion helper 202 def genGroup(self, groupinfo, groupName, alias): 203 OutputGenerator.genGroup(self, groupinfo, groupName, alias) 204 groupElem = groupinfo.elem 205 # For enum_string_header 206 if self.helper_file_type == 'enum_string_header': 207 value_set = set() 208 for elem in groupElem.findall('enum'): 209 if elem.get('supported') != 'disabled' and elem.get('alias') is None: 210 value_set.add(elem.get('name')) 211 self.enum_output += self.GenerateEnumStringConversion(groupName, value_set) 212 elif self.helper_file_type == 'object_types_header': 213 if groupName == 'VkDebugReportObjectTypeEXT': 214 for elem in groupElem.findall('enum'): 215 if elem.get('supported') != 'disabled': 216 item_name = elem.get('name') 217 self.debug_report_object_types.append(item_name) 218 elif groupName == 'VkObjectType': 219 for elem in groupElem.findall('enum'): 220 if elem.get('supported') != 'disabled': 221 item_name = elem.get('name') 222 self.core_object_types.append(item_name) 223 224 # 225 # Called for each type -- if the type is a struct/union, grab the metadata 226 def genType(self, typeinfo, name, alias): 227 OutputGenerator.genType(self, typeinfo, name, alias) 228 typeElem = typeinfo.elem 229 # If the type is a struct type, traverse the imbedded <member> tags generating a structure. 230 # Otherwise, emit the tag text. 231 category = typeElem.get('category') 232 if category == 'handle': 233 if alias: 234 self.object_type_aliases.append((name,alias)) 235 else: 236 self.object_types.append(name) 237 elif (category == 'struct' or category == 'union'): 238 self.structNames.append(name) 239 self.genStruct(typeinfo, name, alias) 240 # 241 # Generate a VkStructureType based on a structure typename 242 def genVkStructureType(self, typename): 243 # Add underscore between lowercase then uppercase 244 value = re.sub('([a-z0-9])([A-Z])', r'\1_\2', typename) 245 # Change to uppercase 246 value = value.upper() 247 # Add STRUCTURE_TYPE_ 248 return re.sub('VK_', 'VK_STRUCTURE_TYPE_', value) 249 # 250 # Check if the parameter passed in is a pointer 251 def paramIsPointer(self, param): 252 ispointer = False 253 for elem in param: 254 if ((elem.tag != 'type') and (elem.tail is not None)) and '*' in elem.tail: 255 ispointer = True 256 return ispointer 257 # 258 # Check if the parameter passed in is a static array 259 def paramIsStaticArray(self, param): 260 isstaticarray = 0 261 paramname = param.find('name') 262 if (paramname.tail is not None) and ('[' in paramname.tail): 263 isstaticarray = paramname.tail.count('[') 264 return isstaticarray 265 # 266 # Retrieve the type and name for a parameter 267 def getTypeNameTuple(self, param): 268 type = '' 269 name = '' 270 for elem in param: 271 if elem.tag == 'type': 272 type = noneStr(elem.text) 273 elif elem.tag == 'name': 274 name = noneStr(elem.text) 275 return (type, name) 276 # 277 # Retrieve the value of the len tag 278 def getLen(self, param): 279 result = None 280 len = param.attrib.get('len') 281 if len and len != 'null-terminated': 282 # For string arrays, 'len' can look like 'count,null-terminated', indicating that we 283 # have a null terminated array of strings. We strip the null-terminated from the 284 # 'len' field and only return the parameter specifying the string count 285 if 'null-terminated' in len: 286 result = len.split(',')[0] 287 else: 288 result = len 289 if 'altlen' in param.attrib: 290 # Elements with latexmath 'len' also contain a C equivalent 'altlen' attribute 291 # Use indexing operator instead of get() so we fail if the attribute is missing 292 result = param.attrib['altlen'] 293 # Spec has now notation for len attributes, using :: instead of platform specific pointer symbol 294 result = str(result).replace('::', '->') 295 return result 296 # 297 # Check if a structure is or contains a dispatchable (dispatchable = True) or 298 # non-dispatchable (dispatchable = False) handle 299 def TypeContainsObjectHandle(self, handle_type, dispatchable): 300 if dispatchable: 301 type_key = 'VK_DEFINE_HANDLE' 302 else: 303 type_key = 'VK_DEFINE_NON_DISPATCHABLE_HANDLE' 304 handle = self.registry.tree.find("types/type/[name='" + handle_type + "'][@category='handle']") 305 if handle is not None and handle.find('type').text == type_key: 306 return True 307 # if handle_type is a struct, search its members 308 if handle_type in self.structNames: 309 member_index = next((i for i, v in enumerate(self.structMembers) if v[0] == handle_type), None) 310 if member_index is not None: 311 for item in self.structMembers[member_index].members: 312 handle = self.registry.tree.find("types/type/[name='" + item.type + "'][@category='handle']") 313 if handle is not None and handle.find('type').text == type_key: 314 return True 315 return False 316 # 317 # Generate local ready-access data describing Vulkan structures and unions from the XML metadata 318 def genStruct(self, typeinfo, typeName, alias): 319 OutputGenerator.genStruct(self, typeinfo, typeName, alias) 320 members = typeinfo.elem.findall('.//member') 321 # Iterate over members once to get length parameters for arrays 322 lens = set() 323 for member in members: 324 len = self.getLen(member) 325 if len: 326 lens.add(len) 327 # Generate member info 328 membersInfo = [] 329 for member in members: 330 # Get the member's type and name 331 info = self.getTypeNameTuple(member) 332 type = info[0] 333 name = info[1] 334 cdecl = self.makeCParamDecl(member, 1) 335 # Process VkStructureType 336 if type == 'VkStructureType': 337 # Extract the required struct type value from the comments 338 # embedded in the original text defining the 'typeinfo' element 339 rawXml = etree.tostring(typeinfo.elem).decode('ascii') 340 result = re.search(r'VK_STRUCTURE_TYPE_\w+', rawXml) 341 if result: 342 value = result.group(0) 343 else: 344 value = self.genVkStructureType(typeName) 345 # Store the required type value 346 self.structTypes[typeName] = self.StructType(name=name, value=value) 347 # Store pointer/array/string info 348 isstaticarray = self.paramIsStaticArray(member) 349 membersInfo.append(self.CommandParam(type=type, 350 name=name, 351 ispointer=self.paramIsPointer(member), 352 isstaticarray=isstaticarray, 353 isconst=True if 'const' in cdecl else False, 354 iscount=True if name in lens else False, 355 len=self.getLen(member), 356 extstructs=self.registry.validextensionstructs[typeName] if name == 'pNext' else None, 357 cdecl=cdecl)) 358 self.structMembers.append(self.StructMemberData(name=typeName, members=membersInfo, ifdef_protect=self.featureExtraProtect)) 359 # 360 # Enum_string_header: Create a routine to convert an enumerated value into a string 361 def GenerateEnumStringConversion(self, groupName, value_list): 362 outstring = '\n' 363 outstring += 'static inline const char* string_%s(%s input_value)\n' % (groupName, groupName) 364 outstring += '{\n' 365 outstring += ' switch ((%s)input_value)\n' % groupName 366 outstring += ' {\n' 367 for item in value_list: 368 outstring += ' case %s:\n' % item 369 outstring += ' return "%s";\n' % item 370 outstring += ' default:\n' 371 outstring += ' return "Unhandled %s";\n' % groupName 372 outstring += ' }\n' 373 outstring += '}\n' 374 return outstring 375 # 376 # Combine object types helper header file preamble with body text and return 377 def GenerateObjectTypesHelperHeader(self): 378 object_types_helper_header = '\n' 379 object_types_helper_header += '#pragma once\n' 380 object_types_helper_header += '\n' 381 object_types_helper_header += '#include <vulkan/vulkan.h>\n\n' 382 object_types_helper_header += self.GenerateObjectTypesHeader() 383 return object_types_helper_header 384 # 385 # Object types header: create object enum type header file 386 def GenerateObjectTypesHeader(self): 387 object_types_header = '' 388 object_types_header += '// Object Type enum for validation layer internal object handling\n' 389 object_types_header += 'typedef enum VulkanObjectType {\n' 390 object_types_header += ' kVulkanObjectTypeUnknown = 0,\n' 391 enum_num = 1 392 type_list = []; 393 enum_entry_map = {} 394 395 # Output enum definition as each handle is processed, saving the names to use for the conversion routine 396 for item in self.object_types: 397 fixup_name = item[2:] 398 enum_entry = 'kVulkanObjectType%s' % fixup_name 399 enum_entry_map[item] = enum_entry 400 object_types_header += ' ' + enum_entry 401 object_types_header += ' = %d,\n' % enum_num 402 enum_num += 1 403 type_list.append(enum_entry) 404 object_types_header += ' kVulkanObjectTypeMax = %d,\n' % enum_num 405 object_types_header += ' // Aliases for backwards compatibilty of "promoted" types\n' 406 for (name, alias) in self.object_type_aliases: 407 fixup_name = name[2:] 408 object_types_header += ' kVulkanObjectType{} = {},\n'.format(fixup_name, enum_entry_map[alias]) 409 object_types_header += '} VulkanObjectType;\n\n' 410 411 # Output name string helper 412 object_types_header += '// Array of object name strings for OBJECT_TYPE enum conversion\n' 413 object_types_header += 'static const char * const object_string[kVulkanObjectTypeMax] = {\n' 414 object_types_header += ' "Unknown",\n' 415 for item in self.object_types: 416 fixup_name = item[2:] 417 object_types_header += ' "%s",\n' % fixup_name 418 object_types_header += '};\n' 419 420 # Key creation helper for map comprehensions that convert between k<Name> and VK<Name> symbols 421 def to_key(regex, raw_key): return re.search(regex, raw_key).group(1).lower().replace("_","") 422 423 # Output a conversion routine from the layer object definitions to the debug report definitions 424 # As the VK_DEBUG_REPORT types are not being updated, specify UNKNOWN for unmatched types 425 object_types_header += '\n' 426 object_types_header += '// Helper array to get Vulkan VK_EXT_debug_report object type enum from the internal layers version\n' 427 object_types_header += 'const VkDebugReportObjectTypeEXT get_debug_report_enum[] = {\n' 428 object_types_header += ' VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT, // kVulkanObjectTypeUnknown\n' 429 430 dbg_re = '^VK_DEBUG_REPORT_OBJECT_TYPE_(.*?)(_EXT)?$' 431 dbg_map = {to_key(dbg_re, dbg) : dbg for dbg in self.debug_report_object_types} 432 dbg_default = 'VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT' 433 for object_type in type_list: 434 vk_object_type = dbg_map.get(object_type.replace("kVulkanObjectType", "").lower(), dbg_default) 435 object_types_header += ' %s, // %s\n' % (vk_object_type, object_type) 436 object_types_header += '};\n' 437 438 # Output a conversion routine from the layer object definitions to the core object type definitions 439 # This will intentionally *fail* for unmatched types as the VK_OBJECT_TYPE list should match the kVulkanObjectType list 440 object_types_header += '\n' 441 object_types_header += '// Helper array to get Official Vulkan VkObjectType enum from the internal layers version\n' 442 object_types_header += 'const VkObjectType get_object_type_enum[] = {\n' 443 object_types_header += ' VK_OBJECT_TYPE_UNKNOWN, // kVulkanObjectTypeUnknown\n' 444 445 vko_re = '^VK_OBJECT_TYPE_(.*)' 446 vko_map = {to_key(vko_re, vko) : vko for vko in self.core_object_types} 447 for object_type in type_list: 448 vk_object_type = vko_map[object_type.replace("kVulkanObjectType", "").lower()] 449 object_types_header += ' %s, // %s\n' % (vk_object_type, object_type) 450 object_types_header += '};\n' 451 452 # Create a function to convert from VkDebugReportObjectTypeEXT to VkObjectType 453 object_types_header += '\n' 454 object_types_header += '// Helper function to convert from VkDebugReportObjectTypeEXT to VkObjectType\n' 455 object_types_header += 'static inline VkObjectType convertDebugReportObjectToCoreObject(VkDebugReportObjectTypeEXT debug_report_obj){\n' 456 object_types_header += ' if (debug_report_obj == VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT) {\n' 457 object_types_header += ' return VK_OBJECT_TYPE_UNKNOWN;\n' 458 for core_object_type in self.core_object_types: 459 core_target_type = core_object_type.replace("VK_OBJECT_TYPE_", "").lower() 460 core_target_type = core_target_type.replace("_", "") 461 for dr_object_type in self.debug_report_object_types: 462 dr_target_type = dr_object_type.replace("VK_DEBUG_REPORT_OBJECT_TYPE_", "").lower() 463 dr_target_type = dr_target_type[:-4] 464 dr_target_type = dr_target_type.replace("_", "") 465 if core_target_type == dr_target_type: 466 object_types_header += ' } else if (debug_report_obj == %s) {\n' % dr_object_type 467 object_types_header += ' return %s;\n' % core_object_type 468 break 469 object_types_header += ' }\n' 470 object_types_header += ' return VK_OBJECT_TYPE_UNKNOWN;\n' 471 object_types_header += '}\n' 472 473 # Create a function to convert from VkObjectType to VkDebugReportObjectTypeEXT 474 object_types_header += '\n' 475 object_types_header += '// Helper function to convert from VkDebugReportObjectTypeEXT to VkObjectType\n' 476 object_types_header += 'static inline VkDebugReportObjectTypeEXT convertCoreObjectToDebugReportObject(VkObjectType core_report_obj){\n' 477 object_types_header += ' if (core_report_obj == VK_OBJECT_TYPE_UNKNOWN) {\n' 478 object_types_header += ' return VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT;\n' 479 for core_object_type in self.core_object_types: 480 core_target_type = core_object_type.replace("VK_OBJECT_TYPE_", "").lower() 481 core_target_type = core_target_type.replace("_", "") 482 for dr_object_type in self.debug_report_object_types: 483 dr_target_type = dr_object_type.replace("VK_DEBUG_REPORT_OBJECT_TYPE_", "").lower() 484 dr_target_type = dr_target_type[:-4] 485 dr_target_type = dr_target_type.replace("_", "") 486 if core_target_type == dr_target_type: 487 object_types_header += ' } else if (core_report_obj == %s) {\n' % core_object_type 488 object_types_header += ' return %s;\n' % dr_object_type 489 break 490 object_types_header += ' }\n' 491 object_types_header += ' return VK_DEBUG_REPORT_OBJECT_TYPE_UNKNOWN_EXT;\n' 492 object_types_header += '}\n' 493 return object_types_header 494 495 # 496 # Create a helper file and return it as a string 497 def OutputDestFile(self): 498 if self.helper_file_type == 'object_types_header': 499 return self.GenerateObjectTypesHelperHeader() 500 else: 501 return 'Bad Helper File Generator Option %s' % self.helper_file_type 502