loader: Update loader readme and add ICD/ layer discovery documentation

1 files changed, 277 insertions, 0 deletions

diff --git a/loader/LinuxICDs.txt b/loader/LinuxICDs.txt
new file mode 100644
index 00000000..9c5fac19
--- /dev/null
+++ b/loader/LinuxICDs.txt
@@ -0,0 +1,277 @@
+This is a proposal for how the Vulkan loader should identify Vulkan installable

+client drivers (ICDs) and layers on Linux systems.  This is designed for

+production installation of Vulkan ICDs and layers.  The design is shown first

+for ICDs, and then the variation for layers will be discussed.

+

+

+1. Installable Client Drivers:

+

+

+1.1. 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 (NOTE: The JSON in this version of the proposal

+is for illustration purposes, and isn’t completely valid yet).  The Vulkan

+loader will open each info file 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",

+        "abi_versions": "1.0.0"

+    }

+}

+

+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 dlopen(). If the layer is specified via a relative pathname, it is

+relative to the path of the info file.  If the ICD is specified via a filename,

+the shared library lives in the following system directory:

+

+/$libdir/vulkan/icd

+

+where $libdir specifies where libraries reside on the given Linux distribution

+(e.g. “/usr/lib/x86_64-linux-gnu” on 64-bit Debian-based distributions, or

+“/usr/lib64” on 64-bit Red Hat-based systems).

+

+The “file_format_version” provides 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 info file

+format versions, it must have multiple text info files (all of which may point

+to the same shared library).

+

+The “abi_versions” specifies a colon-separated list of major.minor.patch

+version numbers of the Vulkan ABI that the shared library (referenced by

+“library_path”) support.

+

+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" }}

+    vendorb_vk.json   { "ICD": { "library_path": "vendorb_vulkan_icd.so" }}

+    vendorc_icd.json  { "ICD": { "library_path": "/usr/lib/VENDORC/icd.so" }}

+

+the loader will open the three files mentioned in the “Text File Name”

+column, and then try to load and use the three shared libraries

+indicated by the ICD.library_path value.

+

+

+1.2. 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

+text information 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.

+

+

+2. Layers:

+

+

+2.1. 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 (see below).

+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 ICDs that are installed

+from Linux-distribution-provided packages.  The “/etc/vulkan/*_layer.d”

+directories are for ICDs 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) “abi_versions” – same as for ICDs.

+- (required) “implementation_version” – layer code version.

+- (required) “description” – informative decription of the layer.

+- (optional) extension and it's “name” - e.g."instance_extensions”{ DEBUG_REPORT }

+- (optional) extension “version” - extension version (formatted as

+  major.minor.patch).

+- (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_0_0") 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_0_0") 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 (NOTE: The JSON in this version of the proposal is for illustration

+purposes, and isn’t completely valid yet):

+

+{

+     “file_format_version” : “1.0.0”,

+     “layer”: {

+         "name": "OverlayLayer",

+         "type": "DEVICE",

+         "library_path": "libvkOverlayLayer.so",

+         “abi_versions” : “1.0.0:1.1.0”,

+         “implementation_version” : “0.9.3”,

+         “description” : “LunarG HUD layer”,

+         “functions”: {

+            “vkGetInstanceProcAddr”: “Overlaylayer_GetInstanceProcAddr”,

+            “vkGetDeviceProcAddr”: “OverlayLayer_GetDeviceProcAddr”

+         },

+         "instance_extensions”: [

+             {

+                 “name”: “DEBUG_REPORT”,

+                 “version”: “1.0.0”

+             },

+             {

+                 “name”: “DEBUG_X”,

+                 “version”: “1.0.0”

+             }

+         ],

+         "device_extensions”: [

+             {

+                 “name”: “DEBUG_MARKER”,

+                 “version”: “1.0.0”

+             }

+         ],

+         “disable_environment”: {

+             “DISABLE_LAYER_OVERLAY_1_0_0”: “”

+         }

+     }

+}

+

+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 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).  If the layer is specified via a filename, the shared

+library lives in the following system directory:

+

+/$libdir/vulkan/layer

+

+where $libdir specifies where libraries reside on the given Linux distribution

+(e.g. “/usr/lib/x86_64-linux-gnu” on 64-bit Debian-based distributions, or

+“/usr/lib64” on 64-bit Red Hat-based systems).

+

+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.

+

+

+2.2. 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_DIRS” 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_DIRS” will be scanned for info files.  Each

+colon-separated entry is:

+

+- The full pathname of a directory containing layer info files

+

+In addition to overriding the mechanism for finding layers, the following

+environment variables are used to select one or more layers/extensions

+(respectively) to explicitly enable:

+

+- “VK_INSTANCE_LAYERS” for instance/global layers/extensions, enabled at

+  vkCreateInstance time

+

+- “VK_DEVICE_LAYERS” for device layers/extensions, enabled at vkCreateDevice

+  time

+

+These are colon-separated lists of extension names, as listed in the “name”

+field of the info file.  The loader will load all layers/extensions that match

+the given extension name(s), ignoring the “version” fields.

+

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