1// Copyright (c) 2014-2020 Khronos Group. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[appendix] 6[[vulkansc-deviations]] 7= Vulkan SC Deviations From Base Vulkan 8 9== Additions 10The following extensions have been added to Vulkan SC: 11 12[width="95%",cols="60%,40%",options="header"] 13|=== 14| Extension | Level 15ifdef::VK_KHR_object_refresh[] 16|<<VK_KHR_object_refresh>> | Optional 17endif::VK_KHR_object_refresh[] 18|=== 19 20 21The following items have been added to Vulkan SC: 22 23[width="95%",cols="20%,80%",options="header"] 24|=== 25| Chapter a| Additions 26| <<fundamentals,Fundamentals>> a| include::{chapters}/fundamentals.adoc[tag=scaddition] 27| <<devsandqueues,Devices and Queues>> a| include::{chapters}/devsandqueues.adoc[tag=scaddition] 28| <<commandbuffers,Command Buffers>> a| include::{chapters}/cmdbuffers.adoc[tag=scaddition] 29| <<pipelines,Pipelines>> a| include::{chapters}/pipelines.adoc[tag=scaddition] 30| <<memory,Memory Allocation>> a| include::{chapters}/memory.adoc[tag=scaddition] 31| <<features,Features>> a| include::{chapters}/features.adoc[tag=scaddition] 32| <<debugging,Debugging>> a| include::{chapters}/fault_handling.adoc[tag=scaddition] 33|=== 34 35== Modifications 36The following aspects of Base Vulkan have been modified for Vulkan SC: 37 38ifdef::editing-notes[] 39[NOTE] 40.editing-note 41==== 42Table entries should be listed in the order listed in table of contents 43==== 44endif::editing-notes[] 45 46[width="95%",cols="20%,80%",options="header"] 47|=== 48| Chapter a| Modifications 49| <<fundamentals,Fundamentals>> a| include::{chapters}/fundamentals.adoc[tag=scdeviation] 50| <<devsandqueues,Devices and Queues>> a| include::{chapters}/devsandqueues.adoc[tag=scdeviation] 51| <<commandbuffers,Command Buffers>> a| include::{chapters}/cmdbuffers.adoc[tag=scdeviation] 52| <<pipelines,Pipelines>> a| include::{chapters}/pipelines.adoc[tag=scdeviation] 53| <<memory,Memory Allocation>> a| include::{chapters}/memory.adoc[tag=scdeviation] 54| <<resources,Resource Creation>> a| include::{chapters}/resources.adoc[tag=scdeviation] 55| <<descriptorsets,Resource Descriptors>> a| include::{chapters}/descriptorsets.adoc[tag=scdeviation] 56| <<sparsememory,Sparse Resources>> a| include::{chapters}/sparsemem.adoc[tag=scdeviation] 57| <<wsi,WSI Swapchain>> a| include::{chapters}/VK_KHR_swapchain/wsi.adoc[tag=scdeviation] 58| <<features,Features>> a| include::{chapters}/features.adoc[tag=scdeviation] 59| <<limits,Limits>> a| include::{chapters}/limits.adoc[tag=scdeviation] 60|=== 61 62== Removals 63The following functionality has been removed from Base Vulkan in Vulkan SC: 64 65ifdef::editing-notes[] 66[NOTE] 67.editing-note 68==== 69Table entries should be listed in the order listed in table of contents. 70==== 71endif::editing-notes[] 72 73[width="95%",cols="20%,80%",options="header"] 74|=== 75| Chapter a| Removals 76| <<fundamentals,Fundamentals>> a| include::{chapters}/fundamentals.adoc[tag=scremoved] 77| <<devsandqueues,Devices and Queues>> a| include::{chapters}/devsandqueues.adoc[tag=scremoved] 78| <<commandbuffers,Command Buffers>> a| include::{chapters}/cmdbuffers.adoc[tag=scremoved] 79| <<synchronization,Synchronization and Cache Control>> a| include::{chapters}/synchronization.adoc[tag=scremoved] 80| <<shaders,Shaders>> a| include::{chapters}/shaders.adoc[tag=scremoved] 81| <<pipelines,Pipelines>> a| include::{chapters}/pipelines.adoc[tag=scremoved] 82| <<memory,Memory Allocation>> a| include::{chapters}/memory.adoc[tag=scremoved] 83| <<descriptorsets,Resource Descriptors>> a| include::{chapters}/descriptorsets.adoc[tag=scremoved] 84| <<queries,Queries>> a| include::{chapters}/queries.adoc[tag=scremoved] 85| <<fragops,Fragment Operations>> a| include::{chapters}/fragops.adoc[tag=scremoved] 86| <<sparsememory,Sparse Resources>> a| include::{chapters}/sparsemem.adoc[tag=scremoved] 87| <<wsi,Window System Integration>> a| include::{chapters}/VK_KHR_surface/wsi.adoc[tag=scremoved] 88| <<wsi,WSI Swapchain>> a| include::{chapters}/VK_KHR_swapchain/wsi.adoc[tag=scremoved] 89|=== 90 91== Extension Support 92 93Vulkan SC supports a subset of the extensions supported in Base Vulkan. 94This subset was decided by: 95 96 * Excluding any extensions that would pose significant difficulty to 97 certify their implementations. 98 * Excluding any extension that would not be used in deployed devices. 99 This was primarily extensions focused on application development and 100 debug. 101 * Excluding any extensions that are specific to an Operating System or 102 Windowing system that is highly unlikely to be used in the Safety 103 Critical space. 104 * Non-KHR or EXT extension are supported on request. 105 106[NOTE] 107.Note 108==== 109During development it is likely that application developers will need 110additional functionality in a Vulkan SC implementation beyond what is 111provided by the supported extensions. 112This can be achieved by implementing a development focused version of the 113implementation that exposes additional Vulkan extensions and tools support 114but is non-conformant to the Vulkan SC specification. 115 116A Vulkan SC conformant implementation with this additional functionality 117removed will be used on the end device. 118==== 119 120== Fault and Error Handling 121 122Vulkan SC maintains the use of <<fundamentals-returncodes>> on a small 123number of commands. 124These allow the command to confirm it completed successfully or return an 125error code for situations where a failure could be detected at runtime 126during the execution of the command. 127 128In addition to <<fundamentals-returncodes>> Vulkan SC adds 129<<fault-handling>> support. 130This provides the implementation the ability to communicate information on 131errors or faults to the application that have been detected but are not 132covered by <<fundamentals-returncodes>> in the Vulkan SC API. 133These could be runtime failures of the system or application faults that are 134detected asynchronously to the Vulkan API commands. 135 136== Undefined Behavior in the API 137 138If an application uses the API incorrectly the behavior of the API is 139undefined:. 140The Vulkan SC runtime will perform minimal error and state checking and it 141is assumed that applications are using the API correctly, see 142<<fundamentals-validusage>>. 143 144With incorrect input to the API, the implementation could continue to 145function correctly, generate unexpected output, become unstable, or be 146terminated. 147The exact behavior will vary and be dependent on the specifics of the 148invalid usage and the implementation. 149 150It is primarily the application's responsibility to ensure it always uses 151the API correctly. 152Potential methods to detect incorrect API usage include performing manual 153code inspection, use of validation layers during development, use of 154validation layers at runtime, or adding runtime checking to the application. 155Outside of this, Vulkan SC implementations can: add implementation-specific 156targeted checks to detect invalid API usage that could significantly impact 157the correct operation of the application or implementation. 158The <<fault-handling>> extension allows implementations to communicate 159information on such occurrences. 160 161== MISRA C:2012 Deviations 162 163`{core_header}` is intended to be compatible with safety coding standards 164like MISRA C:2012. 165 166The following provides information on items a MISRA C code analysis tool 167may: report for a project using Vulkan SC. 168 169MISRA headline guidelines are copyright (C) The MISRA Consortium Limited and 170are reproduced with permission. 171For further explanation of the directives and rules please see the _MISRA 172C:2012_ specification (https://www.misra.org.uk/misra-c/). 173See _MISRA Compliance:2020_ 174(https://www.misra.org.uk/app/uploads/2021/06/MISRA-Compliance-2020.pdf) for 175a framework for handling deviations. 176 177=== Directives 178 179[width="100%",cols="15%,85%",options="header"] 180|=== 181|Directive |4.6: "_typedefs_ that indicate size and signedness should be used 182 in place of the basic numerical types" 183|Category |Advisory 184|Note |This is reported for every `char` and `float` variable used in the 185 API. 186|Rationale |Vulkan SC maintains the Base Vulkan type conventions for 187 compatibility between APIs. 188|=== 189 190=== Rules 191 192[width="100%",cols="15%,85%",options="header"] 193|=== 194|Rule |2.3: "A project should not contain unused type declarations" 195|Category |Advisory 196|Note |This is reported for any unused type definitions. 197|Rationale |The `{core_header}` provides a complete API definition and it is 198 expected that an application may: not use all the provided type declarations. 199|=== 200 201[width="100%",cols="15%,85%",options="header"] 202|=== 203|Rule |2.4: "A project should not contain unused tag declarations" 204|Category |Advisory 205|Note |This is reported for each instance of 206 `typedef struct VkStruct { ... } VkStruct;` and 207 `typedef enum VkEnum { ... } VkEnum;` where the tag declaration is 208 unused. 209|Rationale |The `{core_header}` provides a complete API definition and it is 210 expected that an application may: not use all the provided tag 211 declarations. 212 Vulkan SC maintains the Base Vulkan type conventions for 213 compatibility between APIs. 214 Tag declarations are required in case an application wishes to 215 make forward declarations to API-defined types. 216|=== 217 218[width="100%",cols="15%,85%",options="header"] 219|=== 220|Rule |2.5: "A project should not contain unused macro declarations" 221|Category |Advisory 222|Note |This is reported for every unused macro defined in the header. 223|Rationale |The `{core_header}` provides a complete API definition and it is 224 expected that an application may: not use all the provided macro 225 declarations. 226|=== 227 228[width="100%",cols="15%,85%",options="header"] 229|=== 230|Rule |5.1: "_External identifiers_ shall be distinct" 231|Category |Required 232|Note |This is reported for identifiers with names that do not differ in 233 the first 31 characters, such as 234 flink:vkGetPhysicalDeviceFormatProperties and 235 flink:vkGetPhysicalDeviceFormatProperties2. 236|Rationale |Vulkan SC maintains the Base Vulkan naming conventions for 237 compatibility between APIs. 238 Vulkan SC applications must: be built using a compiler that treats 239 enough characters as significant. 240|=== 241 242[width="100%",cols="15%,85%",options="header"] 243|=== 244|Rule |5.2: "Identifiers declared in the same _scope_ and name space 245 shall be distinct" 246|Category |Required 247|Note |This is reported for many code:typedef statements with long 248 identifiers. 249|Rationale |Vulkan SC maintains the Base Vulkan type and naming conventions for 250 compatibility between APIs. 251 Vulkan SC applications must: be built using a compiler that treats 252 enough characters as significant. 253|=== 254 255[width="100%",cols="15%,85%",options="header"] 256|=== 257|Rule |5.4: "_Macro identifiers_ shall be distinct" 258|Category |Required 259|Note |This is reported for macros with names that do not differ in the 260 first 31 characters, such as 261 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT and 262 ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT. 263|Rationale |Vulkan SC maintains the Base Vulkan naming conventions for 264 compatibility between APIs. 265 Vulkan SC applications must: be built using a compiler that treats 266 enough characters as significant. 267|=== 268 269[width="100%",cols="15%,85%",options="header"] 270|=== 271|Rule |8.6: "An identifier with external linkage shall have exactly one 272 external definition" 273|Category |Required 274|Note |This is reported for every API entry point declaration, and the 275 external definitions are provided by the implementation. 276|Rationale |It is expected that a Vulkan SC application will link against an 277 implementation that provides these definitions. 278|=== 279 280[width="100%",cols="15%,85%",options="header"] 281|=== 282|Rule |19.2: "The _union_ keyword should not be used" 283|Category |Advisory 284|Note |This is reported on the slink:VkClearColorValue, 285 slink:VkClearValue, and slink:VkPerformanceCounterResultKHR 286 unions. 287|Rationale |These are required to remain compatible with the Base Vulkan API. 288|=== 289 290[width="100%",cols="15%,85%",options="header"] 291|=== 292|Rule |20.1: "_#include_ directives should only be preceded by 293 preprocessor directives or comments" 294|Category |Advisory 295|Note |This is reported because the entire Vulkan SC API definition is 296 wrapped in an `extern "C"` block. 297|Rationale |This is expected because the Vulkan SC API is a C ABI and the 298 header may be included from C++ code. 299|=== 300 301[width="100%",cols="15%,85%",options="header"] 302|=== 303|Rule |20.10: "The # and ## preprocessor operators should not be used" 304|Category |Advisory 305|Note a|This is reported for the two lines: 306[source,c] 307--------------------------------------------------- 308#define VK_DEFINE_HANDLE(object) typedef struct object##_T* (object); 309#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *(object); 310--------------------------------------------------- 311|Rationale |This is expected usage of the macro expansion operation and there 312 are not multiple operators used in the statement. 313|=== 314