Add a layered driver extension proposal, docs, and xml

appendices/VK_MSFT_layered_driver.adoc

@@ -0,0 +1,31 @@
+// Copyright 2023 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+include::{generated}/meta/{refprefix}VK_MSFT_layered_driver.adoc[]
+
+=== Other Extension Metadata
+
+*Last Modified Date*::
+ 2023-06-21
+*IP Status*::
+ No known IP claims.
+*Contributors*::
+ - Jesse Natalie, Microsoft
+
+=== Description
+
+This extension adds new physical device properties to allow applications
+and the Vulkan ICD loader to understand when a physical device is
+implemented as a layered driver on top of another underlying API.
+
+include::{generated}/interfaces/VK_MSFT_layered_driver.adoc[]
+
+=== Examples
+
+None.
+
+=== Version History
+
+ * Revision 1, 2023-06-21 (Jesse Natalie)
+ ** Initial revision

chapters/devsandqueues.adoc

@@ -1135,6 +1135,36 @@ include::{generated}/validity/structs/VkPhysicalDeviceShaderTileImagePropertiesE
 --
 endif::VK_EXT_shader_tile_image[]
 
+ifdef::VK_MSFT_layered_driver[]
+[open,refpage='VkPhysicalDeviceLayeredDriverPropertiesMSFT',desc='Structure containing information about driver layering for a physical device',type='structs']
+--
+The sname:VkPhysicalDeviceLayeredDriverPropertiesMSFT structure is defined
+as:
+
+include::{generated}/api/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[]
+
+ * pname:sType is the type of this structure.
+ * pname:pNext is `NULL` or a pointer to a structure extending this
+ structure.
+ * pname:underlyingAPI is a elink:VkLayeredDriverUnderlyingApiMSFT value
+ indicating which underlying API is used to implement the layered driver,
+ or ename:VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT if the driver is not
+ layered.
+
+These are properties of the driver layering information of a physical device.
+
+include::{generated}/validity/structs/VkPhysicalDeviceLayeredDriverPropertiesMSFT.adoc[]
+--
+
+[open,refpage='VkLayeredDriverUnderlyingApiMSFT',desc='Layered driver underlying APIs',type='enums']
+--
+Underlying APIs which may: be returned in
+slink:VkPhysicalDeviceLayeredDriverPropertiesMSFT::pname:underlyingAPI are:
+
+include::{generated}/api/enums/VkLayeredDriverUnderlyingApiMSFT.adoc[]
+--
+endif::VK_MSFT_layered_driver[]
+
 [open,refpage='vkGetPhysicalDeviceQueueFamilyProperties',desc='Reports properties of the queues of the specified physical device',type='protos']
 --
 To query properties of queues available on a physical device, call:

proposals/VK_MSFT_layered_driver.adoc

@@ -0,0 +1,87 @@
+// Copyright 2021-2023 The Khronos Group Inc.
+//
+// SPDX-License-Identifier: CC-BY-4.0
+
+= Proposal Template
+:toc: left
+:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/
+:sectnums:
+
+This document proposes an extension to allow the loader to understand
+driver layering, for improving physical device sorting.
+
+== Problem Statement
+
+The Vulkan loader is able to sort physical devices according to
+platform-specific criteria. For example, on Windows, the loader uses LUIDs
+to put physical devices in the same order as DXGI adapters. However, it is
+possible to have multiple Vulkan drivers that provide support for the same
+physical device, for example, where one is a "native" vendor-provided
+implementation and another is a "layered" implementation on top of a
+different API. Examples of layered implementations would include VulkanOn12
+(aka Dozen), layered on D3D12, and MoltenVK, layered on Metal.
+
+On a system where a physical device has two possible drivers, the sort
+order between them is currently unspecified. An ideal sort order
+should place any native/un-layered drivers sorted-before any layered
+drivers, as it should be expected that native drivers will provide more
+functionality and higher performance, since layering inherently adds
+overhead. But the loader has no way of knowing which driver to prefer.
+
+An additional problem that is not addressed by this specification is the
+case where you have multiple "native" drivers for a single physical device.
+In that case, the sort order remains unspecified, as a correct ordering
+between drivers is non-obvious.
+
+== Solution Space
+
+Options that were considered include:
+* Special-casing well-known layered drivers in the Vulkan loader.
+* Extending the Loader-ICD interface to identify layered drivers.
+* Providing an extension to allow layered drivers to self-identify.
+
+The latter solution is the more general, and also has the benefit of
+allowing applications to understand when they're running on a layered
+driver.
+
+== Proposal
+
+The following properties are exposed by the `VK_MSFT_layered_driver`
+extension:
+[source,c]
+----
+typedef enum VkLayeredDriverUnderlyingApiMSFT {
+ VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT,
+ VK_LAYERED_DRIVER_UNDERLYING_API_D3D12_MSFT,
+} VkLayeredDriverUnderlyingApiMSFT;
+
+typedef struct VkPhysicalDeviceLayeredDriverPropertiesMSFT {
+ VkStructureType sType;
+ const void* pNext;
+ VkLayeredDriverUnderlyingApiMSFT underlyingAPI;
+} VkPhysicalDeviceLayeredDriverPropertiesMSFT;
+----
+
+Layered drivers should implement this extension. The Vulkan loader can then
+be updated to query for the this structure. If the `underlyingAPI` is not
+`NONE`, then the driver should be considered layered. The specific value of
+`underlyingAPI` is simply informational for applications to query if they
+so choose.
+
+== Issues
+
+=== RESOLVED: Is a string the right way to identify an underlying API?
+
+No, an enum is a much better solution. The same conclusion was already
+reached with the `VkDriverId` enum.
+
+== Further Functionality
+
+Additional properties of the layering implementation, such as underlying
+API object pointers, could be exposed, but considering that the nature of
+those will depend on the underlying API, it seems like those should be
+exposed via separate extensions, if at all.
+
+It might make sense to add things like driver version for the underlying
+driver, since the version information exposed through existing properties
+would refer to the version of layered implementation.

xml/vk.xml

@@ -781,6 +781,7 @@ typedef void* <name>MTLSharedEvent_id</name>;
  <type name="VkComponentTypeKHR" category="enum"/>
  <type category="enum" name="VkScopeNV" alias="VkScopeKHR"/>
  <type category="enum" name="VkComponentTypeNV" alias="VkComponentTypeKHR"/>
+ <type name="VkLayeredDriverUnderlyingApiMSFT" category="enum"/>
 
  <comment>WSI extensions</comment>
  <type name="VkColorSpaceKHR" category="enum"/>
@@ -8388,6 +8389,11 @@ typedef void* <name>MTLSharedEvent_id</name>;
  <member optional="true"><type>void</type>* <name>pNext</name></member>
  <member limittype="bitmask"><type>VkShaderStageFlags</type> <name>cooperativeMatrixSupportedStages</name></member>
  </type>
+ <type category="struct" name="VkPhysicalDeviceLayeredDriverPropertiesMSFT" structextends="VkPhysicalDeviceProperties2" returnedonly="true">
+ <member values="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_DRIVER_PROPERTIES_MSFT"><type>VkStructureType</type> <name>sType</name></member>
+ <member optional="true"><type>void</type>* <name>pNext</name></member>
+ <member><type>VkLayeredDriverUnderlyingApiMSFT</type> <name>underlyingAPI</name></member>
+ </type>
  </types>
 
 
@@ -10442,6 +10448,10 @@ typedef void* <name>MTLSharedEvent_id</name>;
  <enum value="9" name="VK_COMPONENT_TYPE_UINT32_KHR"/>
  <enum value="10" name="VK_COMPONENT_TYPE_UINT64_KHR"/>
  </enums>
+ <enums name="VkLayeredDriverUnderlyingApiMSFT" type="enum">
+ <enum value="0" name="VK_LAYERED_DRIVER_UNDERLYING_API_NONE_MSFT"/>
+ <enum value="1" name="VK_LAYERED_DRIVER_UNDERLYING_API_D3D12_MSFT"/>
+ </enums>
 
  <commands comment="Vulkan command definitions">
  <command successcodes="VK_SUCCESS" errorcodes="VK_ERROR_OUT_OF_HOST_MEMORY,VK_ERROR_OUT_OF_DEVICE_MEMORY,VK_ERROR_INITIALIZATION_FAILED,VK_ERROR_LAYER_NOT_PRESENT,VK_ERROR_EXTENSION_NOT_PRESENT,VK_ERROR_INCOMPATIBLE_DRIVER">
@@ -22521,10 +22531,13 @@ typedef void* <name>MTLSharedEvent_id</name>;
  <command name="vkGetScreenBufferPropertiesQNX"/>
  </require>
  </extension>
- <extension name="VK_MSFT_extension_531" number="531" author="MSFT" contact="Jesse Natalie @jenatali" supported="disabled">
+ <extension name="VK_MSFT_layered_driver" number="531" type="device" depends="VK_KHR_get_physical_device_properties2" author="MSFT" contact="Jesse Natalie @jenatali" supported="vulkan">
  <require>
- <enum value="0" name="VK_MSFT_EXTENSION_531_SPEC_VERSION"/>
- <enum value="&quot;VK_MSFT_extension_531&quot;" name="VK_MSFT_EXTENSION_531_EXTENSION_NAME"/>
+ <enum value="1" name="VK_MSFT_LAYERED_DRIVER_SPEC_VERSION"/>
+ <enum value="&quot;VK_MSFT_layered_driver&quot;" name="VK_MSFT_LAYERED_DRIVER_EXTENSION_NAME"/>
+ <enum offset="0" extends="VkStructureType" name="VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_LAYERED_DRIVER_PROPERTIES_MSFT"/>
+ <type name="VkLayeredDriverUnderlyingApiMSFT"/>
+ <type name="VkPhysicalDeviceLayeredDriverPropertiesMSFT"/>
  </require>
  </extension>
  <extension name="VK_KHR_extension_532" number="532" author="KHR" contact="Tobias Hector @tobias" supported="disabled">