Skip to content

Commit

Permalink
Command-buffer query for supported queue properties
Browse files Browse the repository at this point in the history 
This change introduces a new device query related to the
command-buffer extension -
`CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`.

This is different from
`CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR`, as we want
to convey to the user that an implementation supports using a queue
property with a command-buffer, but is not *required* to use the
property.

This supersedes reporting queue related values from the
`CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR` query. The flaw
with `CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR` is that it contains bits
explicitly added by the command-buffer extension for reporting support for
queue properties. This is a brittle design, as any new queue property added
in future would need to have a new bit added here in the command-buffer extension
to report support when used with command-buffers.

Instead a better design is to have a new query reporting queue
properties supported,
`CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`, and keeping
`CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR` for capabilities unrelated
to the command-queue properties.

The `CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR` use-case can now be
covered by returning
`CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE` from
`CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`, so it is
removed.

This will also make it possible for implementations to not have to
support profiling of command-buffers, by not reporting
`CL_QUEUE_PROFILING_ENABLE` from `CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`
  • Loading branch information
@EwanC
EwanC committed Sep 28, 2022
1 parent 996a022 commit 3a44a7b
Show file tree
Hide file tree
Showing 2 changed files with 17 additions and 14 deletions.
22 changes: 13 additions & 9 deletions ext/cl_khr_command_buffer.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ This extension adds the ability to record and replay buffers of OpenCL commands.
| *Date* | *Version* | *Description*
| 2021-11-10 | 0.9.0 | First assigned version (provisional).
| 2022-08-24 | 0.9.1 | Specify an error if a command-buffer is finalized multiple times (provisional).
| 2022-09-28 | 0.9.2 | Add device query for supported queue properties (provisional).
|====

==== Dependencies
Expand Down Expand Up @@ -385,14 +386,14 @@ Enums for querying device command-buffer capabilities with
[source]
----
// Accepted values for the param_name parameter to clGetDeviceInfo
CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR 0x12A9
CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR 0x12AA
CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR 0x12A9
CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR 0x1299
CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR 0x12AA
// Bits for cl_device_command_buffer_capabilities_khr bitfield
CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR (0x1 << 0)
CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR (0x1 << 1)
CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR (0x1 << 2)
CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR (0x1 << 3)
// Values for cl_command_buffer_state_khr
CL_COMMAND_BUFFER_STATE_RECORDING_KHR 0x0
Expand Down Expand Up @@ -452,8 +453,12 @@ Add to *Table 5*, _Device Queries_, of section 4.2:
`CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR` Device supports the
command-buffers having a <<pending_count, Pending Count>> that exceeds 1.

`CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR` Device supports the ability
to record command-buffers to out-of-order command-queues.
| `CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`
| `cl_command_queue_properties`
| Bitmask of the supported properties with which a command-queue may be created
to allow a command-buffer to be executed on it. It is invalid for a
command-queue to be created with a property not reported and still be
compatible with command-buffer execution.

| `CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR`
| `cl_command_queue_properties`
Expand Down Expand Up @@ -589,10 +594,9 @@ error values returned in _errcode_ret_:
* `CL_INVALID_COMMAND_QUEUE` if any command-queue in _queues_ is not a valid
command-queue.

* `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR` if any command-queue in _queues_ is an
out-of-order command-queue and the device associated with the command-queue
does not support the `CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR`
capability.
* `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR` if the properties of any command-queue in
_queues_ contains a property not specified by
`CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR`.

* `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR` if the properties of any command-queue in
_queues_ does not contain the minimum properties specified by
Expand Down
9 changes: 4 additions & 5 deletions xml/cl.xml
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
<?xml version="1.0" encoding="UTF-8"?>
<registry>
<comment>
Copyright 2013-2022 The Khronos Group Inc.
Expand Down Expand Up @@ -1295,7 +1294,7 @@ server's OpenCL/api-docs repository.
<enum bitpos="0" name="CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR"/>
<enum bitpos="1" name="CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR"/>
<enum bitpos="2" name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
<enum bitpos="3" name="CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR"/>
<unused start="3" end="3" comment="Available for future use"/>
<unused start="4" end="5" comment="Used by future command-buffer extensions"/>
<unused start="6" end="31"/>
</enums>
Expand Down Expand Up @@ -1726,7 +1725,7 @@ server's OpenCL/api-docs repository.
<enum value="0x1296" name="CL_COMMAND_BUFFER_REFERENCE_COUNT_KHR"/>
<enum value="0x1297" name="CL_COMMAND_BUFFER_STATE_KHR"/>
<enum value="0x1298" name="CL_COMMAND_BUFFER_PROPERTIES_ARRAY_KHR"/>
<unused start="0x1299" comment="Reserved for MR199"/>
<enum value="0x1299" name="CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR"/>
<unused start="0x129A" end="0x129F" comment="Available to use"/>
<enum value="0x12A0" name="CL_MUTABLE_COMMAND_COMMAND_QUEUE_KHR"/>
<enum value="0x12A1" name="CL_MUTABLE_COMMAND_COMMAND_BUFFER_KHR"/>
Expand Down Expand Up @@ -7001,7 +7000,7 @@ server's OpenCL/api-docs repository.
<command name="clSetContentSizeBufferPoCL"/>
</require>
</extension>
<extension name="cl_khr_command_buffer" comment="in sync with version 0.9.0" supported="opencl">
<extension name="cl_khr_command_buffer" comment="in sync with version 0.9.2" supported="opencl">
<require>
<type name="CL/cl.h"/>
</require>
Expand All @@ -7018,13 +7017,13 @@ server's OpenCL/api-docs repository.
</require>
<require comment="cl_device_info">
<enum name="CL_DEVICE_COMMAND_BUFFER_CAPABILITIES_KHR"/>
<enum name="CL_DEVICE_COMMAND_BUFFER_SUPPORTED_QUEUE_PROPERTIES_KHR"/>
<enum name="CL_DEVICE_COMMAND_BUFFER_REQUIRED_QUEUE_PROPERTIES_KHR"/>
</require>
<require comment="cl_device_command_buffer_capabilities_khr - bitfield">
<enum name="CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR"/>
<enum name="CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR"/>
<enum name="CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR"/>
<enum name="CL_COMMAND_BUFFER_CAPABILITY_OUT_OF_ORDER_KHR"/>
</require>
<require comment="cl_command_buffer_properties_khr">
<enum name="CL_COMMAND_BUFFER_FLAGS_KHR"/>
Expand Down

0 comments on commit 3a44a7b

Please sign in to comment.