KhronosGroup / KhronosGroup/OpenCL-Docs

Update doc for `work_group_broadcast`

Open
#169 14 comments 0 reactions 0 assignees View on GitHub
OpenCL C Spec themed-agenda
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.