Skip to content

Commit c212211

Browse files
bashbaugbashbaug
authored
error code consistency for SVM (KhronosGroup#1482)
1 parent 6f3146b commit c212211

1 file changed

Lines changed: 111 additions & 88 deletions

File tree

‎api/opencl_runtime_layer.asciidoc‎

Lines changed: 111 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -8341,25 +8341,30 @@ context from which _command_queue_ was created the behavior is undefined.
83418341
successfully.
83428342
Otherwise, it returns one of the following errors:
83438343

8344-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host
8345-
command-queue.
8346-
* {CL_INVALID_OPERATION} if the device associated with _command_queue_ does not support SVM.
8347-
* {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and
8348-
events in _event_wait_list_ are not the same.
8349-
* {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and
8350-
_num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and
8351-
_num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_
8352-
are not valid events.
8353-
* {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the copy operation is
8354-
blocking and the execution status of any of the events in
8355-
_event_wait_list_ is a negative integer value.
8356-
* {CL_INVALID_VALUE} if _dst_ptr_ or _src_ptr_ is `NULL`.
8357-
* {CL_MEM_COPY_OVERLAP} if the values specified for _dst_ptr_, _src_ptr_ and
8358-
_size_ result in an overlapping copy.
8359-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
8360-
by the OpenCL implementation on the device.
8361-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
8362-
required by the OpenCL implementation on the host.
8344+
* {CL_INVALID_COMMAND_QUEUE}
8345+
** if _command_queue_ is not a valid host command-queue
8346+
* {CL_INVALID_OPERATION}
8347+
** if the device associated with _command_queue_ does not support SVM
8348+
* {CL_INVALID_CONTEXT}
8349+
** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same
8350+
* {CL_INVALID_VALUE}
8351+
** if _dst_ptr_ is `NULL`
8352+
** if _src_ptr_ is `NULL`
8353+
* {CL_INVALID_EVENT_WAIT_LIST}
8354+
** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero
8355+
** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero
8356+
** if event objects in _event_wait_list_ are not valid events
8357+
* {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST}
8358+
** if the copy operations is blocking and the execution status of
8359+
any of the events in _event_wait_list_ is a negative integer value indicating an error
8360+
* {CL_MEM_COPY_OVERLAP}
8361+
** if the values specified for _dst_ptr_, _src_ptr_ and _size_ result in an overlapping copy
8362+
* {CL_OUT_OF_RESOURCES}
8363+
** if there is a failure to allocate resources required by the OpenCL
8364+
implementation on the device
8365+
* {CL_OUT_OF_HOST_MEMORY}
8366+
** if there is a failure to allocate resources required by the OpenCL
8367+
implementation on the host
83638368
--
83648369

83658370
[open,refpage='clEnqueueSVMMemFill',desc='Enqueues a command to fill a region in memory with a pattern of a given pattern size.',type='protos']
@@ -8423,24 +8428,30 @@ include::{generated}/api/version-notes/clEnqueueSVMMemFill.asciidoc[]
84238428
successfully.
84248429
Otherwise, it returns one of the following errors:
84258430

8426-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host
8427-
command-queue.
8428-
* {CL_INVALID_OPERATION} if the device associated with _command_queue_ does not support SVM.
8429-
* {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and
8430-
events in _event_wait_list_ are not the same.
8431-
* {CL_INVALID_VALUE} if _svm_ptr_ is `NULL`.
8432-
* {CL_INVALID_VALUE} if _svm_ptr_ is not aligned to _pattern_size_ bytes.
8433-
* {CL_INVALID_VALUE} if _pattern_ is `NULL` or if _pattern_size_ is 0 or if
8434-
_pattern_size_ is not one of {1, 2, 4, 8, 16, 32, 64, 128}.
8435-
* {CL_INVALID_VALUE} if _size_ is not a multiple of _pattern_size_.
8436-
* {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and
8437-
_num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and
8438-
_num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_
8439-
are not valid events.
8440-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
8441-
by the OpenCL implementation on the device.
8442-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
8443-
required by the OpenCL implementation on the host.
8431+
* {CL_INVALID_COMMAND_QUEUE}
8432+
** if _command_queue_ is not a valid host command-queue
8433+
* {CL_INVALID_OPERATION}
8434+
** if the device associated with _command_queue_ does not support SVM
8435+
* {CL_INVALID_CONTEXT}
8436+
** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same
8437+
* {CL_INVALID_VALUE}
8438+
** if _svm_ptr_ is `NULL`
8439+
** if _svm_ptr_ is not aligned to _pattern_size_ bytes
8440+
** if _pattern_ is `NULL`
8441+
** if _pattern_size_ is zero
8442+
** if _pattern_size_ is not a power of two
8443+
** if _pattern_size_ is greater than 128
8444+
** if _size_ is not a multiple of _pattern_size_
8445+
* {CL_INVALID_EVENT_WAIT_LIST}
8446+
** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero
8447+
** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero
8448+
** if event objects in _event_wait_list_ are not valid events
8449+
* {CL_OUT_OF_RESOURCES}
8450+
** if there is a failure to allocate resources required by the OpenCL
8451+
implementation on the device
8452+
* {CL_OUT_OF_HOST_MEMORY}
8453+
** if there is a failure to allocate resources required by the OpenCL
8454+
implementation on the host
84448455
--
84458456

84468457
[open,refpage='clEnqueueSVMMap',desc='Enqueues a command that will allow the host to update a region of a SVM buffer',type='protos']
@@ -8503,25 +8514,29 @@ already mapped in the host address space.
85038514
successfully.
85048515
Otherwise, it returns one of the following errors:
85058516

8506-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host
8507-
command-queue.
8508-
* {CL_INVALID_OPERATION} if the device associated with _command_queue_ does not support SVM.
8509-
* {CL_INVALID_CONTEXT} if context associated with _command_queue_ and events
8510-
in _event_wait_list_ are not the same.
8511-
* {CL_INVALID_VALUE} if _svm_ptr_ is `NULL`.
8512-
* {CL_INVALID_VALUE} if _size_ is 0 or if values specified in _map_flags_
8513-
are not valid.
8514-
* {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and
8515-
_num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and
8516-
_num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_
8517-
are not valid events.
8518-
* {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the map operation is
8519-
blocking and the execution status of any of the events in
8520-
_event_wait_list_ is a negative integer value.
8521-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
8522-
by the OpenCL implementation on the device.
8523-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
8524-
required by the OpenCL implementation on the host.
8517+
* {CL_INVALID_COMMAND_QUEUE}
8518+
** if _command_queue_ is not a valid host command-queue
8519+
* {CL_INVALID_OPERATION}
8520+
** if the device associated with _command_queue_ does not support SVM
8521+
* {CL_INVALID_CONTEXT}
8522+
** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same
8523+
* {CL_INVALID_VALUE}
8524+
** if _svm_ptr_ is `NULL`
8525+
** if _size_ is zero
8526+
** if values specified in _map_flags_ are not valid
8527+
* {CL_INVALID_EVENT_WAIT_LIST}
8528+
** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero
8529+
** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero
8530+
** if event objects in _event_wait_list_ are not valid events
8531+
* {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST}
8532+
** if the map operations is blocking and the execution status of
8533+
any of the events in _event_wait_list_ is a negative integer value indicating an error
8534+
* {CL_OUT_OF_RESOURCES}
8535+
** if there is a failure to allocate resources required by the OpenCL
8536+
implementation on the device
8537+
* {CL_OUT_OF_HOST_MEMORY}
8538+
** if there is a failure to allocate resources required by the OpenCL
8539+
implementation on the host
85258540
--
85268541

85278542
[open,refpage='clEnqueueSVMUnmap',desc='Enqueues a command to indicate that the host has completed updating the region given by an SVM pointer and which was specified in a previous call to clEnqueueSVMMap.',type='protos']
@@ -8569,20 +8584,24 @@ the region of the SVM buffer specified in these calls.
85698584
successfully.
85708585
Otherwise, it returns one of the following errors:
85718586

8572-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host
8573-
command-queue.
8574-
* {CL_INVALID_OPERATION} if the device associated with _command_queue_ does not support SVM.
8575-
* {CL_INVALID_CONTEXT} if context associated with _command_queue_ and events
8576-
in _event_wait_list_ are not the same.
8577-
* {CL_INVALID_VALUE} if _svm_ptr_ is `NULL`.
8578-
* {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and
8579-
_num_events_in_wait_list_ > 0, or if _event_wait_list_ is not `NULL` and
8580-
_num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_
8581-
are not valid events.
8582-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
8583-
by the OpenCL implementation on the device.
8584-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
8585-
required by the OpenCL implementation on the host.
8587+
* {CL_INVALID_COMMAND_QUEUE}
8588+
** if _command_queue_ is not a valid host command-queue
8589+
* {CL_INVALID_OPERATION}
8590+
** if the device associated with _command_queue_ does not support SVM
8591+
* {CL_INVALID_CONTEXT}
8592+
** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same
8593+
* {CL_INVALID_VALUE}
8594+
** if _svm_ptr_ is `NULL`
8595+
* {CL_INVALID_EVENT_WAIT_LIST}
8596+
** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero
8597+
** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero
8598+
** if event objects in _event_wait_list_ are not valid events
8599+
* {CL_OUT_OF_RESOURCES}
8600+
** if there is a failure to allocate resources required by the OpenCL
8601+
implementation on the device
8602+
* {CL_OUT_OF_HOST_MEMORY}
8603+
** if there is a failure to allocate resources required by the OpenCL
8604+
implementation on the host
85868605

85878606
[NOTE]
85888607
====
@@ -8670,24 +8689,28 @@ could result in undefined results.
86708689
successfully.
86718690
Otherwise, it returns one of the following errors:
86728691

8673-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host
8674-
command-queue.
8675-
* {CL_INVALID_OPERATION} if the device associated with _command_queue_ does not support SVM.
8676-
* {CL_INVALID_CONTEXT} if context associated with _command_queue_ and events
8677-
in _event_wait_list_ are not the same.
8678-
* {CL_INVALID_VALUE} if _num_svm_pointers_ is zero or _svm_pointers_ is
8679-
`NULL`.
8680-
* {CL_INVALID_VALUE} if _sizes_[i] is non-zero range [_svm_pointers_[i],
8681-
_svm_pointers_[i]+_sizes_[i]) is not contained within an existing
8682-
{clSVMAlloc} allocation.
8683-
* {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and
8684-
_num_events_in_wait_list_ > 0, or if _event_wait_list_ is not `NULL` and
8685-
_num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_
8686-
are not valid events.
8687-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
8688-
by the OpenCL implementation on the device.
8689-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
8690-
required by the OpenCL implementation on the host.
8692+
* {CL_INVALID_COMMAND_QUEUE}
8693+
** if _command_queue_ is not a valid host command-queue
8694+
* {CL_INVALID_OPERATION}
8695+
** if the device associated with _command_queue_ does not support SVM
8696+
* {CL_INVALID_CONTEXT}
8697+
** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same
8698+
* {CL_INVALID_VALUE}
8699+
** if _num_svm_pointers_ is zero
8700+
** if _svm_pointers_ is `NULL`
8701+
** if _flags_ is not zero and is not a valid combination of the values
8702+
described in the <<migration-flags-table, Memory migration Flags>> table
8703+
** if _sizes_[i] is non-zero and the memory range described by _svm_pointers_[i] and _sizes_[i] is not contained within an SVM allocation returned by {clSVMAlloc}
8704+
* {CL_INVALID_EVENT_WAIT_LIST}
8705+
** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero
8706+
** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero
8707+
** if event objects in _event_wait_list_ are not valid events
8708+
* {CL_OUT_OF_RESOURCES}
8709+
** if there is a failure to allocate resources required by the OpenCL
8710+
implementation on the device
8711+
* {CL_OUT_OF_HOST_MEMORY}
8712+
** if there is a failure to allocate resources required by the OpenCL
8713+
implementation on the host
86918714
--
86928715

86938716

0 commit comments

Comments
 (0)