From 50d101c6eeebeeb61640be77739583e7427c7945 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Thu, 14 Aug 2025 15:22:27 -0700 Subject: [PATCH 1/3] error code consistency for platforms and devices --- api/opencl_platform_layer.asciidoc | 299 ++++++++++++++++++----------- 1 file changed, 186 insertions(+), 113 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 0108c87b9..1ca184b8c 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 -- @@ -453,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}. @@ -2245,16 +2268,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[] @@ -2343,14 +2369,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'] @@ -2384,17 +2416,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 @@ -2493,20 +2529,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[] @@ -2605,13 +2647,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[] @@ -2710,13 +2761,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[] @@ -2839,26 +2899,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: @@ -2914,11 +2981,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'] @@ -2941,11 +3011,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 27ba9e49986cc329772ef7d7563063ecc8afd05c Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 25 Aug 2025 17:31:19 -0700 Subject: [PATCH 2/3] code review comments - remove trailing periods Co-authored-by: Ewan Crawford --- api/opencl_platform_layer.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 1ca184b8c..5465fe85a 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -131,7 +131,7 @@ executed successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_PLATFORM} - ** if _platform_ is not a valid 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 @@ -2274,7 +2274,7 @@ Otherwise, it returns one of the following errors: ** 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`. + 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 @@ -2417,12 +2417,12 @@ _host_timestamp_ if provided. Otherwise, it returns one of the following errors: * {CL_INVALID_DEVICE} - ** if _device_ is not a valid 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. + timer synchronization * {CL_INVALID_VALUE} - ** if _host_timestamp_ is `NULL`. + ** 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 @@ -3012,7 +3012,7 @@ successfully. Otherwise, it returns one of the following errors: * {CL_INVALID_DEVICE} - ** if _device_ is not a valid 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 From b49e7d6e68dc6adef9a58507d5772e908bcb0c26 Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 25 Aug 2025 17:42:19 -0700 Subject: [PATCH 3/3] comment out one error condition for now --- api/opencl_platform_layer.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/api/opencl_platform_layer.asciidoc b/api/opencl_platform_layer.asciidoc index 5465fe85a..ed82898ac 100644 --- a/api/opencl_platform_layer.asciidoc +++ b/api/opencl_platform_layer.asciidoc @@ -2651,7 +2651,8 @@ Otherwise it may return ** 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 +//TODO: confirm this is a valid error condition +// ** 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` @@ -2765,7 +2766,8 @@ Otherwise it may return ** 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 +//TODO: confirm this is a valid error condition +// ** 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`