1// Copyright 2021-2022 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= VK_LUNARG_direct_driver_loading 6 7:toc: left 8:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ 9:sectnums: 10 11Adds an extension that allows applications to provide drivers to the loader during 12instance creation. 13 14== Problem Statement 15 16There are several uses cases that cause applications to want to ship a driver with 17themselves. Adding a fallback CPU driver is necessary in many web browsers to 18support hardware which does not support vulkan, as well as for testing 19infrastructure where hardware might not be available. While there are currently 20several desktop Vulkan Loader mechanisms that allow applications to provide 21drivers, they all suffer from various shortcomings. A non comprehensive list is 22detailed below. 23 24* Some require an installer to be run. This necessitates an uninstaller, as well 25as makes the driver 'global' to the system or user. 26* They may require elevated privileges to use, such as with an installer, or 27causes the solution to fail when running with elevated privileges, as with 28Environment Variables. 29 30== Current Solution Space 31 32* Installation to OS specific locations 33 a. Explicit installer and uninstaller needs to be run 34 b. Global to all applications 35 c. Requires elevated privileges in most cases 36* Environment Variables 37 a. Disabled when running with elevated privileges due to the security concerns 38 b. Tedious to setup since they require the full path to the driver manifest 39* MacOS Bundles - Allows placing the .dylib inside a relocatable package, loader knows how to look in them 40 a. Not available for any other platform 41* Looking in current working directory 42 a. Disabled when running with elevated privileges, as that is an attack vector 43 44== Proposal 45 46`VK_LUNARG_direct_driver_loading` extends the pNext chain of 47link:{refpage}VkInstanceCreateInfo.html[VkInstanceCreateInfo] to provide a list 48of structures which contain the information needed by the loader to load the drivers. 49This is achieved by providing the driver's link:{refpage}vkGetInstanceProcAddr.html[vkGetInstanceProcAddr], 50bypassing the loaders need to use the systems dynamic linker to load the drivers functions. 51 52The extension also allows applications to use provided drivers exclusively, so that no 53drivers found on the system are loaded. 54 55This satisfies the requirements: 56 57 * Isolated from all other running processes. 58 * No installation required. 59 * Works when the application is running with elevated privileges. 60 61The intent of the extension is to be implemented in the desktop Vulkan-Loader. 62 63[source,c] 64---- 65typedef struct VkDirectDriverLoadingInfoLUNARG { 66 VkStructureType sType; 67 const void* pNext; 68 VkDirectDriverLoadingFlagsLUNARG flags; 69 PFN_vkGetInstanceProcAddr pfnGetInstanceProcAddr; 70} VkDirectDriverLoadingInfoLUNARG; 71 72typedef struct VkDirectDriverLoadingListLUNARG { 73 VkStructureType sType; 74 const void* pNext; 75 VkDirectDriverLoadingModeLUNARG mode; 76 uint32_t driverCount; 77 const VkDirectDriverLoadingInfoLUNARG* pDrivers; 78} VkDirectDriverLoadingListLUNARG; 79 80typedef enum VkDirectDriverLoadingModeLUNARG { 81 VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG = 0, 82 VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG = 1, 83 VK_DIRECT_DRIVER_LOADING_MODE_MAX_ENUM_LUNARG = 0x7FFFFFFF 84} VkDirectDriverLoadingModeLUNARG; 85---- 86 87`VkDirectDriverLoadingModeLUNARG` allows applications to choose whether to load 88only the drivers they provide or include the drivers they provide with all of 89the drivers the Vulkan Loader finds on the system. 90 91There is a known defect with this extension. When the application queries the 92list of instance extensions, there is no way to provide to the Vulkan Loader the 93list of application provided drivers, to combine the driver's extensions with 94the extensions supported by the drivers and implicit layers on the system. As a 95workaround, applications can instead load the vkEnumerateInstanceExtensionProperties 96entrypoint from the provided drivers instead to get their list of extensions. 97 98This workaround has a known defect when all of the following is true: 99 1001. An application uses VK_LUNARG_direct_driver_loading to add drivers. 1012. A layer (that will be enabled) filters out unsupported extensions during 102calls to vkEnumerateInstanceExtensionProperties entrypoint. 1033. The application enables instance extensions in VkInstanceCreateInfo 104which are supported by the application provided driver but not the layer(s). 105 106As the application directly calls the driver's vkEnumerateInstanceExtensionProperties 107instead of the loader's, this prevents layers from being able to modify the list of 108extensions. Since the layer will not be able to filter out unsupported instance 109extensions, the layer may fail to work, cause bugs elsewhere, or crash. 110 111 112== Example Usage 113 114This example shows typical usage where the provided driver should be the ONLY driver found. 115It uses `VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG` to prevent the loader from loading 116any drivers on the system, useful for use when running under testing conditions. 117 118```c 119 120VkDirectDriverLoadingInfoLUNARG app_provided_driver{}; 121app_provided_driver.sType = VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_INFO_LUNARG; 122app_provided_driver.pfnGetInstanceProcAddr = /* address of drivers function pointer*/ 123 124VkDirectDriverLoadingListLUNARG direct_driver_loading{}; 125direct_driver_loading.sType = VK_STRUCTURE_TYPE_DIRECT_DRIVER_LOADING_LIST_LUNARG; 126direct_driver_loading.mode = VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG; // Do not load any other drivers 127direct_driver_loading.driverCount = 1; 128direct_driver_loading.pDrivers = &app_provided_driver; 129 130VkInstanceCreateInfo instance_info{}; 131instance_info.pNext = &direct_driver_loading; 132 133vkCreateInstance(&instance_info, NULL, inst); 134``` 135 136== Issues 137 138=== RESOLVED: Global functions are not extensible 139 140Since this proposal allows adding drivers, and vkEnumerateInstanceExtensionProperties 141returns the list of extensions supported by drivers on the system, the application 142must either 'know' which extensions the provided drivers support or query them 143directly then manually enable the extensions in VkInstanceCreateInfo. 144While it is an adequate solution for most use cases, it does create a corner case 145when layers that modify the instance extension list are present. Fundamentally 146it is a problem with the design of extension enumeration and instance creation. 147While it is possible to add functionality to this extension which resolves the 148issue, it is better solved with its own extension since there are more issues 149with instance creation that need addressing than what this extension accomplishes. 150 151=== RESOLVED: Should this extension also handle layer loading? 152 153No, layers require significantly more information to be present for the loader 154to handle correctly, and have the same defect of global functions not being extensible. 155 156=== RESOLVED: Do drivers implement this extension? 157 158No, this would be implemented by the Vulkan Loader. 159 160=== RESOLVED: Are there any changes drivers need to make to allow being used in this extension? 161 162Partially, drivers do not need modification to work today. However, to support 163all of the features of the Loader-ICD interface, they will need to support the 164"Loader-ICD interface version 7". This version requires that all currently 165exported entry points in the Loader-ICD interface be queryable through 166vkGetInstanceProcAddr, which is simple addition. 167