From 5c09d4e7397b02e5555c6d06f74403ac3c0a9a0a Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Fri, 12 Sep 2025 17:54:45 -0700 Subject: [PATCH 1/2] error code consistency for images --- api/opencl_runtime_layer.asciidoc | 464 +++++++++++++++--------------- 1 file changed, 237 insertions(+), 227 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 0ce229b6..4e90b179 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -3191,13 +3191,18 @@ all devices in the context. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {CL_INVALID_VALUE} if _flags_ or _image_type_ are not valid, or if - _num_entries_ is 0 and _image_formats_ is not `NULL`. - * {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_CONTEXT} + ** if _context_ is not a valid context + * {CL_INVALID_VALUE} + ** if _flags_ is not valid + ** if _image_type_ is not valid + ** if _num_entries_ is zero and _image_formats_ is not `NULL` + * {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 If {CL_DEVICE_IMAGE_SUPPORT} specified in the <> table is {CL_TRUE}, the values assigned to @@ -3746,56 +3751,54 @@ then be reused by the application. function is executed 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 - _image_ 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 _image_ is not a valid image object. - * {CL_INVALID_VALUE} if _origin_ or _region_ is `NULL`. - * {CL_INVALID_VALUE} if the region being read or written specified by - _origin_ and _region_ is out of bounds. - * {CL_INVALID_VALUE} if values in _origin_ and _region_ do not follow rules - described in the argument description for _origin_ and _region_. - * {CL_INVALID_VALUE} if _image_ is a 1D or 2D image and _slice_pitch_ or - _input_slice_pitch_ is not 0. - * {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_INVALID_IMAGE_SIZE} if image dimensions (image width, height, - specified or compute row and/or slice pitch) for _image_ are not - supported by device associated with _queue_. - * {CL_IMAGE_FORMAT_NOT_SUPPORTED} if image format (image channel order and - data type) for _image_ are not supported by device associated with - _queue_. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _image_. - * {CL_INVALID_OPERATION} if the device associated with _command_queue_ does - not support images (i.e. {CL_DEVICE_IMAGE_SUPPORT} specified in the - <> table is {CL_FALSE}). - * {CL_INVALID_OPERATION} if {clEnqueueReadImage} is called on _image_ which - has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS}. - * {CL_INVALID_OPERATION} if {clEnqueueWriteImage} is called on _image_ which - has been created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS}. - * {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. - This error code is <> version 1.1. - * {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_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _image_ 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 _image_ is not a valid image object + * {CL_INVALID_VALUE} + ** if _origin_ is `NULL` + ** if _region_ is `NULL` + ** if the region being read or written specified by _origin_ and _region_ is out of bounds + ** if values in _origin_ and _region_ do not follow the rules described in the argument description for _origin_ and _region_ + ** if _image_ is a 1D or 2D image and _slice_pitch_ or _input_slice_pitch_ is not zero + ** if _ptr_ is `NULL` ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is - supported, and the mip level specified in _origin_ is not a valid level - for _image_, + * {CL_INVALID_MIP_LEVEL} + ** if the {cl_khr_mipmap_image_EXT} extension is supported and the mip level specified in _origin_ is not a valid level for _image_ endif::cl_khr_mipmap_image[] + * {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_INVALID_IMAGE_SIZE} + ** if the dimensions for _image_, such as the image width or image height, + are not supported by the device associated with _command_queue_ + * {CL_IMAGE_FORMAT_NOT_SUPPORTED} + ** if the format for _image_, such as the image channel order or image + channel data type, are not supported by the device associated with + _command_queue_ + * {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 the data store associated with _image_ + * {CL_INVALID_OPERATION} + ** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE}) + ** if {clEnqueueReadImage} is called on _image_ which has been created with {CL_MEM_HOST_WRITE_ONLY} or {CL_MEM_HOST_NO_ACCESS} + ** if {clEnqueueWriteImage} is called on _image_ 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 {clEnqueueWriteImage} is called on _image_ which - has been created with {CL_MEM_IMMUTABLE_EXT}. + ** if {clEnqueueWriteImage} is called on _image_ 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] ==== @@ -3929,54 +3932,55 @@ argument value specified when _src_image_ or _dst_image_ is created is ignored b 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_image_ and _dst_image_ 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_image_ and _dst_image_ are not valid image - objects. - * {CL_IMAGE_FORMAT_MISMATCH} if _src_image_ and _dst_image_ do not use the - same image format. - * {CL_INVALID_VALUE} if _src_origin_, _dst_origin_, or _region_ is `NULL`. - * {CL_INVALID_VALUE} if the 2D or 3D rectangular region specified by - _src_origin_ and _src_origin_ {plus} _region_ refers to a region outside - _src_image_, or if the 2D or 3D rectangular region specified by - _dst_origin_ and _dst_origin_ {plus} _region_ refers to a region outside - _dst_image_. - * {CL_INVALID_VALUE} if values in _src_origin_, _dst_origin_ and _region_ do - not follow rules described in the argument description for _src_origin_, - _dst_origin_ and _region_. - * {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_INVALID_IMAGE_SIZE} if image dimensions (image width, height, - specified or compute row and/or slice pitch) for _src_image_ or - _dst_image_ are not supported by device associated with _queue_. - * {CL_IMAGE_FORMAT_NOT_SUPPORTED} if image format (image channel order and - data type) for _src_image_ or _dst_image_ are not supported by device - associated with _queue_. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _src_image_ or _dst_image_. - * {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 the device associated with _command_queue_ does - not support images (i.e. {CL_DEVICE_IMAGE_SUPPORT} specified in the - <> table is {CL_FALSE}). - * {CL_MEM_COPY_OVERLAP} if _src_image_ and _dst_image_ are the same image - object and the source and destination regions overlap. + * {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_image_ are not the same + ** if the context associated with _command_queue_ and _dst_image_ 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_image_ is not a valid image object + ** if _dst_image_ is not a valid image object + * {CL_IMAGE_FORMAT_MISMATCH} + ** if _src_image_ and _dst_image_ do not use the same image format + * {CL_INVALID_VALUE} + ** if _src_origin_ is `NULL` + ** if _dst_origin_ is `NULL` + ** if _region_ is `NULL` + ** if the 2D or 3D rectangular region specified by _src_origin_ and _region_ refers to a region outside _src_image_ + ** if the 2D or 3D rectangular region specified by _dst_origin_ and _region_ refers to a region outside _dst_image_ + ** if values in _src_origin_, _dst_origin_, and _region_ do not follow the rules described in the argument descriptions for _src_origin_, _dst_origin_ and _region_ ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is - supported, and the mip level specified in _src_origin_ or _dst_origin_ - is not a valid level for the corresponding _src_image_ or _dst_image_, + * {CL_INVALID_MIP_LEVEL} + ** if the {cl_khr_mipmap_image_EXT} extension is supported and the mip level specified in _src_origin_ is not a valid level for _src_image_ + ** if the {cl_khr_mipmap_image_EXT} extension is supported and the mip level specified in _dst_origin_ is not a valid level for _dst_image_ endif::cl_khr_mipmap_image[] + * {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_INVALID_IMAGE_SIZE} + ** if the dimensions for _src_image_ or _dst_image_, such as the image width or image height, + are not supported by the device associated with _command_queue_ + * {CL_IMAGE_FORMAT_NOT_SUPPORTED} + ** if the format for _src_image_ or _dst_image_, such as the image channel order or image + channel data type, are not supported by the device associated with + _command_queue_ + * {CL_MEM_COPY_OVERLAP} + ** if _src_image_ and _dst_image_ are the same image object and the 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_image_ or _dst_image_ + * {CL_INVALID_OPERATION} + ** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE}) ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _dst_image_ was created with {CL_MEM_IMMUTABLE_EXT}. + ** if _dst_image_ 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 -- @@ -4065,42 +4069,47 @@ argument value specified when _image_ 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 - _image_ 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 _image_ is not a valid image object. - * {CL_INVALID_VALUE} if _fill_color_ is `NULL`. - * {CL_INVALID_VALUE} if _origin_ or _region_ is `NULL`. - * {CL_INVALID_VALUE} if the region being filled as specified by _origin_ and - _region_ is out of bounds. - * {CL_INVALID_VALUE} if values in _origin_ and _region_ do not follow rules - described in the argument description for _origin_ and _region_. - * {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_INVALID_IMAGE_SIZE} if image dimensions (image width, height, - specified or compute row and/or slice pitch) for _image_ are not - supported by device associated with _queue_. - * {CL_IMAGE_FORMAT_NOT_SUPPORTED} if image format (image channel order and - data type) for _image_ are not supported by device associated with - _queue_. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with _image_. - * {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_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _image_ 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 _image_ is not a valid image object + * {CL_INVALID_VALUE} + ** if _fill_color_ is `NULL` + ** if _origin_ is `NULL` + ** if _region_ is `NULL` + ** if the region being filled specified by _origin_ and _region_ is out of bounds + ** if values in _origin_ and _region_ do not follow the rules described in the argument description for _origin_ and _region_ ifdef::cl_khr_mipmap_image[] - * {CL_INVALID_MIP_LEVEL} if the {cl_khr_mipmap_image_EXT} extension is - supported, and the mip level specified in _origin_ is not a valid level - for _image_, + * {CL_INVALID_MIP_LEVEL} + ** if the {cl_khr_mipmap_image_EXT} extension is supported and the mip level specified in _origin_ is not a valid level for _image_ endif::cl_khr_mipmap_image[] + * {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_INVALID_IMAGE_SIZE} + ** if the dimensions for _image_, such as the image width or image height, + are not supported by the device associated with _command_queue_ + * {CL_IMAGE_FORMAT_NOT_SUPPORTED} + ** if the format for _image_, such as the image channel order or image + channel data type, are not supported by the device associated with + _command_queue_ + * {CL_MEM_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with _image_ + * {CL_INVALID_OPERATION} + ** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE}) ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _image_ was created with {CL_MEM_IMMUTABLE_EXT}. + ** if _image_ 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 -- @@ -4466,60 +4475,62 @@ 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 - _image_ are not the same or if context associated with _command_queue_ - and events in _event_wait_list_ are not the same. - * {CL_INVALID_MEM_OBJECT} if _image_ is not a valid image object. - * {CL_INVALID_VALUE} if _origin_ or _region_ is `NULL`. - * {CL_INVALID_VALUE} if region being mapped given by (_origin_, - _origin_ + _region_) is out of bounds or if values specified in _map_flags_ - are not valid. - * {CL_INVALID_VALUE} if values in _origin_ and _region_ do not follow rules - described in the argument description for _origin_ and _region_. - * {CL_INVALID_VALUE} if _image_row_pitch_ is `NULL`. - * {CL_INVALID_VALUE} if _image_ is a 3D image, 1D or 2D image array object - and _image_slice_pitch_ 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_INVALID_IMAGE_SIZE} if image dimensions (image width, height, - specified or compute row and/or slice pitch) for _image_ are not - supported by device associated with _queue_. - * {CL_IMAGE_FORMAT_NOT_SUPPORTED} if image format (image channel order and - data type) for _image_ are not supported by device associated with - _queue_. - * {CL_MAP_FAILURE} if there is a failure to map the requested region into + * {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 _image_ 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 _image_ is not a valid image object + * {CL_INVALID_VALUE} + ** if _origin_ is `NULL` + ** if _region_ is `NULL` + ** if the region being mapped specified by _origin_ and _region_ is out of bounds + ** if values specified in _map_flags_ are not valid + ** if values in _origin_ and _region_ do not follow the rules described in the argument description for _origin_ and _region_ + ** if _image_row_pitch_ is `NULL` + ** if _image_ is a 1D or 2D image array object and _image_slice_pitch_ is `NULL` + ** if _image_ is a 3D and _image_slice_pitch_ is `NULL` +ifdef::cl_khr_mipmap_image[] + * {CL_INVALID_MIP_LEVEL} + ** if the {cl_khr_mipmap_image_EXT} extension is supported and the mip level specified in _origin_ is not a valid level for _image_ +endif::cl_khr_mipmap_image[] + * {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_INVALID_IMAGE_SIZE} + ** if the dimensions for _image_, such as the image width or image height, + are not supported by the device associated with _command_queue_ + * {CL_IMAGE_FORMAT_NOT_SUPPORTED} + ** if the format for _image_, such as the image channel order or image + channel data type, are not supported by the device associated with + _command_queue_ + * {CL_MAP_FAILURE} + ** if there is a failure to map the requested region into the host address space. This error cannot occur for image 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 _image_. - * {CL_INVALID_OPERATION} if the device associated with _command_queue_ does - not support images (i.e. {CL_DEVICE_IMAGE_SUPPORT} specified in the - <> table is {CL_FALSE}). - * {CL_INVALID_OPERATION} 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_ or if _image_ 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 _image_ + * {CL_INVALID_OPERATION} + ** if the device associated with _command_queue_ does not support images (the query for {CL_DEVICE_IMAGE_SUPPORT} returns {CL_FALSE}) + ** 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_ + ** if _image_ 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_ ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _image_ 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 _image_ was created with {CL_MEM_IMMUTABLE_EXT} in _flags_ 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 1D, 2D or 3D region starting at _origin_ and is at least _region_[0] pixels in size for a 1D image, 1D image buffer or 1D @@ -4724,46 +4735,38 @@ endif::cl_khr_d3d11_sharing[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_MEM_OBJECT} if _image_ is a not a valid image object. - * {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or - if the size in bytes specified by _param_value_size_ is less than size of + * {CL_INVALID_MEM_OBJECT} + ** if _image_ is a not a valid image object + * {CL_INVALID_VALUE} + ** if _param_name_ is not one of the supported values + ** if the size in bytes specified by _param_value_size_ is less than the size of the return type specified in the - <> table - and _param_value_ is not `NULL`. - * {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. - + <> + table and _param_value_ is not `NULL` ifdef::cl_khr_dx9_media_sharing[] -The following errors may be returned if the {cl_khr_dx9_media_sharing_EXT} -extension is supported: - - * {CL_INVALID_DX9_MEDIA_SURFACE_KHR} if _param_name_ is - {CL_IMAGE_DX9_MEDIA_PLANE_KHR} and _image_ was not created by calling - {clCreateFromDX9MediaSurfaceKHR}. + * {CL_INVALID_DX9_MEDIA_SURFACE_KHR} + ** if the {cl_khr_dx9_media_sharing_EXT} extension is supported, + if _param_name_ is {CL_IMAGE_DX9_MEDIA_PLANE_KHR}, + and if _image_ was not created by calling {clCreateFromDX9MediaSurfaceKHR} endif::cl_khr_dx9_media_sharing[] - ifdef::cl_khr_d3d10_sharing[] -The following errors may be returned if the {cl_khr_d3d10_sharing_EXT} -extension is supported: - - * {CL_INVALID_D3D10_RESOURCE_KHR} if _param_name_ is - {CL_IMAGE_D3D10_SUBRESOURCE_KHR} and _image_ was not created by the - function {clCreateFromD3D10Texture2DKHR}, or - {clCreateFromD3D10Texture3DKHR}. + * {CL_INVALID_D3D10_RESOURCE_KHR} + ** if the {cl_khr_d3d10_sharing_EXT} extension is supported, + if _param_name_ is {CL_IMAGE_D3D10_SUBRESOURCE_KHR}, + and if _image_ was not created by the function {clCreateFromD3D10Texture2DKHR} or {clCreateFromD3D10Texture3DKHR} endif::cl_khr_d3d10_sharing[] - ifdef::cl_khr_d3d11_sharing[] -The following errors may be returned if the {cl_khr_d3d11_sharing_EXT} -extension is supported: - - * {CL_INVALID_D3D11_RESOURCE_KHR} if _param_name_ is - {CL_IMAGE_D3D11_SUBRESOURCE_KHR} and _image_ was not created by the - function {clCreateFromD3D11Texture2DKHR}, or - {clCreateFromD3D11Texture3DKHR}. + * {CL_INVALID_D3D11_RESOURCE_KHR} + ** if the {cl_khr_d3d11_sharing_EXT} extension is supported, + if _param_name_ is {CL_IMAGE_D3D11_SUBRESOURCE_KHR}, + and if _image_ was not created by the function {clCreateFromD3D11Texture2DKHR} or {clCreateFromD3D11Texture3DKHR} endif::cl_khr_d3d11_sharing[] - + * {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 -- @@ -5670,23 +5673,30 @@ endif::cl_ext_image_from_buffer[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ if not a valid context. - * {CL_INVALID_PROPERTY} if a property name in properties is not a supported - property name, if the value specified for a supported property name is not - valid, or if the same property name is specified more than once. - * {CL_INVALID_VALUE} if values specified in _flags_ are not valid. - * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} if values specified in _image_format_ - are not valid. - * {CL_INVALID_IMAGE_DESCRIPTOR} if values specified in _image_desc_ - are not valid. - * {CL_INVALID_VALUE} if _param_name_ is not valid, or if size in bytes - specified by _param_value_size_ is < size of return type as described in - the <> table and - _param_value_ is not `NULL`. - * {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_CONTEXT} + ** if _context_ if not a valid context + * {CL_INVALID_PROPERTY} + ** if a property name in _properties_ is not a supported property name + ** if the value specified for a supported property name is not valid + ** if the same property name is specified more than once + * {CL_INVALID_VALUE} + ** if values specified in _flags_ are not valid + * {CL_INVALID_IMAGE_FORMAT_DESCRIPTOR} + ** if values specified in _image_format_ are not valid + * {CL_INVALID_IMAGE_DESCRIPTOR} + ** if values specified in _image_desc_ are not valid + * {CL_INVALID_VALUE} + ** if _param_name_ is not valid + ** if size in bytes specified by _param_value_size_ is less than the size of + the return type specified in the + <> + table and _param_value_ is not `NULL` + * {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 -- endif::cl_ext_image_requirements_info[] From c02951a4fa04d221482087047eb8717a1e77fb8b Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 15 Sep 2025 13:22:51 -0700 Subject: [PATCH 2/2] minor wording improvement --- api/opencl_platform_layer.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 762bd5d8..cfece0e8 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -367,7 +367,7 @@ errors footnote:[{fn-error-precedence}]. ** if _platform_ is not a valid platform * {CL_INVALID_VALUE} ** if _param_name_ is not one of the supported values - ** if the size in bytes specified by _param_value_size_ is less than size of + ** if the size in bytes specified by _param_value_size_ is less than the size of the return type specified in the <> table and _param_value_ is not `NULL` * {CL_OUT_OF_HOST_MEMORY} @@ -2274,7 +2274,7 @@ Otherwise, it returns one of the following errors: ** if _device_ is not a valid device * {CL_INVALID_VALUE} ** if _param_name_ is not one of the supported values - ** if the size in bytes specified by _param_value_size_ is less than size of + ** if the size in bytes specified by _param_value_size_ is less than the size of the return type specified in the <> table and _param_value_ is not `NULL` * {CL_OUT_OF_RESOURCES} @@ -3776,7 +3776,7 @@ Otherwise, it returns one of the following errors: ** if _context_ is not a valid context * {CL_INVALID_VALUE} ** if _param_name_ is not one of the supported values - ** if the size in bytes specified by _param_value_size_ is less than size of + ** if the size in bytes specified by _param_value_size_ is less than the size of the return type specified in the <> table and _param_value_ is not `NULL` * {CL_OUT_OF_RESOURCES}