From c92dc10e91788a957c6ca4b10807bf414b8d0e05 Mon Sep 17 00:00:00 2001 From: Lenny Komow Date: Tue, 7 Nov 2017 11:26:49 -0700 Subject: docs: Update loader doc for 1.0 ICD handling The 1.1 loader has to handle 1.0 ICDs specially during instance creation. This commit documents that behavior. --- loader/LoaderAndLayerInterface.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'loader/LoaderAndLayerInterface.md') diff --git a/loader/LoaderAndLayerInterface.md b/loader/LoaderAndLayerInterface.md index 2e96ef6a..2313ad03 100644 --- a/loader/LoaderAndLayerInterface.md +++ b/loader/LoaderAndLayerInterface.md @@ -35,6 +35,7 @@ * [ICD Discovery](#icd-discovery) * [ICD Manifest File Format](#icd-manifest-file-format) * [ICD Vulkan Entry-Point Discovery](#icd-vulkan-entry-point-discovery) + * [ICD API Version](#icd-api-version) * [ICD Unknown Physical Device Extensions](#icd-unknown-physical-device-extensions) * [ICD Dispatchable Object Creation](#icd-dispatchable-object-creation) * [Handling KHR Surface Objects in WSI Extensions](#handling-khr-surface-objects-in-wsi-extensions) @@ -1978,6 +1979,7 @@ ICD to properly hand-shake. * [ICD Manifest File Versions](#icd-manifest-file-versions) * [ICD Manifest File Version 1.0.0](#icd-manifest-file-version-1.0.0) * [ICD Vulkan Entry-Point Discovery](#icd-vulkan-entry-point-discovery) + * [ICD API Version](#icd-api-version) * [ICD Unknown Physical Device Extensions](#icd-unknown-physical-device-extensions) * [ICD Dispatchable Object Creation](#icd-dispatchable-object-creation) * [Handling KHR Surface Objects in WSI Extensions](#handling-khr-surface-objects-in-wsi-extensions) @@ -2323,6 +2325,41 @@ names are used. On Linux, if official names are used, the ICD library must be linked with -Bsymbolic. +### ICD API Version +When an application calls `vkCreateInstance`, it can optionally include a +`VkApplicationInfo` struct, which includes an `apiVersion` field. A Vulkan 1.0 +ICD was required to return `VK_ERROR_INCOMPATIBLE_DRIVER` if it did not +support the API version that the user passed. Beginning with Vulkan 1.1, ICDs +are not allowed to return this error for any value of `apiVersion`. This +creates a problem when working with multiple ICDs, where one is a 1.0 ICD and +another is newer. + +A loader that is newer than 1.0 will always give the version it supports when +the application calls `vkEnumerateInstanceVersion`, regardless of the API +version supported by the ICDs on the system. This means that when the +application calls `vkCreateInstance`, the loader will be forced to pass a copy +of the `VkApplicationInfo` struct where `apiVersion` is 1.0 to any 1.0 drivers +in order to prevent an error. To determine if this must be done, the loader +will perform the following steps: + +1. Load the ICD's dynamic library +2. Call the ICD's `vkGetInstanceProcAddr` command to get a pointer to +`vkEnumerateInstanceVersion` +3. If the pointer to `vkEnumerateInstanceVersion` is not `NULL`, it will be +called to get the ICD's supported API version + +The ICD will be treated as a 1.0 ICD if any of the following conditions are met: + +- The function pointer to `vkEnumerateInstanceVersion` is `NULL` +- The version returned by `vkEnumerateInstanceVersion` is less than 1.1 +- `vkEnumerateInstanceVersion` returns anything other than `VK_SUCCESS` + +If the ICD only supports Vulkan 1.0, the loader will ensure that any +`VkApplicationInfo` struct that is passed to the ICD will have an `apiVersion` +field set to Vulkan 1.0. Otherwise, the loader will pass the struct to the ICD +without any changes. + + ### ICD Unknown Physical Device Extensions Originally, if the loader was called with `vkGetInstanceProcAddr`, it would -- cgit v1.2.3