1// Copyright 2015-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5 6[[introduction]] 7= Introduction 8 9This document, referred to as the 10ifdef::VKSC_VERSION_1_0["`Vulkan SC Specification`", ] 11"`Vulkan Specification`" or just the "`Specification`" hereafter, describes 12the Vulkan 13ifdef::VKSC_VERSION_1_0[SC] 14Application Programming Interface (API). 15ifdef::VKSC_VERSION_1_0[] 16"`Base Vulkan Specification`" refers to the Vulkan Specification 17(https://registry.khronos.org/vulkan/) that Vulkan SC is based on. 18"`Vulkan`" and "`Vulkan SC`" refer to the Vulkan SC API and "`Base Vulkan`" 19refers to the Vulkan API that Vulkan SC is based on. 20endif::VKSC_VERSION_1_0[] 21Vulkan is a http://www.open-std.org/jtc1/sc22/wg14/www/standards[C99] API 22designed for explicit control of low-level graphics and compute 23functionality. 24 25ifndef::VKSC_VERSION_1_0[] 26The canonical version of the Specification is available in the official 27https://registry.khronos.org/vulkan/[Vulkan Registry] 28(https://registry.khronos.org/vulkan/). 29The source files used to generate the Vulkan specification are stored in the 30https://github.com/KhronosGroup/Vulkan-Docs[Vulkan Documentation Repository] 31(https://github.com/KhronosGroup/Vulkan-Docs). 32endif::VKSC_VERSION_1_0[] 33 34ifdef::VKSC_VERSION_1_0[] 35The canonical version of the Specification is available in the official 36https://registry.khronos.org/vulkansc/[Vulkan SC Registry] 37(https://registry.khronos.org/vulkansc/). 38The source files used to generate the Vulkan SC specification are stored in 39the https://github.com/KhronosGroup/VulkanSC-Docs[Vulkan SC Documentation 40Repository] (https://github.com/KhronosGroup/VulkanSC-Docs). 41endif::VKSC_VERSION_1_0[] 42The source repository additionally has a public issue tracker and allows the 43submission of pull requests that improve the specification. 44 45 46[[introduction-conventions]] 47== Document Conventions 48 49The Vulkan specification is intended for use by both implementors of the API 50and application developers seeking to make use of the API, forming a 51contract between these parties. 52Specification text may address either party; typically the intended audience 53can be inferred from context, though some sections are defined to address 54only one of these parties. 55(For example, <<fundamentals-validusage>> sections only address application 56developers). 57Any requirements, prohibitions, recommendations or options defined by 58<<introduction-normative-terminology, normative terminology>> are imposed 59only on the audience of that text. 60 61[NOTE] 62.Note 63==== 64Structure and enumerated types defined in extensions that were promoted to 65core in a later version of Vulkan are now defined in terms of the equivalent 66Vulkan core interfaces. 67This affects the Vulkan Specification, the Vulkan header files, and the 68corresponding XML Registry. 69==== 70 71 72[[introduction-ratified]] 73=== Ratification 74 75_Ratification_ of a Vulkan core version or extension is a status conferred 76by vote of the Khronos Board of Promoters, bringing that core version or 77extension under the umbrella of the Khronos IP Policy. 78 79All Vulkan core versions and `KHR` extensions (including provisional 80specifications) are ratified, as are some multi-vendor `EXT` extensions. 81Ratification status of extensions is described in the <<extensions, Layers & 82Extensions (Informative)>> appendix. 83 84[NOTE] 85.Note 86==== 87Ratification status is primarily of interest to IHVs developing GPU hardware 88and Vulkan implementations 89 90For developers, ratification does not necessarily mean that an extension is 91"`better`"; has a more stable API; or is more widely supported than 92alternative ways of achieving that functionality. 93 94Interactions between ratified and non-ratified extensions are not themselves 95ratified. 96==== 97 98 99[[introduction-informative-language]] 100=== Informative Language 101 102Some language in the specification is purely informative, intended to give 103background or suggestions to implementors or developers. 104 105If an entire chapter or section contains only informative language, its 106title will be suffixed with "`(Informative)`". 107 108All NOTEs are implicitly informative. 109 110 111[[introduction-normative-terminology]] 112=== Normative Terminology 113 114Within this specification, the key words *must*, *required*, *should*, 115*recommended*, *may*, and *optional* are to be interpreted as described in 116https://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to 117Indicate Requirement Levels] (https://www.ietf.org/rfc/rfc2119.txt). 118The additional key word *optionally* is an alternate form of *optional*, for 119use where grammatically appropriate. 120 121These key words are highlighted in the specification for clarity. 122In text addressing application developers, their use expresses requirements 123that apply to application behavior. 124In text addressing implementors, their use expresses requirements that apply 125to implementations. 126 127In text addressing application developers, the additional key words *can* 128and *cannot* are to be interpreted as describing the capabilities of an 129application, as follows: 130 131*can*:: 132This word means that the application is able to perform the action 133described. 134 135*cannot*:: 136This word means that the API and/or the execution environment provide no 137mechanism through which the application can express or accomplish the action 138described. 139 140These key words are never used in text addressing implementors. 141 142[NOTE] 143.Note 144==== 145There is an important distinction between *cannot* and *must not*, as used 146in this Specification. 147*Cannot* means something the application literally is unable to express or 148accomplish through the API, while *must not* means something that the 149application is capable of expressing through the API, but that the 150consequences of doing so are undefined: and potentially unrecoverable for 151the implementation (see <<fundamentals-validusage>>). 152==== 153 154Unless otherwise noted in the section heading, all sections and appendices 155in this document are normative. 156 157 158[[introduction-technical-terminology]] 159=== Technical Terminology 160 161The Vulkan Specification makes use of common engineering and graphics terms 162such as *Pipeline*, *Shader*, and *Host* to identify and describe Vulkan API 163constructs and their attributes, states, and behaviors. 164The <<glossary,Glossary>> defines the basic meanings of these terms in the 165context of the Specification. 166The Specification text provides fuller definitions of the terms and may 167elaborate, extend, or clarify the <<glossary,Glossary>> definitions. 168When a term defined in the <<glossary,Glossary>> is used in normative 169language within the Specification, the definitions within the Specification 170govern and supersede any meanings the terms may have in other technical 171contexts (i.e. outside the Specification). 172 173 174[[introduction-normative-references]] 175=== Normative References 176 177References to external documents are considered normative references if the 178Specification uses any of the normative terms defined in 179<<introduction-normative-terminology>> to refer to them or their 180requirements, either as a whole or in part. 181 182The following documents are referenced by normative sections of the 183specification: 184 185[[ieee-754]] 186IEEE. 187August, 2008. 188_IEEE Standard for Floating-Point Arithmetic_. 189IEEE Std 754-2008. 190https://dx.doi.org/10.1109/IEEESTD.2008.4610935 . 191 192[[data-format]] Andrew Garrard. 193_Khronos Data Format Specification, version 1.3_. 194https://registry.khronos.org/DataFormat/specs/1.3/dataformat.1.3.html . 195 196[[spirv-extended]] John Kessenich. 197_SPIR-V Extended Instructions for GLSL, Version 1.00_ (February 10, 2016). 198https://registry.khronos.org/spir-v/ . 199 200[[spirv-spec]] John Kessenich, Boaz Ouriel, and Raun Krisch. 201_SPIR-V Specification, Version 1.5, Revision 3, Unified_ (April 24, 2020). 202https://registry.khronos.org/spir-v/ . 203 204[[itu-t-h264]] 205ITU-T. 206_H.264 Advanced Video Coding for Generic Audiovisual Services_ (August, 2072021). 208https://www.itu.int/rec/T-REC-H.264-202108-I/ . 209 210[[itu-t-h265]] 211ITU-T. 212_H.265 High Efficiency Video Coding_ (August, 2021). 213https://www.itu.int/rec/T-REC-H.265-202108-I/ . 214 215[[vulkan-registry]] Jon Leech. 216_The Khronos Vulkan API Registry_ (February 26, 2023). 217https://registry.khronos.org/vulkan/specs/1.3/registry.html . 218 219[[vulkan-styleguide]] Jon Leech and Tobias Hector. 220_Vulkan Documentation and Extensions: Procedures and Conventions_ (February 22126, 2023). 222https://registry.khronos.org/vulkan/specs/1.3/styleguide.html . 223 224[[LoaderInterfaceArchitecture]] 225_Architecture of the Vulkan Loader Interfaces_ (October, 2021). 226https://github.com/KhronosGroup/Vulkan-Loader/blob/master/docs/LoaderInterfaceArchitecture.md 227. 228 229ifdef::VKSC_VERSION_1_0[] 230[[introduction-vulkansc-philosophy]] 231== Safety Critical Philosophy 232 233Vulkan SC {revnumber} is based on Vulkan 1.2 and, except where explicitly 234noted, supports all of the same features, properties, and limits as Vulkan 2351.2. 236 237Throughout the Vulkan SC specification, changes have been made to the Base 238Vulkan Specification in order to align it with safety critical use cases and 239certification. 240In general changes were made to meet the following categories: 241 242 * Deterministic Execution (predictable execution times and results) 243 * Robustness (error handling, removing ambiguity, clarifying undefined: 244 behavior) 245 * Simplification (changes made to reduce certification effort and 246 challenges) 247 248To simplify capturing the reasoning behind deviations made from the Base 249Vulkan Specification, the Vulkan SC specification utilizes change 250identifications to give the reader insight into why the change was made in a 251concise manner. 252The change identifications are captured in 253<<introduction-vulkansc-change-justification-table>>. 254In addition, the Vulkan SC specification contains <<vulkansc-deviations>> 255which is a complete list of changes between Base Vulkan and Vulkan SC. 256This is targeted at readers who are familiar with Base Vulkan and would like 257to understand the differences between Vulkan SC and the Base Vulkan 258specification. 259 260Vulkan SC follows the Base Vulkan philosophy of requiring valid usage from 261the application. 262It is left to each implementation to determine how to ensure safe operation 263with respect to invalid usage. 264This may: involve determining that certain invalid usage does not pose a 265safety risk, adding valid usage checks in the driver, requiring valid usage 266checks in the application, or some combination of these. 267Additionally, validation layers are supported during development. 268 269[[introduction-vulkansc-change-justification-table]] 270=== Change Justification Table 271 272The following is a list of the safety critical change identifications used 273to concisely capture the justification for deviations from the Base Vulkan 274Specification. 275 276.Change Justifications 277[width="100%",options="header",cols="15h,~"] 278|==== 279| Change ID | Description 280| SCID-1[[SCID-1]] | *Deterministic behavior* - no randomness or unpredictability, always produce the same output from a given starting condition or initial state 281| SCID-2[[SCID-2]] | *Asynchronous calls* - calls initiated by the application but may not execute or use their parameter data until a later time shall be clearly defined when any parameter data is used, especially data which is passed by reference or pointer 282| SCID-3[[SCID-3]] | *Notification of change of state* - avoid the use of asynchronous events causing code to execute (i.e. callbacks) as this can cause the worst case execution time of a system to be indeterminate 283| SCID-4[[SCID-4]] | *Garbage collection methods* - avoid the use of garbage collection as this can cause the worst case execution time of a system to be indeterminate. Avoid memory fragmentation by deleting entire buffers instead of individual items within a buffer 284| SCID-5[[SCID-5]] | *Fully testable* - all behavior of the API must be testable in a repeatable manner, consistent from test run to test run (in some cases this may mean testable by inspection) 285| SCID-6[[SCID-6]] | *Undefined behavior* - the API must behave as expected under valid input conditions, clearly document conditions that would result in 'fatal error' leaving the system in an unrecoverable state, and document conditions that would result in undefined: behavior based on invalid input 286| SCID-7[[SCID-7]] | *Unique ID* - provide a facility to return a run time implementation unique identifier specific 287to that runtime so that is may be interrogated at any time. For example, such information could be the version number, name, date, release build number or a combination of these that is unique and comprehensible 288| SCID-8[[SCID-8]] | *Code complexity* - reducing code complexity to help facilitate certification (for example if there are multiple ways to do the same thing, potentially eliminating one or more of the alternative methods) 289|==== 290endif::VKSC_VERSION_1_0[] 291