KhronosGroup / KhronosGroup/OpenCL-Docs
The spec isn't fully generalized for arbitrary CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
For `param_name` of `CL_KERNEL_GLOBAL_WORK_SIZE`, the table in the description of `clGetKernelWorkGroupInfo` [specifies](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_KERNEL_GLOBAL_WORK_SIZE) "return type" `size_t[3]` and contains the following description:
> This provides a mechanism for the application to query the maximum global size that can be used to execute a kernel (i.e. the _global_work_size_ argument to `clEnqueueNDRangeKernel`) on a custom device given by _device_ or a built-in kernel on an OpenCL device given by _device_.
>
> If _device_ is not a custom device and _kernel_ is not a built-in kernel, `clGetKernelWorkGroupInfo` returns the error `CL_INVALID_VALUE`.
It isn't clear what is the return value in case `CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS` for _device_ isn't 3, which, per [specification](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS), is possible. In particular:
1. When `CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS > 3`, the return value doesn't fit in the "return type".
2. When `CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS < 3` (possible for custom devices) it isn't clear which elements of the returned `size_t[3]` correspond to actual dimensions and what the rest of the elements are.
[`CL_KERNEL_COMPILE_WORK_GROUP_SIZE`](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_KERNEL_COMPILE_WORK_GROUP_SIZE) has a similar problem and is the only other place where `size_t[3]` return type is found.
Note that, e.g., for [`CL_DEVICE_MAX_WORK_ITEM_SIZES`](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#CL_DEVICE_MAX_WORK_ITEM_SIZES) the "return type" (`size_t[]`) and description are properly generalized:
> Maximum number of work-items that can be specified in each dimension of the work-group to `clEnqueueNDRangeKernel`.
>
> Returns _n_ `size_t` entries, where _n_ is the value returned by the query for `CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS`.
>
> The minimum value is (1, 1, 1) for devices that are not of type `CL_DEVICE_TYPE_CUSTOM`.
However, there's an additional (minor) issue here: the _n_-element minimum value is specified as 3-element list, whereas in some other places, like "The starting local ID is always (0, 0, …, 0)" in the description of [`clEnqueueNDRangeKernel`](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clEnqueueNDRangeKernel), the _n_-element lists are specified using ellipsis. In general, there's an inconsistency in how _n_-element lists are specified.
Contributor guide
Research direction
Start with the CL_KERNEL_GLOBAL_WORK_SIZE and CL_KERNEL_COMPILE_WORK_GROUP_SIZE entries in the clGetKernelWorkGroupInfo specification, then compare their return types and descriptions with CL_DEVICE_MAX_WORK_ITEM_SIZES. Generalize the wording for arbitrary CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS and make the notation for n-element lists consistent with clEnqueueNDRangeKernel; the relevant specification text should clearly define returned elements and minimum values.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 45/100