KhronosGroup / KhronosGroup/OpenCL-Docs
Clarify svm_ptr argument to clEnqueueSVMMemFill
- 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
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