KhronosGroup / KhronosGroup/OpenCL-Docs
Clarify NULL Platform Behavior
- 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
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