Skip to content

Commit a853ac1

Browse files
bashbaugbashbaug
committed
error consistency for clEnqueueNDRangeKernel
1 parent 735516b commit a853ac1

1 file changed

Lines changed: 91 additions & 96 deletions

File tree

‎api/opencl_runtime_layer.asciidoc‎

Lines changed: 91 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -956,7 +956,7 @@ endif::cl_ext_immutable_memory_objects[]
956956
value.
957957
This error code is <<unified-spec, missing before>> version 1.1.
958958
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
959-
** if there is a failure to allocate memory for sub-buffer object
959+
** if there is a failure to allocate memory for the data store associated with the sub-buffer object
960960
* {CL_OUT_OF_RESOURCES}
961961
** if there is a failure to allocate resources required by the OpenCL
962962
implementation on the device
@@ -1096,7 +1096,7 @@ Otherwise, they return one of the following errors:
10961096
any of the events in _event_wait_list_ is a negative integer value indicating an error.
10971097
This error code is <<unified-spec, missing before>> version 1.1.
10981098
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
1099-
** if there is a failure to allocate memory for data store associated with _buffer_
1099+
** if there is a failure to allocate memory for the data store associated with _buffer_
11001100
* {CL_INVALID_OPERATION}
11011101
** if {clEnqueueReadBuffer} is called on _buffer_ which has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS}
11021102
** if {clEnqueueWriteBuffer} is called on _buffer_ which has been created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS}
@@ -1252,7 +1252,7 @@ Otherwise, they return one of the following errors:
12521252
any of the events in _event_wait_list_ is a negative integer value indicating an error.
12531253
This error code is <<unified-spec, missing before>> version 1.1.
12541254
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
1255-
** if there is a failure to allocate memory for data store associated with _buffer_.
1255+
** if there is a failure to allocate memory for the data store associated with _buffer_
12561256
* {CL_INVALID_OPERATION}
12571257
** if {clEnqueueReadBufferRect} is called on _buffer_ which has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS}
12581258
** if {clEnqueueWriteBufferRect} is called on _buffer_ which has been created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS}
@@ -1403,7 +1403,7 @@ Otherwise, it returns one of the following errors:
14031403
** Refer to <<check-copy-overlap, Checking for Memory Copy Overlap>> for
14041404
details on how to determine if source and destination regions overlap.
14051405
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
1406-
** if there is a failure to allocate memory for data store associated with _src_buffer_ or _dst_buffer_
1406+
** if there is a failure to allocate memory for the data store associated with _src_buffer_ or _dst_buffer_
14071407
ifdef::cl_ext_immutable_memory_objects[]
14081408
* {CL_INVALID_OPERATION}
14091409
** if _dst_buffer_ was created with {CL_MEM_IMMUTABLE_EXT}
@@ -1551,7 +1551,7 @@ Otherwise, it returns one of the following errors:
15511551
** Refer to <<check-copy-overlap, Checking for Memory Copy Overlap>> for
15521552
details on how to determine if source and destination regions overlap.
15531553
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
1554-
** if there is a failure to allocate memory for data store associated with _src_buffer_ or _dst_buffer_
1554+
** if there is a failure to allocate memory for the data store associated with _src_buffer_ or _dst_buffer_
15551555
ifdef::cl_ext_immutable_memory_objects[]
15561556
* {CL_INVALID_OPERATION}
15571557
** if _dst_buffer_ was created with {CL_MEM_IMMUTABLE_EXT}
@@ -1658,7 +1658,7 @@ Otherwise, it returns one of the following errors:
16581658
_command_queue_.
16591659
This error code is <<unified-spec, missing before>> version 1.1.
16601660
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
1661-
** if there is a failure to allocate memory for data store associated with _buffer_
1661+
** if there is a failure to allocate memory for the data store associated with _buffer_
16621662
ifdef::cl_ext_immutable_memory_objects[]
16631663
* {CL_INVALID_OPERATION}
16641664
** if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT}
@@ -1769,7 +1769,7 @@ values returned in _errcode_ret_:
17691769
any of the events in _event_wait_list_ is a negative integer value indicating an error.
17701770
This error code is <<unified-spec, missing before>> version 1.1.
17711771
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
1772-
** if there is a failure to allocate memory for data store associated with _buffer_
1772+
** if there is a failure to allocate memory for the data store associated with _buffer_
17731773
* {CL_INVALID_OPERATION}
17741774
** if _buffer_ was created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS} and {CL_MAP_READ} is set in _map_flags_
17751775
** if _buffer_ was created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS} and {CL_MAP_WRITE} or {CL_MAP_WRITE_INVALIDATE_REGION} is set in _map_flags_
@@ -3752,7 +3752,7 @@ endif::cl_khr_mipmap_image[]
37523752
any of the events in _event_wait_list_ is a negative integer value indicating an error.
37533753
This error code is <<unified-spec, missing before>> version 1.1.
37543754
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
3755-
** if there is a failure to allocate memory for data store associated with _image_
3755+
** if there is a failure to allocate memory for the data store associated with _image_
37563756
* {CL_INVALID_OPERATION}
37573757
** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE})
37583758
** if {clEnqueueReadImage} is called on _image_ which has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS}
@@ -3936,7 +3936,7 @@ endif::cl_khr_mipmap_image[]
39363936
* {CL_MEM_COPY_OVERLAP}
39373937
** if _src_image_ and _dst_image_ are the same image object and the source and destination regions overlap
39383938
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
3939-
** if there is a failure to allocate memory for data store associated with _src_image_ or _dst_image_
3939+
** if there is a failure to allocate memory for the data store associated with _src_image_ or _dst_image_
39403940
* {CL_INVALID_OPERATION}
39413941
** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE})
39423942
ifdef::cl_ext_immutable_memory_objects[]
@@ -4065,7 +4065,7 @@ endif::cl_khr_mipmap_image[]
40654065
channel data type, are not supported by the device associated with
40664066
_command_queue_
40674067
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
4068-
** if there is a failure to allocate memory for data store associated with _image_
4068+
** if there is a failure to allocate memory for the data store associated with _image_
40694069
* {CL_INVALID_OPERATION}
40704070
** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE})
40714071
ifdef::cl_ext_immutable_memory_objects[]
@@ -4201,8 +4201,8 @@ endif::cl_khr_mipmap_image[]
42014201
channel data type, are not supported by the device associated with
42024202
_command_queue_
42034203
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
4204-
** if there is a failure to allocate memory for data store associated with _src_image_
4205-
** if there is a failure to allocate memory for data store associated with _dst_buffer_
4204+
** if there is a failure to allocate memory for the data store associated with _src_image_
4205+
** if there is a failure to allocate memory for the data store associated with _dst_buffer_
42064206
* {CL_INVALID_OPERATION}
42074207
** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE})
42084208
ifdef::cl_ext_immutable_memory_objects[]
@@ -4338,8 +4338,8 @@ endif::cl_khr_mipmap_image[]
43384338
channel data type, are not supported by the device associated with
43394339
_command_queue_
43404340
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
4341-
** if there is a failure to allocate memory for data store associated with _src_buffer_
4342-
** if there is a failure to allocate memory for data store associated with _dst_image_
4341+
** if there is a failure to allocate memory for the data store associated with _src_buffer_
4342+
** if there is a failure to allocate memory for the data store associated with _dst_image_
43434343
* {CL_INVALID_OPERATION}
43444344
** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE})
43454345
ifdef::cl_ext_immutable_memory_objects[]
@@ -4487,7 +4487,7 @@ endif::cl_khr_mipmap_image[]
44874487
any of the events in _event_wait_list_ is a negative integer value indicating an error.
44884488
This error code is <<unified-spec, missing before>> version 1.1.
44894489
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
4490-
** if there is a failure to allocate memory for data store associated with _image_
4490+
** if there is a failure to allocate memory for the data store associated with _image_
44914491
* {CL_INVALID_OPERATION}
44924492
** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE})
44934493
** if _image_ has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS} and {CL_MAP_READ} is set in _map_flags_
@@ -12098,90 +12098,85 @@ The starting local ID is always (0, 0, ..., 0).
1209812098
successfully queued.
1209912099
Otherwise, it returns one of the following errors:
1210012100

12101-
* {CL_INVALID_PROGRAM_EXECUTABLE} if there is no successfully built program
12102-
executable available for the device associated with _command_queue_.
12103-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host
12104-
command-queue.
12105-
* {CL_INVALID_KERNEL} if _kernel_ is not a valid kernel object.
12106-
* {CL_INVALID_CONTEXT} if context associated with _command_queue_ and
12107-
_kernel_ are not the same or if the context associated with
12108-
_command_queue_ and events in _event_wait_list_ are not the same.
12109-
* {CL_INVALID_KERNEL_ARGS} if the kernel argument values have not been
12110-
specified.
12111-
* {CL_INVALID_WORK_DIMENSION} if _work_dim_ is not a valid value (i.e. a
12112-
value between 1 and {CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS}).
12113-
* {CL_INVALID_GLOBAL_WORK_SIZE} if _global_work_size_ is NULL or if any of
12114-
the values specified in _global_work_size_[0], ...
12115-
_global_work_size_[_work_dim_ - 1] are zero.
12101+
* {CL_INVALID_COMMAND_QUEUE}
12102+
** if _command_queue_ is not a valid host command-queue
12103+
* {CL_INVALID_KERNEL}
12104+
** if _kernel_ is not a valid kernel
12105+
* {CL_INVALID_PROGRAM_EXECUTABLE}
12106+
** if there is no successfully built program executable available for the
12107+
device associated with _command_queue_
12108+
* {CL_INVALID_CONTEXT}
12109+
** if the context associated with _command_queue_ and _kernel_ are not the same
12110+
** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same
12111+
* {CL_INVALID_KERNEL_ARGS}
12112+
** if any kernel arguments for _kernel_ have not been set
12113+
* {CL_INVALID_WORK_DIMENSION}
12114+
** if _work_dim_ is not valid for the device associated with _command_queue_ (is greater than the value returned for {CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS})
12115+
* {CL_INVALID_GLOBAL_OFFSET}
12116+
** if the device associated with _command_queue_ does not support OpenCL 1.1
12117+
and _global_work_offset_ is not `NULL`
12118+
** if the value specified in _global_work_size_ plus the corresponding value
12119+
in _global_work_offset_ for any dimensions is greater than the maximum value
12120+
representable by {size_t_TYPE} on the device associated with _command_queue_
12121+
* {CL_INVALID_GLOBAL_WORK_SIZE}
12122+
** if _global_work_size_ is NULL or if any of the values specified in
12123+
_global_work_size_[0], ... _global_work_size_[_work_dim_ - 1] are zero.
1211612124
This error condition does not apply when the device associated with
1211712125
_command_queue_ supports OpenCL 2.1 or newer.
12118-
* {CL_INVALID_GLOBAL_WORK_SIZE} if any of the values specified in
12119-
_global_work_size_[0], ... _global_work_size_[_work_dim_ - 1] exceed the
12120-
maximum value representable by {size_t_TYPE} on the device on which the
12121-
kernel-instance will be enqueued.
12122-
* {CL_INVALID_GLOBAL_OFFSET} if the value specified in _global_work_size_
12123-
{plus} the corresponding values in _global_work_offset_ for any
12124-
dimensions is greater than the maximum value representable by size t on
12125-
the device on which the kernel-instance will be enqueued, or if
12126-
_global_work_offset_ is non-`NULL` <<unified-spec, before>> version 1.1.
12127-
* {CL_INVALID_WORK_GROUP_SIZE} if _local_work_size_ is specified and does
12128-
not match the required work-group size for _kernel_ in the program
12129-
source.
12130-
* {CL_INVALID_WORK_GROUP_SIZE} if _local_work_size_ is specified and is not
12131-
consistent with the required number of sub-groups for _kernel_ in the
12132-
program source.
12133-
* {CL_INVALID_WORK_GROUP_SIZE} if _local_work_size_ is specified and the
12134-
total number of work-items in the work-group computed as
12135-
_local_work_size_[0] {times} ... _local_work_size_[_work_dim_ - 1] is
12136-
greater than the value specified by {CL_KERNEL_WORK_GROUP_SIZE} in the
12137-
<<kernel-workgroup-info-table,Kernel Object Device Queries>> table.
12138-
* {CL_INVALID_WORK_GROUP_SIZE} if the work-group size must be uniform and
12139-
the _local_work_size_ is not `NULL`, is not equal to the required
12140-
work-group size specified in the kernel source, or the
12141-
_global_work_size_ is not evenly divisible by the _local_work_size_.
12142-
* {CL_INVALID_WORK_ITEM_SIZE} if the number of work-items specified in any
12143-
of _local_work_size_[0], ... _local_work_size_[_work_dim_ - 1] is
12144-
greater than the corresponding values specified by
12145-
{CL_DEVICE_MAX_WORK_ITEM_SIZES}[0], ...,
12146-
{CL_DEVICE_MAX_WORK_ITEM_SIZES}[_work_dim_ - 1].
12147-
* {CL_MISALIGNED_SUB_BUFFER_OFFSET} if a sub-buffer object is specified as
12148-
the value for an argument that is a buffer object and the _offset_
12149-
specified when the sub-buffer object is created is not aligned to
12150-
{CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated with _queue_.
12126+
** if any of the values specified in _global_work_size_[0], ...
12127+
_global_work_size_[_work_dim_ - 1] exceed the maximum value representable by
12128+
{size_t_TYPE} on the device associated with _command_queue_
12129+
* {CL_INVALID_WORK_GROUP_SIZE}
12130+
** if _local_work_size_ is not `NULL`, if the work-group size must be uniform, and if the _global_work_size_ is not evenly divisible by the _local_work_size_
12131+
** if _local_work_size_ is not `NULL` and if the total number of work-items in the work-group is greater than the maximum work-group size supported for _kernel_ on the device associated with _command_queue_ (is greater than the value returned for {CL_KERNEL_WORK_GROUP_SIZE})
12132+
** if _local_work_size_ is not `NULL` and if the _local_work_size_ does not match the required work-group size for _kernel_
12133+
** if _local_work_size_ is not `NULL` and if the _local_work_size_ is not consistent with the required number of sub-groups for _kernel_
12134+
* {CL_INVALID_WORK_ITEM_SIZE}
12135+
** if the number of work-items specified in any of _local_work_size_[0], ... _local_work_size_[_work_dim_ - 1] is
12136+
greater than the corresponding values returned by {CL_DEVICE_MAX_WORK_ITEM_SIZES}[0], ..., {CL_DEVICE_MAX_WORK_ITEM_SIZES}[_work_dim_ - 1]
12137+
for the device associated with _command_queue_
12138+
* {CL_MISALIGNED_SUB_BUFFER_OFFSET}
12139+
** if a kernel argument for _kernel_ is a sub-buffer object and the offset specified when the
12140+
sub-buffer object is created is not aligned to the
12141+
{CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated with
12142+
_command_queue_.
1215112143
This error code is <<unified-spec, missing before>> version 1.1.
12152-
* {CL_INVALID_IMAGE_SIZE} if an image object is specified as an argument
12153-
value and the image dimensions (image width, height, specified or
12154-
compute row and/or slice pitch) are not supported by device associated
12155-
with _queue_.
12156-
* {CL_IMAGE_FORMAT_NOT_SUPPORTED} if an image object is specified as an
12157-
argument value and the image format (image channel order and data type)
12158-
is not supported by device associated with _queue_.
12159-
* {CL_OUT_OF_RESOURCES} if there is a failure to queue the execution
12160-
instance of _kernel_ on the command-queue because of insufficient
12161-
resources needed to execute the kernel.
12162-
For example, the explicitly specified _local_work_size_ causes a failure
12163-
to execute the kernel because of insufficient resources such as
12164-
registers or local memory.
12165-
Another example would be the number of read-only image args used in
12166-
_kernel_ exceed the {CL_DEVICE_MAX_READ_IMAGE_ARGS} value for device or
12167-
the number of write-only and read-write image args used in _kernel_
12168-
exceed the {CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS} value for device or the
12169-
number of samplers used in _kernel_ exceed {CL_DEVICE_MAX_SAMPLERS} for
12170-
device.
12171-
* {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate
12172-
memory for data store associated with image or buffer objects specified
12173-
as arguments to _kernel_.
12174-
* {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and
12175-
_num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and
12176-
_num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_
12177-
are not valid events.
12178-
* {CL_INVALID_OPERATION} if SVM pointers are passed as arguments to a kernel
12179-
and the device does not support SVM, or if system pointers are passed as
12180-
arguments to a kernel and the device does not support fine-grain system SVM.
12181-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
12182-
by the OpenCL implementation on the device.
12183-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
12184-
required by the OpenCL implementation on the host.
12144+
* {CL_INVALID_IMAGE_SIZE}
12145+
** if a kernel argument for _kernel_ is an image and the dimensions for the image, such
12146+
as the image width or image height, are not supported by the device
12147+
associated with _command_queue_
12148+
* {CL_IMAGE_FORMAT_NOT_SUPPORTED}
12149+
** if a kernel argument for _kernel_ is an image and the format the _image_, such as the
12150+
image channel order or image channel data type, are not supported by the
12151+
device associated with _command_queue_
12152+
* {CL_MEM_OBJECT_ALLOCATION_FAILURE}
12153+
** if there is a failure to allocate memory for the data store associated with any buffer or image object kernel arguments for _kernel_
12154+
* {CL_INVALID_EVENT_WAIT_LIST}
12155+
** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero
12156+
** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero
12157+
** if event objects in _event_wait_list_ are not valid events
12158+
* {CL_INVALID_OPERATION}
12159+
** if SVM pointers are set as arguments for _kernel_ and the device associated with _command_queue_ does not support SVM
12160+
** if system pointers are set as arguments for _kernel_ the device associated with _command_queue_ does not support fine-grain system SVM
12161+
// TODO: Do we still need these explicit examples?
12162+
// * {CL_OUT_OF_RESOURCES} if there is a failure to queue the execution
12163+
// instance of _kernel_ on the command-queue because of insufficient
12164+
// resources needed to execute the kernel.
12165+
// For example, the explicitly specified _local_work_size_ causes a failure
12166+
// to execute the kernel because of insufficient resources such as
12167+
// registers or local memory.
12168+
// Another example would be the number of read-only image args used in
12169+
// _kernel_ exceed the {CL_DEVICE_MAX_READ_IMAGE_ARGS} value for device or
12170+
// the number of write-only and read-write image args used in _kernel_
12171+
// exceed the {CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS} value for device or the
12172+
// number of samplers used in _kernel_ exceed {CL_DEVICE_MAX_SAMPLERS} for
12173+
// device.
12174+
* {CL_OUT_OF_RESOURCES}
12175+
** if there is a failure to allocate resources required by the OpenCL
12176+
implementation on the device
12177+
* {CL_OUT_OF_HOST_MEMORY}
12178+
** if there is a failure to allocate resources required by the OpenCL
12179+
implementation on the host
1218512180
--
1218612181

1218712182
[open,refpage='clEnqueueTask',desc='Enqueues a command to execute a kernel, using a single work-item, on a device.',type='protos']

0 commit comments

Comments
 (0)