| Field Name |
Field Value |
| "file_format_version" |
The JSON format major.minor.patch version number of this file.
Supported versions are: 1.0.0 and 1.0.1. |
| "ICD" |
The identifier used to group all driver information together.
NOTE: Even though this is labelled ICD it is historical
and just as accurate to use for other drivers. |
| "library_path" |
The "library_path" specifies either a filename, a relative pathname, or
a full pathname to a driver shared library file.
If "library_path" specifies a relative pathname, it is relative to the
path of the JSON manifest file.
If "library_path" specifies a filename, the library must live in the
system's shared object search path.
There are no rules about the name of the driver's shared library file
other than it should end with the appropriate suffix (".DLL" on
Windows, ".so" on Linux and ".dylib" on macOS). |
| "library_arch" |
Optional field which specifies the architecture of the binary associated
with "library_path".
Allows the loader to quickly determine if the architecture of the driver
matches that of the running application.
The only valid values are "32" and "64". |
| "api_version" |
The major.minor.patch version number of the maximum Vulkan API supported
by the driver.
However, just because the driver supports the specific Vulkan API
version, it does not guarantee that the hardware on a user's system can
support that version.
Information on what the underlying physical device can support must be
queried by the user using the vkGetPhysicalDeviceProperties API
call.
For example: 1.0.33. |
| "is_portability_driver" |
Defines whether the driver contains any VkPhysicalDevices which
implement the VK_KHR_portability_subset extension.
|
**NOTE:** If the same driver shared library supports multiple, incompatible
versions of text manifest file format versions, it must have separate JSON files
for each (all of which may point to the same shared library).
### Driver Manifest File Versions
The current highest supported Layer Manifest file format supported is 1.0.1.
Information about each version is detailed in the following sub-sections:
#### Driver Manifest File Version 1.0.0
The initial version of the Driver Manifest file specified the basic
format and fields of a layer JSON file.
The fields supported in version 1.0.0 of the file format include:
* "file\_format\_version"
* "ICD"
* "library\_path"
* "api\_version"
#### Driver Manifest File Version 1.0.1
Added the `is_portability_driver` boolean field for drivers to self report that
they contain VkPhysicalDevices which support the VK_KHR_portability_subset
extension. This is an optional field. Omitting the field has the same effect as
setting the field to `false`.
Added the "library\_arch" field to the driver manifest to allow the loader to
quickly determine if the driver matches the architecture of the current running
application. This field is optional.
## Driver Vulkan Entry Point Discovery
The Vulkan symbols exported by a driver must not clash with the loader's
exported Vulkan symbols.
Because of this, all drivers must export the following function that is
used for discovery of driver Vulkan entry-points.
This entry-point is not a part of the Vulkan API itself, only a private
interface between the loader and drivers for version 1 and higher
interfaces.
```cpp
VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL
vk_icdGetInstanceProcAddr(
VkInstance instance,
const char* pName);
```
This function has very similar semantics to `vkGetInstanceProcAddr`.
`vk_icdGetInstanceProcAddr` returns valid function pointers for all the
global-level and instance-level Vulkan functions, and also for
`vkGetDeviceProcAddr`.
Global-level functions are those which contain no dispatchable object as the
first parameter, such as `vkCreateInstance` and
`vkEnumerateInstanceExtensionProperties`.
The driver must support querying global-level entry points by calling
`vk_icdGetInstanceProcAddr` with a NULL `VkInstance` parameter.
Instance-level functions are those that have either `VkInstance`, or
`VkPhysicalDevice` as the first parameter dispatchable object.
Both core entry points and any instance extension entry points the
driver supports should be available via `vk_icdGetInstanceProcAddr`.
Future Vulkan instance extensions may define and use new instance-level
dispatchable objects other than `VkInstance` and `VkPhysicalDevice`, in which
case extension entry points using these newly defined dispatchable objects must
be queryable via `vk_icdGetInstanceProcAddr`.
All other Vulkan entry points must either:
* NOT be exported directly from the driver library
* or NOT use the official Vulkan function names if they are exported
This requirement is for driver libraries that include other functionality (such
as OpenGL) and thus could be loaded by the application prior to when the Vulkan
loader library is loaded by the application.
Beware of interposing by dynamic OS library loaders if the official Vulkan
names are used.
On Linux, if official names are used, the driver library must be linked with
`-Bsymbolic`.
## Driver API Version
When an application calls `vkCreateInstance`, it can optionally include a
`VkApplicationInfo` struct, which includes an `apiVersion` field.
A Vulkan 1.0 driver 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, drivers are not allowed to return this error
for any value of `apiVersion`.
This creates a problem when working with multiple drivers, where one is
a 1.0 driver 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 drivers 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. Check the driver's JSON manifest file for the "api_version" field.
2. If the JSON version is greater than or equal to 1.1, Load the driver's
dynamic library
3. Call the driver's `vkGetInstanceProcAddr` command to get a pointer to
`vkEnumerateInstanceVersion`
4. If the pointer to `vkEnumerateInstanceVersion` is not `NULL`, it will be
called to get the driver's supported API version
The driver will be treated as a 1.0 driver if any of the following conditions
are met:
- The JSON manifest's "api_version" field is less that version 1.1
- 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 driver only supports Vulkan 1.0, the loader will ensure that any
`VkApplicationInfo` struct that is passed to the driver will have an
`apiVersion` field set to Vulkan 1.0.
Otherwise, the loader will pass the struct to the driver without any
changes.
## Mixed Driver Instance Extension Support
On a system with more than one driver, a special case can arise.
Some drivers may expose an instance extension that the loader is already
aware of.
Other drivers on that same system may not support the same instance
extension.
In that scenario, the loader has some additional responsibilities:
### Filtering Out Instance Extension Names
During a call to `vkCreateInstance`, the list of requested instance extensions
is passed down to each driver.
Since the driver may not support one or more of these instance extensions, the
loader will filter out any instance extensions that are not supported by the
driver.
This is done per driver since different drivers may support different instance
extensions.
### Loader Instance Extension Emulation Support
In the same scenario, the loader must emulate the instance extension
entry-points, to the best of its ability, for each driver that does not support
an instance extension directly.
This must work correctly when combined with calling into the other
drivers which do support the extension natively.
In this fashion, the application will be unaware of what drivers are
missing support for this extension.
## Driver Unknown Physical Device Extensions
Drivers that implement entrypoints which take a `VkPhysicalDevice` as the first
parameter *should* support `vk_icdGetPhysicalDeviceProcAddr`.
This function is added to the Loader and Driver Driver Interface Version 4,
allowing the loader to distinguish between entrypoints which take `VkDevice`
and `VkPhysicalDevice` as the first parameter.
This allows the loader to properly support entrypoints that are unknown to it
gracefully.
This entry point is not a part of the Vulkan API itself, only a private
interface between the loader and drivers.
Note: Loader and Driver Interface Version 7 makes exporting
`vk_icdGetPhysicalDeviceProcAddr` optional.
Instead, drivers *must* expose it through `vk_icdGetInstanceProcAddr`.
```cpp
PFN_vkVoidFunction
vk_icdGetPhysicalDeviceProcAddr(
VkInstance instance,
const char* pName);
```
This function behaves similar to `vkGetInstanceProcAddr` and
`vkGetDeviceProcAddr` except it should only return values for physical device
extension entry points.
In this way, it compares "pName" to every physical device function supported in
the driver.
Implementations of the function should have the following behavior:
* If `pName` is the name of a Vulkan API entrypoint that takes a
`VkPhysicalDevice` as its primary dispatch handle, and the driver supports the
entrypoint, then the driver **must** return the valid function pointer to the
driver's implementation of that entrypoint.
* If `pName` is the name of a Vulkan API entrypoint that takes something other
than a `VkPhysicalDevice` as its primary dispatch handle, then the driver
**must** return `NULL`.
* If the driver is unaware of any entrypoint with the name `pName`, it **must**
return `NULL`.
If a driver intends to support functions that take VkPhysicalDevice as the
dispatchable parameter, then the driver should support
`vk_icdGetPhysicalDeviceProcAddr`. This is because if these functions aren't
known to the loader, such as those from unreleased extensions or because
the loader is an older build thus doesn't know about them _yet_, the loader
won't be able to distinguish whether this is a device or physical device
function.
If a driver does implement this support, it must export the function from the
driver library using the name `vk_icdGetPhysicalDeviceProcAddr` so that the
symbol can be located through the platform's dynamic linking utilities, or if
the driver supports Loader and Driver Interface Version 7, exposed through
`vk_icdGetInstanceProcAddr` instead.
The behavior of the loader's `vkGetInstanceProcAddr` with support for the
`vk_icdGetPhysicalDeviceProcAddr` function is as follows:
1. Check if core function:
- If it is, return the function pointer
2. Check if known instance or device extension function:
- If it is, return the function pointer
3. Call the layer/driver `GetPhysicalDeviceProcAddr`
- If it returns `non-NULL`, return a trampoline to a generic physical device
function, and set up a generic terminator which will pass it to the proper
driver.
4. Call down using `GetInstanceProcAddr`
- If it returns non-NULL, treat it as an unknown logical device command.
This means setting up a generic trampoline function that takes in a `VkDevice`
as the first parameter and adjusting the dispatch table to call the
driver/layer's function after getting the dispatch table from the
`VkDevice`.
Then, return the pointer to the corresponding trampoline function.
5. Return `NULL`
The result is that if the command gets promoted to Vulkan core later, it will no
longer be set up using `vk_icdGetPhysicalDeviceProcAddr`.
Additionally, if the loader adds direct support for the extension, it will no
longer get to step 3, because step 2 will return a valid function pointer.
However, the driver should continue to support the command query via
`vk_icdGetPhysicalDeviceProcAddr`, until at least a Vulkan version bump, because
an older loader may still be attempting to use the commands.
### Reason for adding `vk_icdGetPhysicalDeviceProcAddr`
Originally, when the loader's `vkGetInstanceProcAddr` was called, it would
result in the following behavior:
1. The loader would check if it was a core function:
- If so, it would return the function pointer
2. The loader would check if it was a known extension function:
- If so, it would return the function pointer
3. If the loader knew nothing about it, it would call down using
`GetInstanceProcAddr`
- If it returned `non-NULL`, treat it as an unknown logical device command.
- This meant setting up a generic trampoline function that takes in a
VkDevice as the first parameter and adjusting the dispatch table to call the
driver/layer's function after getting the dispatch table from the
`VkDevice`.
4. If all the above failed, the loader would return `NULL` to the application.
This caused problems when a driver attempted to expose new physical device
extensions the loader knew nothing about, but an application was aware of.
Because the loader knew nothing about it, the loader would get to step 3 in the
above process and would treat the function as an unknown logical device command.
The problem is, this would create a generic `VkDevice` trampoline function
which, on the first call, would attempt to dereference the VkPhysicalDevice as a
`VkDevice`.
This would lead to a crash or corruption.
## Physical Device Sorting
When an application selects a GPU to use, it must enumerate physical devices or
physical device groups.
These API functions do not specify which order the physical devices or physical
device groups will be presented in.
On Windows, the loader will attempt to sort these objects so that the system
preference will be listed first.
This mechanism does not force an application to use any particular GPU —
it merely changes the order in which they are presented.
This mechanism requires that a driver provide The Loader and Driver Interface
Version 6.
This version defines a new exported function, `vk_icdEnumerateAdapterPhysicalDevices`,
detailed below, that Drivers may provide on Windows.
This entry point is not a part of the Vulkan API itself, only a private
interface between the loader and drivers.
Note: Loader and Driver Interface Version 7 makes exporting
`vk_icdEnumerateAdapterPhysicalDevices` optional.
Instead, drivers *must* expose it through `vk_icdGetInstanceProcAddr`.
```c
VKAPI_ATTR VkResult VKAPI_CALL
vk_icdEnumerateAdapterPhysicalDevices(
VkInstance instance,
LUID adapterLUID,
uint32_t* pPhysicalDeviceCount,
VkPhysicalDevice* pPhysicalDevices);
```
This function takes an adapter LUID as input, and enumerates all Vulkan physical
devices that are associated with that LUID.
This works in the same way as other Vulkan enumerations — if
`pPhysicalDevices` is `NULL`, then the count will be provided.
Otherwise, the physical devices associated with the queried adapter will be
provided.
The function must provide multiple physical devices when the LUID refers to a
linked adapter.
This allows the loader to translate the adapter into Vulkan physical device
groups.
While the loader attempts to match the system's preference for GPU ordering,
there are some limitations.
Because this feature requires a new driver interface, only physical devices from
drivers that support this function will be sorted.
All unsorted physical devices will be listed at the end of the list, in an
indeterminate order.
Furthermore, only physical devices that correspond to an adapter may be sorted.
This means that a software driver would likely not be sorted.
Finally, this API only applies to Windows systems and will only work on versions
of Windows 10 that support GPU selection through the OS.
Other platforms may be included in the future, but they will require separate
platform-specific interfaces.
A requirement of `vk_icdEnumerateAdapterPhysicalDevices` is that it *must*
return the same `VkPhysicalDevice` handle values for the same physical
devices that are returned by `vkEnumeratePhysicalDevices`.
This is because the loader calls both functions on the driver then
de-duplicates the physical devices using the `VkPhysicalDevice` handles.
Since not all physical devices in a driver will have a LUID, such as for
software implementations, this step is necessary to allow drivers to
enumerate all available physical devices.
## Driver Dispatchable Object Creation
As previously covered, the loader requires dispatch tables to be accessible
within Vulkan dispatchable objects, such as: `VkInstance`, `VkPhysicalDevice`,
`VkDevice`, `VkQueue`, and `VkCommandBuffer`.
The specific requirements on all dispatchable objects created by drivers
are as follows:
- All dispatchable objects created by a driver can be cast to void \*\*
- The loader will replace the first entry with a pointer to the dispatch table
which is owned by the loader.
This implies three things for drivers:
1. The driver must return a pointer for the opaque dispatchable object handle
2. This pointer points to a regular C structure with the first entry being a
pointer.
* **NOTE:** For any C\++ drivers that implement VK objects directly
as C\++ classes:
* The C\++ compiler may put a vtable at offset zero if the class is
non-POD due to the use of a virtual function.
* In this case use a regular C structure (see below).
3. The loader checks for a magic value (ICD\_LOADER\_MAGIC) in all the created
dispatchable objects, as follows (see `include/vulkan/vk_icd.h`):
```cpp
#include "vk_icd.h"
union _VK_LOADER_DATA {
uintptr loadermagic;
void * loaderData;
} VK_LOADER_DATA;
vkObj
alloc_icd_obj()
{
vkObj *newObj = alloc_obj();
...
// Initialize pointer to loader's dispatch table with ICD_LOADER_MAGIC
set_loader_magic_value(newObj);
...
return newObj;
}
```
## Handling KHR Surface Objects in WSI Extensions
Normally, drivers handle object creation and destruction for various Vulkan
objects.
The WSI surface extensions for Linux, Windows, macOS, and QNX
("VK\_KHR\_win32\_surface", "VK\_KHR\_xcb\_surface", "VK\_KHR\_xlib\_surface",
"VK\_KHR\_wayland\_surface", "VK\_MVK\_macos\_surface",
"VK\_QNX\_screen\_surface" and "VK\_KHR\_surface") are handled differently.
For these extensions, the `VkSurfaceKHR` object creation and destruction may be
handled by either the loader or a driver.
If the loader handles the management of the `VkSurfaceKHR` objects:
1. The loader will handle the calls to `vkCreateXXXSurfaceKHR` and
`vkDestroySurfaceKHR`
functions without involving the drivers.
* Where XXX stands for the Windowing System name:
* Wayland
* XCB
* Xlib
* Windows
* Android
* MacOS (`vkCreateMacOSSurfaceMVK`)
* QNX (`vkCreateScreenSurfaceQNX`)
2. The loader creates a `VkIcdSurfaceXXX` object for the corresponding
`vkCreateXXXSurfaceKHR` call.
* The `VkIcdSurfaceXXX` structures are defined in `include/vulkan/vk_icd.h`.
3. Drivers can cast any `VkSurfaceKHR` object to a pointer to the
appropriate `VkIcdSurfaceXXX` structure.
4. The first field of all the `VkIcdSurfaceXXX` structures is a
`VkIcdSurfaceBase` enumerant that indicates whether the
surface object is Win32, XCB, Xlib, Wayland, or Screen.
The driver may choose to handle `VkSurfaceKHR` object creation instead.
If a driver desires to handle creating and destroying it must do the following:
1. Support Loader and Driver Interface Version 3 or newer.
2. Expose and handle all functions that take in a `VkSurfaceKHR` object,
including:
* `vkCreateXXXSurfaceKHR`
* `vkGetPhysicalDeviceSurfaceSupportKHR`
* `vkGetPhysicalDeviceSurfaceCapabilitiesKHR`
* `vkGetPhysicalDeviceSurfaceFormatsKHR`
* `vkGetPhysicalDeviceSurfacePresentModesKHR`
* `vkCreateSwapchainKHR`
* `vkDestroySurfaceKHR`
Because the `VkSurfaceKHR` object is an instance-level object, one object can be
associated with multiple drivers.
Therefore, when the loader receives the `vkCreateXXXSurfaceKHR` call, it still
creates an internal `VkSurfaceIcdXXX` object.
This object acts as a container for each driver's version of the
`VkSurfaceKHR` object.
If a driver does not support the creation of its own `VkSurfaceKHR` object, the
loader's container stores a NULL for that driver.
On the other hand, if the driver does support `VkSurfaceKHR` creation, the
loader will make the appropriate `vkCreateXXXSurfaceKHR` call to the
driver, and store the returned pointer in its container object.
The loader then returns the `VkSurfaceIcdXXX` as a `VkSurfaceKHR` object back up
the call chain.
Finally, when the loader receives the `vkDestroySurfaceKHR` call, it
subsequently calls `vkDestroySurfaceKHR` for each driver whose internal
`VkSurfaceKHR` object is not NULL.
Then the loader destroys the container object before returning.
## Loader and Driver Interface Negotiation
Generally, for functions issued by an application, the loader can be viewed as a
pass through.
That is, the loader generally doesn't modify the functions or their parameters,
but simply calls the driver's entry point for that function.
There are specific additional interface requirements a driver needs to comply
with that are not part of any requirements from the Vulkan specification.
These additional requirements are versioned to allow flexibility in the future.
### Windows, Linux and macOS Driver Negotiation
#### Version Negotiation Between the Loader and Drivers
All drivers supporting Loader and Driver Interface Version 2 or higher must
export the following function that is used for determination of the interface
version that will be used.
This entry point is not a part of the Vulkan API itself, only a private
interface between the loader and drivers.
Note: Loader and Driver Interface Version 7 makes exporting
`vk_icdNegotiateLoaderICDInterfaceVersion` optional.
Instead, drivers *must* expose it through `vk_icdGetInstanceProcAddr`.
```cpp
VKAPI_ATTR VkResult VKAPI_CALL
vk_icdNegotiateLoaderICDInterfaceVersion(
uint32_t* pSupportedVersion);
```
This function allows the loader and driver to agree on an interface version to
use.
The "pSupportedVersion" parameter is both an input and output parameter.
"pSupportedVersion" is filled in by the loader with the desired latest interface
version supported by the loader (typically the latest).
The driver receives this and returns back the version it desires in the same
field.
Because it is setting up the interface version between the loader and
driver, this should be the first call made by a loader to the driver (even prior
to any calls to `vk_icdGetInstanceProcAddr`).
If the driver receiving the call no longer supports the interface version
provided by the loader (due to deprecation), then it should report a
`VK_ERROR_INCOMPATIBLE_DRIVER` error.
Otherwise it sets the value pointed by "pSupportedVersion" to the latest
interface version supported by both the driver and the loader and returns
`VK_SUCCESS`.
The driver should report `VK_SUCCESS` in case the loader-provided interface
version is newer than that supported by the driver, as it's the loader's
responsibility to determine whether it can support the older interface version
supported by the driver.
The driver should also report `VK_SUCCESS` in the case its interface version is
greater than the loader's, but return the loader's version.
Thus, upon return of `VK_SUCCESS` the "pSupportedVersion" will contain the
desired interface version to be used by the driver.
If the loader receives an interface version from the driver that the loader no
longer supports (due to deprecation), or it receives a
`VK_ERROR_INCOMPATIBLE_DRIVER` error instead of `VK_SUCCESS`, then the loader
will treat the driver as incompatible and will not load it for use.
In this case, the application will not see the driver's `vkPhysicalDevice`
during enumeration.
#### Interfacing With Legacy Drivers or Loaders
If a loader sees that a driver does not export or expose the
`vk_icdNegotiateLoaderICDInterfaceVersion` function, then the loader assumes the
corresponding driver only supports either interface version 0 or 1.
From the other side of the interface, if a driver sees a call to
`vk_icdGetInstanceProcAddr` before a call to
`vk_icdNegotiateLoaderICDInterfaceVersion`, then the loader is either a legacy
loader with only support for interface version 0 or 1, or the loader is using
interface version 7 or newer.
If the first call to `vk_icdGetInstanceProcAddr` is to query for
`vk_icdNegotiateLoaderICDInterfaceVersion`, then that means the loader is using
interface version 7.
This only occurs when the driver does not export
`vk_icdNegotiateLoaderICDInterfaceVersion`.
Drivers which export `vk_icdNegotiateLoaderICDInterfaceVersion` will have it
called first.
If the first call to `vk_icdGetInstanceProcAddr` is **not** querying for
`vk_icdNegotiateLoaderICDInterfaceVersion`, then loader is a legacy loader only
which supports version 0 or 1.
In this case, if the loader calls `vk_icdGetInstanceProcAddr` first, it supports
at least interface version 1.
Otherwise, the loader only supports version 0.
#### Loader and Driver Interface Version 7 Requirements
Version 7 relaxes the requirement that Loader and Driver Interface functions
must be exported.
Instead, it only requires that those functions be queryable through
`vk_icdGetInstanceProcAddr`.
The functions are:
`vk_icdNegotiateLoaderICDInterfaceVersion`
`vk_icdGetPhysicalDeviceProcAddr`
`vk_icdEnumerateAdapterPhysicalDevices` (Windows only)
These functions are considered global for the purposes of retrieval, so the
`VkInstance` parameter of `vk_icdGetInstanceProcAddr` will be **NULL**.
While exporting these functions is no longer a requirement, drivers may still
export them for compatibility with older loaders.
The changes in this version allow drivers provided through the
`VK_LUNARG_direct_driver_loading` extension to support the entire Loader and
Driver Interface.
#### Loader and Driver Interface Version 6 Requirements
Version 6 provides a mechanism to allow the loader to sort physical devices.
The loader will only attempt to sort physical devices on a driver if version 6
of the interface is supported.
This version provides the `vk_icdEnumerateAdapterPhysicalDevices` function
defined earlier in this document.
#### Loader and Driver Interface Version 5 Requirements
This interface version has no changes to the actual interface.
If the loader requests interface version 5 or greater, it is simply
an indication to drivers that the loader is now evaluating whether the API
Version info passed into vkCreateInstance is a valid version for the loader.
If it is not, the loader will catch this during vkCreateInstance and fail with a
`VK_ERROR_INCOMPATIBLE_DRIVER` error.
On the other hand, if version 5 or newer is not requested by the loader, then it
indicates to the driver that the loader is ignorant of the API version being
requested.
Because of this, it falls on the driver to validate that the API Version is not
greater than major = 1 and minor = 0.
If it is, then the driver should automatically fail with a
`VK_ERROR_INCOMPATIBLE_DRIVER` error since the loader is a 1.0 loader, and is
unaware of the version.
Here is a table of the expected behaviors:
| Requirement Number |
Requirement Description |
Result of Non-Compliance |
Applicable to Android? |
Enforceable by Loader? |
Reference Section |
| LDP_DRIVER_1 |
A driver must not cause other drivers to fail, crash, or
otherwise misbehave.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
No |
N/A |
| LDP_DRIVER_2 |
A driver must not crash if it detects that there are no supported
Vulkan Physical Devices (VkPhysicalDevice) on the system when a
call to that driver is made using any Vulkan instance of physical device
API.
This is because some devices can be hot-plugged.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
No
The loader has no direct knowledge of what devices (virtual or physical)
may be supported by a given driver. |
N/A
|
| LDP_DRIVER_3 |
A driver must be able to negotiate a supported version of the
Loader and Driver Interface with the loader in accordance with the stated
negotiation process.
|
The driver will not be loaded. |
No |
Yes |
Interface Negotiation
|
| LDP_DRIVER_4 |
A driver must have a valid JSON manifest file for the loader to
process that ends with the ".json" suffix.
|
The driver will not be loaded. |
No |
Yes |
Manifest File Format
|
| LDP_DRIVER_5 |
A driver must pass conformance with the results submitted,
verified, and approved by Khronos before reporting a conformance version
through any mechanism provided by Vulkan (examples include inside the
VkPhysicalDeviceVulkan12Properties and the
VkPhysicalDeviceDriverProperties structs).
Otherwise, when such a structure containing a conformance version is
encountered, the driver must return a conformance version
of 0.0.0.0 to indicate it hasn't been so verified and approved.
|
Yes |
No |
The loader and/or the application may make assumptions about the
capabilities of the driver resulting in undefined behavior
possibly including crashes or corruption.
|
Vulkan CTS Documentation
|
| LDP_DRIVER_6 |
Removed - See
Removed Driver Policies
|
- |
- |
- |
- |
| LDP_DRIVER_7 |
If a driver desires to support Vulkan API 1.1 or newer, it must
expose support for Loader and Driver Interface Version 5 or newer.
|
The driver will be used when it shouldn't be and will cause
undefined behavior possibly including crashes or corruption.
|
No |
Yes |
Version 5 Interface Requirements
|
| LDP_DRIVER_8 |
If a driver wishes to handle its own VkSurfaceKHR object
creation, it must implement the Loader and Driver Interface Version 3 or
newer and support querying all the relevant surface functions via
vk_icdGetInstanceProcAddr.
|
The behavior is undefined and may result in crashes or corruption. |
No |
Yes |
Handling KHR Surface Objects
|
| LDP_DRIVER_9 |
If version negotiation results in a driver using the Loader
and Driver Interface Version 4 or earlier, the driver must verify
that the Vulkan API version passed into vkCreateInstance (through
VkInstanceCreateInfo’s VkApplicationInfo's
apiVersion) is supported.
If the requested Vulkan API version can not be supported by the driver,
it must return VK_ERROR_INCOMPATIBLE_DRIVER.
This is not required if the interface version is 5 or newer because the
loader is responsible for this check.
|
The behavior is undefined and may result in crashes or corruption. |
No |
No |
Version 5 Interface Requirements
|
| LDP_DRIVER_10 |
If version negotiation results in a driver using the Loader and Driver Interface
Version 5 or newer, the driver must not return
VK_ERROR_INCOMPATIBLE_DRIVER if the Vulkan API version
passed into vkCreateInstance (through
VkInstanceCreateInfo’s VkApplicationInfo's
apiVersion) is not supported by the driver. This check is performed
by the loader on the drivers behalf.
|
The behavior is undefined and may result in crashes or corruption. |
No |
No |
Version 5 Interface Requirements
|
| LDP_DRIVER_11 |
A driver must remove all Manifest files and references to those
files (i.e. Registry entries on Windows) when uninstalling.
Similarly, on updating the driver files, the old files must be
all updated or removed.
|
If an old file is left pointing to an incorrect library, it will
result in undefined behavior which may include crashes or corruption.
|
No |
No
The loader has no idea what driver files are new, old, or incorrect.
Any type of driver file verification would quickly become very complex
since it would require the loader to maintain an internal database
tracking badly behaving drivers based on the driver vendor, driver
version, targeted platform(s), and possibly other criteria.
|
N/A |
| LDP_DRIVER_12 |
To work properly with the public Khronos Loader, a driver
must not expose platform interface extensions without first
publishing them with Khronos.
Platforms under development may use modified versions of the Khronos
Loader until the design because stable and/or public.
|
The behavior is undefined and may result in crashes or corruption. |
Yes (specifically for Android extensions) |
No |
N/A |
#### Removed Driver Policies
These policies were in the loader source at some point but later removed.
They are documented here for reference.
| Requirement Number |
Requirement Description |
Result of Non-Compliance |
Applicable to Android? |
Reference Section |
| LDP_LOADER_1 |
A loader must return VK_ERROR_INCOMPATIBLE_DRIVER if it
fails to find and load a valid Vulkan driver on the system.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
N/A |
| LDP_LOADER_2 |
A loader must attempt to load any driver's Manifest file it
discovers and determines is formatted in accordance with this document.
The only exception is on platforms which determines driver
location and functionality through some other mechanism.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
Driver Discovery
|
| LDP_LOADER_3 |
A loader must support a mechanism to load driver in one or more
non-standard locations.
This is to allow support for fully software drivers as well as
evaluating in-development ICDs.
The only exception to this rule is if the OS does not wish to
support this due to security policies.
|
It will be more difficult to use a Vulkan loader by certain
tools and driver developers. |
No |
Pre-Production ICDs or SW
|
| LDP_LOADER_4 |
A loader must not load a Vulkan driver which defines an API
version that is incompatible with itself.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
Driver Discovery
|
| LDP_LOADER_5 |
A loader must ignore any driver for which a compatible
Loader and Driver Interface Version can not be negotiated.
|
The loader would load a driver improperly resulting in undefined
behavior possibly including crashes or corruption.
|
No |
Interface Negotiation
|
| LDP_LOADER_6 |
If a driver negotiation results in the loader using Loader and Driver
Interface Version 5 or newer, a loader must verify that the Vulkan
API version passed into vkCreateInstance (through
VkInstanceCreateInfo’s VkApplicationInfo's
apiVersion) is supported by at least one driver.
If the requested Vulkan API version can not be supported by any
driver, the loader must return
VK_ERROR_INCOMPATIBLE_DRIVER.
This is not required if the Loader and Driver Interface Version is 4 or
earlier because the responsibility for this check falls on the drivers.
|
The behavior is undefined and may result in crashes or corruption. |
No |
Version 5 Interface Requirements
|
| LDP_LOADER_7 |
If there exist more than one driver on a system, and some of those
drivers support only Vulkan API version 1.0 while other drivers
support a newer Vulkan API version, then a loader must adjust
the apiVersion field of the VkInstanceCreateInfo’s
VkApplicationInfo to version 1.0 for all the drivers that are
only aware of Vulkan API version 1.0.
Otherwise, the drivers that support Vulkan API version 1.0 will
return VK_ERROR_INCOMPATIBLE_DRIVER during
vkCreateInstance since 1.0 drivers were not aware of future
versions.
|
The behavior is undefined and may result in crashes or corruption. |
No |
Driver API Version
|
| LDP_LOADER_8 |
If more than one driver is present, and at least one driver does not
support instance-level functionality that other drivers support;
then a loader must support the instance-level functionality in
some fashion for the non-supporting drivers.
|
The behavior is undefined and may result in crashes or corruption. |
No |
Loader Instance Extension Emulation Support
|
| LDP_LOADER_9 |
A loader must filter out instance extensions from the
VkInstanceCreateInfo structure's ppEnabledExtensionNames
field that the driver does not support during a call to the driver's
vkCreateInstance.
This is because the application has no way of knowing which
drivers support which extensions.
This ties in directly with LDP_LOADER_8 above.
|
The behavior is undefined and may result in crashes or corruption. |
No |
Filtering Out Instance Extension Names
|
| LDP_LOADER_10 |
A loader must support creating VkSurfaceKHR handles
that may be shared by all underlying drivers.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
Handling KHR Surface Objects
|
| LDP_LOADER_11 |
If a driver exposes the appropriate VkSurfaceKHR
creation/handling entry-points, a loader must support creating
the driver-specific surface object handle and provide it, and not the
shared VkSurfaceKHR handle, back to that driver when requested.
Otherwise, a loader must provide the loader created
VkSurfaceKHR handle.
|
The behavior is undefined and may result in crashes or corruption. |
No |
Handling KHR Surface Objects
|
| LDP_LOADER_12 |
A loader must not call any vkEnumerate*ExtensionProperties
entry-points in a driver if pLayerName is not NULL.
|
The behavior is undefined and may result in crashes or corruption. |
Yes |
Additional Interface Notes
|
| LDP_LOADER_13 |
A loader must not load from user-defined paths (including the
use of any of VK_ICD_FILENAMES, VK_DRIVER_FILES, or
VK_ADD_DRIVER_FILES environment variables) when running elevated
(Administrator/Super-user) applications.
This is for security reasons.
|
The behavior is undefined and may result in computer security lapses,
crashes or corruption.
|
No |
Exception for Administrator and Super-User mode
|