From 2d3ad63f29ba31efe27d62a93d68b9ba7de09e39 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 25 Aug 2025 17:55:20 -0700 Subject: [PATCH 1/4] error code consistency for buffers --- api/opencl_runtime_layer.asciidoc | 538 +++++++++++++++--------------- 1 file changed, 269 insertions(+), 269 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index e2b0406d3..8544c81bb 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -918,43 +918,39 @@ include::{generated}/api/version-notes/CL_BUFFER_CREATE_TYPE_REGION.asciidoc[] successfully. Otherwise, it returns one of the following errors in _errcode_ret_: - * {CL_INVALID_MEM_OBJECT} if _buffer_ is not a valid buffer object or is a - sub-buffer object. - * {CL_INVALID_VALUE} if _buffer_ was created with {CL_MEM_WRITE_ONLY} and - _flags_ specifies {CL_MEM_READ_WRITE} or {CL_MEM_READ_ONLY}, or if _buffer_ - was created with {CL_MEM_READ_ONLY} and _flags_ specifies - {CL_MEM_READ_WRITE} or {CL_MEM_WRITE_ONLY}, or if _flags_ specifies - {CL_MEM_USE_HOST_PTR} or {CL_MEM_ALLOC_HOST_PTR} or {CL_MEM_COPY_HOST_PTR}. - * {CL_INVALID_VALUE} if _buffer_ was created with {CL_MEM_HOST_WRITE_ONLY} and - _flags_ specify {CL_MEM_HOST_READ_ONLY}, or if _buffer_ was created with - {CL_MEM_HOST_READ_ONLY} and _flags_ specify {CL_MEM_HOST_WRITE_ONLY}, or if - _buffer_ was created with {CL_MEM_HOST_NO_ACCESS} and _flags_ specify - {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_WRITE_ONLY}. - * {CL_INVALID_VALUE} if the value specified in _buffer_create_type_ is not - valid. - * {CL_INVALID_VALUE} if value(s) specified in _buffer_create_info_ (for a - given _buffer_create_type_) is not valid or if _buffer_create_info_ is - `NULL`. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for sub-buffer object. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. -// These errors are specific to the {CL_BUFFER_CREATE_TYPE_REGION} parameter - * {CL_INVALID_VALUE} if the region specified by the {cl_buffer_region_TYPE} - structure passed in _buffer_create_info_ is out of bounds in _buffer_. - * {CL_INVALID_BUFFER_SIZE} if the _size_ field of the {cl_buffer_region_TYPE} - structure passed in _buffer_create_info_ is 0. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if there are no devices in _context_ - associated with _buffer_ for which the _origin_ field of the - {cl_buffer_region_TYPE} structure passed in _buffer_create_info_ is - aligned to the {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value. + * {CL_INVALID_MEM_OBJECT} + ** if _buffer_ is not a valid buffer object + ** if _buffer_ is a sub-buffer object + * {CL_INVALID_VALUE} + ** if _buffer_ was created with {CL_MEM_WRITE_ONLY} and _flags_ specifies {CL_MEM_READ_WRITE} or {CL_MEM_READ_ONLY} + ** if _buffer_ was created with {CL_MEM_READ_ONLY} and _flags_ specifies {CL_MEM_READ_WRITE} or {CL_MEM_WRITE_ONLY} + ** if _buffer_ was created with {CL_MEM_HOST_WRITE_ONLY} and _flags_ specify {CL_MEM_HOST_READ_ONLY} + ** if _buffer_ was created with {CL_MEM_HOST_READ_ONLY} and _flags_ specify {CL_MEM_HOST_WRITE_ONLY} + ** if _buffer_ was created with {CL_MEM_HOST_NO_ACCESS} and _flags_ specify {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_WRITE_ONLY} ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_VALUE} if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} - and _flags_ specifies {CL_MEM_READ_WRITE}, {CL_MEM_WRITE_ONLY}, or - {CL_MEM_HOST_WRITE_ONLY}. + ** if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} and _flags_ specifies {CL_MEM_READ_WRITE}, {CL_MEM_WRITE_ONLY}, or {CL_MEM_HOST_WRITE_ONLY} endif::cl_ext_immutable_memory_objects[] + ** if _flags_ specifies {CL_MEM_USE_HOST_PTR} or {CL_MEM_ALLOC_HOST_PTR} or {CL_MEM_COPY_HOST_PTR} + ** if the value specified in _buffer_create_type_ is not valid + ** if _buffer_create_info_ is `NULL` + ** if a value specified in _buffer_create_info_ for a given _buffer_create_type_ is not valid + ** if the region specified by the {cl_buffer_region_TYPE} structure passed in _buffer_create_info_ is out of bounds in _buffer_ + * {CL_INVALID_BUFFER_SIZE} + ** if the _size_ field of the {cl_buffer_region_TYPE} structure passed in _buffer_create_info_ is zero + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if there are no devices in _context_ associated with _buffer_ for which + the _origin_ field of the {cl_buffer_region_TYPE} structure passed in + _buffer_create_info_ is aligned to the {CL_DEVICE_MEM_BASE_ADDR_ALIGN} + value. + This error code is <> version 1.1. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with the sub-buffer object + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host [NOTE] ==== @@ -1063,43 +1059,44 @@ then be reused by the application. function is executed successfully. Otherwise, they return one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and - _buffer_ are not the same or if the context associated with - _command_queue_ and events in _event_wait_list_ are not the same. - * {CL_INVALID_MEM_OBJECT} if _buffer_ is not a valid buffer object. - * {CL_INVALID_VALUE} if the region being read or written specified by - (_offset_, _size_) is out of bounds or if _ptr_ is a `NULL` value. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and - _num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_ - are not valid events. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _buffer_ is a sub-buffer object and - _offset_ specified when the sub-buffer object is created is not aligned - to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated with - _queue_. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _buffer_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_MEM_OBJECT} + ** if _buffer_ is not a valid buffer object + * {CL_INVALID_VALUE} + ** if the region being read or written specified by _offset_ and _size_ is out of bounds + ** if _ptr_ is `NULL` + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero + ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero + ** if event objects in _event_wait_list_ are not valid events + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if _buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated with + _command_queue_. This error code is <> version 1.1. - * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the read and write - operations are blocking and the execution status of any of the events in - _event_wait_list_ is a negative integer value. + * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} + ** if the read or write operations are blocking and the execution status of + any of the events in _event_wait_list_ is a negative integer value indicating an error. This error code is <> version 1.1. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _buffer_. - * {CL_INVALID_OPERATION} if {clEnqueueReadBuffer} is called on _buffer_ - which has been created with {CL_MEM_HOST_WRITE_ONLY} or - {CL_MEM_HOST_NO_ACCESS}. - * {CL_INVALID_OPERATION} if {clEnqueueWriteBuffer} is called on _buffer_ - which has been created with {CL_MEM_HOST_READ_ONLY} or - {CL_MEM_HOST_NO_ACCESS}. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _buffer_ + * {CL_INVALID_OPERATION} + ** if {clEnqueueReadBuffer} is called on _buffer_ which has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS} + ** if {clEnqueueWriteBuffer} is called on _buffer_ which has been created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS} ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if {clEnqueueWriteBuffer} is called on _buffer_ - which has been created with {CL_MEM_IMMUTABLE_EXT}. + ** if {clEnqueueWriteBuffer} is called on _buffer_ which has been created with {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- [open,refpage='clEnqueueReadBufferRect',desc='Enqueue command to read from a 2D or 3D rectangular region from a buffer object to host memory.',type='protos',alias='clEnqueueWriteBufferRect'] @@ -1210,57 +1207,52 @@ then be reused by the application. if the function is executed successfully. Otherwise, they return one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and - _buffer_ are not the same or if the context associated with - _command_queue_ and events in _event_wait_list_ are not the same. - * {CL_INVALID_MEM_OBJECT} if _buffer_ is not a valid buffer object. - * {CL_INVALID_VALUE} if _buffer_origin_, _host_origin_, or _region_ is `NULL`. - * {CL_INVALID_VALUE} if the region being read or written specified by - (_buffer_origin_, _region_, _buffer_row_pitch_, _buffer_slice_pitch_) is - out of bounds. - * {CL_INVALID_VALUE} if any _region_ array element is 0. - * {CL_INVALID_VALUE} if _buffer_row_pitch_ is not 0 and is less than - _region_[0]. - * {CL_INVALID_VALUE} if _host_row_pitch_ is not 0 and is less than - _region_[0]. - * {CL_INVALID_VALUE} if _buffer_slice_pitch_ is not 0 and is less than - _region_[1] {times} _buffer_row_pitch_ and not a multiple of - _buffer_row_pitch_. - * {CL_INVALID_VALUE} if _host_slice_pitch_ is not 0 and is less than - _region_[1] {times} _host_row_pitch_ and not a multiple of - _host_row_pitch_. - * {CL_INVALID_VALUE} if _ptr_ is `NULL`. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and - _num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_ - are not valid events. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _buffer_ is a sub-buffer object and - _offset_ specified when the sub-buffer object is created is not aligned - to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated with - _queue_. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _buffer_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_MEM_OBJECT} + ** if _buffer_ is not a valid buffer object + * {CL_INVALID_VALUE} + ** if _buffer_origin_, _host_origin_, or _region_ is `NULL` + ** if the region being read or written specified by _buffer_origin_, _region_, _buffer_row_pitch_, and _buffer_slice_pitch_ is out of bounds + ** if any _region_ array element is zero + ** if _buffer_row_pitch_ is not equal to zero and is less than _region_[0]. + ** if _buffer_slice_pitch_ is not equal to zero and is less than the_region_[1] times _buffer_row_pitch_ + ** if _buffer_slice_pitch_ is not equal to zero and is not a multiple of _buffer_row_pitch_ + ** if _host_row_pitch_ is not equal to zero and is less than _region_[0] + ** if _host_slice_pitch_ is not equal to zero and is less than _region_[1] times _host_row_pitch_ + ** if _host_slice_pitch_ is not equal to zero and is not a multiple of _host_row_pitch_ + ** if _ptr_ is `NULL` + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero + ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero + ** if event objects in _event_wait_list_ are not valid events + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if _buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object is created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated with + _command_queue_. This error code is <> version 1.1. - * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the read and write - operations are blocking and the execution status of any of the events in - _event_wait_list_ is a negative integer value. + * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} + ** if the read or write operations are blocking and the execution status of + any of the events in _event_wait_list_ is a negative integer value indicating an error. This error code is <> version 1.1. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _buffer_. - * {CL_INVALID_OPERATION} if {clEnqueueReadBufferRect} is called on _buffer_ - which has been created with {CL_MEM_HOST_WRITE_ONLY} or - {CL_MEM_HOST_NO_ACCESS}. - * {CL_INVALID_OPERATION} if {clEnqueueWriteBufferRect} is called on _buffer_ - which has been created with {CL_MEM_HOST_READ_ONLY} or - {CL_MEM_HOST_NO_ACCESS}. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _buffer_ + * {CL_INVALID_OPERATION} + ** if {clEnqueueReadBufferRect} is called on _buffer_ which has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS} + ** if {clEnqueueWriteBufferRect} is called on _buffer_ which has been created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS} ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if {clEnqueueWriteBufferRect} is called on _buffer_ - which has been created with {CL_MEM_IMMUTABLE_EXT}. + ** if {clEnqueueWriteBufferRect} is called on _buffer_ which has been created with {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host [NOTE] ==== @@ -1366,48 +1358,50 @@ argument value specified when _src_buffer_ or _dst_buffer is created is ignored successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _src_buffer_ and _dst_buffer_ are not the same or if the context - associated with _command_queue_ and events in _event_wait_list_ are not - the same. - * {CL_INVALID_MEM_OBJECT} if _src_buffer_ and _dst_buffer_ are not valid - buffer objects. - * {CL_INVALID_VALUE} if _src_offset_, _dst_offset_, _size_, _src_offset_ - {plus} _size_ or _dst_offset_ + _size_ require accessing elements - outside the _src_buffer_ and _dst_buffer_ buffer objects respectively. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and - _num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_ - are not valid events. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _src_buffer_ is a sub-buffer object - and _offset_ specified when the sub-buffer object is created is not - aligned to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated - with _queue_. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _src_buffer_ are not the same + ** if the context associated with _command_queue_ and _dst_buffer_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_MEM_OBJECT} + ** if _src_buffer_ is not a valid buffer object + ** if _dst_buffer_ is not a valid buffer object + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if _src_buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated + with _command_queue_. This error code is <> version 1.1. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _dst_buffer_ is a sub-buffer object - and _offset_ specified when the sub-buffer object is created is not - aligned to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated - with _queue_. + ** if _dst_buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated + with _command_queue_. This error code is <> version 1.1. - * {CL_MEM_COPY_OVERLAP} if _src_buffer_ and _dst_buffer_ are the same buffer - or sub-buffer object and the source and destination regions overlap or - if _src_buffer_ and _dst_buffer_ are different sub-buffers of the same - associated buffer object and they overlap. - The regions overlap if _src_offset_ {leq} _dst_offset_ {leq} - _src_offset_ + _size_ - 1 or if _dst_offset_ {leq} _src_offset_ {leq} - _dst_offset_ + _size_ - 1. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _src_buffer_ or _dst_buffer_. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + * {CL_INVALID_VALUE} + ** if the region specified by _src_offset_ and _size_ is out of bounds of _src_buffer_ + ** if the region specified by _dst_offset_ and _size_ is out of bounds of _dst_buffer_ + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero + ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero + ** if event objects in _event_wait_list_ are not valid events + * {CL_MEM_COPY_OVERLAP} + ** if _src_buffer_ and _dst_buffer_ are the same buffer or sub-buffer object and the source and destination regions overlap. + ** if _src_buffer_ and _dst_buffer_ are different sub-buffers of the same associated buffer object and they overlap + ** Refer to <> for + details on how to determine if source and destination regions overlap. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _src_buffer_ or _dst_buffer_ ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _dst_buffer_ was created with - {CL_MEM_IMMUTABLE_EXT}. + * {CL_INVALID_OPERATION} + ** if _dst_buffer_ was created with {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- [open,refpage='clEnqueueCopyBufferRect',desc='Enqueues a command to copy a 2D or 3D rectangular region from a buffer object to another buffer object.',type='protos'] @@ -1502,63 +1496,60 @@ argument value specified when _src_buffer_ or _dst_buffer_ is created is ignored successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_, - _src_buffer_ and _dst_buffer_ are not the same or if the context - associated with _command_queue_ and events in _event_wait_list_ are not - the same. - * {CL_INVALID_MEM_OBJECT} if _src_buffer_ and _dst_buffer_ are not valid - buffer objects. - * {CL_INVALID_VALUE} if _src_origin_, _dst_origin_, or _region_ is `NULL`. - * {CL_INVALID_VALUE} if (_src_origin_, _region_, _src_row_pitch_, - _src_slice_pitch_) or (_dst_origin_, _region_, _dst_row_pitch_, - _dst_slice_pitch_) require accessing elements outside the _src_buffer_ - and _dst_buffer_ buffer objects respectively. - * {CL_INVALID_VALUE} if any _region_ array element is 0. - * {CL_INVALID_VALUE} if _src_row_pitch_ is not 0 and is less than - _region_[0]. - * {CL_INVALID_VALUE} if _dst_row_pitch_ is not 0 and is less than - _region_[0]. - * {CL_INVALID_VALUE} if _src_slice_pitch_ is not 0 and is less than - _region_[1] {times} _src_row_pitch_ or if _src_slice_pitch_ is not 0 and - is not a multiple of _src_row_pitch_. - * {CL_INVALID_VALUE} if _dst_slice_pitch_ is not 0 and is less than - _region_[1] {times} _dst_row_pitch_ or if _dst_slice_pitch_ is not 0 and - is not a multiple of _dst_row_pitch_. - * {CL_INVALID_VALUE} if _src_buffer_ and _dst_buffer_ are the same buffer - object and _src_slice_pitch_ is not equal to _dst_slice_pitch_ and - _src_row_pitch_ is not equal to _dst_row_pitch_. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and - _num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_ - are not valid events. - * {CL_MEM_COPY_OVERLAP} if _src_buffer_ and _dst_buffer_ are the same buffer - or sub-buffer object and the source and destination regions overlap or - if _src_buffer_ and _dst_buffer_ are different sub-buffers of the same - associated buffer object and they overlap. - Refer to <> for - details on how to determine if source and destination regions overlap. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _src_buffer_ is a sub-buffer object - and _offset_ specified when the sub-buffer object is created is not - aligned to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated - with _queue_. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _src_buffer_ are not the same + ** if the context associated with _command_queue_ and _dst_buffer_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_MEM_OBJECT} + ** if _src_buffer_ is not a valid buffer object + ** if _dst_buffer_ is not a valid buffer object + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if _src_buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated + with _command_queue_. This error code is <> version 1.1. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _dst_buffer_ is a sub-buffer object - and _offset_ specified when the sub-buffer object is created is not - aligned to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated - with _queue_. + ** if _dst_buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated + with _command_queue_. This error code is <> version 1.1. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _src_buffer_ or _dst_buffer_. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + * {CL_INVALID_VALUE} + ** if _src_origin_, _dst_origin_, or _region_ is `NULL` + ** if the region specified by _src_origin_, _region_, _src_row_pitch_, and _src_slice_pitch_ is out of bounds of _src_buffer_ + ** if the region specified by _dst_origin_, _region_, _dst_row_pitch_, and _dst_slice_pitch_ is out of bounds of _dst_buffer_ + ** if any _region_ array element is zero + ** if _src_row_pitch_ is not equal to zero and is less than _region_[0] + ** if _src_slice_pitch_ is not equal to zero and is less than _region_[1] times _src_row_pitch_ + ** if _src_slice_pitch_ is not equal to zero and is not a multiple of _src_row_pitch_ + ** if _dst_row_pitch_ is not equal to zero and is less than _region_[0] + ** if _dst_slice_pitch_ is not equal to zero and is less than _region_[1] times _dst_row_pitch_ + ** if _dst_slice_pitch_ is not equal to zero and is not a multiple of _dst_row_pitch_ + ** if _src_buffer_ and _dst_buffer_ are the same buffer object and _src_row_pitch_ is not equal to _dst_row_pitch_ + ** if _src_buffer_ and _dst_buffer_ are the same buffer object and _src_slice_pitch_ is not equal to _dst_slice_pitch_ + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero + ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero + ** if event objects in _event_wait_list_ are not valid events + * {CL_MEM_COPY_OVERLAP} + ** if _src_buffer_ and _dst_buffer_ are the same buffer or sub-buffer object and the source and destination regions overlap. + ** if _src_buffer_ and _dst_buffer_ are different sub-buffers of the same associated buffer object and they overlap + ** Refer to <> for + details on how to determine if source and destination regions overlap. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _src_buffer_ or _dst_buffer_ ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _dst_buffer_ was created with - {CL_MEM_IMMUTABLE_EXT}. + * {CL_INVALID_OPERATION} + ** if _dst_buffer_ was created with {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- @@ -1629,35 +1620,43 @@ argument value specified when _buffer_ is created is ignored by successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and - _buffer_ are not the same or if the context associated with - _command_queue_ and events in _event_wait_list_ are not the same. - * {CL_INVALID_MEM_OBJECT} if _buffer_ is not a valid buffer object. - * {CL_INVALID_VALUE} if _offset_ or _offset_ + _size_ require accessing - elements outside the _buffer_ buffer object respectively. - * {CL_INVALID_VALUE} if _pattern_ is `NULL` or if _pattern_size_ is 0 or if - _pattern_size_ is not one of { 1, 2, 4, 8, 16, 32, 64, 128 }. - * {CL_INVALID_VALUE} if _offset_ and _size_ are not a multiple of - _pattern_size_. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and - _num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_ - are not valid events. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _buffer_ is a sub-buffer object and - offset specified when the sub-buffer object is created is not aligned to - {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for device associated with _queue_. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _buffer_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_MEM_OBJECT} + ** if _buffer_ is not a valid buffer object + * {CL_INVALID_VALUE} + ** if the region being read or written specified by _offset_ and _size_ is out of bounds + ** if _pattern_ is `NULL` + ** if _pattern_size_ is zero + ** if _pattern_size_ is not a power of two + ** if _pattern_size_ is greater than 128 + ** if _offset_ is not a multiple of _pattern_size_ + ** if _size_ is not a multiple of _pattern_size_ + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero + ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero + ** if event objects in _event_wait_list_ are not valid events + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if _buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated with + _command_queue_. This error code is <> version 1.1. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _buffer_. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _buffer_ ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT}. + * {CL_INVALID_OPERATION} + ** if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- @@ -1727,50 +1726,51 @@ The _errcode_ret_ is set to {CL_SUCCESS}. A `NULL` pointer is returned otherwise with one of the following error values returned in _errcode_ret_: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_CONTEXT} if context associated with _command_queue_ and - _buffer_ are not the same or if the context associated with - _command_queue_ and events in _event_wait_list_ are not the same. - * {CL_INVALID_MEM_OBJECT} if _buffer_ is not a valid buffer object. - * {CL_INVALID_VALUE} if region being mapped given by (_offset_, _size_) is - out of bounds or if _size_ is 0 or if values specified in _map_flags_ - are not valid. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or _event_wait_list_ is not `NULL` and - _num_events_in_wait_list_ is 0, or if event objects in _event_wait_list_ - are not valid events. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if _buffer_ is a sub-buffer object and - _offset_ specified when the sub-buffer object is created is not aligned - to {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated with - _queue_. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _buffer_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_MEM_OBJECT} + ** if _buffer_ is not a valid buffer object + * {CL_INVALID_VALUE} + ** if the region being mapped specified by _offset_ and _size_ is out of bounds + ** if _size_ is zero + ** if values specified in _map_flags_ are not valid + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is greater than zero + ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero + ** if event objects in _event_wait_list_ are not valid events + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if _buffer_ is a sub-buffer object and the offset specified when the + sub-buffer object was created is not aligned to the + {CL_DEVICE_MEM_BASE_ADDR_ALIGN} value for the device associated with + _command_queue_. This error code is <> version 1.1. - * {CL_MAP_FAILURE} if there is a failure to map the requested region into + * {CL_MAP_FAILURE} + ** if there is a failure to map the requested region into the host address space. This error cannot occur for buffer objects created with {CL_MEM_USE_HOST_PTR} or {CL_MEM_ALLOC_HOST_PTR}. - * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the map operation is - blocking and the execution status of any of the events in - _event_wait_list_ is a negative integer value. + * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} + ** if the map operations is blocking and the execution status of + any of the events in _event_wait_list_ is a negative integer value indicating an error. This error code is <> version 1.1. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _buffer_. - * {CL_INVALID_OPERATION} if _buffer_ has been created with - {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS} and {CL_MAP_READ} is set - in _map_flags_ or if _buffer_ has been 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_. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. - * {CL_INVALID_OPERATION} if mapping would lead to overlapping regions being - mapped for writing. + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _buffer_ + * {CL_INVALID_OPERATION} + ** 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_ + ** 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_ ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} - in _flags_ and {CL_MAP_WRITE} or {CL_MAP_WRITE_INVALIDATE_REGION} is set - in _map_flags_. + ** if _buffer_ was created with {CL_MEM_IMMUTABLE_EXT} and {CL_MAP_WRITE} or {CL_MAP_WRITE_INVALIDATE_REGION} is set in _map_flags_ endif::cl_ext_immutable_memory_objects[] + ** if mapping would lead to overlapping regions being mapped for writing + * {CL_OUT_OF_RESOURCES} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the device + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host The pointer returned maps a region starting at _offset_ and is at least _size_ bytes in size. From 7965e1514fde53f60d91d358bcaf2758a599a98b Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 25 Aug 2025 18:03:19 -0700 Subject: [PATCH 2/4] fix a few trailing periods --- api/opencl_runtime_layer.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 8544c81bb..8d96f11f6 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1218,7 +1218,7 @@ Otherwise, they return one of the following errors: ** if _buffer_origin_, _host_origin_, or _region_ is `NULL` ** if the region being read or written specified by _buffer_origin_, _region_, _buffer_row_pitch_, and _buffer_slice_pitch_ is out of bounds ** if any _region_ array element is zero - ** if _buffer_row_pitch_ is not equal to zero and is less than _region_[0]. + ** if _buffer_row_pitch_ is not equal to zero and is less than _region_[0] ** if _buffer_slice_pitch_ is not equal to zero and is less than the_region_[1] times _buffer_row_pitch_ ** if _buffer_slice_pitch_ is not equal to zero and is not a multiple of _buffer_row_pitch_ ** if _host_row_pitch_ is not equal to zero and is less than _region_[0] @@ -1386,7 +1386,7 @@ Otherwise, it returns one of the following errors: ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero ** if event objects in _event_wait_list_ are not valid events * {CL_MEM_COPY_OVERLAP} - ** if _src_buffer_ and _dst_buffer_ are the same buffer or sub-buffer object and the source and destination regions overlap. + ** if _src_buffer_ and _dst_buffer_ are the same buffer or sub-buffer object and the source and destination regions overlap ** if _src_buffer_ and _dst_buffer_ are different sub-buffers of the same associated buffer object and they overlap ** Refer to <> for details on how to determine if source and destination regions overlap. @@ -1534,7 +1534,7 @@ Otherwise, it returns one of the following errors: ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero ** if event objects in _event_wait_list_ are not valid events * {CL_MEM_COPY_OVERLAP} - ** if _src_buffer_ and _dst_buffer_ are the same buffer or sub-buffer object and the source and destination regions overlap. + ** if _src_buffer_ and _dst_buffer_ are the same buffer or sub-buffer object and the source and destination regions overlap ** if _src_buffer_ and _dst_buffer_ are different sub-buffers of the same associated buffer object and they overlap ** Refer to <> for details on how to determine if source and destination regions overlap. From f02b89262902e5bdfe8e82fcdd9cd9f3edbc2e37 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Fri, 29 Aug 2025 10:02:17 -0700 Subject: [PATCH 3/4] apply typo fix from code review Co-authored-by: Ewan Crawford --- api/opencl_runtime_layer.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 8d96f11f6..8b34dfe29 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1219,7 +1219,7 @@ Otherwise, they return one of the following errors: ** if the region being read or written specified by _buffer_origin_, _region_, _buffer_row_pitch_, and _buffer_slice_pitch_ is out of bounds ** if any _region_ array element is zero ** if _buffer_row_pitch_ is not equal to zero and is less than _region_[0] - ** if _buffer_slice_pitch_ is not equal to zero and is less than the_region_[1] times _buffer_row_pitch_ + ** if _buffer_slice_pitch_ is not equal to zero and is less than _region_[1] times _buffer_row_pitch_ ** if _buffer_slice_pitch_ is not equal to zero and is not a multiple of _buffer_row_pitch_ ** if _host_row_pitch_ is not equal to zero and is less than _region_[0] ** if _host_slice_pitch_ is not equal to zero and is less than _region_[1] times _host_row_pitch_ From f93042717c092acf03288332ac36d3adab5d0b60 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Wed, 3 Sep 2025 13:50:15 -0700 Subject: [PATCH 4/4] apply code review comment Co-authored-by: Jose Lopez --- api/opencl_runtime_layer.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 8b34dfe29..2464f64af 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1628,7 +1628,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} ** if _buffer_ is not a valid buffer object * {CL_INVALID_VALUE} - ** if the region being read or written specified by _offset_ and _size_ is out of bounds + ** if the region being filled specified by _offset_ and _size_ is out of bounds ** if _pattern_ is `NULL` ** if _pattern_size_ is zero ** if _pattern_size_ is not a power of two