clCreateCommandBufferKHR(3)

C Specification

To create a command-buffer that can record commands to the specified queues, call the function

// Provided by cl_khr_command_buffer
cl_command_buffer_khr clCreateCommandBufferKHR(
    cl_uint num_queues,
    const cl_command_queue* queues,
    const cl_command_buffer_properties_khr* properties,
    cl_int* errcode_ret);

clCreateCommandBufferKHR is provided by the cl_khr_command_buffer extension.

Parameters

num_queues is the number of command-queues listed in queues. If the cl_khr_command_buffer_multi_device extension is not supported, this must be one.
queues is a pointer to a list of command-queues that the command-buffer commands will be recorded to. queues must be a non-NULL value and the length of the list equal to num_queues.

properties specifies a list of properties for the command-buffer and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. The list of supported properties is described in the table below. If a supported property and its value is not specified in properties, its default value will be used. properties can be NULL in which case the default values for supported command-buffer properties will be used.

Table 1. **clCreateCommandBufferKHR** properties
Recording Properties	Property Value	Description == Description
`CL_COMMAND_BUFFER_FLAGS_KHR` provided by the `cl_khr_command_buffer` extension.	`cl_command_buffer_flags_khr`	This is a bitfield and can be set to a combination of the following values: `CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR` - Allow multiple instances of the command-buffer to be submitted to the device for execution. If set, devices must support `CL_COMMAND_BUFFER_CAPABILITY_SIMULTANEOUS_USE_KHR`. provided by the `cl_khr_command_buffer` extension. `CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR` - All commands in the command-buffer must use native synchronization, as reported by `CL_DEVICE_COMMAND_BUFFER_SYNC_DEVICES_KHR`. This can be used as a safeguard for performant applications that do not want to accidentally fallback to host synchronization when passing multiple queues. provided by the `cl_khr_command_buffer_multi_device` extension. `CL_COMMAND_BUFFER_MUTABLE_KHR` - Enables modification of the command-buffer, by default command-buffers are immutable. If set, commands in the command-buffer may be updated via clUpdateMutableCommandsKHR. provided by the `cl_khr_command_buffer_mutable_dispatch` extension. The default value of this property is `0`.
`CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR` provided by the `cl_khr_command_buffer_mutable_dispatch` extension.	`cl_mutable_dispatch_asserts_khr`	This is a bitfield and can be set to a combination of the following values: `CL_MUTABLE_DISPATCH_ASSERT_NO_ADDITIONAL_WORK_GROUPS_KHR` - An assertion by the user that the number of work-groups of any ND-range kernel recorded in this command buffer will not be updated beyond the number defined when the ND-range kernel was recorded. If the user’s update to the values of local_work_size and/or global_work_size result in an increase in the number of work-groups in the ND-range over the number specified when the ND-range kernel was recorded, the behavior is undefined. provided by the `cl_khr_command_buffer_mutable_dispatch` extension.

errcode_ret will return an appropriate error code. If errcode_ret is NULL, no error code is returned.

Table 2. Summary of multi-device command-buffer creation configurations
All Devices Associated With `Queues` can Device-side Sync	Platform Supports Universal Sync	Condition	Result
Yes	Yes or No	Any device does not support the multi-queue capability, and has more than one queue targeting it	Error - `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR`
		User sets `CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR` flag	OK
		Otherwise	OK
No	Yes	Any device does not support the multi-queue capability, and has more than one queue targeting it	Error - `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR`
		User sets `CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR` flag	Error - `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR`
		Otherwise	OK - May be performance implications when synchronizing commands between devices without device-side sync support.
No	No	Always	Error - `CL_INCOMPATIBLE_COMMAND_QUEUE_KHR`

Upon creation the command-buffer is defined as being in the Recording state, in order for the command-buffer to be enqueued it must first be finalized using clFinalizeCommandBufferKHR after which no further commands can be recorded. A command-buffer is submitted for execution on command-queues with a call to clEnqueueCommandBufferKHR.

clCreateCommandBufferKHR returns a valid non-zero command-buffer and errcode_ret is set to CL_SUCCESS if the command-buffer is created successfully. Otherwise, it returns a NULL value with one of the following error values returned in errcode_ret:

CL_INVALID_COMMAND_QUEUE if any command-queue in queues is not a valid command-queue.
CL_INVALID_CONTEXT if all the command-queues in queues do not have the same OpenCL context.
CL_INVALID_VALUE if the cl_khr_command_buffer_multi_device extension is supported and num_queues is zero, or if the cl_khr_command_buffer_multi_device extension is not supported and num_queues is not one.
CL_INVALID_VALUE if queues is NULL.
CL_INVALID_VALUE if values specified in properties are not valid, or if the same property name is specified more than once.
CL_INVALID_PROPERTY if values specified in properties are valid but are not supported by all the devices associated with command-queues in queues.
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.

If the cl_khr_command_buffer_multi_device extension is supported:

CL_INCOMPATIBLE_COMMAND_QUEUE_KHR if queues includes more than one command-queue associated with a device that does not support capability CL_COMMAND_BUFFER_CAPABILITY_MULTIPLE_QUEUE_KHR.
CL_INCOMPATIBLE_COMMAND_QUEUE_KHR if the CL_COMMAND_BUFFER_DEVICE_SIDE_SYNC_KHR flag is set, and any device associated with a command-queue in queues cannot natively synchronize with the other devices associated with queues as reported by CL_DEVICE_COMMAND_BUFFER_SYNC_DEVICES_KHR.
CL_INCOMPATIBLE_COMMAND_QUEUE_KHR if the platform does not support the CL_COMMAND_BUFFER_PLATFORM_UNIVERSAL_SYNC_KHR capability, and any device associated with a command-queue in queues cannot natively synchronize with the other devices associated with queues as reported by CL_DEVICE_COMMAND_BUFFER_SYNC_DEVICES_KHR.

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

SPDX-License-Identifier: CC-BY-4.0

clCreateCommandBufferKHR(3) Manual Page

Name

C Specification

Parameters

See Also

Document Notes

Copyright