From 5afa11d5fed8ab25dd8046151119ce2472cd800b Mon Sep 17 00:00:00 2001 From: Jon Ashburn Date: Thu, 16 Jul 2015 10:54:55 -0600 Subject: loader: Update loader readme and add ICD/ layer discovery documentation --- loader/LinuxICDs.txt | 277 +++++++++++++++++++++++++++++++++++++++++++++++++ loader/README.md | 31 +++--- loader/WindowsICDs.txt | 259 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 551 insertions(+), 16 deletions(-) create mode 100644 loader/LinuxICDs.txt create mode 100644 loader/WindowsICDs.txt 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. diff --git a/loader/README.md b/loader/README.md index a6479283..5878685e 100644 --- a/loader/README.md +++ b/loader/README.md @@ -1,8 +1,8 @@ # Loader Description ## Overview -The Loader implements the main VK library (e.g. "VK.dll" on Windows and -"libVK.so" on Linux). It handles layer management and driver management. The +The Loader implements the main VK library (e.g. "vulkan.dll" on Windows and +"libvulkan.so" on Linux). It handles layer management and driver management. The loader fully supports multi-gpu operation. As part of this, it dispatches API calls to the correct driver, and to the correct layers, based on the GPU object selected by the application. @@ -19,23 +19,15 @@ layer can intercept a subset of the full API entrypoints. A layer which doesn't intercept a given entrypoint will be skipped for that entrypoint. The loader supports layers that operate on multiple GPUs. -## Environment Variables -**LIBVK\_DRIVERS\_PATH** directory for loader to search for ICD driver libraries to open - -**LIBVK\_LAYERS\_PATH** directory for loader to search for layer libraries that may get activated and used at vkCreateDevice() time. - -**LIBVK\_LAYER\_NAMES** colon-separated list of layer names to be activated (e.g., LIBVK\_LAYER\_NAMES=MemTracker:DrawState). - -Note: Both of the LIBVK\_*\_PATH variables may contain more than one directory. Each directory must be separated by one of the following characters, depending on your OS: - -- ";" on Windows -- ":" on Linux +## ICD discovery +See file LinuxICDs.txt and WindowsICDs.txt for description of how the loader +finds ICD driver libraries. ## Interface to driver (ICD) -- vkEnumerateGpus exported - vkCreateInstance exported -- vkDestroyInstance exported -- vkGetProcAddr exported and returns valid function pointers for all the VK API entrypoints +- vkGetGlobalExtensionProperties exported +- vkGetDeviceProcAddr exported and returns valid function pointers for all the VK API entrypoints +- vkGetInstanceProcAddr exported and returns valid function pointers for all the VK API entrypoints - all objects created by ICD can be cast to (VK\_LAYER\_DISPATCH\_TABLE \*\*) where 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: @@ -70,3 +62,10 @@ Additional Notes: - The ICD may or may not implement a dispatch table. - ICD entrypoints can be named anything including the offcial vk name such as vkCreateDevice(). However, beware of interposing by dynamic OS library loaders if the offical names are used. On Linux, if offical names are used, the ICD library must be linked with -Bsymbolic. +## Layer library discovery +See file LinuxICDs.txt and WindowsICDs.txt for description of how the loader +finds layer libraries. + +## Interface to layer libraries +TBD + diff --git a/loader/WindowsICDs.txt b/loader/WindowsICDs.txt new file mode 100644 index 00000000..e6337b65 --- /dev/null +++ b/loader/WindowsICDs.txt @@ -0,0 +1,259 @@ +This is a proposal for how the Vulkan loader should identify Vulkan installable +client drivers (ICDs) on MS Windows. 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 +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 +text information file (a.k.a. "manifest file"), that uses a JSON format (NOTE: +The JSON in this version of the proposal is for illustration purposes, and +isn’t completely valid yet), specified by the name of the value. Each name +must be a full pathname to the text info file. The Vulkan loader will open +each info 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", + “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 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 info file. + +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 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. + +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" }} + vendorb_vk.json { "ICD": { "library_path": “vendorb_vk.dll" }} + vendorc_icd.json { "ICD": { "library_path": "vedorc_icd.dll" }} + +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 semi-colon-separated list of +ICD text information 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”. + + +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). + +In order to find properly-installed ICDs, 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 (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 registry key its layer information file is referenced by. + +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 and it's “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": "vkOverlayLayer.dll", + “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 (“.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. + + +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_FOLDERS” 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_FOLDERS” will be scanned for info files. Each +semi-colon-separated entry is: + +- The full pathname of a folder 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 semi-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. -- cgit v1.2.3