xref: /third_party/vk-gl-cts/external/vulkan-docs/src/appendices/vulkanscdeviations.adoc

// Copyright (c) 2014-2020 Khronos Group.
//
// SPDX-License-Identifier: CC-BY-4.0

[appendix]
[[vulkansc-deviations]]
= Vulkan SC Deviations From Base Vulkan

== Additions
The following extensions have been added to Vulkan SC:

[width="95%",cols="60%,40%",options="header"]
|===
| Extension | Level
ifdef::VK_KHR_object_refresh[]
|<<VK_KHR_object_refresh>> | Optional
endif::VK_KHR_object_refresh[]
|===


The following items have been added to Vulkan SC:

[width="95%",cols="20%,80%",options="header"]
|===
| Chapter a| Additions
| <<fundamentals,Fundamentals>> a| include::{chapters}/fundamentals.adoc[tag=scaddition]
| <<devsandqueues,Devices and Queues>> a| include::{chapters}/devsandqueues.adoc[tag=scaddition]
| <<commandbuffers,Command Buffers>> a| include::{chapters}/cmdbuffers.adoc[tag=scaddition]
| <<pipelines,Pipelines>> a| include::{chapters}/pipelines.adoc[tag=scaddition]
| <<memory,Memory Allocation>> a| include::{chapters}/memory.adoc[tag=scaddition]
| <<features,Features>> a| include::{chapters}/features.adoc[tag=scaddition]
| <<debugging,Debugging>> a| include::{chapters}/fault_handling.adoc[tag=scaddition]
|===

== Modifications
The following aspects of Base Vulkan have been modified for Vulkan SC:

ifdef::editing-notes[]
[NOTE]
.editing-note
====
Table entries should be listed in the order listed in table of contents
====
endif::editing-notes[]

[width="95%",cols="20%,80%",options="header"]
|===
| Chapter a| Modifications
| <<fundamentals,Fundamentals>> a| include::{chapters}/fundamentals.adoc[tag=scdeviation]
| <<devsandqueues,Devices and Queues>> a| include::{chapters}/devsandqueues.adoc[tag=scdeviation]
| <<commandbuffers,Command Buffers>> a| include::{chapters}/cmdbuffers.adoc[tag=scdeviation]
| <<pipelines,Pipelines>> a| include::{chapters}/pipelines.adoc[tag=scdeviation]
| <<memory,Memory Allocation>> a| include::{chapters}/memory.adoc[tag=scdeviation]
| <<resources,Resource Creation>> a| include::{chapters}/resources.adoc[tag=scdeviation]
| <<descriptorsets,Resource Descriptors>> a| include::{chapters}/descriptorsets.adoc[tag=scdeviation]
| <<sparsememory,Sparse Resources>> a| include::{chapters}/sparsemem.adoc[tag=scdeviation]
| <<wsi,WSI Swapchain>> a| include::{chapters}/VK_KHR_swapchain/wsi.adoc[tag=scdeviation]
| <<features,Features>> a| include::{chapters}/features.adoc[tag=scdeviation]
| <<limits,Limits>> a| include::{chapters}/limits.adoc[tag=scdeviation]
|===

== Removals
The following functionality has been removed from Base Vulkan in Vulkan SC:

ifdef::editing-notes[]
[NOTE]
.editing-note
====
Table entries should be listed in the order listed in table of contents.
====
endif::editing-notes[]

[width="95%",cols="20%,80%",options="header"]
|===
| Chapter a| Removals
| <<fundamentals,Fundamentals>> a| include::{chapters}/fundamentals.adoc[tag=scremoved]
| <<devsandqueues,Devices and Queues>> a| include::{chapters}/devsandqueues.adoc[tag=scremoved]
| <<commandbuffers,Command Buffers>> a| include::{chapters}/cmdbuffers.adoc[tag=scremoved]
| <<synchronization,Synchronization and Cache Control>> a| include::{chapters}/synchronization.adoc[tag=scremoved]
| <<shaders,Shaders>> a| include::{chapters}/shaders.adoc[tag=scremoved]
| <<pipelines,Pipelines>> a| include::{chapters}/pipelines.adoc[tag=scremoved]
| <<memory,Memory Allocation>> a| include::{chapters}/memory.adoc[tag=scremoved]
| <<descriptorsets,Resource Descriptors>> a| include::{chapters}/descriptorsets.adoc[tag=scremoved]
| <<queries,Queries>> a| include::{chapters}/queries.adoc[tag=scremoved]
| <<fragops,Fragment Operations>> a| include::{chapters}/fragops.adoc[tag=scremoved]
| <<sparsememory,Sparse Resources>> a| include::{chapters}/sparsemem.adoc[tag=scremoved]
| <<wsi,Window System Integration>> a| include::{chapters}/VK_KHR_surface/wsi.adoc[tag=scremoved]
| <<wsi,WSI Swapchain>> a| include::{chapters}/VK_KHR_swapchain/wsi.adoc[tag=scremoved]
|===

== Extension Support

Vulkan SC supports a subset of the extensions supported in Base Vulkan.
This subset was decided by:

  * Excluding any extensions that would pose significant difficulty to
    certify their implementations.
  * Excluding any extension that would not be used in deployed devices.
    This was primarily extensions focused on application development and
    debug.
  * Excluding any extensions that are specific to an Operating System or
    Windowing system that is highly unlikely to be used in the Safety
    Critical space.
  * Non-KHR or EXT extension are supported on request.

[NOTE]
.Note
====
During development it is likely that application developers will need
additional functionality in a Vulkan SC implementation beyond what is
provided by the supported extensions.
This can be achieved by implementing a development focused version of the
implementation that exposes additional Vulkan extensions and tools support
but is non-conformant to the Vulkan SC specification.

A Vulkan SC conformant implementation with this additional functionality
removed will be used on the end device.
====

== Fault and Error Handling

Vulkan SC maintains the use of <<fundamentals-returncodes>> on a small
number of commands.
These allow the command to confirm it completed successfully or return an
error code for situations where a failure could be detected at runtime
during the execution of the command.

In addition to <<fundamentals-returncodes>> Vulkan SC adds
<<fault-handling>> support.
This provides the implementation the ability to communicate information on
errors or faults to the application that have been detected but are not
covered by <<fundamentals-returncodes>> in the Vulkan SC API.
These could be runtime failures of the system or application faults that are
detected asynchronously to the Vulkan API commands.

== Undefined Behavior in the API

If an application uses the API incorrectly the behavior of the API is
undefined:.
The Vulkan SC runtime will perform minimal error and state checking and it
is assumed that applications are using the API correctly, see
<<fundamentals-validusage>>.

With incorrect input to the API, the implementation could continue to
function correctly, generate unexpected output, become unstable, or be
terminated.
The exact behavior will vary and be dependent on the specifics of the
invalid usage and the implementation.

It is primarily the application's responsibility to ensure it always uses
the API correctly.
Potential methods to detect incorrect API usage include performing manual
code inspection, use of validation layers during development, use of
validation layers at runtime, or adding runtime checking to the application.
Outside of this, Vulkan SC implementations can: add implementation-specific
targeted checks to detect invalid API usage that could significantly impact
the correct operation of the application or implementation.
The <<fault-handling>> extension allows implementations to communicate
information on such occurrences.

== MISRA C:2012 Deviations

`{core_header}` is intended to be compatible with safety coding standards
like MISRA C:2012.

The following provides information on items a MISRA C code analysis tool
may: report for a project using Vulkan SC.

MISRA headline guidelines are copyright (C) The MISRA Consortium Limited and
are reproduced with permission.
For further explanation of the directives and rules please see the _MISRA
C:2012_ specification (https://www.misra.org.uk/misra-c/).
See _MISRA Compliance:2020_
(https://www.misra.org.uk/app/uploads/2021/06/MISRA-Compliance-2020.pdf) for
a framework for handling deviations.

=== Directives

[width="100%",cols="15%,85%",options="header"]
|===
|Directive  |4.6: "_typedefs_ that indicate size and signedness should be used
             in place of the basic numerical types"
|Category   |Advisory
|Note       |This is reported for every `char` and `float` variable used in the
             API.
|Rationale  |Vulkan SC maintains the Base Vulkan type conventions for
             compatibility between APIs.
|===

=== Rules

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |2.3: "A project should not contain unused type declarations"
|Category   |Advisory
|Note       |This is reported for any unused type definitions.
|Rationale  |The `{core_header}` provides a complete API definition and it is
             expected that an application may: not use all the provided type declarations.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |2.4: "A project should not contain unused tag declarations"
|Category   |Advisory
|Note       |This is reported for each instance of
             `typedef struct VkStruct { ... } VkStruct;` and
             `typedef enum VkEnum { ... } VkEnum;` where the tag declaration is
             unused.
|Rationale  |The `{core_header}` provides a complete API definition and it is
             expected that an application may: not use all the provided tag
             declarations.
             Vulkan SC maintains the Base Vulkan type conventions for
             compatibility between APIs.
             Tag declarations are required in case an application wishes to
             make forward declarations to API-defined types.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |2.5: "A project should not contain unused macro declarations"
|Category   |Advisory
|Note       |This is reported for every unused macro defined in the header.
|Rationale  |The `{core_header}` provides a complete API definition and it is
             expected that an application may: not use all the provided macro
             declarations.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |5.1: "_External identifiers_ shall be distinct"
|Category   |Required
|Note       |This is reported for identifiers with names that do not differ in
             the first 31 characters, such as
             flink:vkGetPhysicalDeviceFormatProperties and
             flink:vkGetPhysicalDeviceFormatProperties2.
|Rationale  |Vulkan SC maintains the Base Vulkan naming conventions for
             compatibility between APIs.
             Vulkan SC applications must: be built using a compiler that treats
             enough characters as significant.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |5.2: "Identifiers declared in the same _scope_ and name space
             shall be distinct"
|Category   |Required
|Note       |This is reported for many code:typedef statements with long
             identifiers.
|Rationale  |Vulkan SC maintains the Base Vulkan type and naming conventions for
             compatibility between APIs.
             Vulkan SC applications must: be built using a compiler that treats
             enough characters as significant.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |5.4: "_Macro identifiers_ shall be distinct"
|Category   |Required
|Note       |This is reported for macros with names that do not differ in the
             first 31 characters, such as
             ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_READ_BIT and
             ename:VK_ACCESS_DEPTH_STENCIL_ATTACHMENT_WRITE_BIT.
|Rationale  |Vulkan SC maintains the Base Vulkan naming conventions for
             compatibility between APIs.
             Vulkan SC applications must: be built using a compiler that treats
             enough characters as significant.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |8.6: "An identifier with external linkage shall have exactly one
             external definition"
|Category   |Required
|Note       |This is reported for every API entry point declaration, and the
             external definitions are provided by the implementation.
|Rationale  |It is expected that a Vulkan SC application will link against an
             implementation that provides these definitions.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |19.2: "The _union_ keyword should not be used"
|Category   |Advisory
|Note       |This is reported on the slink:VkClearColorValue,
             slink:VkClearValue, and slink:VkPerformanceCounterResultKHR
             unions.
|Rationale  |These are required to remain compatible with the Base Vulkan API.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |20.1: "_#include_ directives should only be preceded by
             preprocessor directives or comments"
|Category   |Advisory
|Note       |This is reported because the entire Vulkan SC API definition is
             wrapped in an `extern "C"` block.
|Rationale  |This is expected because the Vulkan SC API is a C ABI and the
             header may be included from C++ code.
|===

[width="100%",cols="15%,85%",options="header"]
|===
|Rule       |20.10: "The # and ## preprocessor operators should not be used"
|Category   |Advisory
|Note      a|This is reported for the two lines:
[source,c]
---------------------------------------------------
#define VK_DEFINE_HANDLE(object) typedef struct object##_T* (object);
#define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *(object);
---------------------------------------------------
|Rationale  |This is expected usage of the macro expansion operation and there
             are not multiple operators used in the statement.
|===