1# Copyright 2013-2023 The Khronos Group Inc. 2# 3# SPDX-License-Identifier: Apache-2.0 4 5# Relax NG schema for Khronos Vulkan API Registry XML 6# 7# See https://www.khronos.org/vulkan/ 8# 9# This definition is subject to change (mostly in the form of additions) 10 11namespace xsd = "http://www.w3.org/2001/XMLSchema-datatypes" 12 13# Toplevel is a <registry> tag. 14# May be led by an optional <comment> tag containing e.g. copyrights. 15start = element registry { 16 ( 17 element comment { text } ? | 18 Platforms * | 19 Tags * | 20 Types * | 21 Enums * | 22 Commands * | 23 Feature * | 24 Extensions * | 25 Formats * | 26 Sync * | 27 SpirvExtensions * | 28 SpirvCapabilities * 29 ) * 30} 31 32# <platforms> defines a group of platform names 33Platforms = element platforms { 34 Comment ? , 35 Platform * 36} 37 38# <platform> defines a single platform name. 39# name - string name of the platform, used as part of extension names 40# protect - preprocessor symbol to include platform headers from <vulkan.h> 41# comment - platform description 42Platform = element platform { 43 attribute name { text } , 44 attribute protect { text } , 45 Comment 46} 47 48# <tags> defines a group of author tags 49Tags = element tags { 50 Comment ? , 51 Tag * 52} 53 54# <tag> defines a single author tag. 55# name - name of the tag 56# author - name of the author (usually a company or project name) 57# contact - contact responsible for the tag (name and contact information) 58Tag = element tag { 59 attribute name { text } , 60 attribute author { text } , 61 attribute contact { text } 62} 63 64# <types> defines a group of types 65Types = element types { 66 Comment ? , 67 ( 68 Type | 69 element comment { text } 70 ) * 71} 72 73# <type> defines a single type. It is usually a C typedef but 74# may contain arbitrary C code. 75# name - name of this type, if not present in the <name> tag 76# api - matches a <feature> api attribute, if present 77# alias - name of a type this type aliases 78# requires - name of another type definition required by this one 79# bitvalues - for a *Flags type, name of an enum definition that 80# defines the valid values for parameters of that type 81# name - name of the type being defined 82# category - if present, 'enum' indicates a matching <enums> 83# block to generate an enumerated type for, and 'struct' 84# causes special interpretation of the contents of the type 85# tag including ... TBD ... 86# Other allowed values are 'include', 'define', 'handle' and 'bitmask', 87# which do not change syntactic interpretation but allow organization 88# in the generated header. 89# deprecated - denotes that this type is deprecated, and why. 90# Valid values: 'aliased', 'true'. 91# parent - only applicable if category is 'handle'. Notes another type with 92# the 'handle' category that acts as a parent object for this type. 93# returnedonly - only applicable if category is 'struct'. Notes that this 94# struct is going to be filled in by the API, rather than an application 95# filling it out and passing it to the API. 96# structextends - only applicable if category is 'struct'. Lists parent 97# structures which this structure may extend via the pNext chain 98# of the parent. 99# When present it suppresses generation of automatic validity for the 100# pNext member of that structure, and instead the structure is added 101# to pNext chain validity for the parent structures it extends. 102# allowduplicate - only applicable if category is 'struct'. pNext can include 103# multiple structures of this type. 104# objtypeenum - name of VK_OBJECT_TYPE_* API enumerant which corresponds 105# to this type. Currently only specified for category="handle" types. 106# comment - descriptive text with no semantic meaning 107# For types without a category, contents include 108# <apientry /> - substitutes for an APIENTRY-style macro on output 109# <name> - contains name of the type being defined 110# <type> - contains name of types used to define this type. There 111# may be multiple imbedded <type> tags 112# For types with category 'enum', contents should be empty 113# For types with category 'struct', contents should be one or more 114# <member> - like <param> for a struct or union member 115# len - if the member is an array, len may be one or more of the following 116# things, separated by commas (one for each array indirection): 117# another member of that struct, 'null-terminated' for a string, 118# '1' to indicate it is just a pointer (used for nested pointers), 119# or a latex equation (prefixed with 'latexmath:') 120# altlen - if len has latexmath equations, this contains equivalent C99 121# expressions separated by commas. 122# deprecated - denotes that this member is deprecated, and why. 123# Valid values: 'ignored', 'true'. 124# externsync - denotes that the member should be externally synchronized 125# when accessed by Vulkan 126# optional - whether this value can be omitted by providing NULL (for 127# pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values) 128# selector - for a union member, identifies a separate enum member that 129# selects which of the union's members are valid 130# selection - for a member of a union, identifies an enum value indicating the member is valid 131# noautovalidity - tag stating that no automatic validity language should be generated 132# values - comma-separated list of legal values, usually used only for sType enums 133# limittype - only applicable for members of VkPhysicalDeviceProperties and 134# VkPhysicalDeviceProperties2, their substructures, and extensions. 135# Specifies the type of a device limit. 136# Valid values: 'min', 'max', 'pot', 'mul', 'bits', bitmask', 'range', 'struct', 'exact', 'noauto' 137# objecttype - only applicable for members representing a handle as 138# a uint64_t value. Specifies the name of another member which is 139# a VkObjectType or VkDebugReportObjectTypeEXT value specifying 140# the type of object the handle references. 141# <comment> - containing arbitrary text (unused) 142# 143# *** There is a problem here: I am not sure how to represent the <type> 144# syntax where it may contain arbitrarily interleaved text, <type>, and 145# <enum> child tags. This allows only the syntax 146# text <type>name</type> text <enum>name</enum> text 147# where <type> and <enum> are both optional and occur in the specified 148# order, which might eventually be a problem. 149Type = element type { 150 attribute api { text } ? , 151 attribute alias { text } ? , 152 attribute requires { text } ? , 153 attribute bitvalues { text } ? , 154 attribute name { TypeName } ? , 155 attribute category { text } ? , 156 attribute deprecated { text } ? , 157 attribute parent { TypeName } ? , 158 attribute returnedonly { text } ? , 159 attribute structextends { text } ? , 160 attribute allowduplicate { text } ? , 161 attribute objtypeenum { text } ? , 162 Comment ? , 163 ( 164 ( 165 ( text , 166 element type { text } * 167 ) * , 168 element apientry { text } ? , 169 ( text , 170 element type { text } * 171 ) * , 172 element name { TypeName } ? , 173 ( text , 174 element type { text } * 175 ) * 176 ) | 177 ( 178 element member { 179 attribute api { text } ? , 180 attribute len { text } ? , 181 attribute altlen { text } ? , 182 attribute externsync { text } ? , 183 attribute optional { text } ? , 184 attribute selector { text } ? , 185 attribute selection { EnumName } ? , 186 attribute noautovalidity { text } ? , 187 attribute values { text } ? , 188 attribute limittype { text } ? , 189 attribute objecttype { text } ? , 190 attribute deprecated { text } ? , 191 mixed { 192 element type { TypeName } ? , 193 element name { text } ? , 194 element enum { EnumName } ? , 195 element comment { text } ? 196 } + 197 } | 198 element comment { text } 199 ) * 200 ) 201} 202 203# <enums> defines a group of enumerants 204# name - identifies a type name associated with this group. Should 205# match a <type> name to trigger generation of the type. 206# type - 'enum' or 'bitmask', if present 207# bitwidth - bit width of the enum value type. 208# comment - descriptive text with no semantic meaning 209Enums = element enums { 210 attribute name { text } ? , 211 attribute type { text } ? , 212 attribute bitwidth { Integer } ? , 213 Comment ? , 214 ( 215 Enum | 216 Unused | 217 element comment { text} 218 ) * 219} 220 221# <enum> defines or references a single enumerant. There are two places it 222# can be used: in an <enums> block, providing a global definition which 223# may later be required by a feature or extension; or in a feature or 224# extension, defining an enumerant specific to that feature. The second 225# form has more possible attributes. Some combinations of attributes are 226# nonsensical in on or the other place, but these are not detected by the 227# validator. 228# 229# Ways to specify the enumerant value: 230# value - integer (including hex) value of the enumerant 231# bitpos - integer bit position of the enumerant in a bitmask 232# [extnumber], offset, [dir] - integer extension number specifying a 233# base block value (inherited from surrounding <extension> if 234# not specified); integer offset in that block; and direction 235# of offset ('-' for negative, positive if not specified). 236# alias - name of another enum this is an alias of 237# 238# value and bitpos allow, and extnumber/offset/dir require: 239# extends - type name of the enumerant being extended 240# 241# Other attributes: 242# api - matches a <feature> api attribute, if present 243# type - 'uint32_t', 'uint64_t', or 'float', if present. There are 244# certain conditions under which the tag must be present, or absent, 245# but they are context-dependent and difficult to express in the 246# RNC syntax. 247# name - enumerant name 248# alias - another enumerant this is semantically identical to 249# protect - additional #ifdef symbol to place around the enum 250# comment - descriptive text with no semantic meaning 251# deprecated - denotes that this enum is deprecated, and why. 252# Valid values: 'aliased', 'ignored', 'true'. 253Enum = element enum { 254 ( 255 ( 256 ( 257 attribute value { Integer } & 258 attribute extends { TypeName } ? 259 ) | 260 ( 261 attribute bitpos { Integer } & 262 attribute extends { TypeName } ? 263 ) | 264 ( 265 attribute extnumber { Integer } ? & 266 attribute offset { Integer } & 267 attribute dir { text } ? & 268 attribute extends { TypeName } 269 ) | 270 ( 271 attribute extends { TypeName } ? & 272 attribute alias { TypeName } 273 ) 274 ) ? & 275 attribute protect { text } ? & 276 attribute api { text } ? & 277 attribute type { TypeSuffix } ? & 278 attribute name { text } & 279 attribute deprecated { text } ? & 280 Comment ? 281 ) 282} 283 284# <unused> defines a range of enumerants not currently being used 285# start, end - beginning and end of an unused numeric range 286# vendor - unused 287# comment - descriptive text with no semantic meaning 288Unused = element unused { 289 attribute start { Integer } , 290 attribute end { Integer } ? , 291 Vendor ? , 292 Comment ? 293} 294 295# <commands> defines a group of commands 296Commands = element commands { 297 Comment ? , 298 Command * 299} 300 301# <command> defines a single command 302# 303# There are two forms of the tag. 304# 305# Either form may have an 'api' attribute 306# api - matches a <feature> api attribute, if present 307# 308# The first form only has 'name' and 'alias' attributes, and no contents. 309# It defines a command alias. 310# 311# The second form fully defines a command, and has the following structure: 312# The possible attributes are not described in this comment block yet, but 313# are in registry.html. The "prefix" and "suffix" attributes are currently 314# present only in the OpenCL XML registry, where they are currently unused. 315# 316# <proto> is the C function prototype, including the return type 317# <param> are function parameters, in order 318# len - if the member is an array, len may be one or more of the following 319# things, separated by commas (one for each array indirection): 320# another member of that struct, 'null-terminated' for a string, 321# '1' to indicate it is just a pointer (used for nested pointers), 322# or a latex equation (prefixed with 'latexmath:') 323# altlen - if len has latexmath equations, this contains equivalent C99 324# expressions separated by commas. 325# externsync - denotes that the member should be externally synchronized 326# when accessed by Vulkan 327# optional - whether this value can be omitted by providing NULL (for 328# pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values) 329# selector - for a union parameter, identifies a separate enum parameter that 330# selects which of the union's members are valid 331# noautovalidity - tag stating that no automatic validity language should be 332# generated 333# objecttype - only applicable for parameters representing a handle as 334# a uint64_t value. Specifies the name of another parameter which is 335# a VkObjectType or VkDebugReportObjectTypeEXT value specifying 336# the type of object the handle references. 337# validstructs - only applicable for parameters which are pointers to 338# VkBaseInStructure or VkBaseOutStructure types, used as abstract 339# placeholders. Specifies a comma-separated list of structures which 340# may be passed in place of the parameter, or anywhere in the pNext 341# chain of the parameter. 342# stride - if the member is an array, stride specifies the name of 343# another member containing the byte stride between consecutive 344# elements in the array. Is assumed tightly packed if omitted. 345# <type> is a <type> name, if present 346# <name> is the function / parameter name, if present (normally should 347# be, except for void parameters). 348# The textual contents of <proto> and <param> should be legal C 349# for those parts of a function declaration. 350# <alias> - denotes function aliasing, if present 351# name - name of aliased function 352# <description> - unused text 353# <implicitexternsyncparams> are spec-language descriptions of 354# objects that are not parameters of the command, but 355# are related to them and also require external synchronization. 356Command = element command { 357 ( attribute name { text } , 358 attribute alias { text } , 359 attribute api { text } ? 360 ) | 361 ( 362 attribute tasks { text } ? , 363 attribute queues { text } ? , 364 attribute successcodes { text } ? , 365 attribute errorcodes { text } ? , 366 attribute renderpass { text } ? , 367 attribute videocoding { text } ? , 368 attribute cmdbufferlevel { text } ? , 369 attribute prefix { text } ? , 370 attribute suffix { text } ? , 371 attribute api { text } ? , 372 Comment ? , 373 element proto { 374 mixed { 375 element type { TypeName } ? , 376 element name { text } 377 } 378 } , 379 element param { 380 attribute api { text } ? , 381 attribute len { text } ? , 382 attribute altlen { text } ? , 383 attribute externsync { text } ? , 384 attribute optional { text } ? , 385 attribute selector { text } ? , 386 attribute noautovalidity { text } ? , 387 attribute objecttype { text } ? , 388 attribute validstructs { text } ? , 389 attribute stride { text } ? , 390 mixed { 391 element type { TypeName } ? , 392 element name { text } ? 393 } 394 } * , 395 ( 396 element alias { 397 Name 398 } ? & 399 element description { 400 text 401 } ? & 402 element implicitexternsyncparams { 403 element param { text } * 404 } ? 405 ) 406 ) 407} 408 409# Each <feature> defines the interface of an API version (e.g. OpenGL 1.2) 410# api - API tag (e.g. 'gl', 'gles2', etc. - used internally, not 411# necessarily an actual API name 412# name - version name (C preprocessor name, e.g. GL_VERSION_4_2) 413# number - version number, e.g. 4.2 414# protect - additional #ifdef symbol to place around the feature 415# sortorder - order relative to other features, default 0 416# <require> / <remove> contains features to require or remove in 417# this version 418# profile - only require/remove when generated profile matches 419# comment - descriptive text with no semantic meaning 420Feature = element feature { 421 attribute api { text } , 422 Name , 423 attribute number { xsd:float } , 424 attribute protect { text } ? , 425 attribute sortorder { xsd:integer } ?, 426 Comment ? , 427 ( 428 element require { 429 ProfileName ? , 430 Depends ? , 431 Comment ? , 432 ( 433 InterfaceElement | 434 element comment { text } 435 ) * 436 } | 437 element remove { 438 ProfileName ? , 439 Comment ? , 440 ( 441 InterfaceElement | 442 element comment { text } 443 ) * 444 } 445 ) * 446} 447 448Extensions = element extensions { 449 Comment ? , 450 Extension * 451} 452 453# Each <extension> defines the interface of an API <extension>. 454# Like a <feature> tag, but with slightly different attributes: 455# api - regexp pattern matching one or more API tags, indicating 456# which APIs the extension is known to work with. The only 457# syntax supported is <name>{|<name>}* and each name must 458# exactly match an API being generated (implicit ^$ surrounding). 459# name - extension name string 460# number - extension number (positive integer, should be unique) 461# sortorder - order relative to other extensions, default 0 462# protect - C preprocessor symbol to conditionally define the interface 463# platform - should be one of the platform names defined in the 464# <platform> tag. Currently unused. 465# author - name of the author (usually a company or project name) 466# contact - contact responsible for the tag (name and contact information) 467# type - 'device' or 'instance', if present 468# requires - commas-separated list of extension names required by this 469# extension 470# requiresCore - core version of Vulkan required by the extension, e.g. 471# "1.1". Defaults to "1.0". 472# supported - comma-separated list of API name(s) supporting this extension, 473# e.g. 'vulkan', or 'disabled' to never generate output. 474# ratified - comma-separated list of API name(s) for which this extension 475# has been ratified by Khronos. Defaults to "" if not specified. 476# promotedto - Vulkan version or a name of an extension that this 477# extension was promoted to; e.g. 'VK_VERSION_1_1', or 478# 'VK_KHR_draw_indirect_county' 479# deprecatedby - Vulkan version or a name of an extension that deprecates 480# this extension. It may be empty string. 481# e.g. 'VK_VERSION_1_1', or 'VK_EXT_debug_utils', or '' 482# obsoletedby - Vulkan version or a name of an extension that obsoletes 483# this extension. It may be empty string. 484# e.g. 'VK_VERSION_1_1', or 'VK_EXT_debug_utils', or '' 485# provisional - 'true' if this extension is released provisionally 486# specialuse - contains one or more tokens separated by commas, indicating 487# a special purpose of the extension. Tokens may include 'cadsupport', 488# 'd3demulation', 'devtools', 'debugging', and 'glemulation'. Others 489# may be added in the future. 490# In addition, <require> / <remove> tags also support an api attribute: 491# api - only require/remove these features for the matching API. 492# Not a regular expression. 493Extension = element extension { 494 Name , 495 attribute number { Integer } ? , 496 attribute sortorder { xsd:integer } ?, 497 attribute protect { text } ? , 498 attribute platform { text } ? , 499 attribute author { text } ? , 500 attribute contact { text } ? , 501 attribute type { text } ? , 502 attribute depends { text } ?, 503 attribute supported { StringGroup } ? , 504 attribute ratified { text } ? , 505 attribute promotedto { text } ? , 506 attribute deprecatedby { text } ? , 507 attribute obsoletedby { text } ? , 508 attribute provisional { text } ? , 509 attribute specialuse { text } ? , 510 Comment ? , 511 ( 512 element require { 513 attribute api { text } ? , 514 ProfileName ? , 515 Depends ? , 516 Comment ? , 517 ( 518 InterfaceElement | 519 element comment { text } 520 ) * 521 } | 522 element remove { 523 attribute api { text } ? , 524 ProfileName ? , 525 Comment ? , 526 ( 527 InterfaceElement | 528 element comment { text } 529 ) * 530 } 531 ) * 532} 533 534# Each <format> define information about a VkFormat in a machine readable format 535Formats = element formats { 536 Format * 537} 538 539# name - Format name, matching a VkFormat enum name 540# class - Used for 'Compatible Formats' table 541# blockSize - Used for 'Compatible Formats' table 542# texelsPerBlock - Used for 'Compatible Formats' table 543# blockExtent - 3D extent, no attribute is same as blockExtent=1,1,1 544# packed - number of bits data type 545# compressed - compression format class 546# planes - number of planes, no attribute is same as planes=1 547# chroma - can be one of [420, 422, 444] and used to mark if YCbCr Sampler are required by default 548Format = element format { 549 Name , 550 attribute class { text } , 551 attribute blockSize { text } , 552 attribute texelsPerBlock { text } , 553 attribute blockExtent { text } ? , 554 attribute packed { text } ? , 555 attribute compressed { text } ? , 556 attribute chroma { text } ? , 557 Component + , 558 Plane * , 559 SpirvImageFormat * 560} 561 562# bits - size of component or "compressed" if part of block-compression format 563# numericFormat - as per Interpretation of Numeric Format table 564# some formats (depth/stencil) will have different numeric per component 565# planeIndex - For multi-planar formats to map to the plane element 566Component = element component { 567 Name , 568 attribute bits { text } , 569 attribute numericFormat { text }, 570 attribute planeIndex { text } ? 571} 572 573# For multi-planar formats 574Plane = element plane { 575 attribute index { text } , 576 attribute widthDivisor { text } , 577 attribute heightDivisor { text } , 578 attribute compatible { text } 579} 580 581# labels a SPIR-V Image Format 582SpirvImageFormat = element spirvimageformat { 583 Name 584} 585 586# <sync> is a set of all sync objects 587Sync = element sync { 588 Comment ? , 589 SyncStage *, 590 SyncAccess *, 591 SyncPipeline * 592} 593 594SyncSupport = element syncsupport { 595 attribute queues { text } ? , 596 attribute stage { text } ? 597} 598 599SyncEquivalent = element syncequivalent { 600 attribute stage { text } ?, 601 attribute access { text } ? 602} 603 604# describes all Pipeline Stages 605SyncStage = element syncstage { 606 Name , 607 attribute alias { text } ? , 608 SyncSupport ? , 609 SyncEquivalent ? 610} 611 612# describes all Access Flags 613SyncAccess = element syncaccess { 614 element comment { text } ?, 615 Name , 616 attribute alias { text } ? , 617 SyncSupport ? , 618 SyncEquivalent ? 619} 620 621SyncPipelineStage = element syncpipelinestage { 622 attribute order { text } ? , 623 attribute before { text } ? , 624 attribute after { text } ?, 625 text 626} 627 628# describes pipelines 629SyncPipeline = element syncpipeline { 630 Name , 631 attribute depends { text } ? , 632 SyncPipelineStage * 633} 634 635# Each <spirvextension> define a SPIR-V extension that can be used in the API. 636# Each <spirvcapability> define a SPIR-V capability that can be used in the API. 637# Contains information to both generate table in spec as well as validating 638# what needs to be enabled or supported to be used in Vulkan 639SpirvExtensions = element spirvextensions { 640 Comment ? , 641 SpirvExtension * 642} 643 644SpirvExtension = element spirvextension { 645 Name , 646 Enable + 647} 648 649SpirvCapabilities = element spirvcapabilities { 650 Comment ? , 651 SpirvCapability * 652} 653 654SpirvCapability = element spirvcapability { 655 Name , 656 Enable + 657} 658 659# <enable> defines a way to enable the parent element in the API. 660# If anyone of the <enable> elements are valid then the parent element 661# can be used. 662# 663# There are four forms of the tag. 664# 665# The first only has the minimal version of Vulkan of the application 666# 667# The second only has a single Vulkan extension that must be enabled 668# 669# The third has a single Vulkan feature with the struct where it is from 670# 671# The fourth has a property struct, the member field in it, and the value 672# that must be present 673# 674# To make scripting easier, each <enable> has a require attribute to map 675# to the asciidoctor conditional logic in the spec. For version and 676# extension attribute variations, there is no need for the require attribute 677# since it is a redundant 1:1 mapping. 678# 679# The 'alias' attribute is used in cases where the anchor link cannot be 680# properly resolved and needs a manual name to link to 681Enable = element enable { 682 ( 683 attribute version { text } ) | 684 ( 685 attribute extension { text } ) | 686 ( 687 attribute struct { text }, 688 attribute feature { text }, 689 attribute requires { text }, 690 attribute alias { text } ? ) | 691 ( 692 attribute property { text }, 693 attribute member { text }, 694 attribute value { text }, 695 attribute requires { text } ? ) 696} 697 698# Contents of a <require> / <remove> tag, defining a group 699# of features to require or remove. 700# <type> / <enum> / <command> all have attributes 701# name - feature name which must match 702InterfaceElement = 703 element type { 704 Name , 705 Comment ? 706 } | 707 Enum | 708 element command { 709 Name , 710 Comment ? 711 } 712 713# Integers are allowed to be either decimal or C-hex (0x[0-9A-F]+), but 714# XML Schema types do not seem to support hex notation, so we use this 715# as a placeholder. 716Integer = text 717 718# EnumName is an compile-time constant name 719EnumName = text 720 721# TypeName is an argument/return value C type name 722TypeName = text 723 724# TypeSuffix is a C numeric type suffix, e.g. 'u' or 'ull' 725TypeSuffix = text 726 727# StringGroup is a regular expression with an implicit 728# '^(' and ')$' bracketing it. 729StringGroup = text 730 731# Repeatedly used attributes 732ProfileName = attribute profile { text } 733ExtensionName = attribute extension { text } 734# Boolean expression of core version and extension names using (),+ operators 735Depends = attribute depends { text } 736Vendor = attribute vendor { text } 737Comment = attribute comment { text } 738Name = attribute name { text } 739