1// Copyright 2015-2023 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-informative-language]] 73=== Informative Language 74 75Some language in the specification is purely informative, intended to give 76background or suggestions to implementors or developers. 77 78If an entire chapter or section contains only informative language, its 79title will be suffixed with "`(Informative)`". 80 81All NOTEs are implicitly informative. 82 83 84[[introduction-normative-terminology]] 85=== Normative Terminology 86 87Within this specification, the key words *must*, *required*, *should*, 88*recommended*, *may*, and *optional* are to be interpreted as described in 89https://www.ietf.org/rfc/rfc2119.txt[RFC 2119 - Key words for use in RFCs to 90Indicate Requirement Levels] (https://www.ietf.org/rfc/rfc2119.txt). 91The additional key word *optionally* is an alternate form of *optional*, for 92use where grammatically appropriate. 93 94These key words are highlighted in the specification for clarity. 95In text addressing application developers, their use expresses requirements 96that apply to application behavior. 97In text addressing implementors, their use expresses requirements that apply 98to implementations. 99 100In text addressing application developers, the additional key words *can* 101and *cannot* are to be interpreted as describing the capabilities of an 102application, as follows: 103 104*can*:: 105This word means that the application is able to perform the action 106described. 107 108*cannot*:: 109This word means that the API and/or the execution environment provide no 110mechanism through which the application can express or accomplish the action 111described. 112 113These key words are never used in text addressing implementors. 114 115[NOTE] 116.Note 117==== 118There is an important distinction between *cannot* and *must not*, as used 119in this Specification. 120*Cannot* means something the application literally is unable to express or 121accomplish through the API, while *must not* means something that the 122application is capable of expressing through the API, but that the 123consequences of doing so are undefined: and potentially unrecoverable for 124the implementation (see <<fundamentals-validusage>>). 125==== 126 127Unless otherwise noted in the section heading, all sections and appendices 128in this document are normative. 129 130 131[[introduction-technical-terminology]] 132=== Technical Terminology 133 134The Vulkan Specification makes use of common engineering and graphics terms 135such as *Pipeline*, *Shader*, and *Host* to identify and describe Vulkan API 136constructs and their attributes, states, and behaviors. 137The <<glossary,Glossary>> defines the basic meanings of these terms in the 138context of the Specification. 139The Specification text provides fuller definitions of the terms and may 140elaborate, extend, or clarify the <<glossary,Glossary>> definitions. 141When a term defined in the <<glossary,Glossary>> is used in normative 142language within the Specification, the definitions within the Specification 143govern and supersede any meanings the terms may have in other technical 144contexts (i.e. outside the Specification). 145 146 147[[introduction-normative-references]] 148=== Normative References 149 150References to external documents are considered normative references if the 151Specification uses any of the normative terms defined in 152<<introduction-normative-terminology>> to refer to them or their 153requirements, either as a whole or in part. 154 155The following documents are referenced by normative sections of the 156specification: 157 158[[ieee-754]] 159IEEE. 160August, 2008. 161_IEEE Standard for Floating-Point Arithmetic_. 162IEEE Std 754-2008. 163https://dx.doi.org/10.1109/IEEESTD.2008.4610935 . 164 165[[data-format]] Andrew Garrard. 166_Khronos Data Format Specification, version 1.3_. 167https://registry.khronos.org/DataFormat/specs/1.3/dataformat.1.3.html . 168 169[[spirv-extended]] John Kessenich. 170_SPIR-V Extended Instructions for GLSL, Version 1.00_ (February 10, 2016). 171https://registry.khronos.org/spir-v/ . 172 173[[spirv-spec]] John Kessenich, Boaz Ouriel, and Raun Krisch. 174_SPIR-V Specification, Version 1.5, Revision 3, Unified_ (April 24, 2020). 175https://registry.khronos.org/spir-v/ . 176 177[[itu-t-h264]] 178ITU-T. 179_H.264 Advanced Video Coding for Generic Audiovisual Services_ (August, 1802021). 181https://www.itu.int/rec/T-REC-H.264-202108-I/ . 182 183[[itu-t-h265]] 184ITU-T. 185_H.265 High Efficiency Video Coding_ (August, 2021). 186https://www.itu.int/rec/T-REC-H.265-202108-I/ . 187 188[[vulkan-registry]] Jon Leech. 189_The Khronos Vulkan API Registry_ (February 26, 2023). 190https://registry.khronos.org/vulkan/specs/1.3/registry.html . 191 192[[vulkan-styleguide]] Jon Leech and Tobias Hector. 193_Vulkan Documentation and Extensions: Procedures and Conventions_ (February 19426, 2023). 195https://registry.khronos.org/vulkan/specs/1.3/styleguide.html . 196 197[[LoaderInterfaceArchitecture]] 198_Architecture of the Vulkan Loader Interfaces_ (October, 2021). 199https://github.com/KhronosGroup/Vulkan-Loader/blob/master/docs/LoaderInterfaceArchitecture.md 200. 201 202ifdef::VKSC_VERSION_1_0[] 203[[introduction-vulkansc-philosophy]] 204== Safety Critical Philosophy 205 206Vulkan SC {revnumber} is based on Vulkan 1.2 and, except where explicitly 207noted, supports all of the same features, properties, and limits as Vulkan 2081.2. 209 210Throughout the Vulkan SC specification, changes have been made to the Base 211Vulkan Specification in order to align it with safety critical use cases and 212certification. 213In general changes were made to meet the following categories: 214 215 * Deterministic Execution (predictable execution times and results) 216 * Robustness (error handling, removing ambiguity, clarifying undefined: 217 behavior) 218 * Simplification (changes made to reduce certification effort and 219 challenges) 220 221To simplify capturing the reasoning behind deviations made from the Base 222Vulkan Specification, the Vulkan SC specification utilizes change 223identifications to give the reader insight into why the change was made in a 224concise manner. 225The change identifications are captured in 226<<introduction-vulkansc-change-justification-table>>. 227In addition, the Vulkan SC specification contains <<vulkansc-deviations>> 228which is a complete list of changes between Base Vulkan and Vulkan SC. 229This is targeted at readers who are familiar with Base Vulkan and would like 230to understand the differences between Vulkan SC and the Base Vulkan 231specification. 232 233Vulkan SC follows the Base Vulkan philosophy of requiring valid usage from 234the application. 235It is left to each implementation to determine how to ensure safe operation 236with respect to invalid usage. 237This may: involve determining that certain invalid usage does not pose a 238safety risk, adding valid usage checks in the driver, requiring valid usage 239checks in the application, or some combination of these. 240Additionally, validation layers are supported during development. 241 242[[introduction-vulkansc-change-justification-table]] 243=== Change Justification Table 244 245The following is a list of the safety critical change identifications used 246to concisely capture the justification for deviations from the Base Vulkan 247Specification. 248 249.Change Justifications 250[width="100%",options="header",cols="15h,~"] 251|==== 252| Change ID | Description 253| SCID-1[[SCID-1]] | *Deterministic behavior* - no randomness or unpredictability, always produce the same output from a given starting condition or initial state 254| 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 255| 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 256| 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 257| 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) 258| 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 259| SCID-7[[SCID-7]] | *Unique ID* - provide a facility to return a run time implementation unique identifier specific 260to 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 261| 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) 262|==== 263endif::VKSC_VERSION_1_0[] 264