From 716b25cb092d7ecc3aef33c17b152a55e9b4c8bf Mon Sep 17 00:00:00 2001 From: Ben Ashbaugh Date: Mon, 25 Aug 2025 17:52:31 -0700 Subject: [PATCH] error code consistency for command-queues --- api/opencl_runtime_layer.asciidoc | 168 ++++++++++++++++++------------ 1 file changed, 99 insertions(+), 69 deletions(-) diff --git a/api/opencl_runtime_layer.asciidoc b/api/opencl_runtime_layer.asciidoc index e2b0406d3..bbe91b890 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 the size of the return type specified in the - <> table - and _param_value_ is not `NULL`. - * {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required - by the OpenCL implementation on the device. - * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources - required by the OpenCL implementation on the host. + <> + table and _param_value_ is not `NULL` + * {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,16 +532,22 @@ 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 --