From 0e71e265373ad58c623a357010b3a33f54baf789 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 1 Jun 2025 17:39:19 -0700 Subject: [PATCH 01/22] error code consistency for platforms --- api/opencl_platform_layer.asciidoc | 54 ++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 18 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index dc418c2eb..9253a9653 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -42,13 +42,16 @@ endif::cl_khr_icd[] Otherwise, it returns one of the following errors: ifdef::cl_khr_icd[] - * {CL_PLATFORM_NOT_FOUND_KHR} if the {cl_khr_icd_EXT} extension is - supported and zero platforms are available. + * {CL_PLATFORM_NOT_FOUND_KHR} + ** if the {cl_khr_icd_EXT} extension is supported and zero platforms are + available endif::cl_khr_icd[] - * {CL_INVALID_VALUE} if _num_entries_ is equal to zero and _platforms_ is - not `NULL` or if both _num_platforms_ and _platforms_ are `NULL`. - * {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 _num_entries_ is equal to zero and _platforms_ is not `NULL` + ** if both _num_platforms_ and _platforms_ are `NULL` + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- ifdef::cl_khr_icd[] @@ -80,9 +83,14 @@ include::{generated}/api/version-notes/clIcdGetPlatformIDsKHR.asciidoc[] successfully and there are a non zero number of platforms available. Otherwise, it returns one of the following errors: - * {CL_PLATFORM_NOT_FOUND_KHR} if zero platforms are available. - * {CL_INVALID_VALUE} if _num_entries_ is equal to zero and _platforms_ is - not `NULL` or if both _num_platforms_ and _platforms_ are `NULL`. + * {CL_PLATFORM_NOT_FOUND_KHR} + ** if zero platforms are available + * {CL_INVALID_VALUE} + ** if _num_entries_ is equal to zero and _platforms_ is not `NULL` + ** if both _num_platforms_ and _platforms_ are `NULL` + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- [open,refpage='clIcdGetFunctionAddressForPlatformKHR',desc='Query API entry points for a platform',type='protos'] @@ -116,9 +124,17 @@ include::{generated}/api/version-notes/clIcdSetPlatformDispatchDataKHR.asciidoc[ * _dispatch_data_ is the value to set the `dispatch_data` field of the structure to +// refError + {clIcdSetPlatformDispatchDataKHR} returns {CL_SUCCESS} if the function is executed successfully. -It returns {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. +Otherwise, it returns one of the following errors: + + * {CL_INVALID_PLATFORM} + ** if _platform_ is not a valid platform. + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- endif::cl_khr_icd[] @@ -347,14 +363,16 @@ successfully. Otherwise, it returns one of the following errors footnote:[{fn-error-precedence}]. - * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. - * {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 - the return type specified in the - <> table - and _param_value_ is not `NULL`. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + * {CL_INVALID_PLATFORM} + ** 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 + the return type specified in the <> table and _param_value_ is not `NULL` + * {CL_OUT_OF_HOST_MEMORY} + ** if there is a failure to allocate resources required by the OpenCL + implementation on the host -- From 3d8406024d0acf3cc832f1c91d6ccad2f54227a4 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 1 Jun 2025 17:53:53 -0700 Subject: [PATCH 02/22] error consistency for devices --- api/opencl_platform_layer.asciidoc | 245 ++++++++++++++++++----------- 1 file changed, 150 insertions(+), 95 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 9253a9653..be39821a7 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -471,16 +471,21 @@ include::{generated}/api/version-notes/CL_DEVICE_TYPE_ALL.asciidoc[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. - * {CL_INVALID_DEVICE_TYPE} if _device_type_ is not a valid value. - * {CL_INVALID_VALUE} if _num_entries_ is equal to zero and _devices_ is not - `NULL` or if both _num_devices_ and _devices_ are `NULL`. - * {CL_DEVICE_NOT_FOUND} if no OpenCL devices that matched _device_type_ were - found. - * {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_PLATFORM} + ** if _platform_ is not a valid platform + * {CL_INVALID_DEVICE_TYPE} + ** if _device_type_ is not a valid value + * {CL_INVALID_VALUE} + ** if _num_entries_ is equal to zero and _devices_ is not `NULL` + ** if both _num_devices_ and _devices_ are `NULL` + * {CL_DEVICE_NOT_FOUND} + ** if no OpenCL devices that matched _device_type_ were found + * {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 application can query specific capabilities of the OpenCL device(s) returned by {clGetDeviceIDs}. @@ -2244,16 +2249,19 @@ endif::cl_khr_device_uuid[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_DEVICE} if _device_ is not a valid device. - * {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 - 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. + * {CL_INVALID_DEVICE} + ** 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 + 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 -- ifdef::cl_khr_integer_dot_product[] @@ -2342,14 +2350,20 @@ the same timebase. _host_timestamp_ if provided. Otherwise, it returns one of the following errors: - * {CL_INVALID_DEVICE} if _device_ is not a valid device. - * {CL_INVALID_OPERATION} if the platform associated with _device_ does not - support device and host timer synchronization. - * {CL_INVALID_VALUE} if _host_timestamp_ or _device_timestamp_ is `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_DEVICE} + ** if _device_ is not a valid device + * {CL_INVALID_OPERATION} + ** if the platform associated with _device_ does not support device and host + timer synchronization + * {CL_INVALID_VALUE} + ** if _host_timestamp_ is `NULL` + ** if _device_timestamp_ is `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 -- [open,refpage='clGetHostTimer',desc='Query the host clock',type='protos'] @@ -2383,17 +2397,21 @@ the same timebase. _host_timestamp_ if provided. Otherwise, it returns one of the following errors: - * {CL_INVALID_DEVICE} if _device_ is not a valid device. - * {CL_INVALID_OPERATION} if the platform associated with _device_ does not - support device and host timer synchronization. - * {CL_INVALID_VALUE} if _host_timestamp_ is `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_DEVICE} + ** if _device_ is not a valid device. + * {CL_INVALID_OPERATION} + ** if the platform associated with _device_ does not support device and host + timer synchronization. + * {CL_INVALID_VALUE} + ** if _host_timestamp_ is `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 -- - ifdef::cl_khr_dx9_media_sharing[] === Sharing DirectX9 Media Surfaces With OpenCL Images @@ -2492,20 +2510,26 @@ include::{generated}/api/version-notes/CL_ALL_DEVICES_FOR_DX9_MEDIA_ADAPTER_KHR. is executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. - * {CL_INVALID_VALUE} if _num_media_adapters_ is zero or if - _media_adapters_type_ is `NULL` or if _media_adapters_ is `NULL`. - * {CL_INVALID_VALUE} if any of the entries in _media_adapters_type_ or - _media_adapters_ is not a valid value. - * {CL_INVALID_VALUE} if _media_adapter_set_ is not a valid value. - * {CL_INVALID_VALUE} if _num_entries_ is equal to zero and _devices_ is - not `NULL` or if both _num_devices_ and _devices_ are `NULL`. - * {CL_DEVICE_NOT_FOUND} if no OpenCL devices that correspond to adapters - specified in _media_adapters_ and _media_adapters_type_ were found. - * {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_PLATFORM} + ** if _platform_ is not a valid platform + * {CL_INVALID_VALUE} + ** if _num_media_adapters_ is zero + ** if _media_adapters_type_ is `NULL` + ** if _media_adapters_ is `NULL` + ** if any of the entries in _media_adapters_type_ is not a valid value + ** if any of the entries in _media_adapters_ are not valid + ** if _media_adapter_set_ is not a valid value + ** if _num_entries_ is equal to zero and _devices_ is not `NULL` + ** if both _num_devices_ and _devices_ are `NULL` + * {CL_DEVICE_NOT_FOUND} + ** if no OpenCL devices that correspond to adapters specified in + _media_adapters_ and _media_adapters_type_ were found + * {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_khr_dx9_media_sharing[] @@ -2604,13 +2628,22 @@ include::{generated}/api/version-notes/CL_ALL_DEVICES_FOR_D3D10_KHR.asciidoc[] executed successfully. Otherwise it may return - * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. - * {CL_INVALID_VALUE} if _d3d_device_source_ is not a valid value, - _d3d_device_set_ is not a valid value, _num_entries_ is equal to zero - and _devices_ is not `NULL`, or if both _num_devices_ and _devices_ are - `NULL`. - * {CL_DEVICE_NOT_FOUND} if no OpenCL devices that correspond to - _d3d_object_ were found. + * {CL_INVALID_PLATFORM} + ** if _platform_ is not a valid platform + * {CL_INVALID_VALUE} + ** if _d3d_device_source_ is not a valid value + ** if _d3d_object_ is not valid + ** if _d3d_device_set_ is not a valid value + ** if _num_entries_ is equal to zero and _devices_ is not `NULL` + ** if both _num_devices_ and _devices_ are `NULL` + * {CL_DEVICE_NOT_FOUND} + ** if no OpenCL devices that correspond to _d3d_object_ were found. + * {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_khr_d3d10_sharing[] @@ -2709,13 +2742,22 @@ include::{generated}/api/version-notes/CL_ALL_DEVICES_FOR_D3D11_KHR.asciidoc[] executed successfully. Otherwise it may return - * {CL_INVALID_PLATFORM} if _platform_ is not a valid platform. - * {CL_INVALID_VALUE} if _d3d_device_source_ is not a valid value, - _d3d_device_set_ is not a valid value, _num_entries_ is equal to zero - and _devices_ is not `NULL`, or if both _num_devices_ and _devices_ are - `NULL`. - * {CL_DEVICE_NOT_FOUND} if no OpenCL devices that correspond to - _d3d_object_ were found. + * {CL_INVALID_PLATFORM} + ** if _platform_ is not a valid platform + * {CL_INVALID_VALUE} + ** if _d3d_device_source_ is not a valid value + ** if _d3d_object_ is not valid + ** if _d3d_device_set_ is not a valid value + ** if _num_entries_ is equal to zero and _devices_ is not `NULL` + ** if both _num_devices_ and _devices_ are `NULL` + * {CL_DEVICE_NOT_FOUND} + ** if no OpenCL devices that correspond to _d3d_object_ were found. + * {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_khr_d3d11_sharing[] @@ -2838,26 +2880,33 @@ successfully. Otherwise, it returns a `NULL` value with the following error values returned in _errcode_ret_: - * {CL_INVALID_DEVICE} if _in_device_ is not a valid device. - * {CL_INVALID_VALUE} if values specified in _properties_ are not valid or if - values specified in _properties_ are valid but not supported by the - device. - * {CL_INVALID_VALUE} if _out_devices_ is not `NULL` and _num_devices_ is - less than the number of sub-devices created by the partition scheme. - * {CL_DEVICE_PARTITION_FAILED} if the partition name is supported by the - implementation but in_device could not be further partitioned. - * {CL_INVALID_DEVICE_PARTITION_COUNT} if the partition name specified in - _properties_ is {CL_DEVICE_PARTITION_BY_COUNTS} and the number of - sub-devices requested exceeds {CL_DEVICE_PARTITION_MAX_SUB_DEVICES} or the - total number of compute units requested exceeds - {CL_DEVICE_MAX_COMPUTE_UNITS} for _in_device_, or the number of - compute units requested for one or more sub-devices is less than zero or - the number of sub-devices requested exceeds - {CL_DEVICE_MAX_COMPUTE_UNITS} for _in_device_. - * {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_DEVICE} + ** if _in_device_ is not a valid device + * {CL_INVALID_VALUE} + ** if values specified in _properties_ are not valid + ** if values specified in _properties_ are valid but not are supported by + _in_device_ + ** if _out_devices_ is not `NULL` and _num_devices_ is less than the number + of sub-devices created by the partition scheme + * {CL_DEVICE_PARTITION_FAILED} + ** if the partition name is supported by the implementation but in_device + could not be further partitioned + * {CL_INVALID_DEVICE_PARTITION_COUNT} + ** if the partition name specified in _properties_ is + {CL_DEVICE_PARTITION_BY_COUNTS} and the number of sub-devices requested + exceeds {CL_DEVICE_PARTITION_MAX_SUB_DEVICES} + ** if the total number of compute units requested exceeds + {CL_DEVICE_MAX_COMPUTE_UNITS} for _in_device_ + ** if the number of compute units requested for one or more sub-devices is + less than zero + ** if the number of sub-devices requested for one or more sub-devices + exceeds {CL_DEVICE_MAX_COMPUTE_UNITS} for _in_device_ + * {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 A few examples that describe how to specify partition properties in _properties_ argument to {clCreateSubDevices} are given below: @@ -2913,11 +2962,14 @@ If _device_ is a root level device i.e. a {cl_device_id_TYPE} returned by or the device is a root-level device. Otherwise, it returns one of the following errors: - * {CL_INVALID_DEVICE} if _device_ is not a valid device. - * {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_DEVICE} + ** if _device_ is not a valid device + * {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='clReleaseDevice',desc='Release an OpenCL device',type='protos',xrefs='clRetainDevice'] @@ -2940,11 +2992,14 @@ If _device_ is a root level device i.e. a {cl_device_id_TYPE} returned by successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_DEVICE} if _device_ is not a valid device. - * {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_DEVICE} + ** if _device_ is not a valid device. + * {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 After the _device_ reference count becomes zero and all the objects attached to _device_ (such as command-queues) are released, the _device_ object is From 377d76382b06c6a3b8453a2faca1f6a893a89eaf Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 1 Jun 2025 18:13:59 -0700 Subject: [PATCH 03/22] error consistency for contexts --- api/opencl_platform_layer.asciidoc | 385 ++++++++++++++++------------- 1 file changed, 210 insertions(+), 175 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index be39821a7..b6da6ab92 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -3242,110 +3242,118 @@ to {CL_SUCCESS} if the context is created successfully. Otherwise, it returns a `NULL` value with the following error values returned in _errcode_ret_: - * {CL_INVALID_PLATFORM} if no platform is specified in _properties_ and no - platform could be selected, or if the platform specified in _properties_ is - not a valid platform. - * {CL_INVALID_PROPERTY} if a context 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. - This error code is <> version 1.1. - * {CL_INVALID_VALUE} if _devices_ is `NULL`. - * {CL_INVALID_VALUE} if _num_devices_ is equal to zero. - * {CL_INVALID_VALUE} if _pfn_notify_ is `NULL` but _user_data_ is not - `NULL`. - * {CL_INVALID_DEVICE} if any device in _devices_ is not a valid device. - * {CL_DEVICE_NOT_AVAILABLE} if a device in _devices_ is currently not - available even though the device was returned by {clGetDeviceIDs}. - * {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_PLATFORM} + ** if no platform is specified in _properties_ and no platform could be + selected + ** if the platform specified in _properties_ is not a valid platform + * {CL_INVALID_PROPERTY} + ** if a context 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 _devices_ is `NULL` + ** if _num_devices_ is equal to zero + ** if _pfn_notify_ is `NULL` and _user_data_ is not `NULL` + * {CL_INVALID_DEVICE} + ** if any device in _devices_ is not a valid device + * {CL_DEVICE_NOT_AVAILABLE} + ** if a device in _devices_ is currently not available + * {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 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_ADAPTER_KHR} if any of the values of the - properties {CL_CONTEXT_ADAPTER_D3D9_KHR}, + * {CL_INVALID_DX9_MEDIA_ADAPTER_KHR} + ** if any of the values of the properties {CL_CONTEXT_ADAPTER_D3D9_KHR}, {CL_CONTEXT_ADAPTER_D3D9EX_KHR} or {CL_CONTEXT_ADAPTER_DXVA_KHR} is non-`NULL` and does not specify a valid media adapter with which the _cl_device_ids_ against which this context is to be created may - interoperate. + interoperate 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_DEVICE_KHR} if the value of the property - {CL_CONTEXT_D3D10_DEVICE_KHR} is non-`NULL` and does not specify a valid - Direct3D 10 device with which the _cl_device_ids_ against which this - context is to be created may interoperate. - * {CL_INVALID_OPERATION} if Direct3D 10 interoperability is specified by - setting {CL_INVALID_D3D10_DEVICE_KHR} to a non-`NULL` value, and - interoperability with another graphics API is also specified. + * {CL_INVALID_D3D10_DEVICE_KHR} + ** if the value of the property {CL_CONTEXT_D3D10_DEVICE_KHR} is non-`NULL` + and does not specify a valid Direct3D 10 device with which the + _cl_device_ids_ against which this context is to be created may + interoperate + * {CL_INVALID_OPERATION} + ** if Direct3D 10 interoperability is specified by setting + {CL_INVALID_D3D10_DEVICE_KHR} to a non-`NULL` value and interoperability + with another graphics API is also specified 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_DEVICE_KHR} if the value of the property - {CL_CONTEXT_D3D11_DEVICE_KHR} is non-`NULL` and does not specify a valid - Direct3D 11 device with which the _cl_device_ids_ against which this - context is to be created may interoperate. - * {CL_INVALID_OPERATION} if Direct3D 11 interoperability is specified by - setting {CL_INVALID_D3D11_DEVICE_KHR} to a non-`NULL` value, and - interoperability with another graphics API is also specified. + * {CL_INVALID_D3D11_DEVICE_KHR} + ** if the value of the property {CL_CONTEXT_D3D11_DEVICE_KHR} is non-`NULL` + and does not specify a valid Direct3D 11 device with which the + _cl_device_ids_ against which this context is to be created may + interoperate + * {CL_INVALID_OPERATION} + ** if Direct3D 11 interoperability is specified by setting + {CL_INVALID_D3D11_DEVICE_KHR} to a non-`NULL` value and interoperability + with another graphics API is also specified endif::cl_khr_d3d11_sharing[] ifdef::cl_khr_gl_sharing[] The following errors may be returned if the {cl_khr_gl_sharing_EXT} extension is supported: - * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} if a context was specified for - an OpenGL or OpenGL ES implementation using the EGL, GLX, or WGL binding - APIs, as <>; and any of the - following conditions hold: - ** The specified display and context properties do not identify a valid - OpenGL or OpenGL ES context. - ** The specified context does not support buffer and renderbuffer objects. - ** The specified context is not compatible with the OpenCL context being - created (for example, it exists in a physically distinct address space, - such as another hardware device; or it does not support sharing data - with OpenCL due to implementation restrictions). - * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} if a share group was specified - for a CGL-based OpenGL implementation by setting the property - {CL_CGL_SHAREGROUP_KHR}, and the specified share group does not identify - a valid CGL share group object. - * {CL_INVALID_OPERATION} if a context was specified as described above and - any of the following conditions hold: - ** A context or share group object was specified for one of CGL, EGL, GLX, - or WGL and the OpenGL implementation does not support that - window-system binding API. - ** More than one of the properties {CL_CGL_SHAREGROUP_KHR}, - {CL_EGL_DISPLAY_KHR}, {CL_GLX_DISPLAY_KHR}, and {CL_WGL_HDC_KHR} is set - to a non-default value. - ** Both of the properties {CL_CGL_SHAREGROUP_KHR} and {CL_GL_CONTEXT_KHR} - are set to non-default values. - ** Any of the devices specified in the _devices_ argument cannot support - OpenCL objects which share the data store of an OpenGL object. - * {CL_INVALID_PROPERTY} if both {CL_CONTEXT_INTEROP_USER_SYNC}, and any of - the properties defined by the {cl_khr_gl_sharing_EXT} extension are - defined in _properties_. + * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} + ** if a context was specified for an OpenGL or OpenGL ES implementation + using the EGL, GLX, or WGL binding APIs, as <>; and any of the following conditions hold: + *** The specified display and context properties do not identify a valid + OpenGL or OpenGL ES context. + *** The specified context does not support buffer and renderbuffer objects. + *** The specified context is not compatible with the OpenCL context being + created (for example, it exists in a physically distinct address space, + such as another hardware device; or it does not support sharing data with + OpenCL due to implementation restrictions). + * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} + ** if a share group was specified for a CGL-based OpenGL implementation by + setting the property {CL_CGL_SHAREGROUP_KHR}, and the specified share group + does not identify a valid CGL share group object + * {CL_INVALID_OPERATION} + ** if a context was specified as described above and any of the following + conditions hold: + *** A context or share group object was specified for one of CGL, EGL, GLX, + or WGL and the OpenGL implementation does not support that window-system + binding API. + *** More than one of the properties {CL_CGL_SHAREGROUP_KHR}, + {CL_EGL_DISPLAY_KHR}, {CL_GLX_DISPLAY_KHR}, and {CL_WGL_HDC_KHR} is set to + a non-default value. + *** Both of the properties {CL_CGL_SHAREGROUP_KHR} and {CL_GL_CONTEXT_KHR} + are set to non-default values. + *** Any of the devices specified in the _devices_ argument cannot support + OpenCL objects which share the data store of an OpenGL object. + * {CL_INVALID_PROPERTY} + * if both {CL_CONTEXT_INTEROP_USER_SYNC}, and any of the properties defined + by the {cl_khr_gl_sharing_EXT} extension are defined in _properties_ endif::cl_khr_gl_sharing[] ifdef::cl_khr_terminate_context[] The following errors may be returned if the {cl_khr_terminate_context_EXT} extension is supported: - * {CL_INVALID_PROPERTY} if the {cl_khr_terminate_context_EXT} extension is - supported and {CL_CONTEXT_TERMINATE_KHR} is set to {CL_TRUE} in - _properties_, but not all of the devices associated with the context - support the ability to support context termination (i.e. - {CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR} is set for - {CL_DEVICE_TERMINATE_CAPABILITY_KHR}). + * {CL_INVALID_PROPERTY} + ** if the {cl_khr_terminate_context_EXT} extension is supported and + {CL_CONTEXT_TERMINATE_KHR} is set to {CL_TRUE} in _properties_, but not all + of the devices associated with the context support the ability to support + context termination (i.e. {CL_DEVICE_TERMINATE_CAPABILITY_CONTEXT_KHR} is + set for {CL_DEVICE_TERMINATE_CAPABILITY_KHR}) endif::cl_khr_terminate_context[] [NOTE] @@ -3355,8 +3363,8 @@ command-queues that use this device(s) have been created and commands have been queued to command-queues. In this case the behavior of OpenCL API calls that use this context (and command-queues) are considered to be implementation-defined. -The user callback function, if specified, when the context is created can be -used to record appropriate information in the _errinfo_, _private_info_ +The user callback function, if specified when the context is created, can be +used to record appropriate information in the _errinfo_ and _private_info_ arguments passed to the callback function when the device becomes unavailable. ==== @@ -3397,100 +3405,109 @@ is set to {CL_SUCCESS} if the context is created successfully. Otherwise, it returns a `NULL` value with the following error values returned in _errcode_ret_: - * {CL_INVALID_PLATFORM} if no platform is specified in _properties_ and no - platform could be selected, or if the platform specified in _properties_ is - not a valid platform. - * {CL_INVALID_PROPERTY} if a context 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. - This error code is <> version 1.1. - * {CL_INVALID_VALUE} if _pfn_notify_ is `NULL` but _user_data_ is not - `NULL`. - * {CL_INVALID_DEVICE_TYPE} if _device_type_ is not a valid value. - * {CL_DEVICE_NOT_AVAILABLE} if no devices that match _device_type_ and - property values specified in _properties_ are currently available. - * {CL_DEVICE_NOT_FOUND} if no devices that match _device_type_ and property - values specified in _properties_ were found. - * {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_PLATFORM} + ** if no platform is specified in _properties_ and no platform could be + selected, + ** if the platform specified in _properties_ is not a valid platform + * {CL_INVALID_PROPERTY} + ** if a context 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 _pfn_notify_ is `NULL` and _user_data_ is not `NULL` + * {CL_INVALID_DEVICE_TYPE} + ** if _device_type_ is not a valid value + * {CL_DEVICE_NOT_AVAILABLE} + ** if no devices that match _device_type_ and property values specified in + _properties_ are currently available + * {CL_DEVICE_NOT_FOUND} + ** if no devices that match _device_type_ and property values specified in + _properties_ were found + * {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 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_ADAPTER_KHR} if any of the values of the - properties {CL_CONTEXT_ADAPTER_D3D9_KHR}, + * {CL_INVALID_DX9_MEDIA_ADAPTER_KHR} + ** if any of the values of the properties {CL_CONTEXT_ADAPTER_D3D9_KHR}, {CL_CONTEXT_ADAPTER_D3D9EX_KHR} or {CL_CONTEXT_ADAPTER_DXVA_KHR} is non-`NULL` and does not specify a valid media adapter with which the _cl_device_ids_ against which this context is to be created may - interoperate. + interoperate 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_DEVICE_KHR} if the value of the property - {CL_CONTEXT_D3D10_DEVICE_KHR} is non-`NULL` and does not specify a valid - Direct3D 10 device with which the _cl_device_ids_ against which this - context is to be created may interoperate. - * {CL_INVALID_OPERATION} if Direct3D 10 interoperability is specified by - setting {CL_INVALID_D3D10_DEVICE_KHR} to a non-`NULL` value, and - interoperability with another graphics API is also specified. + * {CL_INVALID_D3D10_DEVICE_KHR} + ** if the value of the property {CL_CONTEXT_D3D10_DEVICE_KHR} is non-`NULL` + and does not specify a valid Direct3D 10 device with which the + _cl_device_ids_ against which this context is to be created may + interoperate. + * {CL_INVALID_OPERATION} + ** if Direct3D 10 interoperability is specified by setting + {CL_INVALID_D3D10_DEVICE_KHR} to a non-`NULL` value and interoperability + with another graphics API is also specified 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_DEVICE_KHR} if the value of the property - {CL_CONTEXT_D3D11_DEVICE_KHR} is non-`NULL` and does not specify a valid - Direct3D 11 device with which the _cl_device_ids_ against which this - context is to be created may interoperate. - * {CL_INVALID_OPERATION} if Direct3D 11 interoperability is specified by - setting {CL_INVALID_D3D11_DEVICE_KHR} to a non-`NULL` value, and - interoperability with another graphics API is also specified. + * {CL_INVALID_D3D11_DEVICE_KHR} + ** if the value of the property {CL_CONTEXT_D3D11_DEVICE_KHR} is non-`NULL` + and does not specify a valid Direct3D 11 device with which the + _cl_device_ids_ against which this context is to be created may + interoperate. + * {CL_INVALID_OPERATION} + ** if Direct3D 11 interoperability is specified by setting + {CL_INVALID_D3D11_DEVICE_KHR} to a non-`NULL` value and interoperability + with another graphics API is also specified endif::cl_khr_d3d11_sharing[] ifdef::cl_khr_gl_sharing[] The following errors may be returned if the {cl_khr_gl_sharing_EXT} extension is supported: - * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} if a context was specified for - an OpenGL or OpenGL ES implementation using the EGL, GLX, or WGL binding - APIs, as <>; and - any of the following conditions hold: - ** The specified display and context properties do not identify a valid - OpenGL or OpenGL ES context. - ** The specified context does not support buffer and renderbuffer objects. - ** The specified context is not compatible with the OpenCL context being - created (for example, it exists in a physically distinct address space, - such as another hardware device; or it does not support sharing data - with OpenCL due to implementation restrictions). - * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} if a share group was specified - for a CGL-based OpenGL implementation by setting the property - {CL_CGL_SHAREGROUP_KHR}, and the specified share group does not identify - a valid CGL share group object. - * {CL_INVALID_OPERATION} if a context was specified as described above and - any of the following conditions hold: - ** A context or share group object was specified for one of CGL, EGL, GLX, - or WGL and the OpenGL implementation does not support that - window-system binding API. - ** More than one of the properties {CL_CGL_SHAREGROUP_KHR}, - {CL_EGL_DISPLAY_KHR}, {CL_GLX_DISPLAY_KHR}, and {CL_WGL_HDC_KHR} is set - to a non-default value. - ** Both of the properties {CL_CGL_SHAREGROUP_KHR} and {CL_GL_CONTEXT_KHR} - are set to non-default values. - ** Any of the devices specified in the _devices_ argument cannot support - OpenCL objects which share the data store of an OpenGL object. - * {CL_INVALID_PROPERTY} if both {CL_CONTEXT_INTEROP_USER_SYNC}, and any of - the properties defined by the {cl_khr_gl_sharing_EXT} extension are - defined in _properties_. + * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} + ** if a context was specified for an OpenGL or OpenGL ES implementation + using the EGL, GLX, or WGL binding APIs, as <>; and any of the following conditions hold: + *** The specified display and context properties do not identify a valid + OpenGL or OpenGL ES context. + *** The specified context does not support buffer and renderbuffer objects. + *** The specified context is not compatible with the OpenCL context being + created (for example, it exists in a physically distinct address space, + such as another hardware device; or it does not support sharing data with + OpenCL due to implementation restrictions). + * {CL_INVALID_GL_SHAREGROUP_REFERENCE_KHR} + ** if a share group was specified for a CGL-based OpenGL implementation by + setting the property {CL_CGL_SHAREGROUP_KHR}, and the specified share group + does not identify a valid CGL share group object + * {CL_INVALID_OPERATION} + ** if a context was specified as described above and any of the following + conditions hold: + *** A context or share group object was specified for one of CGL, EGL, GLX, + or WGL and the OpenGL implementation does not support that window-system + binding API. + *** More than one of the properties {CL_CGL_SHAREGROUP_KHR}, + {CL_EGL_DISPLAY_KHR}, {CL_GLX_DISPLAY_KHR}, and {CL_WGL_HDC_KHR} is set to + a non-default value. + *** Both of the properties {CL_CGL_SHAREGROUP_KHR} and {CL_GL_CONTEXT_KHR} + are set to non-default values. + *** Any of the devices specified in the _devices_ argument cannot support + OpenCL objects which share the data store of an OpenGL object. + * {CL_INVALID_PROPERTY} + ** if both {CL_CONTEXT_INTEROP_USER_SYNC}, and any of the properties defined + by the {cl_khr_gl_sharing_EXT} extension are defined in _properties_ endif::cl_khr_gl_sharing[] - -- [open,refpage='clRetainContext',desc='Retain an OpenCL context',type='protos',xrefs='clCreateContext clReleaseContext'] @@ -3518,11 +3535,14 @@ the problem of a context being used by a library no longer being valid. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid OpenCL context. - * {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 OpenCL context + * {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='clReleaseContext',desc='Release an OpenCL context',type='protos',xrefs='clCreateContext clRetainContext'] @@ -3549,11 +3569,14 @@ the object or by calling {clRetainContext} causes undefined behavior. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid OpenCL context. - * {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 OpenCL context + * {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 -- ifdef::cl_khr_terminate_context[] @@ -3607,14 +3630,19 @@ When a context is terminated: successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid OpenCL context. - * {CL_CONTEXT_TERMINATED_KHR} if _context_ has already been terminated. - * {CL_INVALID_OPERATION} if _context_ was not created with - {CL_CONTEXT_TERMINATE_KHR} set to {CL_TRUE}. - * {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 OpenCL context + * {CL_CONTEXT_TERMINATED_KHR} + ** if _context_ has already been terminated + * {CL_INVALID_OPERATION} + ** if _context_ was not created with {CL_CONTEXT_TERMINATE_KHR} set to + {CL_TRUE} + * {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 An implementation that supports this extension must be able to terminate commands currently executing on devices or queued across all command-queues @@ -3721,16 +3749,19 @@ endif::cl_khr_d3d11_sharing[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {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 - 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. + * {CL_INVALID_CONTEXT} + ** 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 + 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 -- [open,refpage='clSetContextDestructorCallback',desc='Registers a destructor callback function with a context.',type='protos'] @@ -3773,11 +3804,15 @@ context callback function when _context_ was created. executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {CL_INVALID_VALUE} if _pfn_notify_ is `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 _pfn_notify_ is `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 -- From 06fc692f7765ce12e0e640e5ad536a04bc3e62ef Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 22 Jun 2025 12:44:14 -0700 Subject: [PATCH 04/22] error consistency for command-queues --- api/opencl_runtime_layer.asciidoc | 169 +++++++++++++++++------------- 1 file changed, 99 insertions(+), 70 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 3ccba72bd..577bed41b 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -177,26 +177,32 @@ successfully. Otherwise, it returns a `NULL` value with one of the following error values returned in _errcode_ret_: - * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {CL_INVALID_DEVICE} if _device_ is not a valid device or is not - associated with _context_. - * {CL_INVALID_VALUE} if values specified in _properties_ are not valid. - * {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are - valid but are not supported by the device. + * {CL_INVALID_CONTEXT} + ** if _context_ is not a valid context + * {CL_INVALID_DEVICE} + ** if _device_ is not a valid device + ** if _device_ is not associated with _context_ + * {CL_INVALID_VALUE} + ** if values specified in _properties_ are not valid + * {CL_INVALID_QUEUE_PROPERTIES} + ** if values specified in _properties_ are valid but are not supported by + _device_ ifdef::cl_khr_priority_hints[] - * {CL_INVALID_QUEUE_PROPERTIES} if the {cl_khr_priority_hints_EXT} - extension is supported, the {CL_QUEUE_PRIORITY_KHR} property is - specified, and the queue is a {CL_QUEUE_ON_DEVICE}. + ** if the {cl_khr_priority_hints_EXT} extension is supported, the + {CL_QUEUE_PRIORITY_KHR} property is specified, and the queue is a + {CL_QUEUE_ON_DEVICE} endif::cl_khr_priority_hints[] ifdef::cl_khr_throttle_hints[] - * {CL_INVALID_QUEUE_PROPERTIES} if the {cl_khr_throttle_hints_EXT} - extension is supported, the {CL_QUEUE_THROTTLE_KHR} property is - specified, and the queue is a {CL_QUEUE_ON_DEVICE}. + ** if the {cl_khr_throttle_hints_EXT} extension is supported, the + {CL_QUEUE_THROTTLE_KHR} property is specified, and the queue is a + {CL_QUEUE_ON_DEVICE} endif::cl_khr_throttle_hints[] - * {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_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='clCreateCommandQueue',desc='Create a host command-queue on a specific device.',type='protos'] @@ -247,16 +253,22 @@ is set to {CL_SUCCESS} if the command-queue is created successfully. Otherwise, it returns a `NULL` value with one of the following error values returned in _errcode_ret_: - * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {CL_INVALID_DEVICE} if _device_ is not a valid device or is not associated - with _context_. - * {CL_INVALID_VALUE} if values specified in _properties_ are not valid. - * {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are - valid but are not supported by the device. - * {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_DEVICE} + ** if _device_ is not a valid device + ** if _device_ is not associated with _context_ + * {CL_INVALID_VALUE} + ** if values specified in _properties_ are not valid + * {CL_INVALID_QUEUE_PROPERTIES} + ** if values specified in _properties_ are valid but are not supported by + _device_ + * {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='clSetDefaultDeviceCommandQueue',desc='Replaces the default command-queue on the device.',type='protos'] @@ -281,16 +293,21 @@ command-queue created with {clCreateCommandQueueWithProperties} and the executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_CONTEXT} if _context_ is not a valid context. - * {CL_INVALID_DEVICE} if _device_ is not a valid device or is not associated - with _context_. - * {CL_INVALID_OPERATION} if _device_ does not support a replaceable default on-device queue. - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid command-queue - for _device_. - * {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_DEVICE} + ** if _device_ is not a valid device + ** if _device_ is not associated with _context_ + * {CL_INVALID_OPERATION} + ** if _device_ does not support a replaceable default on-device queue + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid command-queue for _device_ + * {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='clRetainCommandQueue',desc='Increments the command_queue reference count.',type='protos'] @@ -320,12 +337,14 @@ being valid. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid - command-queue. - * {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 command-queue + * {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='clReleaseCommandQueue',desc='Decrements the command_queue reference count.',type='protos'] @@ -354,12 +373,14 @@ the object or by calling {clRetainCommandQueue} causes undefined behavior. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid - command-queue. - * {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 command-queue + * {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='clGetCommandQueueInfo',desc='Query information about a command-queue.',type='protos'] @@ -460,18 +481,21 @@ include::{generated}/api/version-notes/CL_QUEUE_DEVICE_DEFAULT.asciidoc[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid - command-queue, or if _command_queue_ is not a valid command-queue - for _param_name_. - * {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_COMMAND_QUEUE} + ** if _command_queue_ is not a valid command-queue + ** if _command_queue_ is not a valid command-queue for _param_name_ + * {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 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` + * {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='clSetCommandQueueProperty',desc='Enable or disable properties of a command-queue.',type='protos'] @@ -508,19 +532,24 @@ OpenCL 1.0 devices. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid command-queue. - * {CL_INVALID_OPERATION} if no devices in the context associated with - _command_queue_ support modifying the properties of a command-queue. - * {CL_INVALID_VALUE} if values specified in _properties_ are not valid. - * {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are - valid but are not supported by the device. - * {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 command-queue + * {CL_INVALID_OPERATION} + ** if no devices in the context associated with _command_queue_ support + modifying the properties of a command-queue + * {CL_INVALID_VALUE} + ** if values specified in _properties_ are not valid + * {CL_INVALID_QUEUE_PROPERTIES} + ** if values specified in _properties_ are valid but are not supported by + the device associated with _command_queue_ + * {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 -- - == Buffer Objects A _buffer_ object stores a one-dimensional collection of elements. From 582afd9eaff2aeaf78ce8023e77a5784578e2a8c Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Sun, 22 Jun 2025 22:51:07 -0700 Subject: [PATCH 05/22] error consistency for reading and writing buffers --- api/opencl_runtime_layer.asciidoc | 400 +++++++++++++++--------------- 1 file changed, 194 insertions(+), 206 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 577bed41b..6e890ce56 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -930,43 +930,38 @@ 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. + * {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 [NOTE] ==== @@ -1075,43 +1070,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_ 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 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'] @@ -1222,57 +1218,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_ 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 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] ==== @@ -1378,48 +1369,49 @@ 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 _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_ 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 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'] @@ -1514,63 +1506,59 @@ 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 _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_ 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 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 -- From f5cd8012bbfc5cbe4b6c200546eb2ce3eaeb8fcb Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 13:12:04 -0700 Subject: [PATCH 06/22] error consistency for filling buffers --- api/opencl_runtime_layer.asciidoc | 70 ++++++++++++++++++------------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 6e890ce56..873187e0f 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1074,7 +1074,7 @@ Otherwise, they return one of the following errors: ** 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. + ** 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} @@ -1095,7 +1095,7 @@ Otherwise, they return one of the following errors: 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_. + ** 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} ** if {clEnqueueWriteBuffer} is called on _buffer_ which has been created with {CL_MEM_HOST_READ_ONLY} or {CL_MEM_HOST_NO_ACCESS} @@ -1372,7 +1372,8 @@ 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 + ** 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 @@ -1509,7 +1510,8 @@ 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 + ** 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 @@ -1629,35 +1631,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_ 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 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 -- From e1ecda4bca74ce2b19638565abe1a0698a2d518e Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 13:18:25 -0700 Subject: [PATCH 07/22] error consistency for mapping memory objects --- api/opencl_runtime_layer.asciidoc | 75 ++++++++++++++++--------------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 873187e0f..2c5317fac 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1737,50 +1737,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_ 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 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 9652eedc2668479978d1120b384b87e0064e4436 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 13:32:25 -0700 Subject: [PATCH 08/22] error consistency for reading and writing images --- api/opencl_runtime_layer.asciidoc | 109 +++++++++++++++--------------- 1 file changed, 56 insertions(+), 53 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 2c5317fac..0898172e8 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -3157,13 +3157,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 @@ -3715,56 +3720,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 buffer 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 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_ 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 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] ==== From dac471477bc17bdb50e7d410888c6993b47f60cb Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 14:16:18 -0700 Subject: [PATCH 09/22] error consistency for copying images --- api/opencl_runtime_layer.asciidoc | 95 ++++++++++++++++--------------- 1 file changed, 48 insertions(+), 47 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 0898172e8..70600835b 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1374,7 +1374,7 @@ Otherwise, it returns one of the following errors: * {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. + ** 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 @@ -1512,7 +1512,7 @@ Otherwise, it returns one of the following errors: * {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. + ** 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 @@ -3731,7 +3731,7 @@ Otherwise, it returns one of the following errors: ** 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 rules described in the argument description for _origin_ and _region_ + ** 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[] @@ -3901,54 +3901,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_ 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 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 -- From 0c7bc859cde5e3026efad045b5914711c21ed30f Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 14:19:44 -0700 Subject: [PATCH 10/22] error consistency for filling images --- api/opencl_runtime_layer.asciidoc | 70 ++++++++++++++++--------------- 1 file changed, 37 insertions(+), 33 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 70600835b..3e6edce0d 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -3726,7 +3726,7 @@ Otherwise, it returns one of the following errors: ** 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 buffer object + ** if _image_ is not a valid image object * {CL_INVALID_VALUE} ** if _origin_ is `NULL` ** if _region_ is `NULL` @@ -4038,42 +4038,46 @@ 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_ 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 data store associated with _image_ ifdef::cl_ext_immutable_memory_objects[] - * {CL_INVALID_OPERATION} if _image_ was created with {CL_MEM_IMMUTABLE_EXT}. + * {CL_INVALID_OPERATION} + ** 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 -- From ebfb99fd5696b69073705b26b91ed7b3e382a62d Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 14:35:33 -0700 Subject: [PATCH 11/22] error consistency for copying between images and buffers --- api/opencl_runtime_layer.asciidoc | 188 +++++++++++++++--------------- 1 file changed, 97 insertions(+), 91 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 3e6edce0d..d1df32469 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -954,6 +954,7 @@ endif::cl_ext_immutable_memory_objects[] 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 sub-buffer object * {CL_OUT_OF_RESOURCES} @@ -4068,8 +4069,9 @@ endif::cl_khr_mipmap_image[] _command_queue_ * {CL_MEM_OBJECT_ALLOCATION_FAILURE} ** if there is a failure to allocate memory for data store associated with _image_ -ifdef::cl_ext_immutable_memory_objects[] * {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[] ** if _image_ was created with {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] * {CL_OUT_OF_RESOURCES} @@ -4164,55 +4166,57 @@ argument value specified when _src_image_ 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_image_ 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_image_ is not a valid image object or - _dst_buffer_ is not a valid buffer object or if _src_image_ is a 1D - image buffer object created from _dst_buffer_. - * {CL_INVALID_VALUE} if _src_origin_ or _region_ is `NULL`. - * {CL_INVALID_VALUE} if the 1D, 2D or 3D rectangular region specified by - _src_origin_ and _src_origin_ + _region_ refers to a region outside - _src_image_, or if the region specified by _dst_offset_ and _dst_offset_ - + _dst_cb_ to a region outside _dst_buffer_. - * {CL_INVALID_VALUE} if values in _src_origin_ and _region_ do not follow - rules described in the argument description for _src_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_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_. - This error code is <> version 1.1. - * {CL_INVALID_IMAGE_SIZE} if image dimensions (image width, height, - specified or compute row and/or slice pitch) for _src_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_ 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_buffer_. - * {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_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 _src_image_ 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_image_ is not a valid image object + ** if _dst_buffer_ is not a valid buffer object + ** if _src_image_ is a 1D image buffer object created from _dst_buffer_ + * {CL_INVALID_VALUE} + ** if _src_origin_ is `NULL` + ** if _region_ is `NULL` + ** if the 1D, 2D or 3D rectangular region specified by _src_origin_ and _region_ is out of bounds of _src_image_ + ** if the region specified by _dst_offset_ and the computed _dst_cb_ is out of bounds of _dst_buffer_ + ** if values in _src_origin_ and _region_ do not follow the rules described in the argument description for _src_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_ is not a valid - level for _src_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_ endif::cl_khr_mipmap_image[] + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ 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 _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_INVALID_IMAGE_SIZE} + ** if the dimensions for _src_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_, 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 data store associated with _src_image_ + ** if there is a failure to allocate memory for data store associated with _dst_buffer_ + * {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_buffer_ was created with {CL_MEM_IMMUTABLE_EXT}. + ** 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 -- @@ -4299,55 +4303,57 @@ argument value specified when _src_buffer_ or _dst_image_ 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_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_buffer_ is not a valid buffer object or - _dst_image_ is not a valid image object or if _dst_image_ is a 1D image - buffer object created from _src_buffer_. - * {CL_INVALID_VALUE} if _dst_origin_ or _region_ is `NULL`. - * {CL_INVALID_VALUE} if the 1D, 2D or 3D rectangular region specified by - _dst_origin_ and _dst_origin_ + _region_ refer to a region outside - _dst_image_, or if the region specified by _src_offset_ and _src_offset_ - + _src_cb_ refer to a region outside _src_buffer_. - * {CL_INVALID_VALUE} if values in _dst_origin_ and _region_ do not follow - rules described in the argument description for _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_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_. - This error code is <> version 1.1. - * {CL_INVALID_IMAGE_SIZE} if image dimensions (image width, height, - specified or compute row and/or slice pitch) for _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 _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_buffer_ or _dst_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_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 _src_buffer_ 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_buffer_ is not a valid buffer object + ** if _dst_image_ is not a valid image object + ** if _dst_image_ is a 1D image buffer object created from _src_buffer_ + * {CL_INVALID_VALUE} + ** if _dst_origin_ is `NULL` + ** if _region_ is `NULL` + ** if the region specified by _src_offset_ and the computed _src_cb_ is out of bounds of _src_buffer_ + ** if the 1D, 2D or 3D rectangular region specified by _dst_origin_ and _region_ is out of bounds of _dst_image_ + ** if values in _dst_origin_ and _region_ do not follow rules described in the argument description for _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 _dst_origin_ is not a valid - level for _dst_image_, + * {CL_INVALID_MIP_LEVEL} + ** 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_ 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 _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_INVALID_IMAGE_SIZE} + ** if the dimensions for _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 _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_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for data store associated with _src_buffer_ + ** if there is a failure to allocate memory for data store associated with _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 -- From 1f4a7b4d9251ff528e05307e3430b55f62cb9307 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 14:43:33 -0700 Subject: [PATCH 12/22] error consistency for mapping images --- api/opencl_runtime_layer.asciidoc | 98 ++++++++++++++++--------------- 1 file changed, 50 insertions(+), 48 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index d1df32469..2aabbe24a 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -4449,60 +4449,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_ 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 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 From a42a21258e8527659eef299829dd18960df1453a Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 14:48:45 -0700 Subject: [PATCH 13/22] error consistency for getting image information --- api/opencl_runtime_layer.asciidoc | 58 +++++++++++++------------------ 1 file changed, 25 insertions(+), 33 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 2aabbe24a..16eec6c6e 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -4709,46 +4709,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 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 -- From 47a785fa7322ec42e86885c2bcd964f428d450b6 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 14:54:47 -0700 Subject: [PATCH 14/22] more error consistency for memory objects --- api/opencl_runtime_layer.asciidoc | 88 ++++++++++++++++++------------- 1 file changed, 52 insertions(+), 36 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 16eec6c6e..2f60d9070 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -486,7 +486,7 @@ Otherwise, it returns one of the following errors: ** if _command_queue_ is not a valid command-queue for _param_name_ * {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` @@ -4713,7 +4713,7 @@ Otherwise, it returns one of the following errors: ** 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 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` @@ -5647,23 +5647,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[] @@ -5852,12 +5859,14 @@ The _memobj_ reference count is incremented. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_MEM_OBJECT} if _memobj_ is not a valid memory object (buffer - or image 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. + * {CL_INVALID_MEM_OBJECT} + ** if _memobj_ is not a valid memory 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 {clCreateBuffer}, {clCreateBufferWithProperties}, {clCreateSubBuffer}, {clCreateImage}, {clCreateImageWithProperties}, {clCreateImage2D}, @@ -5881,11 +5890,14 @@ The _memobj_ reference count is decremented. successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_MEM_OBJECT} if _memobj_ is not a valid memory 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. + * {CL_INVALID_MEM_OBJECT} + ** if _memobj_ is not a valid memory 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 After the _memobj_ reference count becomes zero and commands queued for execution on a command-queue(s) that use _memobj_ have finished, the memory @@ -5936,12 +5948,16 @@ _memobj_ was created and used as the storage bits for the memory object. executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_MEM_OBJECT} if _memobj_ is not a valid memory object. - * {CL_INVALID_VALUE} if _pfn_notify_ is `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_MEM_OBJECT} + ** if _memobj_ is not a valid memory object + * {CL_INVALID_VALUE} + ** if _pfn_notify_ is `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 [[callback-functions]] [NOTE] From 58c403e1953a0d171461ee73948f561e7b72fdb3 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 15:00:52 -0700 Subject: [PATCH 15/22] error consistency for aquiring and releasing external mem objects --- api/opencl_runtime_layer.asciidoc | 94 ++++++++++++++++--------------- 1 file changed, 48 insertions(+), 46 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 2f60d9070..d33780db4 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -6077,31 +6077,32 @@ its completion event. is executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _num_mem_objects_ is zero and _mem_objects_ is not - a `NULL` value, or if _num_mem_objects_ is greater than 0 and - _mem_objects_ is `NULL`. - * {CL_INVALID_MEM_OBJECT} if any of the memory objects in _mem_objects_ is - not a valid OpenCL memory object created using an external memory - handle. * {CL_INVALID_COMMAND_QUEUE} - ** if _command_queue_ is not a valid command-queue, or - ** if device associated with _command_queue_ is not one of the devices - specified by {CL_MEM_DEVICE_HANDLE_LIST_KHR} at the time of creating - one or more of _mem_objects_, or - ** if one or more of _mem_objects_ belong to a context that does not - contain a device associated with _command_queue_. + ** if _command_queue_ is not a valid command-queue + ** if the device associated with _command_queue_ is not one of the devices + specified by {CL_MEM_DEVICE_HANDLE_LIST_KHR} at the time of creating + one or more of _mem_objects_ + ** if one or more of _mem_objects_ belong to a context that does not + contain a device associated with _command_queue_ + * {CL_INVALID_VALUE} + ** if _num_mem_objects_ is zero and _mem_objects_ is not `NULL` + ** if _num_mem_objects_ is greater than zero and _mem_objects_ is `NULL` + * {CL_INVALID_MEM_OBJECT} + ** if any of the memory objects in _mem_objects_ is not a valid OpenCL memory object created using an external memory handle * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is not 0, - or - ** if _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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the execution status - of any of the events in _event_wait_list_ is a negative integer value. - * {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 _event_wait_list_ is `NULL` and _num_events_in_wait_list_ 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 + // TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. + * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} + ** if 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_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='clEnqueueReleaseExternalMemObjectsKHR',desc='Enqueue a command to release OpenCL memory objects created from external memory handles',type='protos'] @@ -6174,31 +6175,32 @@ its completion event. is executed successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_VALUE} if _num_mem_objects_ is zero and _mem_objects_ is not - a `NULL` value, or if _num_mem_objects_ is greater than 0 and - _mem_objects_ is `NULL`. - * {CL_INVALID_MEM_OBJECT} if any of the memory objects in _mem_objects_ is - not a valid OpenCL memory object created using an external memory - handle. * {CL_INVALID_COMMAND_QUEUE} - ** if _command_queue_ is not a valid command-queue, or - ** if device associated with _command_queue_ is not one of the devices - specified by {CL_MEM_DEVICE_HANDLE_LIST_KHR} at the time of creating - one or more of _mem_objects_, or - ** if one or more of _mem_objects_ belong to a context that does not - contain a device associated with _command_queue_. + ** if _command_queue_ is not a valid command-queue + ** if device associated with _command_queue_ is not one of the devices + specified by {CL_MEM_DEVICE_HANDLE_LIST_KHR} at the time of creating + one or more of _mem_objects_ + ** if one or more of _mem_objects_ belong to a context that does not + contain a device associated with _command_queue_ + * {CL_INVALID_VALUE} + ** if _num_mem_objects_ is zero and _mem_objects_ is not `NULL` + ** if _num_mem_objects_ is greater than zero and _mem_objects_ is `NULL` + * {CL_INVALID_MEM_OBJECT} + ** if any of the memory objects in _mem_objects_ is not a valid OpenCL memory object created using an external memory handle * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ is not 0, - or - ** if _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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the execution status - of any of the events in _event_wait_list_ is a negative integer value. - * {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 _event_wait_list_ is `NULL` and _num_events_in_wait_list_ 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 + // TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. + * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} + ** if 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_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 -- From e01c61dd7d9b12e626ba474e5c1c26fe918b24b3 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 15:04:06 -0700 Subject: [PATCH 16/22] error consistency for unmapping memory objects --- api/opencl_runtime_layer.asciidoc | 41 +++++++++++++++++-------------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index d33780db4..e4a153a41 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -6078,7 +6078,7 @@ is executed successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_COMMAND_QUEUE} - ** if _command_queue_ is not a valid command-queue + ** if _command_queue_ is not a valid host command-queue ** if the device associated with _command_queue_ is not one of the devices specified by {CL_MEM_DEVICE_HANDLE_LIST_KHR} at the time of creating one or more of _mem_objects_ @@ -6176,7 +6176,7 @@ is executed successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_COMMAND_QUEUE} - ** if _command_queue_ is not a valid command-queue + ** if _command_queue_ is not a valid host command-queue ** if device associated with _command_queue_ is not one of the devices specified by {CL_MEM_DEVICE_HANDLE_LIST_KHR} at the time of creating one or more of _mem_objects_ @@ -6368,23 +6368,26 @@ for a region of the buffer object being mapped. 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_MEM_OBJECT} if _memobj_ is not a valid memory object or is a - pipe object. - * {CL_INVALID_VALUE} if _mapped_ptr_ is not a valid pointer returned by - {clEnqueueMapBuffer} or {clEnqueueMapImage} for _memobj_. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or if _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_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 associated with _command_queue_ and - _memobj_ are not the same or if the context associated with - _command_queue_ and events in _event_wait_list_ are not the same. + * {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 _memobj_ 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 _memobj_ is not a valid memory object + ** if _memobj_ is a pipe object + * {CL_INVALID_VALUE} + ** if _mapped_ptr_ is not a pointer returned by {clEnqueueMapBuffer} or {clEnqueueMapImage} for _memobj_ + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ 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_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 -- From f0d56e08ac7d9aadac8eaa0bd3b9348f37320456 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 15:34:36 -0700 Subject: [PATCH 17/22] error consistency for clEnqueueMigrateMemObjects --- api/opencl_runtime_layer.asciidoc | 48 ++++++++++++++++--------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index e4a153a41..a9cd1a949 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -6545,32 +6545,34 @@ Improperly specified event dependencies passed to // refError -{clEnqueueMigrateMemObjects} return {CL_SUCCESS} if the function is executed +{clEnqueueMigrateMemObjects} returns {CL_SUCCESS} if the 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 - memory objects in _mem_objects_ 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 any of the memory objects in _mem_objects_ is - not a valid memory object. - * {CL_INVALID_VALUE} if _num_mem_objects_ is zero or if _mem_objects_ is - `NULL`. - * {CL_INVALID_VALUE} if _flags_ is not 0 or is not any of the values - described in the table above. - * {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_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for the specified set of memory objects in _mem_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. + * {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 memory objects in _mem_objects_ 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 any of the memory objects in _mem_objects_ is not a valid memory object + * {CL_INVALID_VALUE} + ** if _num_mem_objects_ is zero + ** if _mem_objects_ is `NULL` + ** if _flags_ is not zero and is not a vakud combination of the values + described in the <> table + * {CL_INVALID_EVENT_WAIT_LIST} + ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ 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_OBJECT_ALLOCATION_FAILURE} + ** if there is a failure to allocate memory for the data store associated with a memory object in _mem_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 -- From 8d4cc09e08e659b9db08efc943531c8e467882c2 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 15:42:38 -0700 Subject: [PATCH 18/22] error consistency for clGetMemObjectInfo --- api/opencl_runtime_layer.asciidoc | 69 ++++++++++++++----------------- 1 file changed, 32 insertions(+), 37 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index a9cd1a949..3a902f34e 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -6559,8 +6559,8 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_VALUE} ** if _num_mem_objects_ is zero ** if _mem_objects_ is `NULL` - ** if _flags_ is not zero and is not a vakud combination of the values - described in the <> table + ** if _flags_ is not zero and is not a valid combination of the values + described in the <> table * {CL_INVALID_EVENT_WAIT_LIST} ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ greater than zero ** if _event_wait_list_ is not `NULL` and _num_events_in_wait_list_ is zero @@ -6795,51 +6795,46 @@ endif::cl_ext_buffer_device_address[] successfully. Otherwise, it returns one of the following errors: - * {CL_INVALID_MEM_OBJECT} if _memobj_ is a not a valid memory object. -ifdef::cl_ext_buffer_device_address[] - * {CL_INVALID_OPERATION} is returned for the {CL_MEM_DEVICE_ADDRESS_EXT} query if - the {cl_ext_buffer_device_address_EXT} is not supported or if the - buffer was not allocated with {CL_MEM_DEVICE_PRIVATE_ADDRESS_EXT}. -endif::cl_ext_buffer_device_address[] - * {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 _memobj_ is a not a valid memory 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 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. - + and _param_value_ is not `NULL` +ifdef::cl_ext_buffer_device_address[] + * {CL_INVALID_OPERATION} + ** if the {cl_ext_buffer_device_address_EXT} extension is supported, if + _param_name_ is {CL_MEM_DEVICE_ADDRESS_EXT}, and if _memobj_ was not created + with the {CL_MEM_DEVICE_PRIVATE_ADDRESS_EXT} property set to {CL_TRUE} +endif::cl_ext_buffer_device_address[] 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_MEM_DX9_MEDIA_SURFACE_INFO_KHR} and _memobj_ was not created by - calling {clCreateFromDX9MediaSurfaceKHR} from a Direct3D9 surface. + * {CL_INVALID_DX9_MEDIA_SURFACE_KHR} + ** if the {cl_khr_dx9_media_sharing_EXT} extension is supported, if + _param_name_ is {CL_MEM_DX9_MEDIA_SURFACE_INFO_KHR}, and if _memobj_ 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_MEM_D3D10_RESOURCE_KHR} and _memobj_ was not created by calling + * {CL_INVALID_D3D10_RESOURCE_KHR} + ** if the {cl_khr_d3d10_sharing_EXT} extension is supported, if _param_name_ + is {CL_MEM_D3D10_RESOURCE_KHR}, and if _memobj_ was not created by calling {clCreateFromD3D10BufferKHR}, {clCreateFromD3D10Texture2DKHR}, or - {clCreateFromD3D10Texture3DKHR}. + {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_MEM_D3D11_RESOURCE_KHR} and _memobj_ was not created by calling + * {CL_INVALID_D3D11_RESOURCE_KHR} + ** if the {cl_khr_d3d11_sharing_EXT} extension is supported, if _param_name_ + is {CL_MEM_D3D11_RESOURCE_KHR} and if _memobj_ was not created by calling {clCreateFromD3D11BufferKHR}, {clCreateFromD3D11Texture2DKHR}, or - {clCreateFromD3D11Texture3DKHR}. + {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 -- From 26a8d7c51ac4265b6e425e612d207d0da8dbf0a8 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 16:13:07 -0700 Subject: [PATCH 19/22] error consistency for SVM --- api/opencl_runtime_layer.asciidoc | 294 ++++++++++++++++-------------- 1 file changed, 160 insertions(+), 134 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index 3a902f34e..50e15e693 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -1082,7 +1082,7 @@ Otherwise, they return one of the following errors: ** 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_ greater than zero + ** 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} @@ -1238,7 +1238,7 @@ Otherwise, they return one of the following errors: ** 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_ greater than zero + ** 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} @@ -1394,7 +1394,7 @@ Otherwise, it returns one of the following errors: ** 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_ greater than zero + ** 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} @@ -1542,7 +1542,7 @@ Otherwise, it returns one of the following errors: ** 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_ greater than zero + ** 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} @@ -1648,7 +1648,7 @@ Otherwise, it returns one of the following errors: ** 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_ greater than zero + ** 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} @@ -1750,7 +1750,7 @@ values returned in _errcode_ret_: ** 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_ greater than zero + ** 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} @@ -3740,7 +3740,7 @@ ifdef::cl_khr_mipmap_image[] ** 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_ greater than zero + ** 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} @@ -3926,7 +3926,7 @@ ifdef::cl_khr_mipmap_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_ greater than zero + ** 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} @@ -4057,7 +4057,7 @@ ifdef::cl_khr_mipmap_image[] ** 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_ greater than zero + ** 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} @@ -4187,7 +4187,7 @@ ifdef::cl_khr_mipmap_image[] ** 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_ endif::cl_khr_mipmap_image[] * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ greater than zero + ** 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} @@ -4324,7 +4324,7 @@ ifdef::cl_khr_mipmap_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_ greater than zero + ** 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} @@ -4470,7 +4470,7 @@ ifdef::cl_khr_mipmap_image[] ** 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_ greater than zero + ** 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} @@ -6090,7 +6090,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} ** if any of the memory objects in _mem_objects_ is not a valid OpenCL memory object created using an external memory handle * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ greater than zero + ** 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 // TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. @@ -6188,7 +6188,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_MEM_OBJECT} ** if any of the memory objects in _mem_objects_ is not a valid OpenCL memory object created using an external memory handle * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ greater than zero + ** 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 // TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. @@ -6379,7 +6379,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_VALUE} ** if _mapped_ptr_ is not a pointer returned by {clEnqueueMapBuffer} or {clEnqueueMapImage} for _memobj_ * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ greater than zero + ** 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_OUT_OF_RESOURCES} @@ -6562,7 +6562,7 @@ Otherwise, it returns one of the following errors: ** if _flags_ is not zero and is not a valid combination of the values described in the <> table * {CL_INVALID_EVENT_WAIT_LIST} - ** if _event_wait_list_ is `NULL` and _num_events_in_wait_list_ greater than zero + ** 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_OBJECT_ALLOCATION_FAILURE} @@ -8110,25 +8110,22 @@ and writes in a kernel. {clSVMAlloc} returns a valid non-`NULL` shared virtual memory address if the SVM buffer is successfully allocated. Otherwise, like *malloc*, it returns a `NULL` pointer value. -{clSVMAlloc} will fail if +{clSVMAlloc} will fail if: - * _context_ is not a valid context, or no devices in _context_ support SVM. - * _flags_ does not contain {CL_MEM_SVM_FINE_GRAIN_BUFFER} but does contain - {CL_MEM_SVM_ATOMICS}. + * _context_ is not a valid context + * no devices in _context_ support SVM + * values specified in _flags_ do not match those defined in the <> table + * values specified in _flags_ do not follow rules described for supported values in the <> table + * _flags_ contains {CL_MEM_SVM_ATOMICS} and does not contain {CL_MEM_SVM_FINE_GRAIN_BUFFER} ifdef::cl_ext_immutable_memory_objects[] - * _flags_ contains {CL_MEM_IMMUTABLE_EXT}. + * _flags_ contains {CL_MEM_IMMUTABLE_EXT} endif::cl_ext_immutable_memory_objects[] - * Values specified in _flags_ do not follow rules described for supported - values in the <> table. - * {CL_MEM_SVM_FINE_GRAIN_BUFFER} or {CL_MEM_SVM_ATOMICS} is specified in - _flags_ and these are not supported by at least one device in _context_. - * The values specified in _flags_ are not valid, i.e. do not match those - defined in the <> table. - * _size_ is 0 or > {CL_DEVICE_MAX_MEM_ALLOC_SIZE} value for any device in - _context_. - * _alignment_ is not a power of two or the OpenCL implementation cannot - support the specified alignment for at least one device in _context_. - * There was a failure to allocate resources. + * _flags_ contains {CL_MEM_SVM_FINE_GRAIN_BUFFER} or {CL_MEM_SVM_ATOMICS} and these flags are not supported by at least one device in _context_ + * _size_ is 0 or greater than or equal to {CL_DEVICE_MAX_MEM_ALLOC_SIZE} value for any device in _context_ + * _alignment_ is not a power of two + * _alignment_ is not supported for at least one device in _context_ + * there was a failure to allocate resources on the device + * there was a failure to allocate resources on the host -- [open,refpage='clSVMFree',desc='Frees a shared virtual memory buffer allocated using clSVMAlloc.',type='protos'] @@ -8227,20 +8224,26 @@ include::{generated}/api/version-notes/clEnqueueSVMFree.asciidoc[] 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_OPERATION} if the device associated with _command_queue_ does not support SVM. - * {CL_INVALID_VALUE} if _num_svm_pointers_ is 0 and _svm_pointers_ is - non-`NULL`, _or_ if _svm_pointers_ is `NULL` and _num_svm_pointers_ is - not 0. - * {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_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_OPERATION} + ** if the device associated with _command_queue_ does not support SVM + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_VALUE} + ** if _svm_pointers_ is `NULL` and _num_svm_pointers_ is greater than zero + ** if _svm_pointers_ is not `NULL` and _num_svm_pointers_ is zero + // TODO: error condition for invalid SVM pointers? + * {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_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='clEnqueueSVMMemcpy',desc='Enqueues a command to do a memcpy operation.',type='protos'] @@ -8304,25 +8307,30 @@ context from which _command_queue_ was created the behavior is undefined. 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_OPERATION} if the device associated with _command_queue_ does not support SVM. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and - events in _event_wait_list_ are not the same. - * {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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} if the copy operation is - blocking and the execution status of any of the events in - _event_wait_list_ is a negative integer value. - * {CL_INVALID_VALUE} if _dst_ptr_ or _src_ptr_ is `NULL`. - * {CL_MEM_COPY_OVERLAP} if the values specified for _dst_ptr_, _src_ptr_ and - _size_ result in an overlapping copy. - * {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_OPERATION} + ** if the device associated with _command_queue_ does not support SVM + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_VALUE} + ** if _dst_ptr_ is `NULL` + ** if _src_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_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} + ** if the copy operations is blocking and the execution status of + any of the events in _event_wait_list_ is a negative integer value indicating an error + * {CL_MEM_COPY_OVERLAP} + ** if the values specified for _dst_ptr_, _src_ptr_ and _size_ result in an overlapping copy + * {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='clEnqueueSVMMemFill',desc='Enqueues a command to fill a region in memory with a pattern of a given pattern size.',type='protos'] @@ -8386,24 +8394,30 @@ include::{generated}/api/version-notes/clEnqueueSVMMemFill.asciidoc[] 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_OPERATION} if the device associated with _command_queue_ does not support SVM. - * {CL_INVALID_CONTEXT} if the context associated with _command_queue_ and - events in _event_wait_list_ are not the same. - * {CL_INVALID_VALUE} if _svm_ptr_ is `NULL`. - * {CL_INVALID_VALUE} if _svm_ptr_ is not aligned to _pattern_size_ bytes. - * {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 _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_ > 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_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_OPERATION} + ** if the device associated with _command_queue_ does not support SVM + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_VALUE} + ** if _svm_ptr_ is `NULL` + ** if _svm_ptr_ is not aligned to _pattern_size_ bytes + ** 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 _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_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='clEnqueueSVMMap',desc='Enqueues a command that will allow the host to update a region of a SVM buffer',type='protos'] @@ -8466,25 +8480,29 @@ already mapped in the host address space. 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_OPERATION} if the device associated with _command_queue_ does not support SVM. - * {CL_INVALID_CONTEXT} if context associated with _command_queue_ and events - in _event_wait_list_ are not the same. - * {CL_INVALID_VALUE} if _svm_ptr_ is `NULL`. - * {CL_INVALID_VALUE} 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_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_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_OPERATION} + ** if the device associated with _command_queue_ does not support SVM + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_VALUE} + ** if _svm_ptr_ is `NULL` + ** 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_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 + * {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='clEnqueueSVMUnmap',desc='Enqueues a command to indicate that the host has completed updating the region given by an SVM pointer and which was specified in a previous call to clEnqueueSVMMap.',type='protos'] @@ -8532,20 +8550,24 @@ the region of the SVM buffer specified in these calls. 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_OPERATION} if the device associated with _command_queue_ does not support SVM. - * {CL_INVALID_CONTEXT} if context associated with _command_queue_ and events - in _event_wait_list_ are not the same. - * {CL_INVALID_VALUE} if _svm_ptr_ is `NULL`. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or if _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_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_OPERATION} + ** if the device associated with _command_queue_ does not support SVM + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_VALUE} + ** if _svm_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_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] ==== @@ -8633,24 +8655,28 @@ could result in undefined results. 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_OPERATION} if the device associated with _command_queue_ does not support SVM. - * {CL_INVALID_CONTEXT} if context associated with _command_queue_ and events - in _event_wait_list_ are not the same. - * {CL_INVALID_VALUE} if _num_svm_pointers_ is zero or _svm_pointers_ is - `NULL`. - * {CL_INVALID_VALUE} if _sizes_[i] is non-zero range [_svm_pointers_[i], - _svm_pointers_[i]+_sizes_[i]) is not contained within an existing - {clSVMAlloc} allocation. - * {CL_INVALID_EVENT_WAIT_LIST} if _event_wait_list_ is `NULL` and - _num_events_in_wait_list_ > 0, or if _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_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_OPERATION} + ** if the device associated with _command_queue_ does not support SVM + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_VALUE} + ** if _num_svm_pointers_ is zero + ** if _svm_pointers_ is `NULL` + ** if _flags_ is not zero and is not a valid combination of the values + described in the <> table + ** if _sizes_[i] is non-zero and the memory range described by _svm_pointers_[i] and _sizes_[i] is not contained within an SVM allocation returned by {clSVMAlloc} + * {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_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 -- From a853ac1a53c02f73678010d63f700af3b44db2a5 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 16:48:06 -0700 Subject: [PATCH 20/22] error consistency for clEnqueueNDRangeKernel --- api/opencl_runtime_layer.asciidoc | 187 +++++++++++++++--------------- 1 file changed, 91 insertions(+), 96 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index d8f33b185..ad892c91d 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -956,7 +956,7 @@ endif::cl_ext_immutable_memory_objects[] value. This error code is <> version 1.1. * {CL_MEM_OBJECT_ALLOCATION_FAILURE} - ** if there is a failure to allocate memory for sub-buffer object + ** 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 @@ -1096,7 +1096,7 @@ Otherwise, they return one of the following errors: 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_ + ** 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} @@ -1252,7 +1252,7 @@ Otherwise, they return one of the following errors: 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_. + ** 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} @@ -1403,7 +1403,7 @@ Otherwise, it returns one of the following errors: ** 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 data store associated with _src_buffer_ or _dst_buffer_ + ** 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} @@ -1551,7 +1551,7 @@ Otherwise, it returns one of the following errors: ** 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 data store associated with _src_buffer_ or _dst_buffer_ + ** 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} @@ -1658,7 +1658,7 @@ Otherwise, it returns one of the following errors: _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_ + ** 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} @@ -1769,7 +1769,7 @@ values returned in _errcode_ret_: 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_ + ** 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_ @@ -3752,7 +3752,7 @@ endif::cl_khr_mipmap_image[] 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_ + ** 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} @@ -3936,7 +3936,7 @@ endif::cl_khr_mipmap_image[] * {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 data store associated with _src_image_ or _dst_image_ + ** 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[] @@ -4065,7 +4065,7 @@ endif::cl_khr_mipmap_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 data store associated with _image_ + ** 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[] @@ -4201,8 +4201,8 @@ endif::cl_khr_mipmap_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 data store associated with _src_image_ - ** if there is a failure to allocate memory for data store associated with _dst_buffer_ + ** if there is a failure to allocate memory for the data store associated with _src_image_ + ** if there is a failure to allocate memory for the data store associated with _dst_buffer_ * {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[] @@ -4338,8 +4338,8 @@ endif::cl_khr_mipmap_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 data store associated with _src_buffer_ - ** if there is a failure to allocate memory for data store associated with _dst_image_ + ** if there is a failure to allocate memory for the data store associated with _src_buffer_ + ** if there is a failure to allocate memory for the data store associated with _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[] @@ -4487,7 +4487,7 @@ endif::cl_khr_mipmap_image[] 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_ + ** 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_ @@ -12098,90 +12098,85 @@ The starting local ID is always (0, 0, ..., 0). successfully queued. Otherwise, it returns one of the following errors: - * {CL_INVALID_PROGRAM_EXECUTABLE} if there is no successfully built program - executable available for the device associated with _command_queue_. - * {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid host - command-queue. - * {CL_INVALID_KERNEL} if _kernel_ is not a valid kernel object. - * {CL_INVALID_CONTEXT} if context associated with _command_queue_ and - _kernel_ are not the same or if the context associated with - _command_queue_ and events in _event_wait_list_ are not the same. - * {CL_INVALID_KERNEL_ARGS} if the kernel argument values have not been - specified. - * {CL_INVALID_WORK_DIMENSION} if _work_dim_ is not a valid value (i.e. a - value between 1 and {CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS}). - * {CL_INVALID_GLOBAL_WORK_SIZE} if _global_work_size_ is NULL or if any of - the values specified in _global_work_size_[0], ... - _global_work_size_[_work_dim_ - 1] are zero. + * {CL_INVALID_COMMAND_QUEUE} + ** if _command_queue_ is not a valid host command-queue + * {CL_INVALID_KERNEL} + ** if _kernel_ is not a valid kernel + * {CL_INVALID_PROGRAM_EXECUTABLE} + ** if there is no successfully built program executable available for the + device associated with _command_queue_ + * {CL_INVALID_CONTEXT} + ** if the context associated with _command_queue_ and _kernel_ are not the same + ** if the context associated with _command_queue_ and events in _event_wait_list_ are not the same + * {CL_INVALID_KERNEL_ARGS} + ** if any kernel arguments for _kernel_ have not been set + * {CL_INVALID_WORK_DIMENSION} + ** 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}) + * {CL_INVALID_GLOBAL_OFFSET} + ** if the device associated with _command_queue_ does not support OpenCL 1.1 + and _global_work_offset_ is not `NULL` + ** if the value specified in _global_work_size_ plus the corresponding value + in _global_work_offset_ for any dimensions is greater than the maximum value + representable by {size_t_TYPE} on the device associated with _command_queue_ + * {CL_INVALID_GLOBAL_WORK_SIZE} + ** if _global_work_size_ is NULL or if any of the values specified in + _global_work_size_[0], ... _global_work_size_[_work_dim_ - 1] are zero. This error condition does not apply when the device associated with _command_queue_ supports OpenCL 2.1 or newer. - * {CL_INVALID_GLOBAL_WORK_SIZE} if any of the values specified in - _global_work_size_[0], ... _global_work_size_[_work_dim_ - 1] exceed the - maximum value representable by {size_t_TYPE} on the device on which the - kernel-instance will be enqueued. - * {CL_INVALID_GLOBAL_OFFSET} if the value specified in _global_work_size_ - {plus} the corresponding values in _global_work_offset_ for any - dimensions is greater than the maximum value representable by size t on - the device on which the kernel-instance will be enqueued, or if - _global_work_offset_ is non-`NULL` <> version 1.1. - * {CL_INVALID_WORK_GROUP_SIZE} if _local_work_size_ is specified and does - not match the required work-group size for _kernel_ in the program - source. - * {CL_INVALID_WORK_GROUP_SIZE} if _local_work_size_ is specified and is not - consistent with the required number of sub-groups for _kernel_ in the - program source. - * {CL_INVALID_WORK_GROUP_SIZE} if _local_work_size_ is specified and the - total number of work-items in the work-group computed as - _local_work_size_[0] {times} ... _local_work_size_[_work_dim_ - 1] is - greater than the value specified by {CL_KERNEL_WORK_GROUP_SIZE} in the - <> table. - * {CL_INVALID_WORK_GROUP_SIZE} if the work-group size must be uniform and - the _local_work_size_ is not `NULL`, is not equal to the required - work-group size specified in the kernel source, or the - _global_work_size_ is not evenly divisible by the _local_work_size_. - * {CL_INVALID_WORK_ITEM_SIZE} if the number of work-items specified in any - of _local_work_size_[0], ... _local_work_size_[_work_dim_ - 1] is - greater than the corresponding values specified by - {CL_DEVICE_MAX_WORK_ITEM_SIZES}[0], ..., - {CL_DEVICE_MAX_WORK_ITEM_SIZES}[_work_dim_ - 1]. - * {CL_MISALIGNED_SUB_BUFFER_OFFSET} if a sub-buffer object is specified as - the value for an argument that is a buffer object and the _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 any of the values specified in _global_work_size_[0], ... + _global_work_size_[_work_dim_ - 1] exceed the maximum value representable by + {size_t_TYPE} on the device associated with _command_queue_ + * {CL_INVALID_WORK_GROUP_SIZE} + ** 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_ + ** 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}) + ** if _local_work_size_ is not `NULL` and if the _local_work_size_ does not match the required work-group size for _kernel_ + ** 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_ + * {CL_INVALID_WORK_ITEM_SIZE} + ** if the number of work-items specified in any of _local_work_size_[0], ... _local_work_size_[_work_dim_ - 1] is + greater than the corresponding values returned by {CL_DEVICE_MAX_WORK_ITEM_SIZES}[0], ..., {CL_DEVICE_MAX_WORK_ITEM_SIZES}[_work_dim_ - 1] + for the device associated with _command_queue_ + * {CL_MISALIGNED_SUB_BUFFER_OFFSET} + ** if a kernel argument for _kernel_ 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_INVALID_IMAGE_SIZE} if an image object is specified as an argument - value and the image dimensions (image width, height, specified or - compute row and/or slice pitch) are not supported by device associated - with _queue_. - * {CL_IMAGE_FORMAT_NOT_SUPPORTED} if an image object is specified as an - argument value and the image format (image channel order and data type) - is not supported by device associated with _queue_. - * {CL_OUT_OF_RESOURCES} if there is a failure to queue the execution - instance of _kernel_ on the command-queue because of insufficient - resources needed to execute the kernel. - For example, the explicitly specified _local_work_size_ causes a failure - to execute the kernel because of insufficient resources such as - registers or local memory. - Another example would be the number of read-only image args used in - _kernel_ exceed the {CL_DEVICE_MAX_READ_IMAGE_ARGS} value for device or - the number of write-only and read-write image args used in _kernel_ - exceed the {CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS} value for device or the - number of samplers used in _kernel_ exceed {CL_DEVICE_MAX_SAMPLERS} for - device. - * {CL_MEM_OBJECT_ALLOCATION_FAILURE} if there is a failure to allocate - memory for data store associated with image or buffer objects specified - as arguments to _kernel_. - * {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_OPERATION} if SVM pointers are passed as arguments to a kernel - and the device does not support SVM, or if system pointers are passed as - arguments to a kernel and the device does not support fine-grain system SVM. - * {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_IMAGE_SIZE} + ** if a kernel argument for _kernel_ is an image and the dimensions for the 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 a kernel argument for _kernel_ is an image and the format the _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 any buffer or image object kernel arguments for _kernel_ + * {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_OPERATION} + ** if SVM pointers are set as arguments for _kernel_ and the device associated with _command_queue_ does not support SVM + ** if system pointers are set as arguments for _kernel_ the device associated with _command_queue_ does not support fine-grain system SVM + // TODO: Do we still need these explicit examples? + // * {CL_OUT_OF_RESOURCES} if there is a failure to queue the execution + // instance of _kernel_ on the command-queue because of insufficient + // resources needed to execute the kernel. + // For example, the explicitly specified _local_work_size_ causes a failure + // to execute the kernel because of insufficient resources such as + // registers or local memory. + // Another example would be the number of read-only image args used in + // _kernel_ exceed the {CL_DEVICE_MAX_READ_IMAGE_ARGS} value for device or + // the number of write-only and read-write image args used in _kernel_ + // exceed the {CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS} value for device or the + // number of samplers used in _kernel_ exceed {CL_DEVICE_MAX_SAMPLERS} for + // device. + * {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='clEnqueueTask',desc='Enqueues a command to execute a kernel, using a single work-item, on a device.',type='protos'] From ee72fe35ff5e72dc0b9266e466d0ce8d086b930c Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 16:53:05 -0700 Subject: [PATCH 21/22] fix TODO comments --- api/opencl_runtime_layer.asciidoc | 32 +++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index ad892c91d..f6f4a4806 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -6090,7 +6090,7 @@ Otherwise, it returns one of the following errors: ** 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 - // TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. +// TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} ** if 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. @@ -6188,7 +6188,7 @@ Otherwise, it returns one of the following errors: ** 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 - // TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. +// TODO: Do we want this to be an error? For other APIs, it is only an error when the API is blocking. * {CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST} ** if 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. @@ -8230,7 +8230,7 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_VALUE} ** if _svm_pointers_ is `NULL` and _num_svm_pointers_ is greater than zero ** if _svm_pointers_ is not `NULL` and _num_svm_pointers_ is zero - // TODO: error condition for invalid SVM pointers? +// TODO: error condition for invalid SVM pointers? * {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 @@ -12158,19 +12158,19 @@ Otherwise, it returns one of the following errors: * {CL_INVALID_OPERATION} ** if SVM pointers are set as arguments for _kernel_ and the device associated with _command_queue_ does not support SVM ** if system pointers are set as arguments for _kernel_ the device associated with _command_queue_ does not support fine-grain system SVM - // TODO: Do we still need these explicit examples? - // * {CL_OUT_OF_RESOURCES} if there is a failure to queue the execution - // instance of _kernel_ on the command-queue because of insufficient - // resources needed to execute the kernel. - // For example, the explicitly specified _local_work_size_ causes a failure - // to execute the kernel because of insufficient resources such as - // registers or local memory. - // Another example would be the number of read-only image args used in - // _kernel_ exceed the {CL_DEVICE_MAX_READ_IMAGE_ARGS} value for device or - // the number of write-only and read-write image args used in _kernel_ - // exceed the {CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS} value for device or the - // number of samplers used in _kernel_ exceed {CL_DEVICE_MAX_SAMPLERS} for - // device. +// TODO: Do we still need these explicit examples? +// * {CL_OUT_OF_RESOURCES} if there is a failure to queue the execution +// instance of _kernel_ on the command-queue because of insufficient +// resources needed to execute the kernel. +// For example, the explicitly specified _local_work_size_ causes a failure +// to execute the kernel because of insufficient resources such as +// registers or local memory. +// Another example would be the number of read-only image args used in +// _kernel_ exceed the {CL_DEVICE_MAX_READ_IMAGE_ARGS} value for device or +// the number of write-only and read-write image args used in _kernel_ +// exceed the {CL_DEVICE_MAX_READ_WRITE_IMAGE_ARGS} value for device or the +// number of samplers used in _kernel_ exceed {CL_DEVICE_MAX_SAMPLERS} for +// device. * {CL_OUT_OF_RESOURCES} ** if there is a failure to allocate resources required by the OpenCL implementation on the device From 8ba3baa42541360cc453ad8cd50c5751cbcf05a0 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 23 Jun 2025 16:56:42 -0700 Subject: [PATCH 22/22] consistent text treatment for NULL --- api/opencl_runtime_layer.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index f6f4a4806..13ba92442 100644 --- a/api/opencl_runtime_layer.asciidoc +++ b/api/opencl_runtime_layer.asciidoc @@ -11950,8 +11950,8 @@ Otherwise, it returns one of the following errors: SVM or the required SVM capabilities for the SVM pointer. * {CL_INVALID_WORK_DIMENSION} if _work_dim_ is not a valid value (i.e. a value between 1 and {CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS}). - * {CL_INVALID_GLOBAL_WORK_SIZE} if _global_work_size_ is NULL or if any of - the values specified in _global_work_size_ are 0. + * {CL_INVALID_GLOBAL_WORK_SIZE} if _global_work_size_ is `NULL` or if any of + the values specified in _global_work_size_ are zero. * {CL_INVALID_GLOBAL_WORK_SIZE} if any of the values specified in _global_work_size_ exceed the maximum value representable by `size_t` on the device associated with _command_queue_. @@ -11959,7 +11959,7 @@ Otherwise, it returns one of the following errors: plus the corresponding value in _global_work_offset_ for dimension exceeds the maximum value representable by `size_t` on the device associated with _command_queue_. - * {CL_INVALID_VALUE} if _suggested_local_work_size_ is NULL. + * {CL_INVALID_VALUE} if _suggested_local_work_size_ is `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 @@ -12119,7 +12119,7 @@ Otherwise, it returns one of the following errors: in _global_work_offset_ for any dimensions is greater than the maximum value representable by {size_t_TYPE} on the device associated with _command_queue_ * {CL_INVALID_GLOBAL_WORK_SIZE} - ** if _global_work_size_ is NULL or if any of the values specified in + ** if _global_work_size_ is `NULL` or if any of the values specified in _global_work_size_[0], ... _global_work_size_[_work_dim_ - 1] are zero. This error condition does not apply when the device associated with _command_queue_ supports OpenCL 2.1 or newer. @@ -13891,7 +13891,7 @@ be provided for semaphores created from {clEnqueueWaitSemaphoresKHR} and {clEnqueueSignalSemaphoresKHR} may return {CL_INVALID_VALUE} if _sema_objects_ list has one or more semaphores obtained from {CL_SEMAPHORE_HANDLE_D3D12_FENCE_KHR} and _sema_payload_list_ -is NULL. +is `NULL`. endif::cl_khr_external_semaphore_dx_fence[] @@ -16701,7 +16701,7 @@ one of the errors below is returned: _configs_ is not `NULL` and _num_configs_ is 0. * {CL_INVALID_VALUE} if any element of _config_types_ is not a valid {cl_command_buffer_update_type_khr_TYPE} enum. - * {CL_INVALID_VALUE} if any element of _configs_ is NULL. + * {CL_INVALID_VALUE} if any element of _configs_ is `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