clCommandNDRangeKernelKHR(3)

C Specification

To record a command to execute a kernel on a device, call the function

// Provided by cl_khr_command_buffer
cl_int clCommandNDRangeKernelKHR(
    cl_command_buffer_khr command_buffer,
    cl_command_queue command_queue,
    const cl_command_properties_khr* properties,
    cl_kernel kernel,
    cl_uint work_dim,
    const size_t* global_work_offset,
    const size_t* global_work_size,
    const size_t* local_work_size,
    cl_uint num_sync_points_in_wait_list,
    const cl_sync_point_khr* sync_point_wait_list,
    cl_sync_point_khr* sync_point,
    cl_mutable_command_khr* mutable_handle);

clCommandNDRangeKernelKHR is provided by the cl_khr_command_buffer extension.

Parameters

command_buffer refers to a valid command-buffer object.
command_queue specifies the command-queue the command will be recorded to.
If the cl_khr_command_buffer_multi_device extension is not supported, only a single command-queue is supported, and command_queue must be NULL.
If the cl_khr_command_buffer_multi_device extension is supported and command_queue is NULL, then only one command-queue must have been set on command_buffer creation; otherwise, command_queue must not be NULL.
properties specifies a list of properties for the kernel command and their corresponding values. Each property name is immediately followed by the corresponding desired value. The list is terminated with 0. If a supported property and its value is not specified in properties, its default value will be used. properties may be NULL, in which case the default values for supported properties will be used. The cl_khr_command_buffer extension does not define any properties, but supported properties defined by extensions are defined in the List of supported properties by clCommandNDRangeKernelKHR table.
kernel is a valid kernel object which must have its arguments set. Any changes to kernel after calling clCommandNDRangeKernelKHR, such as with clSetKernelArg or clSetKernelExecInfo, have no effect on the recorded command. If kernel is recorded to a following clCommandNDRangeKernelKHR command however, then that command will capture the updated state of kernel.
work_dim, global_work_offset, global_work_size, local_work_size Refer to clEnqueueNDRangeKernel.
sync_point_wait_list, num_sync_points_in_wait_list specify synchronization-points that need to complete before this particular command can be executed.

If sync_point_wait_list is NULL, num_sync_points_in_wait_list must be 0. If sync_point_wait_list is not NULL, the list of synchronization-points pointed to by sync_point_wait_list must be valid and num_sync_points_in_wait_list must be greater than 0. The synchronization-points specified in sync_point_wait_list are device-side synchronization-points. The command-buffer associated with synchronization-points in sync_point_wait_list must be the same as command_buffer. The memory associated with sync_point_wait_list can be reused or freed after the function returns.
sync_point returns a synchronization-point ID that identifies this particular command. Synchronization-point objects are unique and can be used to identify this command later on. sync_point can be NULL in which case it will not be possible for the application to record a wait for this command to complete. If the sync_point_wait_list and the sync_point arguments are not NULL, the sync_point argument should not refer to an element of the sync_point_wait_list array.
mutable_handle returns a handle to the command. If the cl_khr_command_buffer_mutable_dispatch extension is supported, and mutable_handle is not NULL, it can be used in the cl_mutable_dispatch_config_khr struct to update the command configuration between recordings. The lifetime of this handle is tied to the parent command-buffer, such that freeing the command-buffer will also free this handle.

Description

Table 1. List of supported properties by **clCommandNDRangeKernelKHR**
Recording Properties	Property Value	Description
`CL_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 this ND-range kernel will not be updated beyond the number defined when the ND-range kernel was recorded. The number of work-groups is defined as the product for each i from 0 to work_dim - 1 of ceil(global_work_size[i]/local_work_size[i]).
`CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR` provided by the `cl_khr_command_buffer_mutable_dispatch` extension.	`cl_mutable_dispatch_fields_khr`	This is a bitfield and can be set to a combination of the following values: `CL_MUTABLE_DISPATCH_GLOBAL_OFFSET_KHR` determines whether the global_work_offset of kernel execution can be modified after recording. If set, the global_work_offset of the kernel execution can be changed with clUpdateMutableCommandsKHR using the `cl_mutable_dispatch_config_khr` field of the mutable_config parameter. Otherwise, the global_work_offset cannot be modified. `CL_MUTABLE_DISPATCH_GLOBAL_SIZE_KHR` determines whether the global_work_size of kernel execution can be modified after recording. If set, the global_work_size of the kernel execution can be changed with clUpdateMutableCommandsKHR using the `cl_mutable_dispatch_config_khr` field of the mutable_config parameter. Otherwise, the global_work_size cannot be modified. `CL_MUTABLE_DISPATCH_LOCAL_SIZE_KHR` determines whether the local_work_size of kernel execution can be modified after recording. If set, the local_work_size of the kernel execution can be changed with clUpdateMutableCommandsKHR using the `cl_mutable_dispatch_config_khr` field of the mutable_config parameter. Otherwise, the local_work_size cannot be modified. `CL_MUTABLE_DISPATCH_ARGUMENTS_KHR` determines whether the kernel arguments set on kernel can be updated between executions. If set, the kernel arguments normally set with clSetKernelArg and clSetKernelArgSVMPointer can be changed with clUpdateMutableCommandsKHR using the `cl_mutable_dispatch_config_khr` field of the mutable_config parameter. Otherwise, the kernel arguments cannot be modified between executions. `CL_MUTABLE_DISPATCH_EXEC_INFO_KHR` determines whether the information passed to kernel can be updated between executions. If set, the execution information of the kernel can be changed with clUpdateMutableCommandsKHR using the `cl_mutable_dispatch_config_khr` field of the mutable_config parameter. Otherwise, the kernel execution information cannot be modified. If `CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR` is not specified then it defaults to the value returned by the `CL_DEVICE_MUTABLE_DISPATCH_CAPABILITIES_KHR` device query.

The work-group size to be used for kernel can also be specified in the program source using the __attribute__((reqd_work_group_size(X, Y, Z))) qualifier. In this case the size of work-group specified by local_work_size must match the value specified by the reqd_work_group_size __attribute__ qualifier.

These work-group instances are executed in parallel across multiple compute units or concurrently on the same compute unit.

Each work-item is uniquely identified by a global identifier. The global ID, which can be read inside the kernel, is computed using the value given by global_work_size and global_work_offset. In addition, a work-item is also identified within a work-group by a unique local ID. The local ID, which can also be read by the kernel, is computed using the value given by local_work_size. The starting local ID is always (0, 0, … 0).

clCommandNDRangeKernelKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the errors defined by clEnqueueNDRangeKernel except:

CL_INVALID_COMMAND_QUEUE is replaced with:

CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is not supported and command_queue is not NULL.
CL_INVALID_COMMAND_QUEUE if the cl_khr_command_buffer_multi_device extension is supported; and either command_queue is NULL and command_buffer was created with more than one queue, or command_queue is not NULL and not a command-queue listed on command_buffer creation.

CL_INVALID_CONTEXT is replaced with:

CL_INVALID_CONTEXT if the context associated with command_buffer and kernel is not the same.
CL_INVALID_CONTEXT if command_queue is not NULL, and the context associated with command_queue and command_buffer is not the same.

CL_INVALID_EVENT_WAIT_LIST is replaced with:

CL_INVALID_SYNC_POINT_WAIT_LIST_KHR if sync_point_wait_list is NULL and num_sync_points_in_wait_list is > 0, or sync_point_wait_list is not NULL and num_sync_points_in_wait_list is 0, or if synchronization-point objects in sync_point_wait_list are not valid synchronization-points.

New errors:

CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.
CL_INVALID_OPERATION if command_buffer has been finalized.
CL_INVALID_VALUE if values specified in properties are not valid.
CL_INVALID_VALUE if the cl_khr_command_buffer_mutable_dispatch extension is not supported and mutable_handle is not NULL.
CL_INVALID_OPERATION if the device associated with command_queue does not support CL_COMMAND_BUFFER_CAPABILITY_KERNEL_PRINTF_KHR and kernel contains a printf call.
CL_INVALID_OPERATION if the device associated with command_queue does not support CL_COMMAND_BUFFER_CAPABILITY_DEVICE_SIDE_ENQUEUE_KHR and kernel contains a kernel-enqueue call.

If the cl_khr_command_buffer_mutable_dispatch extension is supported:

CL_INVALID_OPERATION if the requested CL_MUTABLE_DISPATCH_UPDATABLE_FIELDS_KHR properties are not reported by CL_DEVICE_MUTABLE_DISPATCH_CAPABILITIES_KHR for the device associated with command_queue. If command_queue is NULL, the device associated with command_buffer must report support for these properties.
CL_INVALID_VALUE if command_buffer was created with the CL_COMMAND_BUFFER_MUTABLE_DISPATCH_ASSERTS_KHR property with CL_MUTABLE_DISPATCH_ASSERT_NO_ADDITIONAL_WORK_GROUPS_KHR and local_work_size is NULL, or if properties includes the CL_MUTABLE_DISPATCH_ASSERTS_KHR property with CL_MUTABLE_DISPATCH_ASSERT_NO_ADDITIONAL_WORK_GROUPS_KHR and local_work_size is NULL.

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

clCommandNDRangeKernelKHR(3) Manual Page

Name

C Specification

Parameters

Description

See Also

Document Notes

Copyright