loader/LinuxICDs.txt - third_party/vulkan_loader_and_validation_layers - Git at Google

 This is a specification 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
 specification 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",
         "api_version": "1.0.1"
     }
 }

 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 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 “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" }}
     vendorb_vk.json   { "ICD": { "library_path": "vendorb_vulkan_icd.so" }}
     vendorc_icd.json  { "ICD": { "library_path": "/usr/lib/VENDORC/icd.so" }}

 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 mentioned
 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) "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
 - (optional) extension "name" - Vulkan registered name
 - (optional) extension "spec_version" - extension specification version, a single number, increasing with backward compatible changes.
 - (optional) 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": "OverlayLayer",
          "type": "DEVICE",
          "library_path": "libvkOverlayLayer.so",
          "api_version" : "1.0.1",
          "implementation_version" : "2",
          "description" : "LunarG HUD layer",
          "functions": {
             "vkGetInstanceProcAddr": "Overlaylayer_GetInstanceProcAddr",
             "vkGetDeviceProcAddr": "OverlayLayer_GetDeviceProcAddr"
          },
          "instance_extensions": [
              {
                  "name": "VK_LUNARG_DEBUG_REPORT",
                  "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.


 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_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

 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.
	This is a specification 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
	specification 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",
	"api_version": "1.0.1"
	}
	}

	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 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 “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" }}
	vendorb_vk.json { "ICD": { "library_path": "vendorb_vulkan_icd.so" }}
	vendorc_icd.json { "ICD": { "library_path": "/usr/lib/VENDORC/icd.so" }}

	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 mentioned
	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) "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
	- (optional) extension "name" - Vulkan registered name
	- (optional) extension "spec_version" - extension specification version, a single number, increasing with backward compatible changes.
	- (optional) 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": "OverlayLayer",
	"type": "DEVICE",
	"library_path": "libvkOverlayLayer.so",
	"api_version" : "1.0.1",
	"implementation_version" : "2",
	"description" : "LunarG HUD layer",
	"functions": {
	"vkGetInstanceProcAddr": "Overlaylayer_GetInstanceProcAddr",
	"vkGetDeviceProcAddr": "OverlayLayer_GetDeviceProcAddr"
	},
	"instance_extensions": [
	{
	"name": "VK_LUNARG_DEBUG_REPORT",
	"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.


	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_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

	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.