KhronosGroup / KhronosGroup/OpenCL-Docs
Update doc for `work_group_broadcast`
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
The doc for `work_group_broadcast` is currently this:
https://github.com/KhronosGroup/OpenCL-Docs/blob/b86f597faf4829234b68fa72c7f33fa85d8c0566/OpenCL_C.txt#L8315-L8324
There's a small typo: it should _Broadcast the value of **`a`**_, not `x`.
I would suggest renaming `local_id` to `local_id_x` for explicitness.
I would also suggest stating that calling {first, second, third} overload from a NDRange with a dimension that is _not_ {1D, 2D, 3D} (respectively) results in undefined behaviour.
It might also be worth, for completeness, mentioning that the local id should refer to an "existing" and "valid" id (i.e. to ensure that at lest one value can be returned by this builtin). Those are probably not the right words, but it should give the idea.
Together, these two last suggestions ensure **one and only one** value can be returned by this builtin.
I believe this has no impact on existing CTS tests as it only make undefined behaviour explicit and doesn't change existing expectations.
---
The reasoning is the following:
* When calling `work_group_broadcast(a, local_id_x)` from within a 2D or 3D NDRange, multiple work-items could by identified by `local_id_x`. Hence, more than one value should be returned, which is impossible/ambiguous. The same applies when calling `work_group_broadcast(a, local_id_x, local_id_y)` from a 3D NDRange.
* It would technically possible to identify a unique work-item from a 2/3D NDRange when the second/third dimensions are "1", but I don't think it's worth explicitly supporting that.
* When calling `work_group_broadcast(a, local_id_x, local_id_y)` from a 1D NDRange, no work-item will match the request (unless, maybe, if `local_id_y` is one, but again I don't think it's work explicitly supporting that), hence no value can be returned. The same applies when calling `work_group_broadcast(a, local_id_x, local_id_y, local_id_z)` from a 1D or 2D NDRange.
Contributor guide
Research direction
Start with OpenCL_C.txt at the linked work_group_broadcast section around lines 8315-8324. Review the requested parameter rename and the dimensionality and valid-local-ID wording, then ensure the documentation clearly reflects the intended constraints and corrects the typo. Done means the section is accurate and unambiguous about which overloads apply to each NDRange dimensionality.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100