KhronosGroup / KhronosGroup/OpenCL-Docs

Clarification of clCreateBuffer memory flags

Open
#1,372 2 comments 0 reactions 0 assignees View on GitHub

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:

  1. When flags is 0, the behaviour is as if it was CL_MEM_READ_WRITE. This is supported by an additional sentence in flags parameter 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.

  2. Among CL_MEM_READ_WRITE, CL_MEM_READ_ONLY and CL_MEM_WRITE_ONLY, which are mutually exclusive and specify what kinds of access the kernel does to the memory object, CL_MEM_READ_WRITE is assumed by default (i.e., when all 3 corresponding bits in flags are 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 is CL_MEM_READ_WRITE a 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.