• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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