KhronosGroup / KhronosGroup/OpenCL-Docs

Clarify NULL Platform Behavior

Open
#459 1 comment 2 reactions 0 assignees View on GitHub
OpenCL API Spec OpenCL Extension Spec
Dominant language
Python
Stars
420
Forks
131
Avg merge
5d 13h
Merged PRs (30d)
11

Description

Currently the NULL platform behavior is a bit inconsistent in the spec and in various ICD loader implementations leading to issues and comments like these:

* https://github.com/KhronosGroup/OpenCL-CTS/issues/977
* https://github.com/KhronosGroup/OpenCL-ICD-Loader/pull/114#issuecomment-669246825

This is partly because the spec allows for implementation-defined behavior for the NULL platform behavior in some cases, such as for [clGetDeviceIDs](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clGetDeviceIDs):

> platform refers to the platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.

But, not for other cases, such as [clUnloadPlatformCompiler](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clUnloadPlatformCompiler):

> platform is the platform to unload.

This is further complicated by an issue discussion in the extension spec for [cl_khr_icd](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#cl_khr_icd-opencl):

> How will the ICD handle a NULL cl_platform_id?
>
> RESOLVED: The ICD will by default choose the first enumerated platform as the NULL platform. The user can override this default by setting an environment variable OPENCL_ICD_DEFAULT_PLATFORM to the desired platform index. The API calls that deal with platforms will return CL_INVALID_PLATFORM if the index is not between zero and (number of platforms - 1), both inclusive.

We should clarify the expected NULL platform behavior in the spec to remove ambiguity and inconsistency.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the clGetDeviceIDs and clUnloadPlatformCompiler sections cited in the issue, along with the cl_khr_icd discussion and linked CTS and ICD Loader references. Done means the relevant specification text consistently and explicitly defines NULL platform behavior across the affected cases.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.