commit	978b4b3a29a3aebc86ce9315d5c5963e88722d03	[log] [tgz]
author	Nikhil Joshi <nikhilj@nvidia.com>	Fri Jul 12 15:42:54 2019 +0530
committer	bashbaug <ben.ashbaugh@intel.com>	Mon Oct 07 13:12:16 2019 -0700
tree	bdeac6903161f10a48803b0d47542818570fa46f
parent	6c03f8b58fafd9dd693eaac826749a5cfad515f8 [diff]

Use QueryAdapter APIs as per MS directives

Update ICD loader to use QueryAdapter APIs
as per MS directives for para-virtualization.

This includes changes to -
1. Order OpenCL platforms consistent with Windows adapters,
   to honor user-settings for multi-adapter machines.
2. Fix OS version detection.
3. Some minor fixes including
    1. Add trace prints at required places.
    2. Fix build failure in getting the address of D3DKMTQueryAdapterInfo.
    3. Fix early return platform enumeartion if there are no entries found for old reg key
       under "HKLM\\SOFTWARE\\Khronos\\OpenCL\\Vendors" to allow add for the entries found
       using DXGK interface and HKR entries.
4. Some other fixes including
    1. Update README.md with WDK dependency information.
    2. Move AddAdapter* call inside for which got misplaced while resolving conflicts.
    3. Free WinAdapter allocations and avoid overriding NULL platform.
5. Fixes based on review comments including -
    1. WinAdapter is reallocated with previous allocation freed.
       However, the final allocation is not freed.
       Fixed the same to free at the end of enumeration.
    2. Fix header file ordering by including windows headers
       inside necessary header files.

Minor fixes to para-virtualization support

Changes to following aspects of para-virtualization changes -
1. Revert platform[0] override when platform is NULL

Fix variable naming, array size and cleanup paths.

Fix changes added as part of para_virtualization support
1. to use camelCase for variable names
2. Use sizeof(element) while calculating array size.
3. Free/unload allocations/libraries during cleanup.

Add return value checks for adapterAdd.

Return boolean result from adapterAdd API
and add checks for success of this API
for better error reporting.

Free adapter names and add check for DXGI interface queries

Add adapterFree to free memory allocated to hold WinAdapter
handles.
Also, check for successful query of DXGIFactory interfaces.

Minor fixes to cleanup Windows para-virtualization changes

Fix indentation and variable name casing.
Fix adapterFree to remove null-pointer check and set it to null after
free.
Add missing header required for adapterAdd.
Add checks for malloced pointers.

Bump up OpenCL ICD Loader version

Bump up OpenCL ICD Loader version
with para-virtualization changes.

Update status based on DXGK and HKR enumearation

khrIcdOsVendorsEnumerate currently does not consider
the status returned by DXGK and HKR enumeration
and returns TRUE only if HKLM regkey enumeration
results in successful adapterAdd.

Fix the returned status to consider successful
adapterAdd from DXGK and HKR enumeration.

Also, set freed adapger pointers to NULL to avoid
potential double-free issue.

Refactor ICD loader windows header files

Add icd_windows.h to include Windows specific
types and functions.
Keep icd_windows_hkr.h and icd_windows_dxgk.h
limited to the HKR and DXGK specific information.

10 files changed

tree: bdeac6903161f10a48803b0d47542818570fa46f

README.md

OpenCL ICD Loader

This repo contains the source code and tests for the Khronos official OpenCL ICD Loader.

CI Build Status

Introduction

OpenCL defines an Installable Client Driver (ICD) mechanism to allow developers to build applications against an Installable Client Driver loader (ICD loader) rather than linking their applications against a specific OpenCL implementation. The ICD Loader is responsible for:

Exporting OpenCL API entry points
Enumerating OpenCL implementations
Forwarding OpenCL API calls to the correct implementation

This repo contains the source code and tests for the Khronos official OpenCL ICD Loader.

Note that this repo does not contain an OpenCL implementation (ICD). You will need to obtain and install an OpenCL implementation for your OpenCL device that supports the OpenCL ICD extension cl_khr_icd to run an application using the OpenCL ICD Loader.

The OpenCL Installable Client Driver extension (cl_khr_icd) is described in the OpenCL extensions specification, which may be found on the Khronos OpenCL Registry.

Build Instructions

Dependencies

The OpenCL ICD Loader requires OpenCL Headers. To use system OpenCL Headers, please specify the OpenCL Header location using the CMake variable OPENCL_ICD_LOADER_HEADERS_DIR. By default, the OpenCL ICD Loader will look for OpenCL Headers in the inc directory.

By default, the OpenCL ICD Loader on Windows requires the Windows Driver Kit (WDK). To build OpenCL ICD Loader with WDK support -

Install recent Windows WDK currently at https://docs.microsoft.com/en-us/windows-hardware/drivers/download-the-wdk
Establish environment variable WDK to include directory. Ex: set WDK=C:\Program Files (x86)\Windows Kits\10\include\10.0.17763.0

An OpenCL ICD Loader may be built without the Windows Driver Kit using the CMake variable OPENCL_ICD_LOADER_REQUIRE_WDK, however this option should be used with caution since it may prevent the OpenCL ICD Loader from enumerating some OpenCL implementations. This dependency may be removed in the future.

The OpenCL ICD Loader uses CMake for its build system. If CMake is not provided by your build system or OS package manager, please consult the CMake website.

Build and Install Directories

A common convention is to place the build directory in the top directory of the repository and to place the install directory as a child of the build directory. The remainder of these instructions follow this convention, although you may place these directories in any location.

Example Usage

For most Windows and Linux usages, the following steps are sufficient to build the OpenCL ICD Loader:

Clone this repo:

 git clone https://github.com/KhronosGroup/OpenCL-ICD-Loader

Obtain the OpenCL Headers, if you are not planning to use system OpenCL headers. Headers may be obtained from the Khronos OpenCL Headers repository.

Create a build directory:

 cd OpenCL-ICD-Loader
 mkdir build
 cd build

Invoke cmake to generate solution files, Makefiles, or files for other build systems.
```
 cmake ..
```
Build using the CMake-generated files.

Notes:

For 64-bit Windows builds, you may need to specify a 64-bit generator manually, for example:
```
  cmake.exe -G "Visual Studio 14 2015 Win64" ..
```
Some users may prefer to use a CMake GUI frontend, such as cmake-gui or ccmake, vs. the command-line CMake.

OpenCL ICD Loader Tests

OpenCL ICD Loader Tests can be run using ctest, which is a companion to CMake. The OpenCL ICD Loader Tests can also be run directly by executing icd_loader_test(.exe) executable from the bin folder.

Test Setup

The OpenCL ICD Loader Tests use a “stub” ICD, which must be set up manually. The OpenCL ICD Loader Tests will “fail” if the “stub” ICD is not set up correctly. The method to install the “stub” ICD is operating system dependent.

On Linux, install the “stub” ICD by creating a file with the full path to the “stub” ICD in /etc/OpenCL/vendors:

echo full/path/to/libOpenCLDriverStub.so > /etc/OpenCL/vendors/test.icd

On Windows, add the “stub” ICD by adding a REG_DWORD value to the registry keys:

// For 32-bit operating systems, or 64-bit tests on a 64-bit operating system:
HKEY_LOCAL_MACHINE\SOFTWARE\Khronos\OpenCL\Vendors

// For 32-bit tests on a 64-bit operating system:
HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Khronos\OpenCL\Vendors

// The name of the REG_DWORD value should be the full path to the "stub" ICD
// OpenCLDriverStub.dll, and the data for this value should be 0.

Running Tests

To run the tests, invoke ctest from the build directory. The CMake-generated build files may be able to invoke the OpenCL ICD Loader tests as well.

Test Cleanup

Manually remove the file or registry keys added during Test Setup.

Support

Please create a GitHub issue to report an issue or ask questions.

Contributing

Contributions to the OpenCL ICD Loader are welcomed and encouraged. You will be prompted with a one-time “click-through” CLA dialog as part of submitting your pull request or other contribution to GitHub.

Table of Debug Environment Variables

The following debug environment variables are available for use with the OpenCL ICD loader:

Environment Variable	Behavior	Example Format
OCL_ICD_FILENAMES	Specifies a list of additional ICDs to load. The ICDs will be enumerated first, before any ICDs discovered via default mechanisms.	`export OCL_ICD_FILENAMES=libVendorA.so:libVendorB.so` `set OCL_ICD_FILENAMES=vendor_a.dll;vendor_b.dll`
OCL_ICD_VENDORS	On Linux and Android, specifies a directory to scan for ICDs to enumerate in place of the default `/etc/OpenCL/vendors'.	`export OCL_ICD_VENDORS=/my/local/icd/search/path`