Windows Opencl clEnqueueNDRangeKernel()函数

Windows Opencl clEnqueueNDRangeKernel()函数详细解析

Executing Kernels
函数原型

cl_int clEnqueueNDRangeKernel(cl_command_queue command_queue,
							  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_events_in_wait_list,
							  const cl_event *event_wait_list,
							  cl_event *event) 

clEnqueueNDRangeKernel()将命令排队以在设备上执行内核。

command_queue是有效的命令队列。内核将排队等待在与command_queue关联的设备上执行。

kernel 是一个有效的内核对象。与kernel 和command_queue 关联的OpenCL上下文必须相同。

work_dim 是用于指定全局工作项和工作组中工作项的维度数。work_dim 必须大于零且小于或等于3。

global_work_offset 当前必须为空值。在OpenCL的未来版本中，global_work_offset 可用于指定work_dim unsigned值的数组，这些值描述用于计算工作项的全局ID的偏移量，而不是让全局ID始终以偏移量（0，0，…0）开始。

global_work_size 指向一个work_dim 无符号值数组，这些值描述将执行内核函数的work_dim 维度中的全局工作项的数量。全局工作项的总数按global_work_size[0]*…*global_work_size[work_dim–1]计算。

在global_work_size中指定的值不能超过sizeof（size_t）为内核执行将被排队的设备指定的范围。设备的sizeof（size_t）可以使用表4.3中的CL_DEVICE_ADDRESS_BITS来确定。例如，如果CL_DEVICE_ADDRESS_BITS=32，即设备使用32位地址空间，则size_t是32位无符号整数，全局“工作”大小值必须在范围1…2^32-1内。超出此范围的值返回“CL_OUT_OF_RESOURCES”错误。

local_work_size指向一个work_dim unsigned值数组，该数组描述组成工作组（也称为工作组的大小）的工作项数，该工作组将执行kernel指定的内核。工作组中工作项的总数按local_work_size[0]…local_work_size[work_dim–1]计算。工作组中工作项的总数必须小于或等于表4.3中指定的CL_DEVICE_MAX_WORK_GROUP_SIZE值，并且在local_work_size[0]，…local_work_size[work_dim–1]中指定的工作项数必须小于或等于指定的CL_DEVICE_MAX_WORK_ITEM_SIZES[0]，…CL_DEVICE_MAX_WORK_ITEM_SIZES[work_dim - 1]的值。显式指定的local_work_size大小将用于确定如何将由global_work_size大小指定的全局工作项分解为适当的工作组实例。如果指定了local_work_size，则在global_work_size[0]，…global_work_size[work_dim - 1]中指定的值必须可以被local_work_size[0]，… local_work_size[work_dim–1]中指定的相应值整除。

用于内核的工作组大小也可以在程序源代码中使用__attribute__((reqd_work_group_size(X，Y，Z))限定符指定（参见第6.7.2节）。在这种情况下，由local_work_size 指定的工作组大小必须与reqd_work_group_size属性限定符指定的值匹配。

local_work_size 大小也可以是空值，在这种情况下，OpenCL实现将决定如何将全局工作项分解为适当的工作组实例。

这些工作组实例在多个计算单元之间并行执行，或者在同一计算单元上并发执行。

每个工作项由全局标识符唯一标识。可以在内核内部读取的全局ID是使用global_work_size和global_work_offset指定的值来计算的。在opencl1.0中，起始全局ID总是（0，0，…0）。此外，工作项还通过一个唯一的本地ID在工作组中标识。本地ID也可以被内核读取，它是使用local_work_size 给定的值来计算的。起始本地ID始终是（0，0，…0）。

event_wait_list 和num_events_in_wait_list 指定执行此特定命令之前需要完成的事件。如果event_wait_list 为空，则此特定命令不会等待任何事件完成。如果event_wait_list 为空，则num_events_in_wait_list 必须为0。如果event_wait_list 不为空，则event_wait_list 所指向的event_wait_list 必须有效，且num_events_in_wait_list 必须大于0。事件等待列表中指定的事件充当同步点。与event_wait_list和command_queue中的事件关联的上下文必须相同。

event返回标识此特定内核执行实例的事件对象。事件对象是唯一的，可以在以后用于标识特定的内核执行实例。如果event 为NULL，则不会为此内核执行实例创建任何事件，因此应用程序将无法查询或排队等待此特定的内核执行实例。

如果内核执行成功排队，clEnqueueNDRangeKernel将返回CL_SUCCESS。否则，将返回以下错误之一：

1. CL_INVALID_PROGRAM_EXECUTABLE 如果与command_queue 关联的设备没有成功生成的可执行程序。
2. CL_INVALID_COMMAND_QUEUE 如果命令队列不是有效的命令队列。
3. CL_INVALID_KERNEL 如果内核不是有效的内核对象
4. CL_INVALID_CONTEXT 如果与command_queue 和kernel 关联的上下文不相同，或者如果与command_queue 关联的上下文和事件在event_wait_list 中不相同。
5. CL_INVALID_KERNEL_ARGS 如果没有指定内核参数值。
6. CL_INVALID_WORK_DIMENSION 如果work_dim 不是有效值（即介于1和3之间的值）
7. CL_INVALID_GLOBAL_WORK_SIZE 如果global_work_size 为空，或者如果在global_work_size [0]，…global_work_size [work_dim–1]中指定的任何值为0或超出sizeof（size_t）为将要在其上排队执行内核的设备指定的范围。
8. CL_INVALID_WORK_GROUP_SIZE 如果指定了local_work_size 大小，而global_work_size 大小指定的工作项数目不能平均除以由local_work_size大小指定的工作组大小，或者与使用程序源中的__attribute__((reqd_work_group_size(X, Y, Z))) 为kernel指定的工作组大小不匹配。
9. CL_INVALID_WORK_GROUP_SIZE 如果指定了local_work_size，并且工作组中工作项的总数计算为local_work_size[0]*…local_work_size[work_dim–1]大于表4.3中CL_DEVICE_MAX_WORK_GROUP_SIZE指定的值。
10. CL_INVALID_WORK_GROUP_SIZE 如果local_work_size为空，并且__attribute__((reqd_work_group_size(X, Y, Z)))限定符用于在程序源中声明内核的工作组大小。
11. CL_INVALID_WORK_ITEM_SIZE 如果在任何一个local_work_size[0]，…local_work_size[work_dim–1]中指定的工作项数大于CL_DEVICE_MAX_WORK_ITEM_SIZES[0]指定的相应值…。设备最大CL_DEVICE_MAX_WORK_ITEM_SIZES[work_dim - 1]。
12. CL_INVALID_GLOBAL_OFFSET 如果global_work_offset不为空。
13. CL_OUT_OF_RESOURCES 如果由于执行内核所需的资源不足，无法将内核的执行实例排队到命令队列中。例如，显式指定的local_work_size会因为寄存器或本地内存等资源不足而导致内核执行失败。另一个例子是kernel 中使用的只读图像参数的数量超过设备的CL_DEVICE_MAX_READ_IMAGE_ARGS值，或者kernel 中使用的只写映像参数的数量超过设备的CL_DEVICE_MAX_WRITE_IMAGE_ARGS值，或者kernel 中使用的采样器数量超过设备的CL_DEVICE_MAX_SAMPLERS。
14. CL_MEM_OBJECT_ALLOCATION_FAILURE 如果无法为指定为kernel 参数的图像或缓冲区对象关联的数据存储分配内存。
15. CL_INVALID_EVENT_WAIT_LIST 如果event_wait_list 为空且num_events_in_wait_list >0，或event_wait_list不为NULL且num_events_in_wait_list 为0，或者event_wait_list 中的事件对象不是有效的事件。
16. CL_OUT_OF_HOST_MEMORY 如果在主机上分配OpenCL实现所需的资源失败。