Skip to content

Commit fadb84c

Browse files
bashbaugbashbaug
authored
error code consistency for command-queues (#1449)
1 parent 7f2674e commit fadb84c

File tree

1 file changed

+99
-69
lines changed

1 file changed

+99
-69
lines changed

‎api/opencl_runtime_layer.asciidoc

Lines changed: 99 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -177,26 +177,32 @@ successfully.
177177
Otherwise, it returns a `NULL` value with one of the following error values
178178
returned in _errcode_ret_:
179179

180-
* {CL_INVALID_CONTEXT} if _context_ is not a valid context.
181-
* {CL_INVALID_DEVICE} if _device_ is not a valid device or is not
182-
associated with _context_.
183-
* {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
184-
* {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are
185-
valid but are not supported by the device.
180+
* {CL_INVALID_CONTEXT}
181+
** if _context_ is not a valid context
182+
* {CL_INVALID_DEVICE}
183+
** if _device_ is not a valid device
184+
** if _device_ is not associated with _context_
185+
* {CL_INVALID_VALUE}
186+
** if values specified in _properties_ are not valid
187+
* {CL_INVALID_QUEUE_PROPERTIES}
188+
** if values specified in _properties_ are valid but are not supported by
189+
_device_
186190
ifdef::cl_khr_priority_hints[]
187-
* {CL_INVALID_QUEUE_PROPERTIES} if the {cl_khr_priority_hints_EXT}
188-
extension is supported, the {CL_QUEUE_PRIORITY_KHR} property is
189-
specified, and the queue is a {CL_QUEUE_ON_DEVICE}.
191+
** if the {cl_khr_priority_hints_EXT} extension is supported, the
192+
{CL_QUEUE_PRIORITY_KHR} property is specified, and the queue is a
193+
{CL_QUEUE_ON_DEVICE}
190194
endif::cl_khr_priority_hints[]
191195
ifdef::cl_khr_throttle_hints[]
192-
* {CL_INVALID_QUEUE_PROPERTIES} if the {cl_khr_throttle_hints_EXT}
193-
extension is supported, the {CL_QUEUE_THROTTLE_KHR} property is
194-
specified, and the queue is a {CL_QUEUE_ON_DEVICE}.
196+
** if the {cl_khr_throttle_hints_EXT} extension is supported, the
197+
{CL_QUEUE_THROTTLE_KHR} property is specified, and the queue is a
198+
{CL_QUEUE_ON_DEVICE}
195199
endif::cl_khr_throttle_hints[]
196-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources
197-
required by the OpenCL implementation on the device.
198-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
199-
required by the OpenCL implementation on the host.
200+
* {CL_OUT_OF_RESOURCES}
201+
** if there is a failure to allocate resources required by the OpenCL
202+
implementation on the device
203+
* {CL_OUT_OF_HOST_MEMORY}
204+
** if there is a failure to allocate resources required by the OpenCL
205+
implementation on the host
200206
--
201207

202208
[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.
247253
Otherwise, it returns a `NULL` value with one of the following error values
248254
returned in _errcode_ret_:
249255

250-
* {CL_INVALID_CONTEXT} if _context_ is not a valid context.
251-
* {CL_INVALID_DEVICE} if _device_ is not a valid device or is not associated
252-
with _context_.
253-
* {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
254-
* {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are
255-
valid but are not supported by the device.
256-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
257-
by the OpenCL implementation on the device.
258-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
259-
required by the OpenCL implementation on the host.
256+
* {CL_INVALID_CONTEXT}
257+
** if _context_ is not a valid context
258+
* {CL_INVALID_DEVICE}
259+
** if _device_ is not a valid device
260+
** if _device_ is not associated with _context_
261+
* {CL_INVALID_VALUE}
262+
** if values specified in _properties_ are not valid
263+
* {CL_INVALID_QUEUE_PROPERTIES}
264+
** if values specified in _properties_ are valid but are not supported by
265+
_device_
266+
* {CL_OUT_OF_RESOURCES}
267+
** if there is a failure to allocate resources required by the OpenCL
268+
implementation on the device
269+
* {CL_OUT_OF_HOST_MEMORY}
270+
** if there is a failure to allocate resources required by the OpenCL
271+
implementation on the host
260272
--
261273

262274
[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
281293
executed successfully.
282294
Otherwise, it returns one of the following errors:
283295

284-
* {CL_INVALID_CONTEXT} if _context_ is not a valid context.
285-
* {CL_INVALID_DEVICE} if _device_ is not a valid device or is not associated
286-
with _context_.
287-
* {CL_INVALID_OPERATION} if _device_ does not support a replaceable default on-device queue.
288-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid command-queue
289-
for _device_.
290-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
291-
by the OpenCL implementation on the device.
292-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
293-
required by the OpenCL implementation on the host.
296+
* {CL_INVALID_CONTEXT}
297+
** if _context_ is not a valid context
298+
* {CL_INVALID_DEVICE}
299+
** if _device_ is not a valid device
300+
** if _device_ is not associated with _context_
301+
* {CL_INVALID_OPERATION}
302+
** if _device_ does not support a replaceable default on-device queue
303+
* {CL_INVALID_COMMAND_QUEUE}
304+
** if _command_queue_ is not a valid command-queue for _device_
305+
* {CL_OUT_OF_RESOURCES}
306+
** if there is a failure to allocate resources required by the OpenCL
307+
implementation on the device
308+
* {CL_OUT_OF_HOST_MEMORY}
309+
** if there is a failure to allocate resources required by the OpenCL
310+
implementation on the host
294311
--
295312

296313
[open,refpage='clRetainCommandQueue',desc='Increments the command_queue reference count.',type='protos']
@@ -320,12 +337,14 @@ being valid.
320337
successfully.
321338
Otherwise, it returns one of the following errors:
322339

323-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid
324-
command-queue.
325-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
326-
by the OpenCL implementation on the device.
327-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
328-
required by the OpenCL implementation on the host.
340+
* {CL_INVALID_COMMAND_QUEUE}
341+
** if _command_queue_ is not a valid command-queue
342+
* {CL_OUT_OF_RESOURCES}
343+
** if there is a failure to allocate resources required by the OpenCL
344+
implementation on the device
345+
* {CL_OUT_OF_HOST_MEMORY}
346+
** if there is a failure to allocate resources required by the OpenCL
347+
implementation on the host
329348
--
330349

331350
[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.
354373
successfully.
355374
Otherwise, it returns one of the following errors:
356375

357-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid
358-
command-queue.
359-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
360-
by the OpenCL implementation on the device.
361-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
362-
required by the OpenCL implementation on the host.
376+
* {CL_INVALID_COMMAND_QUEUE}
377+
** if _command_queue_ is not a valid command-queue
378+
* {CL_OUT_OF_RESOURCES}
379+
** if there is a failure to allocate resources required by the OpenCL
380+
implementation on the device
381+
* {CL_OUT_OF_HOST_MEMORY}
382+
** if there is a failure to allocate resources required by the OpenCL
383+
implementation on the host
363384
--
364385

365386
[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[]
460481
successfully.
461482
Otherwise, it returns one of the following errors:
462483

463-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid
464-
command-queue, or if _command_queue_ is not a valid command-queue
465-
for _param_name_.
466-
* {CL_INVALID_VALUE} if _param_name_ is not one of the supported values, or
467-
if the size in bytes specified by _param_value_size_ is less than size of
484+
* {CL_INVALID_COMMAND_QUEUE}
485+
** if _command_queue_ is not a valid command-queue
486+
** if _command_queue_ is not a valid command-queue for _param_name_
487+
* {CL_INVALID_VALUE}
488+
** if _param_name_ is not one of the supported values
489+
** if the size in bytes specified by _param_value_size_ is less than the size of
468490
the return type specified in the
469-
<<command-queue-info-table, Command-Queue Queries>> table
470-
and _param_value_ is not `NULL`.
471-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
472-
by the OpenCL implementation on the device.
473-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
474-
required by the OpenCL implementation on the host.
491+
<<command-queue-info-table, Command-Queue Queries>>
492+
table and _param_value_ is not `NULL`
493+
* {CL_OUT_OF_RESOURCES}
494+
** if there is a failure to allocate resources required by the OpenCL
495+
implementation on the device
496+
* {CL_OUT_OF_HOST_MEMORY}
497+
** if there is a failure to allocate resources required by the OpenCL
498+
implementation on the host
475499
--
476500

477501
[open,refpage='clSetCommandQueueProperty',desc='Enable or disable properties of a command-queue.',type='protos']
@@ -508,16 +532,22 @@ OpenCL 1.0 devices.
508532
successfully.
509533
Otherwise, it returns one of the following errors:
510534

511-
* {CL_INVALID_COMMAND_QUEUE} if _command_queue_ is not a valid command-queue.
512-
* {CL_INVALID_OPERATION} if no devices in the context associated with
513-
_command_queue_ support modifying the properties of a command-queue.
514-
* {CL_INVALID_VALUE} if values specified in _properties_ are not valid.
515-
* {CL_INVALID_QUEUE_PROPERTIES} if values specified in _properties_ are
516-
valid but are not supported by the device.
517-
* {CL_OUT_OF_RESOURCES} if there is a failure to allocate resources required
518-
by the OpenCL implementation on the device.
519-
* {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
520-
required by the OpenCL implementation on the host.
535+
* {CL_INVALID_COMMAND_QUEUE}
536+
** if _command_queue_ is not a valid command-queue
537+
* {CL_INVALID_OPERATION}
538+
** if no devices in the context associated with _command_queue_ support
539+
modifying the properties of a command-queue
540+
* {CL_INVALID_VALUE}
541+
** if values specified in _properties_ are not valid
542+
* {CL_INVALID_QUEUE_PROPERTIES}
543+
** if values specified in _properties_ are valid but are not supported by
544+
the device associated with _command_queue_
545+
* {CL_OUT_OF_RESOURCES}
546+
** if there is a failure to allocate resources required by the OpenCL
547+
implementation on the device
548+
* {CL_OUT_OF_HOST_MEMORY}
549+
** if there is a failure to allocate resources required by the OpenCL
550+
implementation on the host
521551
--
522552

523553

0 commit comments

Comments
 (0)