Skip to content

error code consistency for command-queues #1449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bashbaug merged 1 commit into from
Sep 2, 2025
Merged

error code consistency for command-queues #1449

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 99 additions & 69 deletions api/opencl_runtime_layer.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']
Expand Down Expand Up @@ -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']
Expand All @@ -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']
Expand Down Expand Up @@ -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']
Expand Down Expand Up @@ -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']
Expand Down Expand Up @@ -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
<<command-queue-info-table, Command-Queue Queries>> 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.
<<command-queue-info-table, Command-Queue Queries>>
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']
Expand Down Expand Up @@ -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
--


Expand Down