Lines Matching +full:vulkan +full:- +full:device +full:- +full:select +full:- +full:layer
1 <!-- markdownlint-disable MD041 -->
2 [![Khronos Vulkan][1]][2]
4 [1]: https://vulkan.lunarg.com/img/Vulkan_100px_Dec16.png "https://www.khronos.org/vulkan/"
5 [2]: https://www.khronos.org/vulkan/
7 # Driver interface to the Vulkan Loader <!-- omit from toc -->
10 <!-- Copyright © 2015-2023 LunarG, Inc. -->
12 [3]: https://i.creativecommons.org/l/by-nd/4.0/88x31.png "Creative Commons License"
13 [4]: https://creativecommons.org/licenses/by-nd/4.0/
16 ## Table of Contents <!-- omit from toc -->
18 - [Overview](#overview)
19 - [Driver Discovery](#driver-discovery)
20 - [Overriding the Default Driver Discovery](#overriding-the-default-driver-discovery)
21 - [Additional Driver Discovery](#additional-driver-discovery)
22 - [Driver Filtering](#driver-filtering)
23 - [Driver Select Filtering](#driver-select-filtering)
24 - [Driver Disable Filtering](#driver-disable-filtering)
25 - [Exception for Elevated Privileges](#exception-for-elevated-privileges)
26 - [Examples](#examples)
27 - [On Windows](#on-windows)
28 - [On Linux](#on-linux)
29 - [On macOS](#on-macos)
30 - [Driver Manifest File Usage](#driver-manifest-file-usage)
31 - [Driver Discovery on Windows](#driver-discovery-on-windows)
32 - [Driver Discovery on Linux](#driver-discovery-on-linux)
33 - [Example Linux Driver Search Path](#example-linux-driver-search-path)
34 - [Driver Discovery on Fuchsia](#driver-discovery-on-fuchsia)
35 - [Driver Discovery on macOS](#driver-discovery-on-macos)
36 - [Example macOS Driver Search Path](#example-macos-driver-search-path)
37 - [Additional Settings For Driver Debugging](#additional-settings-for-driver-debugging)
38 …- [Driver Discovery using the`VK_LUNARG_direct_driver_loading` extension](#driver-discovery-using-…
39 - [How to use `VK_LUNARG_direct_driver_loading`](#how-to-use-vk_lunarg_direct_driver_loading)
40 …- [Interactions with other driver discovery mechanisms](#interactions-with-other-driver-discovery-…
41 …- [Limitations of `VK_LUNARG_direct_driver_loading`](#limitations-of-vk_lunarg_direct_driver_loadi…
42 - [Using Pre-Production ICDs or Software Drivers](#using-pre-production-icds-or-software-drivers)
43 - [Driver Discovery on Android](#driver-discovery-on-android)
44 - [Driver Manifest File Format](#driver-manifest-file-format)
45 - [Driver Manifest File Versions](#driver-manifest-file-versions)
46 - [Driver Manifest File Version 1.0.0](#driver-manifest-file-version-100)
47 - [Driver Manifest File Version 1.0.1](#driver-manifest-file-version-101)
48 - [Driver Vulkan Entry Point Discovery](#driver-vulkan-entry-point-discovery)
49 - [Driver API Version](#driver-api-version)
50 - [Mixed Driver Instance Extension Support](#mixed-driver-instance-extension-support)
51 - [Filtering Out Instance Extension Names](#filtering-out-instance-extension-names)
52 - [Loader Instance Extension Emulation Support](#loader-instance-extension-emulation-support)
53 - [Driver Unknown Physical Device Extensions](#driver-unknown-physical-device-extensions)
54 …- [Reason for adding `vk_icdGetPhysicalDeviceProcAddr`](#reason-for-adding-vk_icdgetphysicaldevice…
55 - [Physical Device Sorting](#physical-device-sorting)
56 - [Driver Dispatchable Object Creation](#driver-dispatchable-object-creation)
57 - [Handling KHR Surface Objects in WSI Extensions](#handling-khr-surface-objects-in-wsi-extensions)
58 - [Loader and Driver Interface Negotiation](#loader-and-driver-interface-negotiation)
59 - [Windows, Linux and macOS Driver Negotiation](#windows-linux-and-macos-driver-negotiation)
60 …- [Version Negotiation Between the Loader and Drivers](#version-negotiation-between-the-loader-and…
61 - [Interfacing With Legacy Drivers or Loaders](#interfacing-with-legacy-drivers-or-loaders)
62 …- [Loader and Driver Interface Version 7 Requirements](#loader-and-driver-interface-version-7-requ…
63 …- [Loader and Driver Interface Version 6 Requirements](#loader-and-driver-interface-version-6-requ…
64 …- [Loader and Driver Interface Version 5 Requirements](#loader-and-driver-interface-version-5-requ…
65 …- [Loader and Driver Interface Version 4 Requirements](#loader-and-driver-interface-version-4-requ…
66 …- [Loader and Driver Interface Version 3 Requirements](#loader-and-driver-interface-version-3-requ…
67 …- [Loader and Driver Interface Version 2 Requirements](#loader-and-driver-interface-version-2-requ…
68 …- [Loader and Driver Interface Version 1 Requirements](#loader-and-driver-interface-version-1-requ…
69 …- [Loader and Driver Interface Version 0 Requirements](#loader-and-driver-interface-version-0-requ…
70 - [Additional Interface Notes:](#additional-interface-notes)
71 - [Android Driver Negotiation](#android-driver-negotiation)
72 - [Loader implementation of VK\_KHR\_portability\_enumeration](#loader-implementation-of-vk_khr_por…
73 - [Loader and Driver Policy](#loader-and-driver-policy)
74 - [Number Format](#number-format)
75 - [Android Differences](#android-differences)
76 - [Requirements of Well-Behaved Drivers](#requirements-of-well-behaved-drivers)
77 - [Removed Driver Policies](#removed-driver-policies)
78 - [Requirements of a Well-Behaved Loader](#requirements-of-a-well-behaved-loader)
83 This is the Driver-centric view of working with the Vulkan loader.
87 **NOTE:** While many of the interfaces still use the "icd" sub-string to
96 Vulkan allows multiple drivers each with one or more devices
97 (represented by a Vulkan `VkPhysicalDevice` object) to be used collectively.
98 The loader is responsible for discovering available Vulkan drivers on
104 system is platform-dependent.
126 This list is colon-separated on Linux and macOS, and semicolon-separated on
140 This list is colon-separated on Linux and macOS, and semicolon-separated on
150 1.3.234 of the Vulkan headers and later.
152 The loader supports filter environment variables which can forcibly select and
161 [Filter Environment Variable Behaviors](LoaderInterfaceArchitecture.md#filter-environment-variable-…
164 #### Driver Select Filtering
166 The driver select environment variable `VK_LOADER_DRIVERS_SELECT` is a
167 comma-delimited list of globs to search for in known drivers.
180 any Vulkan application that is run.
185 comma-delimited list of globs to search for in known drivers.
202 `VK_ADD_DRIVER_FILES` are all ignored if running the Vulkan application
210 [Elevated Privilege Caveats](LoaderInterfaceArchitecture.md#elevated-privilege-caveats)
211 in the top-level
225 set VK_DRIVER_FILES=\windows\system32\nv-vk64.json
229 point to the Nvidia Vulkan Driver's Manifest file.
232 set VK_ADD_DRIVER_FILES=\windows\system32\nv-vk64.json
236 point to the Nvidia Vulkan Driver's Manifest file which will be loaded first
242 export VK_DRIVER_FILES=/home/user/dev/mesa/share/vulkan/icd.d/intel_icd.x86_64.json
249 export VK_ADD_DRIVER_FILES=/home/user/dev/mesa/share/vulkan/icd.d/intel_icd.x86_64.json
267 [Table of Debug Environment Variables](LoaderInterfaceArchitecture.md#table-of-debug-environment-va…
274 As with layers, on Windows, Linux and macOS systems, JSON-formatted manifest
276 In order to find system-installed drivers, the Vulkan loader will read the JSON
279 layer Manifest files.
282 [Current Driver Manifest File Format](#driver-manifest-file-format)
292 These keys are located in device keys created during driver installation and
296 The Device Adapter and Software Component key paths will be obtained by first
299 The `000X` key will be a numbered key, where each device is assigned a different
307 In addition, on 64-bit systems there may be another set of registry values,
309 These values record the locations of 32-bit layers on 64-bit operating systems,
310 in the same way as the Windows-on-Windows functionality.
323 Additionally, the Vulkan loader will scan the values in the following Windows
327 HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers
330 For 32-bit applications on 64-bit Windows, the loader scan's the 32-bit
334 HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Khronos\Vulkan\Drivers
339 The Vulkan loader will attempt to open each manifest file to obtain the
345 [HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers\]
358 Additionally, the Vulkan loader will scan the system for well-known Windows
363 …d OpenGL® Compatibility Pack](https://apps.microsoft.com/store/detail/9NQPSL29BFFF?hl=en-us&gl=US).
365 The Vulkan loader will open each enabled manifest file found to obtain the name
371 ties the driver to a given device.
372 The `SOFTWARE\Khronos\Vulkan\Drivers` location is the older method for locating
376 [Driver Manifest File Format](#driver-manifest-file-format)
382 On Linux, the Vulkan loader will scan for Driver Manifest files using
400 that the environment variables are non-malicious.<br/>
401 See <a href="LoaderInterfaceArchitecture.md#elevated-privilege-caveats">
415 <td>Compile-time option set to possible location of drivers
416 installed from non-Linux-distribution-provided packages.
423 <td>Compile-time option set to possible location of drivers
424 installed from non-Linux-distribution-provided packages.
435 that the environment variables are non-malicious.<br/>
436 See <a href="LoaderInterfaceArchitecture.md#elevated-privilege-caveats">
450 The loader then selects each path, and applies the "/vulkan/icd.d" suffix onto
453 The Vulkan loader will open each manifest file found to obtain the name or
458 …ehavior of readdir](https://www.ibm.com/support/pages/order-directory-contents-returned-calls-read…
461 [Driver Manifest File Format](#driver-manifest-file-format)
485 /home/me/.config/vulkan/icd.d
486 /etc/xdg/vulkan/icd.d
487 /usr/local/etc/vulkan/icd.d
488 /etc/vulkan/icd.d
489 /home/me/.local/share/vulkan/icd.d
490 /usr/local/share/vulkan/icd.d
491 /usr/share/vulkan/icd.d
497 On Fuchsia, the Vulkan loader will scan for manifest files using environment
500 [Linux](#linux-driver-discovery).
507 On macOS, the Vulkan loader will scan for Driver Manifest files using
532 <bundle>/Contents/Resources/vulkan/icd.d
533 /Users/Me/.config/vulkan/icd.d
534 /etc/xdg/vulkan/icd.d
535 /usr/local/etc/vulkan/icd.d
536 /etc/vulkan/icd.d
537 /Users/Me/.local/share/vulkan/icd.d
538 /usr/local/share/vulkan/icd.d
539 /usr/share/vulkan/icd.d
550 will expose it and cause the Vulkan loader to fail on loading the driver.
607 * `VK_DIRECT_DRIVER_LOADING_MODE_EXCLUSIVE_LUNARG` - specifies that the only drivers
609 * `VK_DIRECT_DRIVER_LOADING_MODE_INCLUSIVE_LUNARG` - specifies that drivers
650 `vkEnumerateInstanceExtensionProperties` and append non-duplicate entriees to the
666 ### Using Pre-Production ICDs or Software Drivers
668 Both software and pre-production ICDs can use an alternative mechanism to
670 Independent Hardware Vendor (IHV) may not want to fully install a pre-production
672 For example, a pre-production ICD may simply be a shared library in the
675 ICD without modifying the system-installed ICD(s) on their system.
678 which will override the mechanism used for finding system-installed
685 [Overriding the Default Driver Discovery](#overriding-the-default-driver-discovery)
693 The loader will load the driver via `hw_get_module` with the ID of "vulkan".
758 <td>The major.minor.patch version number of the maximum Vulkan API supported
760 However, just because the driver supports the specific Vulkan API
763 Information on what the underlying physical device can support must be
782 The current highest supported Layer Manifest file format supported is 1.0.1.
783 Information about each version is detailed in the following sub-sections:
788 format and fields of a layer JSON file.
806 ## Driver Vulkan Entry Point Discovery
808 The Vulkan symbols exported by a driver must not clash with the loader's
809 exported Vulkan symbols.
811 used for discovery of driver Vulkan entry-points.
812 This entry-point is not a part of the Vulkan API itself, only a private
825 global-level and instance-level Vulkan functions, and also for
827 Global-level functions are those which contain no dispatchable object as the
830 The driver must support querying global-level entry points by calling
832 Instance-level functions are those that have either `VkInstance`, or
836 Future Vulkan instance extensions may define and use new instance-level
841 All other Vulkan entry points must either:
843 * or NOT use the official Vulkan function names if they are exported
846 as OpenGL) and thus could be loaded by the application prior to when the Vulkan
849 Beware of interposing by dynamic OS library loaders if the official Vulkan
852 `-Bsymbolic`.
859 A Vulkan 1.0 driver was required to return `VK_ERROR_INCOMPATIBLE_DRIVER` if it
861 Beginning with Vulkan 1.1, drivers are not allowed to return this error
885 - The JSON manifest's "api_version" field is less that version 1.1
886 - The function pointer to `vkEnumerateInstanceVersion` is `NULL`
887 - The version returned by `vkEnumerateInstanceVersion` is less than 1.1
888 - `vkEnumerateInstanceVersion` returns anything other than `VK_SUCCESS`
890 If the driver only supports Vulkan 1.0, the loader will ensure that any
892 `apiVersion` field set to Vulkan 1.0.
922 entry-points, to the best of its ability, for each driver that does not support
930 ## Driver Unknown Physical Device Extensions
939 This entry point is not a part of the Vulkan API itself, only a private
953 `vkGetDeviceProcAddr` except it should only return values for physical device
955 In this way, it compares "pName" to every physical device function supported in
959 * If `pName` is the name of a Vulkan API entrypoint that takes a
963 * If `pName` is the name of a Vulkan API entrypoint that takes something other
974 won't be able to distinguish whether this is a device or physical device
986 - If it is, return the function pointer
987 2. Check if known instance or device extension function:
988 - If it is, return the function pointer
989 3. Call the layer/driver `GetPhysicalDeviceProcAddr`
990 - If it returns `non-NULL`, return a trampoline to a generic physical device
994 - If it returns non-NULL, treat it as an unknown logical device command.
997 driver/layer's function after getting the dispatch table from the
1002 The result is that if the command gets promoted to Vulkan core later, it will no
1007 `vk_icdGetPhysicalDeviceProcAddr`, until at least a Vulkan version bump, because
1015 - If so, it would return the function pointer
1017 - If so, it would return the function pointer
1020 - If it returned `non-NULL`, treat it as an unknown logical device command.
1021 - This meant setting up a generic trampoline function that takes in a
1023 driver/layer's function after getting the dispatch table from the
1027 This caused problems when a driver attempted to expose new physical device
1030 above process and would treat the function as an unknown logical device command.
1036 ## Physical Device Sorting
1039 physical device groups.
1041 device groups will be presented in.
1051 This entry point is not a part of the Vulkan API itself, only a private
1067 This function takes an adapter LUID as input, and enumerates all Vulkan physical
1069 This works in the same way as other Vulkan enumerations — if
1075 This allows the loader to translate the adapter into Vulkan physical device
1089 platform-specific interfaces.
1095 de-duplicates the physical devices using the `VkPhysicalDevice` handles.
1103 within Vulkan dispatchable objects, such as: `VkInstance`, `VkPhysicalDevice`,
1108 - All dispatchable objects created by a driver can be cast to void \*\*
1109 - The loader will replace the first entry with a pointer to the dispatch table
1118 non-POD due to the use of a virtual function.
1121 dispatchable objects, as follows (see `include/vulkan/vk_icd.h`):
1147 Normally, drivers handle object creation and destruction for various Vulkan
1170 * The `VkIcdSurfaceXXX` structures are defined in `include/vulkan/vk_icd.h`.
1190 Because the `VkSurfaceKHR` object is an instance-level object, one object can be
1216 with that are not part of any requirements from the Vulkan specification.
1228 This entry point is not a part of the Vulkan API itself, only a private
1258 The driver should report `VK_SUCCESS` in case the loader-provided interface
1357 for all vkCreateInstance calls with apiVersion set to > Vulkan 1.0
1369 anything > Vulkan 1.0 and fail with <b>VK_ERROR_INCOMPATIBLE_DRIVER</b>.
1389 [Unknown Physical Device Extensions](#driver-unknown-physical-device-extensions)
1392 However, if a driver supports a physical device extension, it must provide a
1406 Interface Version 3, as well as any Vulkan function that uses a `VkSurfaceKHR`
1408 - `vkCreateXXXSurfaceKHR` (where XXX is the platform-specific identifier [i.e.
1410 - `vkDestroySurfaceKHR`
1411 - `vkCreateSwapchainKHR`
1412 - `vkGetPhysicalDeviceSurfaceSupportKHR`
1413 - `vkGetPhysicalDeviceSurfaceCapabilitiesKHR`
1414 - `vkGetPhysicalDeviceSurfaceFormatsKHR`
1415 - `vkGetPhysicalDeviceSurfacePresentModesKHR`
1426 …ee [Version Negotiation Between Loader and Drivers](#version-negotiation-between-loader-and-driver…
1428 Additional, version 2 requires that Vulkan dispatchable objects created by
1430 [Driver Dispatchable Object Creation](#driver-dispatchable-object-creation)
1436 Version 1 of the interface added the driver-specific entry-point
1439 `vk_icdNegotiateLoaderICDInterfaceVersion` entry-point, the loader has no
1445 No other entry-points need to be exported by the driver as the loader will query
1457 Vulkan entry-points so the loader may build up the interface to the driver:
1459 - The function `vkGetInstanceProcAddr` **must be exported** in the driver
1460 library and returns valid function pointers for all the Vulkan API entry points.
1461 - `vkCreateInstance` **must be exported** by the driver library.
1462 - `vkEnumerateInstanceExtensionProperties` **must be exported** by the driver
1468 - The loader will filter out extensions requested in `vkCreateInstance` and
1471 - The loader will not call the driver for `vkEnumerate*LayerProperties`
1472 as layer properties are obtained from the layer libraries and layer JSON files.
1473 - If a driver library author wants to implement a layer, it can do so by having
1474 the appropriate layer JSON manifest file refer to the driver library file.
1475 - The loader will not call the driver for `vkEnumerate*ExtensionProperties` if
1477 - Drivers creating new dispatchable objects via device extensions need
1479 The loader has generic *trampoline* code for unknown device extensions.
1483 [Driver Dispatchable Object Creation](#driver-dispatchable-object-creation)
1492 The only difference is that the Android loader queries layer and extension
1501 device extension. Unless the application explicitly requests enumeration of
1509 [More information here](#driver-manifest-file-version-101)
1520 Much of this section is additive to the Vulkan spec, and necessary for
1524 Additionally, there should be a way to identify bad or non-conformant behavior
1533 best experience to end-users and developers.
1542 - Drivers: which will have the string `DRIVER_` as part of the policy number.
1543 - The Loader: which will have the string `LOADER_` as part of the policy
1557 <a href="https://source.android.com/devices/graphics/implement-vulkan">
1558 Android Vulkan documentation</a>.
1561 ### Requirements of Well-Behaved Drivers
1567 <th>Result of Non-Compliance</th>
1585 Vulkan Physical Devices (<i>VkPhysicalDevice</i>) on the system when a
1586 call to that driver is made using any Vulkan instance of physical device
1588 This is because some devices can be hot-plugged.
1608 <a href="#loader-and-driver-interface-negotiation">
1621 <a href="#driver-manifest-file-format">Manifest File Format</a>
1629 through any mechanism provided by Vulkan (examples include inside the
1643 <a href="https://github.com/KhronosGroup/VK-GL-CTS/blob/main/external/openglcts/README.md">
1644 Vulkan CTS Documentation</a>
1650 <td>Removed - See
1651 <a href="#removed-driver-policies">Removed Driver Policies</a>
1653 <td>-</td>
1654 <td>-</td>
1655 <td>-</td>
1656 <td>-</td>
1660 <td>If a driver desires to support Vulkan API 1.1 or newer, it <b>must</b>
1669 <a href="#loader-version-5-interface-requirements">
1684 <a href="#handling-khr-surface-objects-in-wsi-extensions">
1692 that the Vulkan API version passed into <i>vkCreateInstance</i> (through
1695 If the requested Vulkan API version can not be supported by the driver,
1704 <a href="#loader-version-5-interface-requirements">
1712 <b>VK_ERROR_INCOMPATIBLE_DRIVER</b> if the Vulkan API version
1722 <a href="#loader-version-5-interface-requirements">
1776 not</b> directly export standard Vulkan entry-points.
1797 ### Requirements of a Well-Behaved Loader
1803 <th>Result of Non-Compliance</th>
1810 fails to find and load a valid Vulkan driver on the system.
1827 <a href="#driver-discovery">Driver Discovery</a></small>
1833 non-standard locations.<br/>
1835 evaluating in-development ICDs. <br/>
1839 <td>It will be more difficult to use a Vulkan loader by certain
1843 <a href="#using-pre-production-icds-or-software-drivers">
1844 Pre-Production ICDs or SW</a></small>
1849 <td>A loader <b>must not</b> load a Vulkan driver which defines an API
1855 <a href="#driver-discovery">Driver Discovery</a></small>
1868 <a href="#loader-and-driver-interface-negotiation">
1875 Interface Version 5 or newer, a loader <b>must</b> verify that the Vulkan
1879 If the requested Vulkan API version can not be supported by any
1888 <a href="#loader-version-5-interface-requirements">
1895 drivers support <i>only</i> Vulkan API version 1.0 while other drivers
1896 support a newer Vulkan API version, then a loader <b>must</b> adjust
1899 only aware of Vulkan API version 1.0.<br/>
1900 Otherwise, the drivers that support Vulkan API version 1.0 will
1908 <a href="#driver-api-version">Driver API Version</a>
1915 support</i> instance-level functionality that other drivers support;
1916 then a loader <b>must</b> support the instance-level functionality in
1917 some fashion for the non-supporting drivers.
1922 <a href="#loader-instance-extension-emulation-support">
1939 <a href="#filtering-out-instance-extension-names">
1951 <a href="#handling-khr-surface-objects-in-wsi-extensions">
1958 creation/handling entry-points, a loader <b>must</b> support creating
1959 the driver-specific surface object handle and provide it, and not the
1968 <a href="#handling-khr-surface-objects-in-wsi-extensions">
1975 entry-points in a driver if <i>pLayerName</i> is not <b>NULL</b>.
1980 <a href="#additional-interface-notes">
1986 <td>A loader <b>must</b> not load from user-defined paths (including the
1989 (Administrator/Super-user) applications.<br/>
1997 <a href="#exception-for-administrator-and-super-user-mode">
1998 Exception for Administrator and Super-User mode
2006 [Return to the top-level LoaderInterfaceArchitecture.md file.](LoaderInterfaceArchitecture.md)