KhronosGroup / KhronosGroup/OpenCL-Docs

Clarify svm_ptr argument to clEnqueueSVMMemFill

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

Description

Found while discussing and developing the unified SVM extension: the current description for the _svm_ptr_ argument to [clEnqueueSVMMemFill](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clEnqueueSVMMemFill) is confusing and should be improved. For reference, the current text is:

> svm_ptr is a pointer to a memory region that will be filled with pattern. It must be aligned to pattern_size bytes. If svm_ptr is allocated using [clSVMAlloc](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clSVMAlloc) then it must be allocated from the same context from which command_queue was created. Otherwise the behavior is undefined.

There are three specific _svm_ptr_ cases I believe we need to document:

1. _svm_ptr_ is unaligned. This is a `CL_INVALID_VALUE` error.
2. _svm_ptr_ is `NULL`. This is a `CL_INVALID_VALUE` error.
3. _svm_ptr_ was allocated using clSVMAlloc from a different context. This is undefined behavior (note: even if the device supports system SVM?).
4. _svm_ptr_ was not allocated using clSVMAlloc. This is valid if the device associated with the _command_queue_ supports system SVM, otherwise this is undefined behaivor.
5. _svm_ptr_ was allocated using clSVMAlloc from the same context. This is a valid.

Debatably cases (3) and (4) should be errors instead of undefined behavior, but this would be a change compared to the current spec. Note though:

* It is possible for an implementation to return an error in these cases (because behavior is undefined), but this would not be required.
* If we _really_ wanted to, we could consider tightening the behavior for implementations supporting unified SVM.

Contributor guide

Open the contributing guide

Research direction

Start at the clEnqueueSVMMemFill entry in the OpenCL API specification and compare the current svm_ptr wording with the five cases listed in the issue. Clarify the alignment, NULL, context, system-SVM, and clSVMAlloc requirements, while checking the surrounding error and undefined-behavior language; done means the specification explicitly covers each case.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.