diff options
Diffstat (limited to 'codegen/vulkan/xml/registry.rnc')
| -rw-r--r-- | codegen/vulkan/xml/registry.rnc | 610 |
1 files changed, 610 insertions, 0 deletions
diff --git a/codegen/vulkan/xml/registry.rnc b/codegen/vulkan/xml/registry.rnc new file mode 100644 index 00000000..ad645c04 --- /dev/null +++ b/codegen/vulkan/xml/registry.rnc @@ -0,0 +1,610 @@ +# Copyright 2013-2021 The Khronos Group Inc. +# +# SPDX-License-Identifier: Apache-2.0 + +# Relax NG schema for Khronos Vulkan API Registry XML +# +# See https://www.khronos.org/vulkan/ +# +# This definition is subject to change (mostly in the form of additions) + +namespace xsd = "http://www.w3.org/2001/XMLSchema-datatypes" + +# Toplevel is a <registry> tag. +# May be led by an optional <comment> tag containing e.g. copyrights. +start = element registry { + ( + element comment { text } ? | + Platforms * | + Tags * | + Types * | + Enums * | + Commands * | + Feature * | + Extensions * | + SpirvExtensions * | + SpirvCapabilities * + ) * +} + +# <platforms> defines a group of platform names +Platforms = element platforms { + Comment ? , + Platform * +} + +# <platform> defines a single platform name. +# name - string name of the platform, used as part of extension names +# protect - preprocessor symbol to include platform headers from <vulkan.h> +# comment - platform description +Platform = element platform { + attribute name { text } , + attribute protect { text } , + Comment +} + +# <tags> defines a group of author tags +Tags = element tags { + Comment ? , + Tag * +} + +# <tag> defines a single author tag. +# name - name of the tag +# author - name of the author (usually a company or project name) +# contact - contact responsible for the tag (name and contact information) +Tag = element tag { + attribute name { text } , + attribute author { text } , + attribute contact { text } +} + +# <types> defines a group of types +Types = element types { + Comment ? , + ( + Type | + element comment { text } + ) * +} + +# <type> defines a single type. It is usually a C typedef but +# may contain arbitrary C code. +# name - name of this type, if not present in the <name> tag +# api - matches a <feature> api attribute, if present +# alias - name of a type this type aliases +# requires - name of another type definition required by this one +# bitvalues - for a *Flags type, name of an enum definition that +# defines the valid values for parameters of that type +# name - name of the type being defined +# category - if present, 'enum' indicates a matching <enums> +# block to generate an enumerated type for, and 'struct' +# causes special interpretation of the contents of the type +# tag including ... TBD ... +# Other allowed values are 'include', 'define', 'handle' and 'bitmask', +# which don't change syntactic interpretation but allow organization in +# the generated header. +# parent - only applicable if category is 'handle'. Notes another type with +# the 'handle' category that acts as a parent object for this type. +# returnedonly - only applicable if category is 'struct'. Notes that this +# struct is going to be filled in by the API, rather than an application +# filling it out and passing it to the API. +# structextends - only applicable if category is 'struct'. Lists parent +# structures which this structure may extend via the pNext chain +# of the parent. +# When present it suppresses generation of automatic validity for the +# pNext member of that structure, and instead the structure is added +# to pNext chain validity for the parent structures it extends. +# allowduplicate - only applicable if category is 'struct'. pNext can include +# multiple structures of this type. +# objtypeenum - name of VK_OBJECT_TYPE_* API enumerant which corresponds +# to this type. Currently only specified for category="handle" types. +# comment - descriptive text with no semantic meaning +# For types without a category, contents include +# <apientry /> - substitutes for an APIENTRY-style macro on output +# <name> - contains name of the type being defined +# <type> - contains name of types used to define this type. There +# may be multiple imbedded <type> tags +# For types with category 'enum', contents should be empty +# For types with category 'struct', contents should be one or more +# <member> - like <param> for a struct or union member +# len - if the member is an array, len may be one or more of the following +# things, separated by commas (one for each array indirection): another +# member of that struct, 'null-terminated' for a string, '1' to indicate it's +# just a pointer (used for nested pointers), or a latex equation (prefixed with +# 'latexmath:') +# altlen - if len has latexmath equations, this contains equivalent C99 +# expressions separated by commas. +# externsync - denotes that the member should be externally synchronized +# when accessed by Vulkan +# optional - whether this value can be omitted by providing NULL (for +# pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values) +# selector - for a union member, identifies a separate enum member that +# selects which of the union's members are valid +# selection - for a member of a union, identifies an enum value indicating the member is valid +# noautovalidity - tag stating that no automatic validity language should be generated +# values - comma-separated list of legal values, usually used only for sType enums +# limittype - only applicable for members of VkPhysicalDeviceProperties and +# VkPhysicalDeviceProperties2, their substrucutres, and extensions. +# Specifies the type of a device limit. +# Valid values: 'min', 'max', 'bitmask', 'range', 'struct', 'noauto' +# objecttype - only applicable for members representing a handle as +# a uint64_t value. Specifies the name of another member which is +# a VkObjectType or VkDebugReportObjectTypeEXT value specifying +# the type of object the handle references. +# <comment> - containing arbitrary text (unused) +# +# *** There's a problem here: I'm not sure how to represent the <type> +# syntax where it may contain arbitrarily interleaved text, <type>, and +# <enum> child tags. This allows only the syntax +# text <type>name</type> text <enum>name</enum> text +# where <type> and <enum> are both optional and occur in the specified +# order, which might eventually be a problem. +Type = element type { + attribute api { text } ? , + attribute alias { text } ? , + attribute requires { text } ? , + attribute bitvalues { text } ? , + attribute name { TypeName } ? , + attribute category { text } ? , + attribute parent { TypeName } ? , + attribute returnedonly { text } ? , + attribute structextends { text } ? , + attribute allowduplicate { text } ? , + attribute objtypeenum { text } ? , + Comment ? , + ( + ( + ( text , + element type { text } * + ) * , + element apientry { text } ? , + ( text , + element type { text } * + ) * , + element name { TypeName } ? , + ( text , + element type { text } * + ) * + ) | + ( + element member { + attribute len { text } ? , + attribute altlen { text } ? , + attribute externsync { text } ? , + attribute optional { text } ? , + attribute selector { text } ? , + attribute selection { EnumName } ? , + attribute noautovalidity { text } ? , + attribute values { text } ? , + attribute limittype { text } ? , + attribute objecttype { text } ? , + mixed { + element type { TypeName } ? , + element name { text } ? , + element enum { EnumName } ? , + element comment { text } ? + } + } | + element comment { text } + ) * + ) +} + +# <enums> defines a group of enumerants +# name - identifies a type name associated with this group. Should +# match a <type> name to trigger generation of the type. +# start, end - beginning and end of a numeric range +# vendor - owner of the numeric range +# type - 'enum' or 'bitmask', if present +# bitwidth - bit width of the enum value type. +# comment - descriptive text with no semantic meaning +Enums = element enums { + attribute name { text } ? , + attribute type { text } ? , + attribute start { Integer } ? , + attribute end { Integer } ? , + attribute bitwidth { Integer } ? , + Vendor ? , + Comment ? , + ( + Enum | + Unused | + element comment { text} + ) * +} + +# <enum> defines or references a single enumerant. There are two places it +# can be used: in an <enums> block, providing a global definition which +# may later be required by a feature or extension; or in a feature or +# extension, defining an enumerant specific to that feature. The second +# form has more possible attributes. Some combinations of attributes are +# nonsensical in on or the other place, but these are not detected by the +# validator. +# +# Ways to specify the enumerant value: +# value - integer (including hex) value of the enumerant +# bitpos - integer bit position of the enumerant in a bitmask +# [extnumber], offset, [dir] - integer extension number specifying a +# base block value (inherited from surrounding <extension> if +# not specified); integer offset in that block; and direction +# of offset ('-' for negative, positive if not specified). +# alias - name of another enum this is an alias of +# +# value and bitpos allow, and extnumber/offset/dir require: +# extends - type name of the enumerant being extended +# +# Other attributes: +# api - matches a <feature> api attribute, if present +# type - 'uint32_t', 'uint64_t', or 'float', if present. There are +# certain conditions under which the tag must be present, or absent, +# but they are context-dependent and difficult to express in the +# RNC syntax. +# name - enumerant name +# alias - another enumerant this is semantically identical to +# protect - additional #ifdef symbol to place around the enum +# comment - descriptive text with no semantic meaning +Enum = element enum { + ( + ( + ( + attribute value { Integer } & + attribute extends { TypeName } ? + ) | + ( + attribute bitpos { Integer } & + attribute extends { TypeName } ? + ) | + ( + attribute extnumber { Integer } ? & + attribute offset { Integer } & + attribute dir { text } ? & + attribute extends { TypeName } + ) | + ( + attribute extends { TypeName } ? & + attribute alias { TypeName } + ) + ) ? & + attribute protect { text } ? & + attribute api { text } ? & + attribute type { TypeSuffix } ? & + attribute name { text } & + Comment ? + ) +} + +# <unused> defines a range of enumerants not currently being used +# start, end - beginning and end of an unused numeric range +# vendor - unused +# comment - descriptive text with no semantic meaning +Unused = element unused { + attribute start { Integer } , + attribute end { Integer } ? , + Vendor ? , + Comment ? +} + +# <commands> defines a group of commands +Commands = element commands { + Comment ? , + Command * +} + +# <command> defines a single command +# +# There are two forms of the tag. +# +# The first only has 'name' and 'alias' attributes, and no contents. +# It defines a command alias. +# +# The second fully defines a command, and has the following structure: +# The possible attributes are not described in this comment block yet, but +# are in readme.pdf. The "prefix" and "suffix" attributes are currently +# present only in the OpenCL XML registry, where they are currently unused. +# +# <proto> is the C function prototype, including the return type +# <param> are function parameters, in order +# len - if the member is an array, len may be one or more of the following +# things, separated by commas (one for each array indirection): another +# member of that struct, 'null-terminated' for a string, '1' to indicate it's +# just a pointer (used for nested pointers), or a latex equation (prefixed with +# 'latexmath:') +# altlen - if len has latexmath equations, this contains equivalent C99 +# expressions separated by commas. +# externsync - denotes that the member should be externally synchronized +# when accessed by Vulkan +# optional - whether this value can be omitted by providing NULL (for +# pointers), VK_NULL_HANDLE (for handles) or 0 (for bitmasks/values) +# selector - for a union parameter, identifies a separate enum parameter that +# selects which of the union's members are valid +# noautovalidity - tag stating that no automatic validity language should be generated +# objecttype - only applicable for parameters representing a handle as +# a uint64_t value. Specifies the name of another parameter which is +# a VkObjectType or VkDebugReportObjectTypeEXT value specifying +# the type of object the handle references. +# <type> is a <type> name, if present +# <name> is the function / parameter name, if present (normally should +# be, except for void parameters). +# The textual contents of <proto> and <param> should be legal C +# for those parts of a function declaration. +# <alias> - denotes function aliasing, if present +# name - name of aliased function +# <description> - unused text +# <implicitexternsyncparams> are spec-language descriptions of +# objects that are not parameters of the command, but +# are related to them and also require external synchronization. +Command = element command { + ( attribute name { text } , + attribute alias { text } ) | + ( + attribute queues { text } ? , + attribute successcodes { text } ? , + attribute errorcodes { text } ? , + attribute renderpass { text } ? , + attribute cmdbufferlevel { text } ? , + attribute prefix { text } ? , + attribute suffix { text } ? , + Comment ? , + element proto { + mixed { + element type { TypeName } ? , + element name { text } + } + } , + element param { + attribute len { text } ? , + attribute altlen { text } ? , + attribute externsync { text } ? , + attribute optional { text } ? , + attribute selector { text } ? , + attribute noautovalidity { text } ? , + attribute objecttype { text } ? , + mixed { + element type { TypeName } ? , + element name { text } ? + } + } * , + ( + element alias { + Name + } ? & + element description { + text + } ? & + element implicitexternsyncparams { + element param { text } * + } ? + ) + ) +} + +# Each <feature> defines the interface of an API version (e.g. OpenGL 1.2) +# api - API tag (e.g. 'gl', 'gles2', etc. - used internally, not +# necessarily an actual API name +# name - version name (C preprocessor name, e.g. GL_VERSION_4_2) +# number - version number, e.g. 4.2 +# protect - additional #ifdef symbol to place around the feature +# sortorder - order relative to other features, default 0 +# <require> / <remove> contains features to require or remove in +# this version +# profile - only require/remove when generated profile matches +# comment - descriptive text with no semantic meaning +Feature = element feature { + attribute api { text } , + Name , + attribute number { xsd:float } , + attribute protect { text } ? , + attribute sortorder { xsd:integer } ?, + Comment ? , + ( + element require { + ProfileName ? , + ExtensionName ? , + Comment ? , + ( + InterfaceElement | + element comment { text } + ) * + } | + element remove { + ProfileName ? , + Comment ? , + ( + InterfaceElement | + element comment { text } + ) * + } + ) * +} + +Extensions = element extensions { + Comment ? , + Extension * +} + +# Defines the interface of an API <extension>. Like a <feature> +# tag, but with slightly different attributes: +# api - regexp pattern matching one or more API tags, indicating +# which APIs the extension is known to work with. The only +# syntax supported is <name>{|<name>}* and each name must +# exactly match an API being generated (implicit ^$ surrounding). +# name - extension name string +# number - extension number (positive integer, should be unique) +# sortorder - order relative to other extensions, default 0 +# protect - C preprocessor symbol to conditionally define the interface +# platform - should be one of the platform names defined in the +# <platform> tag. Currently unused. +# author - name of the author (usually a company or project name) +# contact - contact responsible for the tag (name and contact information) +# type - 'device' or 'instance', if present +# requires - commas-separated list of extension names required by this +# extension +# requiresCore - core version of Vulkan required by the extension, e.g. +# "1.1". Defaults to "1.0". +# supported - profile name(s) supporting this extension, e.g. 'vulkan' +# or 'disabled' to never generate output. +# promotedto - Vulkan version or a name of an extension that this +# extension was promoted to; e.g. 'VK_VERSION_1_1', or +# 'VK_KHR_draw_indirect_county' +# deprecatedby - Vulkan version or a name of an extension that deprecates +# this extension. It may be empty string. +# e.g. 'VK_VERSION_1_1', or 'VK_EXT_debug_utils', or '' +# obsoletedby - Vulkan version or a name of an extension that obsoletes +# this extension. It may be empty string. +# e.g. 'VK_VERSION_1_1', or 'VK_EXT_debug_utils', or '' +# provisional - 'true' if this extension is released provisionally +# specialuse - contains one or more tokens separated by commas, indicating +# a special purpose of the extension. Tokens may include 'cadsupport', +# 'd3demulation', 'devtools', 'debugging', and 'glemulation'. Others +# may be added in the future. +# In addition, <require> / <remove> tags also support an api attribute: +# api - only require/remove these features for the matching API. +# Not a regular expression. +Extension = element extension { + Name , + attribute number { Integer } ? , + attribute sortorder { xsd:integer } ?, + attribute protect { text } ? , + attribute platform { text } ? , + attribute author { text } ? , + attribute contact { text } ? , + attribute type { text } ? , + attribute requires { text } ? , + attribute requiresCore { text } ? , + attribute supported { StringGroup } ? , + attribute promotedto { text } ? , + attribute deprecatedby { text } ? , + attribute obsoletedby { text } ? , + attribute provisional { text } ? , + attribute specialuse { text } ? , + Comment ? , + ( + element require { + attribute api { text } ? , + ProfileName ? , + ExtensionName ? , + FeatureName ? , + Comment ? , + ( + InterfaceElement | + element comment { text } + ) * + } | + element remove { + attribute api { text } ? , + ProfileName ? , + Comment ? , + ( + InterfaceElement | + element comment { text } + ) * + } + ) * +} + +# Each <spirvextension> define a SPIR-V extension that can be used in the API. +# Each <spirvcapability> define a SPIR-V capability that can be used in the API. +# Contains information to both generate table in spec as well as validation +# what needs to be enabled be used in Vulkan +SpirvExtensions = element spirvextensions { + Comment ? , + SpirvExtension * +} + +SpirvExtension = element spirvextension { + Name , + Enable * +} + +SpirvCapabilities = element spirvcapabilities { + Comment ? , + SpirvCapability * +} + +SpirvCapability = element spirvcapability { + Name , + Enable * +} + +# <enable> defines a way to enable the parent element in the API. +# If anyone of the <enable> elements are valid then the parent element +# can be used. +# +# There are four forms of the tag. +# +# The first only has the minimal version of Vulkan of the application +# +# The second only has a single Vulkan extension that must be enabled +# +# The third has a single Vulkan feature with the struct where it is from +# +# The forth has a property struct, the member field in it, and the value +# that must be present +# +# To make scripting easier, each <enable> has a require attribute to map +# to the asciidoctor conditional logic in the spec. For version and +# extension attribute variations, there is no need for the require attribute +# since it is a redundant 1:1 mapping. +# +# The 'alias' attribute is used in cases where the anchor link can't be +# propertly resolved and needs a manual name to link to +Enable = element enable { + ( + attribute version { text } ) | + ( + attribute extension { text } ) | + ( + attribute struct { text }, + attribute feature { text }, + attribute requires { text }, + attribute alias { text } ? ) | + ( + attribute property { text }, + attribute member { text }, + attribute value { text }, + attribute requires { text } ? ) +} + +# Contents of a <require> / <remove> tag, defining a group +# of features to require or remove. +# <type> / <enum> / <command> all have attributes +# name - feature name which must match +InterfaceElement = + element type { + Name , + Comment ? + } | + Enum | + element command { + Name , + Comment ? + } + +# Integers are allowed to be either decimal or C-hex (0x[0-9A-F]+), but +# XML Schema types don't seem to support hex notation, so we use this +# as a placeholder. +Integer = text + +# EnumName is an compile-time constant name +EnumName = text + +# TypeName is an argument/return value C type name +TypeName = text + +# TypeSuffix is a C numeric type suffix, e.g. 'u' or 'ull' +TypeSuffix = text + +# StringGroup is a regular expression with an implicit +# '^(' and ')$' bracketing it. +StringGroup = text + +# Repeatedly used attributes +ProfileName = attribute profile { text } +ExtensionName = attribute extension { text } +FeatureName = attribute feature { text } +Vendor = attribute vendor { text } +Comment = attribute comment { text } +Name = attribute name { text } + + |