KhronosGroup / KhronosGroup/OpenCL-Docs
Clarification of clCreateBuffer memory flags
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 421
- Forks
- 132
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
The table of memory flags describes CL_MEM_READ_WRITE like this:
This flag specifies that the memory object will be read and written by a kernel. This is the default.
It isn't clear what "the default" means in this case (see SO question where this causes confusion). I can think of two options:
- When
flagsis 0, the behaviour is as if it wasCL_MEM_READ_WRITE. This is supported by an additional sentence inflagsparameter description in specification version 2.2, which is, however, missing from version 3.0:... If the value specified for flags is 0, the default is used which is CL_MEM_READ_WRITE.
- Among
CL_MEM_READ_WRITE,CL_MEM_READ_ONLYandCL_MEM_WRITE_ONLY, which are mutually exclusive and specify what kinds of access the kernel does to the memory object,CL_MEM_READ_WRITEis assumed by default (i.e., when all 3 corresponding bits inflagsare set to 0, even if some of the other bits are set to 1). This seems more intuitive to me, because it would mean that the flags cannot specify a memory object which is inaccessible by the kernel. But, if so, why isCL_MEM_READ_WRITEa separate bit at all?
Whichever of these (or something else) is the intention, I think the wording should be clarified to reflect it.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the OpenCL 3.0 clCreateBuffer memory-flags table and flags parameter description with the linked OpenCL 2.2 wording. Resolve which interpretation of the default is intended, then clarify the OpenCL 3.0 specification so the table and parameter description agree.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100