KhronosGroup / KhronosGroup/OpenCL-Docs

clarify behavior of clLinkProgram when linking fails

Open
#1,075 4 comments 0 reactions 0 assignees View on GitHub
OpenCL API Spec
Dominant language
Python
Stars
420
Forks
131
Avg merge
5d 13h
Merged PRs (30d)
11

Description

Creating an issue based on discussion in PR https://github.com/KhronosGroup/OpenCL-Docs/pull/798.

The behavior of `clLinkProgram` does not seem to be precisely described and as a result implementations are behaving differently. We need to determine what we can fix now, and if we cannot fix everything, what we would like to fix in a future spec version.

Notes:
* `clLinkProgram` creates a new program object, unlike `clCompileProgram` and `clBuildProgram`, which operate on program objects that have already been created.
* `clLinkProgram` may (or may not!) link asynchronously if a callback function _pfn_notify_ is passed to the function.
* The spec defines conditions when "the linking operation can begin": if the context, list of devices, input programs and linker options specified are all valid and appropriate host and device resources needed to perform the link are available.

Some things we need to decide where implementations are behaving differently are:

1. What are the situations when `clLinkProgram` must return a `NULL` program object and an error code in _errcode_ret_? Are these all of the cases where "the linking operation cannot begin", or are there other cases that must return a `NULL` program object and an error code also?
2. Are there scenarios when `clLinkProgram` may return both a new non-`NULL` program object and an error code in _errcode_ret_? Or, if an error code is generated, will `clLinkProgram` also return a `NULL` program object?
3. If a callback function is provided, will it always be called, even if an error occurs? If an error occurs, what program object is passed to the callback function?

(If you're curious to see how your implementation behaves, I put my tester here: https://github.com/bashbaug/SimpleOpenCLSamples/tree/link-program-error-behavior/samples/99_linkprogramerror.)

Contributor guide

Open the contributing guide

Research direction

Start with the discussion in PR https://github.com/KhronosGroup/OpenCL-Docs/pull/798 and review the clLinkProgram behavior described in this issue. Run or inspect the linked SimpleOpenCLSamples tester at samples/99_linkprogramerror to compare implementation behavior. Done means deciding the NULL-object, error-code, and callback rules and updating the relevant specification text.

Written by the indexing model from the issue text.

Assessment

Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.