1#!/usr/bin/python3 -i 2# 3# Copyright (c) 2013-2018 The Khronos Group Inc. 4# 5# Licensed under the Apache License, Version 2.0 (the "License"); 6# you may not use this file except in compliance with the License. 7# You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, software 12# distributed under the License is distributed on an "AS IS" BASIS, 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14# See the License for the specific language governing permissions and 15# limitations under the License. 16 17import io,os,re,string,sys,copy 18import xml.etree.ElementTree as etree 19from collections import defaultdict 20 21# matchAPIProfile - returns whether an API and profile 22# being generated matches an element's profile 23# api - string naming the API to match 24# profile - string naming the profile to match 25# elem - Element which (may) have 'api' and 'profile' 26# attributes to match to. 27# If a tag is not present in the Element, the corresponding API 28# or profile always matches. 29# Otherwise, the tag must exactly match the API or profile. 30# Thus, if 'profile' = core: 31# <remove> with no attribute will match 32# <remove profile='core'> will match 33# <remove profile='compatibility'> will not match 34# Possible match conditions: 35# Requested Element 36# Profile Profile 37# --------- -------- 38# None None Always matches 39# 'string' None Always matches 40# None 'string' Does not match. Can't generate multiple APIs 41# or profiles, so if an API/profile constraint 42# is present, it must be asked for explicitly. 43# 'string' 'string' Strings must match 44# 45# ** In the future, we will allow regexes for the attributes, 46# not just strings, so that api="^(gl|gles2)" will match. Even 47# this isn't really quite enough, we might prefer something 48# like "gl(core)|gles1(common-lite)". 49def matchAPIProfile(api, profile, elem): 50 """Match a requested API & profile name to a api & profile attributes of an Element""" 51 match = True 52 # Match 'api', if present 53 if ('api' in elem.attrib): 54 if (api == None): 55 raise UserWarning("No API requested, but 'api' attribute is present with value '" + 56 elem.get('api') + "'") 57 elif (api != elem.get('api')): 58 # Requested API doesn't match attribute 59 return False 60 if ('profile' in elem.attrib): 61 if (profile == None): 62 raise UserWarning("No profile requested, but 'profile' attribute is present with value '" + 63 elem.get('profile') + "'") 64 elif (profile != elem.get('profile')): 65 # Requested profile doesn't match attribute 66 return False 67 return True 68 69# BaseInfo - base class for information about a registry feature 70# (type/group/enum/command/API/extension). 71# required - should this feature be defined during header generation 72# (has it been removed by a profile or version)? 73# declared - has this feature been defined already? 74# elem - etree Element for this feature 75# resetState() - reset required/declared to initial values. Used 76# prior to generating a new API interface. 77class BaseInfo: 78 """Represents the state of a registry feature, used during API generation""" 79 def __init__(self, elem): 80 self.required = False 81 self.declared = False 82 self.elem = elem 83 def resetState(self): 84 self.required = False 85 self.declared = False 86 87# TypeInfo - registry information about a type. No additional state 88# beyond BaseInfo is required. 89class TypeInfo(BaseInfo): 90 """Represents the state of a registry type""" 91 def __init__(self, elem): 92 BaseInfo.__init__(self, elem) 93 self.additionalValidity = [] 94 self.removedValidity = [] 95 def resetState(self): 96 BaseInfo.resetState(self) 97 self.additionalValidity = [] 98 self.removedValidity = [] 99 100# GroupInfo - registry information about a group of related enums 101# in an <enums> block, generally corresponding to a C "enum" type. 102class GroupInfo(BaseInfo): 103 """Represents the state of a registry <enums> group""" 104 def __init__(self, elem): 105 BaseInfo.__init__(self, elem) 106 107# EnumInfo - registry information about an enum 108# type - numeric type of the value of the <enum> tag 109# ( '' for GLint, 'u' for GLuint, 'ull' for GLuint64 ) 110class EnumInfo(BaseInfo): 111 """Represents the state of a registry enum""" 112 def __init__(self, elem): 113 BaseInfo.__init__(self, elem) 114 self.type = elem.get('type') 115 if (self.type == None): 116 self.type = '' 117 118# CmdInfo - registry information about a command 119class CmdInfo(BaseInfo): 120 """Represents the state of a registry command""" 121 def __init__(self, elem): 122 BaseInfo.__init__(self, elem) 123 self.additionalValidity = [] 124 self.removedValidity = [] 125 def resetState(self): 126 BaseInfo.resetState(self) 127 self.additionalValidity = [] 128 self.removedValidity = [] 129 130# FeatureInfo - registry information about an API <feature> 131# or <extension> 132# name - feature name string (e.g. 'VK_KHR_surface') 133# version - feature version number (e.g. 1.2). <extension> 134# features are unversioned and assigned version number 0. 135# ** This is confusingly taken from the 'number' attribute of <feature>. 136# Needs fixing. 137# number - extension number, used for ordering and for 138# assigning enumerant offsets. <feature> features do 139# not have extension numbers and are assigned number 0. 140# category - category, e.g. VERSION or khr/vendor tag 141# emit - has this feature been defined already? 142class FeatureInfo(BaseInfo): 143 """Represents the state of an API feature (version/extension)""" 144 def __init__(self, elem): 145 BaseInfo.__init__(self, elem) 146 self.name = elem.get('name') 147 # Determine element category (vendor). Only works 148 # for <extension> elements. 149 if (elem.tag == 'feature'): 150 self.category = 'VERSION' 151 self.version = elem.get('number') 152 self.number = "0" 153 self.supported = None 154 else: 155 self.category = self.name.split('_', 2)[1] 156 self.version = "0" 157 self.number = elem.get('number') 158 self.supported = elem.get('supported') 159 self.emit = False 160 161from generator import write, GeneratorOptions, OutputGenerator 162 163# Registry - object representing an API registry, loaded from an XML file 164# Members 165# tree - ElementTree containing the root <registry> 166# typedict - dictionary of TypeInfo objects keyed by type name 167# groupdict - dictionary of GroupInfo objects keyed by group name 168# enumdict - dictionary of EnumInfo objects keyed by enum name 169# cmddict - dictionary of CmdInfo objects keyed by command name 170# apidict - dictionary of <api> Elements keyed by API name 171# extensions - list of <extension> Elements 172# extdict - dictionary of <extension> Elements keyed by extension name 173# gen - OutputGenerator object used to write headers / messages 174# genOpts - GeneratorOptions object used to control which 175# fetures to write and how to format them 176# emitFeatures - True to actually emit features for a version / extension, 177# or False to just treat them as emitted 178# Public methods 179# loadElementTree(etree) - load registry from specified ElementTree 180# loadFile(filename) - load registry from XML file 181# setGenerator(gen) - OutputGenerator to use 182# parseTree() - parse the registry once loaded & create dictionaries 183# dumpReg(maxlen, filehandle) - diagnostic to dump the dictionaries 184# to specified file handle (default stdout). Truncates type / 185# enum / command elements to maxlen characters (default 80) 186# generator(g) - specify the output generator object 187# apiGen(apiname, genOpts) - generate API headers for the API type 188# and profile specified in genOpts, but only for the versions and 189# extensions specified there. 190# apiReset() - call between calls to apiGen() to reset internal state 191# Private methods 192# addElementInfo(elem,info,infoName,dictionary) - add feature info to dict 193# lookupElementInfo(fname,dictionary) - lookup feature info in dict 194class Registry: 195 """Represents an API registry loaded from XML""" 196 def __init__(self): 197 self.tree = None 198 self.typedict = {} 199 self.groupdict = {} 200 self.enumdict = {} 201 self.cmddict = {} 202 self.apidict = {} 203 self.extensions = [] 204 self.requiredextensions = [] # Hack - can remove it after validity generator goes away 205 self.validextensionstructs = defaultdict(list) 206 self.extdict = {} 207 # A default output generator, so commands prior to apiGen can report 208 # errors via the generator object. 209 self.gen = OutputGenerator() 210 self.genOpts = None 211 self.emitFeatures = False 212 def loadElementTree(self, tree): 213 """Load ElementTree into a Registry object and parse it""" 214 self.tree = tree 215 self.parseTree() 216 def loadFile(self, file): 217 """Load an API registry XML file into a Registry object and parse it""" 218 self.tree = etree.parse(file) 219 self.parseTree() 220 def setGenerator(self, gen): 221 """Specify output generator object. None restores the default generator""" 222 self.gen = gen 223 self.gen.setRegistry(self) 224 225 # addElementInfo - add information about an element to the 226 # corresponding dictionary 227 # elem - <type>/<enums>/<enum>/<command>/<feature>/<extension> Element 228 # info - corresponding {Type|Group|Enum|Cmd|Feature}Info object 229 # infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension' 230 # dictionary - self.{type|group|enum|cmd|api|ext}dict 231 # If the Element has an 'api' attribute, the dictionary key is the 232 # tuple (name,api). If not, the key is the name. 'name' is an 233 # attribute of the Element 234 def addElementInfo(self, elem, info, infoName, dictionary): 235 if ('api' in elem.attrib): 236 key = (elem.get('name'),elem.get('api')) 237 else: 238 key = elem.get('name') 239 if key in dictionary: 240 self.gen.logMsg('warn', '*** Attempt to redefine', 241 infoName, 'with key:', key) 242 else: 243 dictionary[key] = info 244 # 245 # lookupElementInfo - find a {Type|Enum|Cmd}Info object by name. 246 # If an object qualified by API name exists, use that. 247 # fname - name of type / enum / command 248 # dictionary - self.{type|enum|cmd}dict 249 def lookupElementInfo(self, fname, dictionary): 250 key = (fname, self.genOpts.apiname) 251 if (key in dictionary): 252 # self.gen.logMsg('diag', 'Found API-specific element for feature', fname) 253 return dictionary[key] 254 elif (fname in dictionary): 255 # self.gen.logMsg('diag', 'Found generic element for feature', fname) 256 return dictionary[fname] 257 else: 258 return None 259 def parseTree(self): 260 """Parse the registry Element, once created""" 261 # This must be the Element for the root <registry> 262 self.reg = self.tree.getroot() 263 # 264 # Create dictionary of registry types from toplevel <types> tags 265 # and add 'name' attribute to each <type> tag (where missing) 266 # based on its <name> element. 267 # 268 # There's usually one <types> block; more are OK 269 # Required <type> attributes: 'name' or nested <name> tag contents 270 self.typedict = {} 271 for type in self.reg.findall('types/type'): 272 # If the <type> doesn't already have a 'name' attribute, set 273 # it from contents of its <name> tag. 274 if (type.get('name') == None): 275 type.attrib['name'] = type.find('name').text 276 self.addElementInfo(type, TypeInfo(type), 'type', self.typedict) 277 # 278 # Create dictionary of registry enum groups from <enums> tags. 279 # 280 # Required <enums> attributes: 'name'. If no name is given, one is 281 # generated, but that group can't be identified and turned into an 282 # enum type definition - it's just a container for <enum> tags. 283 self.groupdict = {} 284 for group in self.reg.findall('enums'): 285 self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict) 286 # 287 # Create dictionary of registry enums from <enum> tags 288 # 289 # <enums> tags usually define different namespaces for the values 290 # defined in those tags, but the actual names all share the 291 # same dictionary. 292 # Required <enum> attributes: 'name', 'value' 293 # For containing <enums> which have type="enum" or type="bitmask", 294 # tag all contained <enum>s are required. This is a stopgap until 295 # a better scheme for tagging core and extension enums is created. 296 self.enumdict = {} 297 for enums in self.reg.findall('enums'): 298 required = (enums.get('type') != None) 299 for enum in enums.findall('enum'): 300 enumInfo = EnumInfo(enum) 301 enumInfo.required = required 302 self.addElementInfo(enum, enumInfo, 'enum', self.enumdict) 303 # 304 # Create dictionary of registry commands from <command> tags 305 # and add 'name' attribute to each <command> tag (where missing) 306 # based on its <proto><name> element. 307 # 308 # There's usually only one <commands> block; more are OK. 309 # Required <command> attributes: 'name' or <proto><name> tag contents 310 self.cmddict = {} 311 for cmd in self.reg.findall('commands/command'): 312 # If the <command> doesn't already have a 'name' attribute, set 313 # it from contents of its <proto><name> tag. 314 if (cmd.get('name') == None): 315 cmd.attrib['name'] = cmd.find('proto/name').text 316 ci = CmdInfo(cmd) 317 self.addElementInfo(cmd, ci, 'command', self.cmddict) 318 # 319 # Create dictionaries of API and extension interfaces 320 # from toplevel <api> and <extension> tags. 321 # 322 self.apidict = {} 323 for feature in self.reg.findall('feature'): 324 featureInfo = FeatureInfo(feature) 325 self.addElementInfo(feature, featureInfo, 'feature', self.apidict) 326 self.extensions = self.reg.findall('extensions/extension') 327 self.extdict = {} 328 for feature in self.extensions: 329 featureInfo = FeatureInfo(feature) 330 self.addElementInfo(feature, featureInfo, 'extension', self.extdict) 331 332 # Add additional enums defined only in <extension> tags 333 # to the corresponding core type. 334 # When seen here, the <enum> element, processed to contain the 335 # numeric enum value, is added to the corresponding <enums> 336 # element, as well as adding to the enum dictionary. It is 337 # *removed* from the <require> element it is introduced in. 338 # Not doing this will cause spurious genEnum() 339 # calls to be made in output generation, and it's easier 340 # to handle here than in genEnum(). 341 # 342 # In lxml.etree, an Element can have only one parent, so the 343 # append() operation also removes the element. But in Python's 344 # ElementTree package, an Element can have multiple parents. So 345 # it must be explicitly removed from the <require> tag, leading 346 # to the nested loop traversal of <require>/<enum> elements 347 # below. 348 # 349 # This code also adds a 'extnumber' attribute containing the 350 # extension number, used for enumerant value calculation. 351 # 352 # For <enum> tags which are actually just constants, if there's 353 # no 'extends' tag but there is a 'value' or 'bitpos' tag, just 354 # add an EnumInfo record to the dictionary. That works because 355 # output generation of constants is purely dependency-based, and 356 # doesn't need to iterate through the XML tags. 357 # 358 # Something like this will need to be done for 'feature's up 359 # above, if we use the same mechanism for adding to the core 360 # API in 1.1. 361 # 362 for elem in feature.findall('require'): 363 for enum in elem.findall('enum'): 364 addEnumInfo = False 365 groupName = enum.get('extends') 366 if (groupName != None): 367 # self.gen.logMsg('diag', '*** Found extension enum', 368 # enum.get('name')) 369 # Add extension number attribute to the <enum> element 370 enum.attrib['extnumber'] = featureInfo.number 371 enum.attrib['extname'] = featureInfo.name 372 enum.attrib['supported'] = featureInfo.supported 373 # Look up the GroupInfo with matching groupName 374 if (groupName in self.groupdict.keys()): 375 # self.gen.logMsg('diag', '*** Matching group', 376 # groupName, 'found, adding element...') 377 gi = self.groupdict[groupName] 378 gi.elem.append(enum) 379 # Remove element from parent <require> tag 380 # This should be a no-op in lxml.etree 381 elem.remove(enum) 382 else: 383 self.gen.logMsg('warn', '*** NO matching group', 384 groupName, 'for enum', enum.get('name'), 'found.') 385 addEnumInfo = True 386 elif (enum.get('value') or enum.get('bitpos')): 387 # self.gen.logMsg('diag', '*** Adding extension constant "enum"', 388 # enum.get('name')) 389 addEnumInfo = True 390 if (addEnumInfo): 391 enumInfo = EnumInfo(enum) 392 self.addElementInfo(enum, enumInfo, 'enum', self.enumdict) 393 # Construct a "validextensionstructs" list for parent structures 394 # based on "structextends" tags in child structures 395 for type in self.reg.findall('types/type'): 396 parentStructs = type.get('structextends') 397 if (parentStructs != None): 398 for parent in parentStructs.split(','): 399 # self.gen.logMsg('diag', type.get('name'), 'extends', parent) 400 self.validextensionstructs[parent].append(type.get('name')) 401 # Sort the lists so they don't depend on the XML order 402 for parent in self.validextensionstructs: 403 self.validextensionstructs[parent].sort() 404 405 def dumpReg(self, maxlen = 40, filehandle = sys.stdout): 406 """Dump all the dictionaries constructed from the Registry object""" 407 write('***************************************', file=filehandle) 408 write(' ** Dumping Registry contents **', file=filehandle) 409 write('***************************************', file=filehandle) 410 write('// Types', file=filehandle) 411 for name in self.typedict: 412 tobj = self.typedict[name] 413 write(' Type', name, '->', etree.tostring(tobj.elem)[0:maxlen], file=filehandle) 414 write('// Groups', file=filehandle) 415 for name in self.groupdict: 416 gobj = self.groupdict[name] 417 write(' Group', name, '->', etree.tostring(gobj.elem)[0:maxlen], file=filehandle) 418 write('// Enums', file=filehandle) 419 for name in self.enumdict: 420 eobj = self.enumdict[name] 421 write(' Enum', name, '->', etree.tostring(eobj.elem)[0:maxlen], file=filehandle) 422 write('// Commands', file=filehandle) 423 for name in self.cmddict: 424 cobj = self.cmddict[name] 425 write(' Command', name, '->', etree.tostring(cobj.elem)[0:maxlen], file=filehandle) 426 write('// APIs', file=filehandle) 427 for key in self.apidict: 428 write(' API Version ', key, '->', 429 etree.tostring(self.apidict[key].elem)[0:maxlen], file=filehandle) 430 write('// Extensions', file=filehandle) 431 for key in self.extdict: 432 write(' Extension', key, '->', 433 etree.tostring(self.extdict[key].elem)[0:maxlen], file=filehandle) 434 # write('***************************************', file=filehandle) 435 # write(' ** Dumping XML ElementTree **', file=filehandle) 436 # write('***************************************', file=filehandle) 437 # write(etree.tostring(self.tree.getroot(),pretty_print=True), file=filehandle) 438 # 439 # typename - name of type 440 # required - boolean (to tag features as required or not) 441 def markTypeRequired(self, typename, required): 442 """Require (along with its dependencies) or remove (but not its dependencies) a type""" 443 self.gen.logMsg('diag', '*** tagging type:', typename, '-> required =', required) 444 # Get TypeInfo object for <type> tag corresponding to typename 445 type = self.lookupElementInfo(typename, self.typedict) 446 if (type != None): 447 if (required): 448 # Tag type dependencies in 'required' attributes as 449 # required. This DOES NOT un-tag dependencies in a <remove> 450 # tag. See comments in markRequired() below for the reason. 451 if ('requires' in type.elem.attrib): 452 depType = type.elem.get('requires') 453 self.gen.logMsg('diag', '*** Generating dependent type', 454 depType, 'for type', typename) 455 self.markTypeRequired(depType, required) 456 # Tag types used in defining this type (e.g. in nested 457 # <type> tags) 458 # Look for <type> in entire <command> tree, 459 # not just immediate children 460 for subtype in type.elem.findall('.//type'): 461 self.gen.logMsg('diag', '*** markRequired: type requires dependent <type>', subtype.text) 462 self.markTypeRequired(subtype.text, required) 463 # Tag enums used in defining this type, for example in 464 # <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member> 465 for subenum in type.elem.findall('.//enum'): 466 self.gen.logMsg('diag', '*** markRequired: type requires dependent <enum>', subenum.text) 467 self.markEnumRequired(subenum.text, required) 468 type.required = required 469 else: 470 self.gen.logMsg('warn', '*** type:', typename , 'IS NOT DEFINED') 471 # 472 # enumname - name of enum 473 # required - boolean (to tag features as required or not) 474 def markEnumRequired(self, enumname, required): 475 self.gen.logMsg('diag', '*** tagging enum:', enumname, '-> required =', required) 476 enum = self.lookupElementInfo(enumname, self.enumdict) 477 if (enum != None): 478 enum.required = required 479 else: 480 self.gen.logMsg('warn', '*** enum:', enumname , 'IS NOT DEFINED') 481 # 482 # features - Element for <require> or <remove> tag 483 # required - boolean (to tag features as required or not) 484 def markRequired(self, features, required): 485 """Require or remove features specified in the Element""" 486 self.gen.logMsg('diag', '*** markRequired (features = <too long to print>, required =', required, ')') 487 # Loop over types, enums, and commands in the tag 488 # @@ It would be possible to respect 'api' and 'profile' attributes 489 # in individual features, but that's not done yet. 490 for typeElem in features.findall('type'): 491 self.markTypeRequired(typeElem.get('name'), required) 492 for enumElem in features.findall('enum'): 493 self.markEnumRequired(enumElem.get('name'), required) 494 for cmdElem in features.findall('command'): 495 name = cmdElem.get('name') 496 self.gen.logMsg('diag', '*** tagging command:', name, '-> required =', required) 497 cmd = self.lookupElementInfo(name, self.cmddict) 498 if (cmd != None): 499 cmd.required = required 500 # Tag all parameter types of this command as required. 501 # This DOES NOT remove types of commands in a <remove> 502 # tag, because many other commands may use the same type. 503 # We could be more clever and reference count types, 504 # instead of using a boolean. 505 if (required): 506 # Look for <type> in entire <command> tree, 507 # not just immediate children 508 for type in cmd.elem.findall('.//type'): 509 self.gen.logMsg('diag', '*** markRequired: command implicitly requires dependent type', type.text) 510 self.markTypeRequired(type.text, required) 511 else: 512 self.gen.logMsg('warn', '*** command:', name, 'IS NOT DEFINED') 513 # 514 # interface - Element for <version> or <extension>, containing 515 # <require> and <remove> tags 516 # api - string specifying API name being generated 517 # profile - string specifying API profile being generated 518 def requireAndRemoveFeatures(self, interface, api, profile): 519 """Process <recquire> and <remove> tags for a <version> or <extension>""" 520 # <require> marks things that are required by this version/profile 521 for feature in interface.findall('require'): 522 if (matchAPIProfile(api, profile, feature)): 523 self.markRequired(feature,True) 524 # <remove> marks things that are removed by this version/profile 525 for feature in interface.findall('remove'): 526 if (matchAPIProfile(api, profile, feature)): 527 self.markRequired(feature,False) 528 529 def assignAdditionalValidity(self, interface, api, profile): 530 # 531 # Loop over all usage inside all <require> tags. 532 for feature in interface.findall('require'): 533 if (matchAPIProfile(api, profile, feature)): 534 for v in feature.findall('usage'): 535 if v.get('command'): 536 self.cmddict[v.get('command')].additionalValidity.append(copy.deepcopy(v)) 537 if v.get('struct'): 538 self.typedict[v.get('struct')].additionalValidity.append(copy.deepcopy(v)) 539 540 # 541 # Loop over all usage inside all <remove> tags. 542 for feature in interface.findall('remove'): 543 if (matchAPIProfile(api, profile, feature)): 544 for v in feature.findall('usage'): 545 if v.get('command'): 546 self.cmddict[v.get('command')].removedValidity.append(copy.deepcopy(v)) 547 if v.get('struct'): 548 self.typedict[v.get('struct')].removedValidity.append(copy.deepcopy(v)) 549 550 # 551 # generateFeature - generate a single type / enum group / enum / command, 552 # and all its dependencies as needed. 553 # fname - name of feature (<type>/<enum>/<command>) 554 # ftype - type of feature, 'type' | 'enum' | 'command' 555 # dictionary - of *Info objects - self.{type|enum|cmd}dict 556 def generateFeature(self, fname, ftype, dictionary): 557 f = self.lookupElementInfo(fname, dictionary) 558 if (f == None): 559 # No such feature. This is an error, but reported earlier 560 self.gen.logMsg('diag', '*** No entry found for feature', fname, 561 'returning!') 562 return 563 # 564 # If feature isn't required, or has already been declared, return 565 if (not f.required): 566 self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(not required)') 567 return 568 if (f.declared): 569 self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(already declared)') 570 return 571 # Always mark feature declared, as though actually emitted 572 f.declared = True 573 # 574 # Pull in dependent declaration(s) of the feature. 575 # For types, there may be one type in the 'required' attribute of 576 # the element, as well as many in imbedded <type> and <enum> tags 577 # within the element. 578 # For commands, there may be many in <type> tags within the element. 579 # For enums, no dependencies are allowed (though perhaps if you 580 # have a uint64 enum, it should require that type). 581 genProc = None 582 if (ftype == 'type'): 583 genProc = self.gen.genType 584 if ('requires' in f.elem.attrib): 585 depname = f.elem.get('requires') 586 self.gen.logMsg('diag', '*** Generating required dependent type', 587 depname) 588 self.generateFeature(depname, 'type', self.typedict) 589 for subtype in f.elem.findall('.//type'): 590 self.gen.logMsg('diag', '*** Generating required dependent <type>', 591 subtype.text) 592 self.generateFeature(subtype.text, 'type', self.typedict) 593 for subtype in f.elem.findall('.//enum'): 594 self.gen.logMsg('diag', '*** Generating required dependent <enum>', 595 subtype.text) 596 self.generateFeature(subtype.text, 'enum', self.enumdict) 597 # If the type is an enum group, look up the corresponding 598 # group in the group dictionary and generate that instead. 599 if (f.elem.get('category') == 'enum'): 600 self.gen.logMsg('diag', '*** Type', fname, 'is an enum group, so generate that instead') 601 group = self.lookupElementInfo(fname, self.groupdict) 602 if (group == None): 603 # Unless this is tested for, it's probably fatal to call below 604 genProc = None 605 self.logMsg('warn', '*** NO MATCHING ENUM GROUP FOUND!!!') 606 else: 607 genProc = self.gen.genGroup 608 f = group 609 elif (ftype == 'command'): 610 genProc = self.gen.genCmd 611 for type in f.elem.findall('.//type'): 612 depname = type.text 613 self.gen.logMsg('diag', '*** Generating required parameter type', 614 depname) 615 self.generateFeature(depname, 'type', self.typedict) 616 elif (ftype == 'enum'): 617 genProc = self.gen.genEnum 618 # Actually generate the type only if emitting declarations 619 if self.emitFeatures: 620 self.gen.logMsg('diag', '*** Emitting', ftype, 'decl for', fname) 621 genProc(f, fname) 622 else: 623 self.gen.logMsg('diag', '*** Skipping', ftype, fname, 624 '(not emitting this feature)') 625 # 626 # generateRequiredInterface - generate all interfaces required 627 # by an API version or extension 628 # interface - Element for <version> or <extension> 629 def generateRequiredInterface(self, interface): 630 """Generate required C interface for specified API version/extension""" 631 632 # 633 # Loop over all features inside all <require> tags. 634 for features in interface.findall('require'): 635 for t in features.findall('type'): 636 self.generateFeature(t.get('name'), 'type', self.typedict) 637 for e in features.findall('enum'): 638 self.generateFeature(e.get('name'), 'enum', self.enumdict) 639 for c in features.findall('command'): 640 self.generateFeature(c.get('name'), 'command', self.cmddict) 641 642 # 643 # apiGen(genOpts) - generate interface for specified versions 644 # genOpts - GeneratorOptions object with parameters used 645 # by the Generator object. 646 def apiGen(self, genOpts): 647 """Generate interfaces for the specified API type and range of versions""" 648 # 649 self.gen.logMsg('diag', '*******************************************') 650 self.gen.logMsg('diag', ' Registry.apiGen file:', genOpts.filename, 651 'api:', genOpts.apiname, 652 'profile:', genOpts.profile) 653 self.gen.logMsg('diag', '*******************************************') 654 # 655 self.genOpts = genOpts 656 # Reset required/declared flags for all features 657 self.apiReset() 658 # 659 # Compile regexps used to select versions & extensions 660 regVersions = re.compile(self.genOpts.versions) 661 regEmitVersions = re.compile(self.genOpts.emitversions) 662 regAddExtensions = re.compile(self.genOpts.addExtensions) 663 regRemoveExtensions = re.compile(self.genOpts.removeExtensions) 664 # 665 # Get all matching API versions & add to list of FeatureInfo 666 features = [] 667 apiMatch = False 668 for key in self.apidict: 669 fi = self.apidict[key] 670 api = fi.elem.get('api') 671 if (api == self.genOpts.apiname): 672 apiMatch = True 673 if (regVersions.match(fi.version)): 674 # Matches API & version #s being generated. Mark for 675 # emission and add to the features[] list . 676 # @@ Could use 'declared' instead of 'emit'? 677 fi.emit = (regEmitVersions.match(fi.version) != None) 678 features.append(fi) 679 if (not fi.emit): 680 self.gen.logMsg('diag', '*** NOT tagging feature api =', api, 681 'name =', fi.name, 'version =', fi.version, 682 'for emission (does not match emitversions pattern)') 683 else: 684 self.gen.logMsg('diag', '*** NOT including feature api =', api, 685 'name =', fi.name, 'version =', fi.version, 686 '(does not match requested versions)') 687 else: 688 self.gen.logMsg('diag', '*** NOT including feature api =', api, 689 'name =', fi.name, 690 '(does not match requested API)') 691 if (not apiMatch): 692 self.gen.logMsg('warn', '*** No matching API versions found!') 693 # 694 # Get all matching extensions, in order by their extension number, 695 # and add to the list of features. 696 # Start with extensions tagged with 'api' pattern matching the API 697 # being generated. Add extensions matching the pattern specified in 698 # regExtensions, then remove extensions matching the pattern 699 # specified in regRemoveExtensions 700 for (extName,ei) in sorted(self.extdict.items(),key = lambda x : x[1].number): 701 extName = ei.name 702 include = False 703 # 704 # Include extension if defaultExtensions is not None and if the 705 # 'supported' attribute matches defaultExtensions. The regexp in 706 # 'supported' must exactly match defaultExtensions, so bracket 707 # it with ^(pat)$. 708 pat = '^(' + ei.elem.get('supported') + ')$' 709 if (self.genOpts.defaultExtensions and 710 re.match(pat, self.genOpts.defaultExtensions)): 711 self.gen.logMsg('diag', '*** Including extension', 712 extName, "(defaultExtensions matches the 'supported' attribute)") 713 include = True 714 # 715 # Include additional extensions if the extension name matches 716 # the regexp specified in the generator options. This allows 717 # forcing extensions into an interface even if they're not 718 # tagged appropriately in the registry. 719 if (regAddExtensions.match(extName) != None): 720 self.gen.logMsg('diag', '*** Including extension', 721 extName, '(matches explicitly requested extensions to add)') 722 include = True 723 # Remove extensions if the name matches the regexp specified 724 # in generator options. This allows forcing removal of 725 # extensions from an interface even if they're tagged that 726 # way in the registry. 727 if (regRemoveExtensions.match(extName) != None): 728 self.gen.logMsg('diag', '*** Removing extension', 729 extName, '(matches explicitly requested extensions to remove)') 730 include = False 731 # 732 # If the extension is to be included, add it to the 733 # extension features list. 734 if (include): 735 ei.emit = True 736 features.append(ei) 737 738 # Hack - can be removed when validity generator goes away 739 self.requiredextensions.append(extName) 740 else: 741 self.gen.logMsg('diag', '*** NOT including extension', 742 extName, '(does not match api attribute or explicitly requested extensions)') 743 # 744 # Sort the extension features list, if a sort procedure is defined 745 if (self.genOpts.sortProcedure): 746 self.genOpts.sortProcedure(features) 747 # 748 # Pass 1: loop over requested API versions and extensions tagging 749 # types/commands/features as required (in an <require> block) or no 750 # longer required (in an <remove> block). It is possible to remove 751 # a feature in one version and restore it later by requiring it in 752 # a later version. 753 # If a profile other than 'None' is being generated, it must 754 # match the profile attribute (if any) of the <require> and 755 # <remove> tags. 756 self.gen.logMsg('diag', '*** PASS 1: TAG FEATURES ********************************************') 757 for f in features: 758 self.gen.logMsg('diag', '*** PASS 1: Tagging required and removed features for', 759 f.name) 760 self.requireAndRemoveFeatures(f.elem, self.genOpts.apiname, self.genOpts.profile) 761 self.assignAdditionalValidity(f.elem, self.genOpts.apiname, self.genOpts.profile) 762 # 763 # Pass 2: loop over specified API versions and extensions printing 764 # declarations for required things which haven't already been 765 # generated. 766 self.gen.logMsg('diag', '*** PASS 2: GENERATE INTERFACES FOR FEATURES ************************') 767 self.gen.beginFile(self.genOpts) 768 for f in features: 769 self.gen.logMsg('diag', '*** PASS 2: Generating interface for', 770 f.name) 771 emit = self.emitFeatures = f.emit 772 if (not emit): 773 self.gen.logMsg('diag', '*** PASS 2: NOT declaring feature', 774 f.elem.get('name'), 'because it is not tagged for emission') 775 # Generate the interface (or just tag its elements as having been 776 # emitted, if they haven't been). 777 self.gen.beginFeature(f.elem, emit) 778 self.generateRequiredInterface(f.elem) 779 self.gen.endFeature() 780 self.gen.endFile() 781 # 782 # apiReset - use between apiGen() calls to reset internal state 783 # 784 def apiReset(self): 785 """Reset type/enum/command dictionaries before generating another API""" 786 for type in self.typedict: 787 self.typedict[type].resetState() 788 for enum in self.enumdict: 789 self.enumdict[enum].resetState() 790 for cmd in self.cmddict: 791 self.cmddict[cmd].resetState() 792 for cmd in self.apidict: 793 self.apidict[cmd].resetState() 794 # 795 # validateGroups - check that group= attributes match actual groups 796 # 797 def validateGroups(self): 798 """Validate group= attributes on <param> and <proto> tags""" 799 # Keep track of group names not in <group> tags 800 badGroup = {} 801 self.gen.logMsg('diag', '*** VALIDATING GROUP ATTRIBUTES ***') 802 for cmd in self.reg.findall('commands/command'): 803 proto = cmd.find('proto') 804 funcname = cmd.find('proto/name').text 805 if ('group' in proto.attrib.keys()): 806 group = proto.get('group') 807 # self.gen.logMsg('diag', '*** Command ', funcname, ' has return group ', group) 808 if (group not in self.groupdict.keys()): 809 # self.gen.logMsg('diag', '*** Command ', funcname, ' has UNKNOWN return group ', group) 810 if (group not in badGroup.keys()): 811 badGroup[group] = 1 812 else: 813 badGroup[group] = badGroup[group] + 1 814 for param in cmd.findall('param'): 815 pname = param.find('name') 816 if (pname != None): 817 pname = pname.text 818 else: 819 pname = type.get('name') 820 if ('group' in param.attrib.keys()): 821 group = param.get('group') 822 if (group not in self.groupdict.keys()): 823 # self.gen.logMsg('diag', '*** Command ', funcname, ' param ', pname, ' has UNKNOWN group ', group) 824 if (group not in badGroup.keys()): 825 badGroup[group] = 1 826 else: 827 badGroup[group] = badGroup[group] + 1 828 if (len(badGroup.keys()) > 0): 829 self.gen.logMsg('diag', '*** SUMMARY OF UNRECOGNIZED GROUPS ***') 830 for key in sorted(badGroup.keys()): 831 self.gen.logMsg('diag', ' ', key, ' occurred ', badGroup[key], ' times') 832