loader/LoaderAndLayerInterface.md

# Vulkan Loader Specification and Architecture Overview


Goals of this document
----------------------

Specify necessary functions and expected behavior of interface between the
loader library and ICDs and layers for Windows, Linux and Android based
systems. Also describe the application visible behaviors of the loader.

Audience
--------

Application, Vulkan driver and Vulkan layer developers.

Any developers interested in understanding more about loader and layer behavior
and architecture.


Loader goals
------------

-   Support multiple ICDs (Installable Client Drivers) to co-exist on a system
without interfering with each other.

-   Support optional modules (layers) that can be enabled by an application,
developer or the system and have no impact when not enabled.

-   Negligible performance cost for an application calling through the loader
to an ICD entry point.

Architectural overview of layers and loader
-------------------------------------------

Vulkan is layered architecture. Layers can hook (intercept) Vulkan commands to
achieve various functionality that a Vulkan driver (aka ICD) or loader doesn’t
support. Functionality such as Vulkan API tracing and debugging, API usage
validation, and other tools such as framebuffer overlays are all natural
candidates for Vulkan layers. Layers are implemented as libraries that are
inserted between the application and the driver.

Not only is Vulkan a layered architecture but it also supports multiple GPUs
and their drivers. Vulkan commands called by an application may wind up calling
into a diverse set of modules: loader, layers, and ICDs. The loader is critical
to managing the proper dispatching of Vulkan commands to the appropriate set of
layers and ICDs. The loader inserts layers into a call chain so they can
intercept Vulkan commands prior to the proper ICD being called. To achieve
proper dispatching of Vulkan command to layers and ICDs the loader uses the
Vulkan object model.

Vulkan uses an object model to control the scope of a particular action /
operation.  The object to be acted on is always the first parameter of a Vulkan
call and is a dispatchable object (see Vulkan specification section 2.2 Object
Model).  Under the covers, the dispatchable object handle is a pointer to a
structure that contains a pointer to a dispatch table maintained by the loader.
This dispatch table contains pointers to the Vulkan functions appropriate to
that object. I.e. a VkInstance object’s dispatch table will point to Vulkan
functions such as vkEnumeratePhysicalDevices, vkDestroyInstance,
vkCreateInstance, etc.

Device objects have a separate dispatch table containing the appropriate
function pointers.

These instance and device dispatch tables are constructed when the application
calls vkCreateInstance and vkCreateDevice. At that time the application and/or
system can specify optional layers to be included. The loader will initialize
the specified layers to create a call chain for each Vulkan function and each
entry of the dispatch table will point to the first element of that chain.
Thus, the loader builds an instance call chain for each VkInstance that is
created and a device call chain for each VkDevice that is created.

For example, the diagram below represents what happens in the call chain for
vkCreateInstance. After initializing the chain, the loader will call into the
first layer’s vkCreateInstance which will call the next finally terminating in
the loader again where this function calls every ICD’s vkCreateInstance and
saves the results. This allows every enabled layer for this chain to set up
what it needs based on the VkInstanceCreateInfo structure from the application.

This also highlights some of the complexity the loader must manage when using
instance chains. As shown here, the loader must aggregate information from
multiple devices when they are present. This means that the loader has to know
about instance level extensions to aggregate them correctly.

Device chains are created at vkCreateDevice and are generally simpler because
they deal with only a single device and the ICD can always be the terminator of
the chain. The below diagram also illustrates how layers (either device or
instance) can skip intercepting any given Vulkan entry point.

Application interface to loader
-------------------------------

In this section we’ll discuss how an application interacts with the loader.

-   Linking to loader library for core and WSI extension symbols.

-   Dynamic Vulkan command lookup & application dispatch table.

-   Loader library filenames for linking to different Vulkan ABI versions.

-   Layers

-   Extensions

-   vkGetInstanceProcAddr, vkGetDeviceProcAddr

The loader library on Windows, Linux and Android will export all core Vulkan
and all appropriate Window System Interface (WSI) extensions. This is done to
make it simpler to get started with Vulkan development. When an application
links directly to the loader library in this way, the Vulkan calls are simple
trampoline functions that jump to the appropriate dispatch table entry for the
object they are given.

Applications are not required to link directly to the loader library, instead
they can use the appropriate platform specific dynamic symbol lookup on the
loader library to initialize the application’s own dispatch table. This allows
an application to fail gracefully if the loader cannot be found and provide the
fastest mechanism for the application to call Vulkan functions. An application
will only need to query (via system calls such as dlsym()) the address of
vkGetInstanceProcAddr from the loader library. Using vkGetInstanceProcAddr the
application can then discover the address of all instance and global functions
and extensions, such as vkCreateInstance,
vkEnumerateInstanceExtensionProperties and vkEnumerateInstanceLayerProperties
in a platform independent way.

The Vulkan loader library will be distributed in various ways including Vulkan
SDKs, OS package distributions and IHV driver packages. These details are
beyond the scope of this document. However, the name and versioning of the
Vulkan loader library is specified so an app can link to the correct Vulkan ABI
library version. Vulkan versioning is such that ABI backwards compatibility is
guaranteed for all versions with the same major number (eg 1.0 and 1.1). On
Windows, the loader library encodes the ABI version in its name such that
multiple ABI incompatible versions of the loader can peacefully coexist on a
given system. The vulkan loader library key name is “vulkan-<ABI
version>”. For example, for Vulkan version 1.X on Windows the library
filename is vulkan-1.dll. And this library file can typically be found in the
windows/system32 directory.

For Linux, shared libraries are versioned based on a suffix. Thus, the ABI
number is not encoded in the base of the library filename as on Windows. On
Linux an application wanting to link to the latest Vulkan ABI version would
just link to the name vulkan (libvulkan.so).  A specific Vulkan ABI version can
also be linked to by applications (eg libvulkan.so.1).

Applications desiring Vulkan functionality beyond what the core API offers may
use various layers or extensions. A layer cannot add new or modify existing
Vulkan commands, but may offer extensions that do. A common use of layers is
for API validation. A developer can use validation layers during application
development, but during production the layers can be disabled by the
application. Thus, eliminating the overhead of validating the applications
usage of the API. Layers discovered by the loader can be reported to the
application via vkEnumerateInstanceLayerProperties and
vkEnumerateDeviceLayerProperties, for instance and device layers respectively.
Instance layers are enabled at vkCreateInstance; device layers are enabled at
vkCreateDevice. For example, the ppEnabledLayerNames array in the
VkDeviceCreateInfo structure is used by the application to list the device
layer names to be enabled at vkCreateDevice. At vkCreateInstance and
vkCreateDevice, the loader will construct call chains that include the
application specified (enabled) layers. Order is important in the
ppEnabledLayerNames array; array element 0 is the topmost (closest to the
application) layer inserted in the chain and the last array element is closest
to the driver.

Developers may want to enable layers that are not enabled by the given
application they are using. On Linux and Windows, the environment variables
“VK\_INSTANCE\_LAYERS” and “VK\_DEVICE\_LAYERS” can be used to enable
additional layers which are not specified (enabled) by the application at
vkCreateInstance/vkCreateDevice. VK\_INSTANCE\_LAYERS is a colon
(Linux)/semi-colon (Windows) separated list of layer names to enable. Order is
relevant with the first layer in the list being the topmost layer (closest to
the application) and the last layer in the list being the bottommost layer
(closest to the driver).

Application specified layers and user specified layers (via environment
variables) are aggregated and duplicates removed by the loader when enabling
layers. Layers specified via environment variable are topmost (closest to the
application) while layers specified by the application are bottommost.

An example of using these environment variables to activate the validation
layer VK\_LAYER\_LUNARG\_param\_checker on Windows or Linux is as follows:

```
> $ export VK_INSTANCE_LAYERS=VK_LAYER_LUNARG_param_checker

> $ export VK_DEVICE_LAYERS=VK_LAYER_LUNARG_param_checker
```

**Note**: Many layers, including all LunarG validation layers are “global”
(i.e. both instance and device) layers and *must* be enabled on both the
instance and device chains to function properly. This is required for “global”
layers regardless of which method is used to enable the layer (application or
environment variable).

Some platforms, including Linux and Windows, support layers which are enabled
automatically by the loader rather than explicitly by the application (or via
environment variable). Explicit layers are those layers enabled by the
application (or environment variable) by providing the layer name. Implicit
layers are those layers enabled by the loader automatically. Any implicit
layers the loader discovers on the system in the appropriate location will be
enabled (subject to environment variable overrides described later). Discovery
of properly installed implicit and explicit layers is described later.
Explicitly enabling a layer that is implicitly enabled has no additional
effect: the layer will still be enabled implicitly by the loader.

Extensions are optional functionality provided by a layer, the loader or an
ICD. Extensions can modify the behavior of the Vulkan API and need to be
specified and registered with Khronos.

Instance extensions can be discovered via
vkEnumerateInstanceExtensionProperties. Device extensions can be discovered via
vkEnumerateDeviceExtensionProperties. The loader discovers and aggregates all
extensions from layers (both explicit and implicit), ICDs and the loader before
reporting them to the application in vkEnumerate\*ExtensionProperties. The
pLayerName parameter in these functions are used to select either a single
layer or the Vulkan platform implementation. If pLayerName is NULL, extensions
from Vulkan implementation components (including loader, implicit layers, and
ICDs) are enumerated. If pLayerName is equal to a discovered layer module name
then any extensions from that layer (which may be implicit or explicit) are
enumerated. Duplicate extensions (eg an implicit layer and ICD might report
support for the same extension) are eliminated by the loader. Extensions must
be enabled (in vkCreateInstance or vkCreateDevice) before they can be used.

Extension command entry points should be queried via vkGetInstanceProcAddr or
vkGetDeviceProcAddr. vkGetDeviceProcAddr can only be used to query for device
extension or core device entry points. Device entry points include any command
that uses a VkDevice as the first parameter or a dispatchable object that is a
child of a VkDevice (currently this includes VkQueue and VkCommandBuffer).
vkGetInstanceProcAddr can be used to query either device or instance extension
entry points in addition to all core entry points.

VkGetDeviceProcAddr is particularly interesting because it will provide the
most efficient way to call into the ICD. For example, the diagram below shows
what could happen if the application were to use vkGetDeviceProcAddr for the
function “vkGetDeviceQueue” and “vkDestroyDevice” but not “vkAllocateMemory”.
The resulting function pointer (fpGetDeviceQueue) would be the ICD’s entry
point if the loader and any enabled layers do not need to see that call. Even
if an enabled layer intercepts the call (eg vkDestroyDevice) the loader
trampoline code is skipped for function pointers obtained via
vkGetDeviceProcAddr. This also means that function pointers obtained via
vkGetDeviceProcAddr will only work with the specific VkDevice it was created
for, using it with another device has undefined results. For extensions,
Get\*ProcAddr will often be the only way to access extension API features.


Vulkan Installable Client Driver interface with the loader
----------------------------------------------------------

### ICD discovery

Vulkan allows multiple drivers each with one or more devices (represented by a
Vulkan VkPhysicalDevice object) to be used collectively. The loader is
responsible for discovering available Vulkan ICDs on the system. Given a list
of available ICDs, the loader can enumerate all the physical devices available
for an application and return this information to the application. The process
in which the loader discovers the available Installable Client Drivers (ICDs)
on a system is platform dependent. Windows, Linux and Android ICD discovery
details are listed below.

#### Windows

##### Properly-Installed ICDs

In order to find properly-installed ICDs, the Vulkan loader will scan the
values in the following Windows registry key:

HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\Drivers

For each value in this key which has DWORD data set to 0, the loader opens the
JSON format text information file (a.k.a. "manifest file") specified by the
name of the value. Each name must be a full pathname to the text manifest file.
The Vulkan loader will open each manifest file to obtain the name or pathname
of an ICD shared library (".dll") file. For example:

 ```
 {
    "file_format_version": "1.0.0",
    "ICD": {
        "library_path": "path to ICD library",
        "api_version": "1.0.3"
    }
  }
  ```


The "library\_path" specifies either a filename, a relative pathname, or a full
pathname to an ICD shared library file, which the loader will attempt to load
using LoadLibrary(). If the ICD is specified via a filename, the shared library
lives in the system's DLL search path (e.g. in the "C:\\\\Windows\\\\System32"
folder). If the ICD is specified via a relative pathname, it is relative to the
path of the manifest file. Relative pathnames are those that do not start with
a drive specifier (e.g. "C:"), nor with a directory separator (i.e. the '\\'
character), but do contain at least one directory separator.

The "file\_format\_version" specifies a major.minor.patch version number in
case the format of the text information file changes in the future. If the same
ICD shared library supports multiple, incompatible versions of text manifest
file format versions, it must have multiple text info files (all of which may
point to the same shared library).

The “api\_version” specifies the major.minor.patch version number of the Vulkan
API that the shared library (referenced by "library\_path") was built with.

There are no rules about the name of the text information files (except the
.json suffix).

There are no rules about the name of the ICD shared library files. For example,
if the registry contains the following values,

```
[HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\Vulkan\Drivers\]

"C:\vendor a\vk\_vendora.json"=dword:00000000

"C:\windows\system32\vendorb\_vk.json"=dword:00000000

"C:\windows\system32\vendorc\_icd.json"=dword:00000000
```
then the loader will open the following text information files, with the
specified contents:

| Text File Name | Text File Contents |
|-------------------------------------|
|vk\_vendora.json  | "ICD": { "library\_path": "C:\\\\VENDORA\\\\vk\_vendora.dll", "api_version": "1.0.3" } |
| vendorb\_vk.json |  "ICD": { "library\_path": "vendorb\_vk.dll", "api_version": "1.0.3" } |
|vendorc\_icd.json  | "ICD": { "library\_path": "vedorc\_icd.dll", "api_version": "1.0.3" }|

Then the loader will open the three files mentioned in the "Text File Contents"
column, and then try to load and use the three shared libraries indicated by
the ICD.library\_path value.

##### Using Pre-Production ICDs

IHV developers (and sometimes other developers) need to use special,
pre-production ICDs. In some cases, a pre-production ICD may be in an
installable package. In other cases, a pre-production ICD may simply be a
shared library in the developer's build tree. In this latter case, we want to
allow developers to point to such an ICD without modifying the
properly-installed ICD(s) on their system.

This need is met with the use of the "VK\_ICD\_FILENAMES" environment variable,
which will override the mechanism used for finding properly-installed ICDs. In
other words, only the ICDs listed in "VK\_ICD\_FILENAMES" will be used. The
"VK\_ICD\_FILENAMES" environment variable is a semi-colon-separated list of ICD
text information files (aka manifest files), containing the following:

- A full pathname (e.g. "C:\\my\_build\\my\_icd.json")

Typically, "VK\_ICD\_FILENAMES" will only contain a full pathname to one info
file for a developer-built ICD. A semi-colon is only used if more than one ICD
is listed.

For example, if a developer wants to refer to one ICD that they built, they
could set the "VK\_ICD\_FILENAMES" environment variable to:

C:\\my\_build\\my\_icd.json

If a developer wants to refer to two ICDs, one of which is a properly-installed
ICD, they can use the full pathname of the text file:

C:\\Windows\\System32\\vendorc\_icd.json;C:\\my\_build\\my\_icd.json

Notice the semi-colon between "C:\\Windows\\System32\\vendorc\_icd.json" and
"C:\\my\_build\\my\_icd.json".

#### Linux

##### Properly-Installed ICDs

In order to find properly-installed ICDs, the Vulkan loader will scan the files
in the following Linux directories:

/usr/share/vulkan/icd.d
/etc/vulkan/icd.d

These directories will contain text information files (a.k.a. "manifest
files"), that use a JSON format.

The Vulkan loader will open each manifest file found to obtain the name or
pathname of an ICD shared library (".so") file. For example:

```
{
    "file_format_version": "1.0.0",
    "ICD": {
        "library_path": "path to ICD library",
        "api_version": "1.0.3"
    }
}
```
The "library\_path" specifies either a filename, a relative pathname, or a full
pathname to an ICD shared library file. If the ICD is specified via a filename,
the loader will attempt to open that file as a shared object using dlopen(),
and the file must be in a directory that dlopen is configured to look in (Note:
various distributions are configured differently). A distribution is free to
create Vulkan-specific system directories (e.g. ".../vulkan/icd"), but is not
required to do so. If the ICD is specified via a relative pathname, it is
relative to the path of the info file. Relative pathnames are those that do not
start with, but do contain at least one directory separator (i.e. the '/'
character). For example, "lib/vendora.so" and "./vendora.so" are examples of
relative pathnames.

The "file\_format\_version" provides a major.minor.patch version number in case
the format of the manifest file changes in the future. If the same ICD shared
library supports multiple, incompatible versions of manifest file format
versions, it must have multiple manifest files (all of which may point to the
same shared library).

The “api\_version” specifies the major.minor.patch version number of the Vulkan
API that the shared library (referenced by "library\_path") was built with.

The "/usr/share/vulkan/icd.d" directory is for ICDs that are installed from
Linux-distribution-provided packages. The "/etc/vulkan/icd.d" directory is for
ICDs that are installed from non-Linux-distribution-provided packages.

There are no rules about the name of the text files (except the .json suffix).

There are no rules about the name of the ICD shared library files. For example,
if the "/usr/share/vulkan/icd.d" directory contain the following files, with
the specified contents:

| Text File Name  | Text File Contents |
|-----------------|--------------------|
|vk\_vendora.json | "ICD": { "library\_path": "vendora.so", "api_version": "1.0.3" } |
| vendorb\_vk.json | "ICD": { "library\_path": "vendorb\_vulkan\_icd.so", "api_version": "1.0.3" } |
| vendorc\_icd.json | "ICD": { "library\_path": "/usr/lib/VENDORC/icd.so", "api_version": "1.0.1" }|

then the loader will open the three files mentioned in the "Text File Contents"
column, and then try to load and use the three shared libraries indicated by
the ICD.library\_path value.

##### Using Pre-Production ICDs

IHV developers (and sometimes other developers) need to use special,
pre-production ICDs. In some cases, a pre-production ICD may be in an
installable package. In other cases, a pre-production ICD may simply be a
shared library in the developer's build tree. In this latter case, we want to
allow developers to point to such an ICD without modifying the
properly-installed ICD(s) on their system.

This need is met with the use of the "VK\_ICD\_FILENAMES" environment variable,
which will override the mechanism used for finding properly-installed ICDs. In
other words, only the ICDs listed in "VK\_ICD\_FILENAMES" will be used.

The "VK\_ICD\_FILENAMES" environment variable is a colon-separated list of ICD
manifest files, containing the following:

- A filename (e.g. "libvkicd.json") in the "/usr/share/vulkan/icd.d" or "/etc/vulkan/icd.d" system directories

- A full pathname (e.g. "/my\_build/my\_icd.json")

Typically, "VK\_ICD\_FILENAMES" will only contain a full pathname to one info
file for a developer-built ICD. A colon is only used if more than one ICD is
listed.

For example, if a developer wants to refer to one ICD that they built, they
could set the "VK\_ICD\_FILENAMES" environment variable to:

/my\_build/my\_icd.json

If a developer wants to refer to two ICDs, one of which is a properly-installed
ICD, they can use the name of the text file in the system directory:

vendorc\_vulkan.json:/my\_build/my\_icd.json

Notice the colon between "vendorc\_vulkan.json" and "/my\_build/my\_icd.json".

NOTE: this environment variable will be ignored for suid programs.

#### Android

TODO: Fill out this section


ICD interface requirements
----------------------------------------

Generally, for all Vulkan commands issued by an application, the loader can be
viewed as a pass through. That is, the loader generally doesn’t modified the
commands or their parameters but simply calls the ICDs entry point for that
command. Thus, the loader to ICD interface requirements will be specified by
covering two areas: 1) Obtaining ICD Vulkan entry points; 2) Specifying
requirements for a given Vulkan command(s) over and above the Vulkan
specification requirements.

#### Windows and Linux

##### Obtaining ICD entry points

Currently, two methods of the loader finding ICD entry points are supported on
Linux and Windows:

1) Recommended

- vk\_icdGetInstanceProcAddr exported in the ICD library and it returns valid
  function pointers for all the global level and instance level Vulkan commands,
  and also vkGetDeviceProcAddr. Global level commands are those which contain no
  dispatchable object as the first parameter, such as vkCreateInstance and
  vkEnumerateInstanceExtensionProperties. The ICD must support querying global
  level entry points by calling vk\_icdGetInstanceProcAddr with a NULL VkInstance
  parameter. Instance level commands 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 ICD 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, extensions entry points using these newly
  defined dispatchable oibjects must be queryable via vk\_icdGetInstanceProcAddr.

- All other Vulkan entry points must either NOT be exported from the ICD
  library or else NOT use the official Vulkan function names if they are
  exported. This requirement is for ICD libraries that include other
  functionality (such as OpenGL library) and thus could be loaded by the
  application prior to when the Vulkan loader library is loaded by the
  application. In other words, the ICD library exported Vulkan symbols must not
  clash with the loader's exported Vulkan symbols.

2) Deprecated

- vkGetInstanceProcAddr exported in the ICD library and returns valid function
  pointers for all the Vulkan API entrypoints.

- vkCreateInstance exported in the ICD library;

- vkEnumerateInstanceExtensionProperties exported in the ICD library;

##### Loader specific requirements for Vulkan commands

Normally, ICDs handle object creation and destruction for various Vulkan
objects. The WSI surface extensions for Linux and Windows
(VK\_KHR\_win32\_surface, VK\_KHR\_xcb\_surface, VK\_KHR\_xlib\_surface,
VK\_KHR\_mir\_surface, VK\_KHR\_wayland\_surface, and VK\_KHR\_surface) are
handled differently. For these extensions, the VkSurfaceKHR object creation and
destruction is handled by the loader as follows:

1. Loader handles the vkCreate\*SurfaceKHR() and vkDestroySurfaceKHR()
   functions including creating/destroying the VkSurfaceKHR object.

2. VkSurfaceKHR objects have the underlying structure (VkIcdSurface\*) as
   defined in include/vulkan/vk\_icd.h.

3. ICDs can cast any VkSurfaceKHR object to a pointer to the appropriate
   VkIcdSurface\* structure.

4. VkIcdSurface\* structures include VkIcdSurfaceWin32, VkIcdSurfaceXcb,
   VkIcdSurfaceXlib, VkIcdSurfaceMir, and VkIcdSurfaceWayland. The first field in
   the structure is a  VkIcdSurfaceBase enumerant that indicates westher the
   surface object is Win32, Xcb, Xlib, Mir, or Wayland.

As previously covered, the loader requires dispatch tables to be accessible
within Vulkan dispatchable objects, which include VkInstance, VkPhysicalDevice,
VkDevice, VkQueue, and VkCommandBuffer. The specific requirements on all
dispatchable objects created by ICDs are as follows:

- All dispatchable objects created by an ICD 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 ICD drivers:

1. The ICD 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\++ ICD's that implement VK objects directly as C\++
   classes. The C\++ compiler may put a vtable at offset zero if your class is
   virtual. 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):

```

#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;
}
```

Additional Notes:

- The loader will filter out extensions requested in vkCreateInstance and
vkCreateDevice before calling into the ICD; Filtering will be of extensions
advertised by entities (eg layers) different from the ICD in question.
- The loader will not call ICD for vkEnumerate\*LayerProperties() as layer
properties are obtained from the layer libraries and layer JSON files.
- If an ICD library wants to implement a layer it can do so by having the
appropriate layer JSON manifest file refer to the ICD library file.
- The loader will not call ICD for vkEnumerate\*ExtensionProperties(pLayerName
!= NULL).
- The ICD may or may not implement a dispatch table.

#### Android

TODO: Fill out this section

Vulkan layer interface with the loader
--------------------------------------

### Layer discovery

#### Windows

##### Properly-Installed Layers

In order to find properly-installed layers, the Vulkan loader will use a
similar mechanism as used for ICDs. Text information files (aka manifest
files), that use a JSON format, are read in order to identify the names and
attributes of layers and their extensions. The use of manifest files allows the
loader to avoid loading any shared library files when the application does not
query nor request any extensions. Layers and extensions have additional
complexity, and so their manifest files contain more information than ICD info
files. For example, a layer shared library file may contain multiple
layers/extensions (perhaps even an ICD).

In order to find properly-installed layers, the Vulkan loader will scan the
values in the following Windows registry keys:

HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\ExplicitLayers

HKEY\_LOCAL\_MACHINE\\SOFTWARE\\Khronos\\Vulkan\\ImplicitLayers

Explicit layers are those which are enabled by an application (e.g. with the
vkCreateInstance function), or by an environment variable (as mentioned
previously).

Implicit layers are those which are enabled by their existence. For example,
certain application environments (e.g. Steam or an automotive infotainment
system) may have layers which they always want enabled for all applications
that they start. Other implicit layers may be for all applications started on a
given system (e.g. layers that overlay frames-per-second). Implicit layers are
enabled automatically, whereas explicit layers must be enabled explicitly. What
distinguishes a layer as implicit or explicit is by which registry key its
layer information file is referenced by.

For each value in these keys which has DWORD data set to 0, the loader opens
the JSON manifest file specified by the name of the value. Each name must be a
full pathname to the manifest file.

The Vulkan loader will open each info file to obtain information about the
layer, including the name or pathname of a shared library (".dll") file.

This manifest file is in the JSON format and contains the following
information:

- (required) "file\_format\_version" - same as for ICDs, except that the format
version can vary independently for ICDs and layers.

- (required) "name" - layer name

- (required) "type" - which layer chains should the layer be activated on.
Allowable values are "INSTANCE", "DEVICE", "GLOBAL". Global means activate on
both device and instance chains.

- (required) "library\_path" - filename / full path / relative path to the
library file

- (required) "api\_version" - same as for ICDs.

- (required) "implementation\_version" - layer version, a single number
increasing with backward compatible changes.

- (required) "description" - informative description of the layer.

- (optional) "device\_extensions" or "instance\_extensions" - array of
extension information as follows

    - (required) extension "name" - Vulkan registered name

    - (required) extension "spec\_version" - extension specification version, a
single number, increasing with backward compatible changes.

    - (required for device\_extensions with entry points) extension
"entrypoints" - array of device extension entrypoints; not used for instance
extensions

- (sometimes required) "functions" - mapping list of function entry points. If
multiple layers exist within the same shared library (or if a layer is in the
same shared library as an ICD), this must be specified to allow each layer to
have its own vkGet\*ProcAddr entrypoints that can be found by the loader. At
this time, only the following two functions are required:

    - "vkGetInstanceProcAddr" name

    - "vkGetDeviceProcAddr" name

- (optional for implicit layers) "enable\_environment" requirement(s) -
environment variable and value required to enable an implicit layer. This
environment variable (which should vary with each "version" of the layer, as in
"ENABLE\_LAYER\_FOO\_1") must be set to the given value or else the implicit
layer is not loaded. This is for application environments (e.g. Steam) which
want to enable a layer(s) only for applications that they launch, and allows
for applications run outside of an application environment to not get that
implicit layer(s).

- (required for implicit layers) "disable\_environment" requirement(s) -
environment variable and value required to disable an implicit layer. Note: in
rare cases of an application not working with an implicit layer, the
application can set this environment variable (before calling Vulkan functions)
in order to "blacklist" the layer. This environment variable (which should vary
with each "version" of the layer, as in "DISABLE\_LAYER\_FOO\_1") must be set
(not particularly to any value). If both the "enable\_environment" and
"disable\_environment" variables are set, the implicit layer is disabled.

For example:

```
{
"file_format_version" : "1.0.0",
"layer": {
    "name": "VK_LAYER_LUNARG_OverlayLayer",
    "type": "DEVICE",
    "library_path": "vkOverlayLayer.dll"
    "api_version" : "1.0.3",
    "implementation_version" : "2",
    "description" : "LunarG HUD layer",
    "functions": {
        "vkGetInstanceProcAddr": "OverlayLayer_GetInstanceProcAddr",
        "vkGetDeviceProcAddr": "OverlayLayer_GetDeviceProcAddr"
    },
    instance_extensions": [
        {
            "name": "VK_debug_report_EXT",
            "spec_version": "1"
        },
        {
            "name": "VK_VENDOR_DEBUG_X",
            "spec_version": "3"
         }
    ],
    device_extensions": [
        {
            "name": "VK_LUNARG_DEBUG_MARKER",
            "spec_version": "1",
            "entrypoints": ["vkCmdDbgMarkerBegin", "vkCmdDbgMarkerEnd"]
        }
    ],
    "disable_environment": {
        "DISABLE_LAYER_OVERLAY_1": ""
    }
}
}
```

The "library\_path" specifies either a filename, a relative pathname, or a full
pathname to a layer shared library (".dll") file, which the loader will attempt
to load using LoadLibrary(). If the layer is specified via a relative pathname,
it is relative to the path of the info file (e.g. for cases when an application
provides a layer that is in the same folder hierarchy as the rest of the
application files). If the layer is specified via a filename, the shared
library lives in the system's DLL search path (e.g. in the
"C:\\Windows\\System32" folder).

There are no rules about the name of the text files (except the .json suffix).

There are no rules about the name of the layer shared library files.

##### Using Pre-Production Layers

As with ICDs, developers may need to use special, pre-production layers,
without modifying the properly-installed layers. This need is met with the use
of the "VK\_LAYER\_PATH" environment variable, which will override the
mechanism using for finding properly-installed layers. Because many layers may
exist on a system, this environment variable is a semi-colon-separated list of
folders that contain layer info files. Only the folder listed in
"VK\_LAYER\_PATH" will be scanned for info files. Each semi-colon-separated
entry is:

- The full pathname of a folder containing layer info files

#### Linux

##### Properly-Installed Layers

In order to find properly-installed layers, the Vulkan loader will use a
similar mechanism as used for ICDs. Text information files, that use a JSON
format, are read in order to identify the names and attributes of layers and
their extensions. The use of text info files allows the loader to avoid loading
any shared library files when the application does not query nor request any
extensions. Layers and extensions have additional complexity, and so their info
files contain more information than ICD info files. For example, a layer shared
library file may contain multiple layers/extensions (perhaps even an ICD).

The Vulkan loader will scan the files in the following Linux directories:

/usr/share/vulkan/explicit\_layer.d
/usr/share/vulkan/implicit\_layer.d
/etc/vulkan/explicit\_layer.d
/etc/vulkan/implicit\_layer.d

Explicit layers are those which are enabled by an application (e.g. with the
vkCreateInstance function), or by an environment variable (as mentioned
previously). Implicit layers are those which are enabled by their existence.
For example, certain application environments (e.g. Steam or an automotive
infotainment system) may have layers which they always want enabled for all
applications that they start. Other implicit layers may be for all applications
started on a given system (e.g. layers that overlay frames-per-second).
Implicit layers are enabled automatically, whereas explicit layers must be
enabled explicitly. What distinguishes a layer as implicit or explicit is by
which directory its layer information file exists in.

The "/usr/share/vulkan/\*\_layer.d" directories are for layers that are
installed from Linux-distribution-provided packages. The
"/etc/vulkan/\*\_layer.d" directories are for layers that are installed from
non-Linux-distribution-provided packages.

The information file is in the JSON format and contains the following
information:

- (required) "file\_format\_version" – same as for ICDs, except that the format
version can vary independently for ICDs and layers.

- (required) "name" - layer name

- (required) "type" - which layer chains should the layer be activated on.
Allowable values are "INSTANCE", "DEVICE", "GLOBAL". Global means activate on
both device and instance chains.

- (required) "library\_path" - filename / full path / relative path to the text
file

- (required) "api\_version" – same as for ICDs.

- (required) "implementation\_version" – layer version, a single number
increasing with backward compatible changes.

- (required) "description" – informative decription of the layer.

- (optional) "device\_extensions" or "instance\_extensions" - array of
extension information as follows

    - (required) extension "name" - Vulkan registered name

    - (required) extension "spec\_version" - extension specification version, a
single number, increasing with backward compatible changes.

    - (required for device extensions with entry points) extension
"entrypoints" - array of device extension entrypoints; not used for instance
extensions

- (sometimes required) "functions" - mapping list of function entry points. If
multiple layers exist within the same shared library (or if a layer is in the
same shared library as an ICD), this must be specified to allow each layer to
have its own vkGet\*ProcAddr entrypoints that can be found by the loader. At
this time, only the following two functions are required:
    - "vkGetInstanceProcAddr" name
    - "vkGetDeviceProcAddr" name

- (optional for implicit layers) "enable\_environment" requirement(s) -
environment variable and value required to enable an implicit layer. This
environment variable (which should vary with each "version" of the layer, as in
"ENABLE\_LAYER\_FOO\_1") must be set to the given value or else the implicit
layer is not loaded. This is for application environments (e.g. Steam) which
want to enable a layer(s) only for applications that they launch, and allows
for applications run outside of an application environment to not get that
implicit layer(s).

- (required for implicit layers) "disable\_environment" requirement(s) -
environment variable and value required to disable an implicit layer. Note: in
rare cases of an application not working with an implicit layer, the
application can set this environment variable (before calling Vulkan functions)
in order to "blacklist" the layer. This environment variable (which should vary
with each "version" of the layer, as in "DISABLE\_LAYER\_FOO\_1") must be set
(not particularly to any value). If both the "enable\_environment" and
"disable\_environment" variables are set, the implicit layer is disabled.

For example:
```
{
"file_format_version" : "1.0.0",
"layer": {
    "name": "VK_LAYER_LUNARG_OverlayLayer",
    "type": "DEVICE",
    "library_path": "vkOverlayLayer.dll"
    "api_version" : "1.0.3",
    "implementation_version" : "2",
    "description" : "LunarG HUD layer",
    "functions": {
        "vkGetInstanceProcAddr": "OverlayLayer_GetInstanceProcAddr",
        "vkGetDeviceProcAddr": "OverlayLayer_GetDeviceProcAddr"
    },
    instance_extensions": [
        {
            "name": "VK_debug_report_EXT",
            "spec_version": "1"
        },
        {
            "name": "VK_VENDOR_DEBUG_X",
            "spec_version": "3"
         }
    ],
    device_extensions": [
        {
            "name": "VK_LUNARG_DEBUG_MARKER",
            "spec_version": "1",
            "entrypoints": ["vkCmdDbgMarkerBegin", "vkCmdDbgMarkerEnd"]
        }
    ],
    "disable_environment": {
        "DISABLE_LAYER_OVERLAY_1": ""
    }
}
}
```
The "library\_path" specifies either a filename, a relative pathname, or a full
pathname to a layer shared library (".so") file, which the loader will attempt
to load using dlopen(). If the layer is specified via a filename, the loader
will attempt to open that file as a shared object using dlopen(), and the file
must be in a directory that dlopen is configured to look in (Note: various
distributions are configured differently). A distribution is free to create
Vulkan-specific system directories (e.g. ".../vulkan/layers"), but is not
required to do so. If the layer is specified via a relative pathname, it is
relative to the path of the info file (e.g. for cases when an application
provides a layer that is in the same directory hierarchy as the rest of the
application files).

There are no rules about the name of the text files (except the .json suffix).

There are no rules about the name of the layer shared library files.

##### Using Pre-Production Layers

As with ICDs, developers may need to use special, pre-production layers,
without modifying the properly-installed layers.  This need is met with the use
of the "VK\_LAYER\_PATH" environment variable, which will override the
mechanism using for finding properly-installed layers. Because many layers may
exist on a system, this environment variable is a colon-separated list of
directories that contain layer info files. Only the directories listed in
"VK\_LAYER\_PATH" will be scanned for info files. Each colon-separated entry
is:

- The full pathname of a directory containing layer info files

NOTE: these environment variables will be ignored for suid programs.

#### Android

TODO: Fill out this section

Layer interface requirements
------------------------------------------------------

#### Architectural interface overview

There are two key architectural features that drive the loader to layer library
interface: 1) separate and distinct instance and device call chains, and 2)
distributed dispatch. First these architectural features will be described and
then the detailed interface will be specified.

Call chains are the links of calls for a given Vulkan command from layer module
to layer module with the loader and or the ICD being the bottom most command.
Call chains are constructed at both the instance level and the device level by
the loader with cooperation from the layer libraries. Instance call chains are
constructed by the loader when layers are enabled at vkCreateInstance. Device
call chains are constructed by the loader when layers are enabled at
CreateDevice. A layer can intercept Vulkan instance commands, device commands
or both. For a layer to intercept instance commands, it must participate in the
instance call chain. For a layer to intercept device commands, it must
participate in the device chain. Layers which participate in intercepting calls
in both the intance and device chains are called global layers.

Normally, when a layer intercepts a given Vulkan command, it will call down the
instance or device chain as needed. The loader and all layer libraries that
participate in a call chain cooperate to ensure the correct sequencing of calls
from one entity to the next. This group effort for call cahin sequencing is
hereinafter referred to as disitributed dispatch. In distributed dispatch,
since each layer is responsible for properly calling the next entity in the
device or instance chain, a dispatch mechanism is required for all Vulkan
commands a layer intercepts. For Vulkan commands that are not intercepted by a
layer, or if the layer chooses to terminate a given Vulkman command by not
calling down the chain, then no dispatch mechanism is needed for that
particular Vulkan command.  Only for those Vulkan commands, which may be a
subset of all Vulkan commands, that a layer intercepts is a dispatching
mechanism by the layer needed. The loader is responsible for dispatching all
core and instance extension Vulkan commands to the first entity in the chain.

Instance level Vulkan commands are those that have the disapatchable objects
VkInstance, or VkPhysicalDevice as the first parameter and alos includes
vkCreateInstance.
Device level Vulkan commands are those that use VkDevice, VkQueue or
VkCommandBuffer as the first parameter and also include vkCreateDevice. Future
extensions may introduce new instance or device level dispatchable objects, so
the above lists may be extended in the future.

#### Discovery of layer entrypoints
For the layer libraries that have been discovered by the loader, their
intercepting entry points that will participate in a device or instance call
chain need to be available to the loader or whatever layer is before them in
the chain.  Layers having the following requirements in this area.
- A layer intercepting instance level Vulkan commands (aka an instance level
layer)  must implement a vkGetInstanceProcAddr type of function.
- This vkGetInstanceProcAddr type function must be exported by the layer
library. The name of this function is specified in various ways: 1) the layer
manifest JSON file in the "functions", "vkGetInstanceProcAddr" node
(Linux/Windows); 2) it is named "vkGetInstanceProcAddr"; 3) it is
"<layerName>GetInstanceProcAddr (Android).
- A layer intercepting device level Vulkan commands (aka a device level layer)
must implement a vkGetDeviceProcAddr type of function.
- This vkGetDeviceProcAddr type function must be exported by the layer library.
The name of this function is specified in various ways: 1) the layer manifest
JSON file in the "functions", "vkGetDeviceProcAddr" node (Linux/Windows); 2) it
is named "vkGetDeviceProcAddr"; 3) it is "<layerName>GetDeviceProcAddr
(Android).
- A layer's vkGetInstanceProcAddr function (irregardless of it's name) must
return the local entry points for all instance level Vulkan commands it
intercepts. At a minimum, this includes vkGetInstanceProcAddr and
vkCreateInstance.
- A layer's vkGetDeviceProcAddr function (irregardless of it's name) must
return the entry points for all device level Vulkan commands it intercepts. At
a minimum, this includes vkGetDeviceProcAddr and vkCreateDevice.
- There are no requirements on the names of the intercepting functions a layer
implements except those listed above for vkGetInstanceProcAddr and
vkGetDeviceProcAddr.
- Currently a layer's VkGetInstanceProcAddr must be able to handle a VkInstance
parameter equal to NULL for
instance level commands it intercepts including vkCreateDevice.
- Currently a layer's VkGetDeviceProcAddr must be able to handle a VkDevice
parameter equal to NULL for device level commands it intercepts.

#### Layer intercept requirements
- Layers intercept a Vulkan command by defining a C/C++ function with signature
identical to the Vulkan API for that command.
- Other than the two vkGet*ProcAddr, all other functions intercepted by a layer
need NOT be exported by the layer.
- For any Vulkan command a layer intercepts which has a non-void return value,
an appropriate value must be returned by the layer intercept function.
- The layer intercept function must call down the chain to the corresponding
Vulkan command in the next entity. Undefined results will occur if a layer
doesn't propagate calls down the chain. The two exceptions to this requirement
are vkGetInstanceProcAddr and vkGetDeviceProcAddr which only call down the
chain for Vulkan commands that they do not intercept.
- Layer intercept functions may insert extra calls to Vulkan commands in
addition to the intercept. For example, a layer intercepting vkQueueSubmit may
want to add a call to vkQueueWaitIdle after calling down the chain for
vkQueueSubmit.  Any additional calls inserted by a layer must be on the same
chain. They should call down the chain.

#### Distributed dispatching requirements
- For each entry point a layer intercepts, it must keep track of the entry
point residing in the next entity in the chain it will call down into. In other
words, the layer must have a list of pointers to functions of the appropriate
type to call into the next entity. This can be implemented in various ways but
for clarity will be referred to as a dispatch table.
- A layer can use the VkLayerDispatchTable structure as a device dispatch table
(see include/vulkan/vk_layer.h).
- A layer can use the VkLayerInstanceDispatchTable structure as a instance
dispatch table (see include/vulkan/vk_layer.h).
- Layers vkGetInstanceProcAddr function uses the next entity's
vkGetInstanceProcAddr to call down the chain for unknown (ie non-intercepted)
functions.
- Layers vkGetDeviceProcAddr function uses the next entity's
vkGetDeviceProcAddr to call down the chain for unknown (ie non-intercepted)
functions.

#### Layer dispatch initialization
- A layer intializes it's instance dispatch table within it's vkCreateInstance
function.
- A layer intializes it's device dispatch table within it's vkCreateDevice
function.
- The loader passes a linked list of initialization structures to layers via
the "pNext" field in the VkInstanceCreateInfo and VkDeviceCreateInfo structures
for vkCreateInstance  and VkCreateDevice respectively.
- The head node in this linked list is of type VkLayerInstanceCreateInfo for
instance  and VkLayerDeviceCreateInfo for device. See file
include/vulkan/vk_layer.h for details.
- A VK_STRUCTURE_TYPE_LOADER_INSTANCE_CREATE_INFO is used by the loader for the
"sType" field in VkLayerInstanceCreateInfo.
- A VK_STRUCTURE_TYPE_LOADER_DEVICE_CREATE_INFO is used by the loader for the
"sType" field in VkLayerDeviceCreateInfo.
- The "function" field indicates how the union field "u" should be interpreted
within VkLayer*CreateInfo. The loader will set the "function" field to
VK_LAYER_LINK_INFO. This indicates "u" field should be VkLayerInstanceLink or
VkLayerDeviceLink.
- The VkLayerInstanceLink and VkLayerDeviceLink structures are the list nodes.
- The VkLayerInstanceLink contains the next entity's vkGetInstanceProcAddr used
by a layer.
- The VkLayerDeviceLink contains the next entity's vkGetInstanceProcAddr and
vkGetDeviceProcAddr used by a layer.
- Given the above structures set up by the loader, layer must initialize their
dispatch table as follows:
  - Find the  VkLayerInstanceCreateInfo/VkLayerDeviceCreateInfo structure in
the VkInstanceCreateInfo/VkDeviceCreateInfo structure.
  - Get the next entity's vkGet*ProcAddr from the "pLayerInfo" field.
  - For CreateInstance get the next entity's vkCreateInstance by calling the
"pfnNextGetInstanceProcAddr":
     pfnNextGetInstanceProcAddr(NULL, "vkCreateInstance").
  - For CreateDevice get the next entity's vkCreateDevice by calling the
"pfnNextGetInstanceProcAddr":
     pfnNextGetInstanceProcAddr(NULL, "vkCreateDevice").
  - Advanced the linked list to the next node: pLayerInfo = pLayerInfo->pNext.
  - Call down the chain either CreateDevice or CreateInstance
  - Initialize your layer dispatch table by calling the next entity's
Get*ProcAddr function once for each Vulkan command needed in your dispatch
table

Example code for CreateInstance:
Example code for CreateDevice
#### Special Considerations
Wrapping versus maps.
create dispatchable objects