get_global_size - get_global_id - get_local_size - get_local_id - get_num_groups - get_group_id

OpenCL Work-Item Functions (工作项函数) - get_work_dim - get_global_size - get_global_id - get_local_size - get_local_id - get_num_groups - get_group_id - get_global_offset

1. Built-in Functions - OpenCL C 内置函数

OpenCL 3.0 Reference Pages
https://www.khronos.org/registry/OpenCL/sdk/3.0/docs/man/html/

The OpenCL C programming language provides a rich set of built-in functions for scalar and vector operations. Many of these functions are similar to the function names provided in common C libraries but they support scalar and vector argument types. Applications should use the built-in functions wherever possible instead of writing their own version.
OpenCL C 编程语言提供了一套丰富的内置函数用于标量和矢量运算。这些函数中有很多跟通用 C 库中提供的函数名字类似 (math.h 中定义的函数)，不同的是他们所支持的参数型别既可是标量，也可是矢量。OpenCL C 函数支持标量和矢量参数类型，建议直接使用而不要自行编写。

User defined OpenCL C functions behave per C standard rules for functions as defined in section 6.9.1 of the C99 Specification. On entry to the function, the size of each variably modified parameter is evaluated and the value of each argument expression is converted to the type of the corresponding parameter as per the usual arithmetic conversion rules. Built-in functions described in this section behave similarly, except that in order to avoid ambiguity between multiple forms of the same built-in function, implicit scalar widening shall not occur. Note that some built-in functions described in this section do have forms that operate on mixed scalar and vector types, however.
用户自定义的 OpenCL C 函数的行为符合 C99 规范第 6.9.1 节中定义的函数的 C 标准规则。在函数入口处，对于所有动态变化的参数 (variably modified parameter) 都会求出其大小，并根据通常的算术转换规则将每个参数表达式的值转换为相应参数的类型。本节所描述的内置函数行为类似，不过由于同一个内置函数可能有多种形式，为避免歧义，不会有隐式的标量拓宽。注意，某些内置函数的某些形式是针对标量以及矢量型别的混合运算。

behave [bɪ'heɪv]：v. 行为，表现，举止，规矩

OpenCL 3.0 Reference Pages -> OpenCL Compiler -> Built-in Functions

• Work-Item Functions - 工作项函数
• Math Functions - 数学函数
• Integer Functions - 整数函数
• Common Functions - 公共函数
• Geometric Functions - 几何函数
• Relational Functions - 关系函数
• Vector Data Load and Store Functions - 矢量数据加载和存储函数
• Synchronization Functions - 同步函数
• Legacy Explicit Memory Fence Functions
• Address Space Qualifier Functions
• Async Copies from Global to Local Memory, Local to Global Memory, and Prefetch - 异步复制和预取函数
• Atomic Functions - 原子函数
• Miscellaneous Vector Functions - 杂项矢量函数
• printf
• Image Read and Write Functions - 内置图像读和写函数
• Work-group Collective Functions
• Pipe Functions
• Enqueuing Kernels
• Subgroup Functions

synchronization [ˌsɪŋkrənaɪ'zeɪʃ(ə)n]：n. 同时，同时性，同步，同期录音
asynchronization [əsɪŋkrənaɪ'zeɪʃ(ə)n]：n. 异步，不同步性，非同步化
geometric [ˌdʒiːəˈmetrɪk]：adj. 几何的，几何图形的 n. 有几何图形的东西
miscellaneous [.mɪsə'leɪniəs]：adj. 混杂的，各种各样的

2. Work-Item Functions - 工作项函数

Built-in Work-Item Functions - 内置工作项函数

Introduction

应用程序使用 clEnqueueNDRangeKernel 和 clEnqueueTask API 将 OpenCL 中的数据并行和任务并行内核排队。对于一个数据并行内核 (使用 clEnqueueNDRangeKernel 排队等待执行)，应用程序会指定全局工作大小，即可以并行执行这个内核的工作项总数，还会指定局部工作大小，即可以归组到一个工作组中的工作项数目。

如果使用的是 clEnqueueNDRangeKernel，则查询给定的维数、全局和局部的索引空间大小、以及在设备上执行此内核时每个作业项的全局 ID 和局部 ID。
如果使用的是 clEnqueueTask，则给定的维数、全局和局部索引空间的大小都是一。

work-item functions - 工作项函数

设备上执行的内核可以访问 clEnqueueNDRangeKernel 中指定的全局工作大小和局部工作大小。执行内核的全局工作大小为 16 个工作项，工作组大小为每组 8 个工作项。

OpenCL 没有描述全局 ID 和局部 ID 如何映射到工作项和工作组。一个应用程序不会假设组 ID 为 0 的工作组就包含全局 ID 为 0 ~ get_local_size(0) - 1 的工作项。这个映射由 OpenCL 实现以及执行内核的设备来确定。

一个任务由多个 work-group 组成，work-group 又由多个 work-item 组成。各个 work-group 之间不相互通信，也不能保证同时运行，而同一个 work-group 内的 work-item 之间可以相互通信，并且可认为是同时进行的。

OpenCL 工作组、工作项和处理单元：
工作项：一个循环中最里面的一次运算，称为一个工作项。
工作组：由访问相同处理资源的工作项组成。
处理单元：支持工作组的处理资源被称为处理单元，各个工作组在单个处理单元上的执行，各个处理单元一次只能够执行一个工作组。

处理单元的数量由硬件决定，OpenCL 的内核函数应根据处理单元数量合理设置工作组和工作项，而工作项往往是一个具体的运算，例如矩阵乘法里的乘加运算。

Description

The following table describes the list of built-in work-item functions that can be used to query the number of dimensions, the global and local work size specified to clEnqueueNDRangeKernel, and the global and local identifier of each work-item when this kernel is being executed on a device.
内置工作项函数可用于查询指定给 clEnqueueNDRangeKernel 的维度数、全局和局部索引空间大小，以及在设备上执行此内核时每个工作项的全局 ID 和局部 ID。

2.1 get_work_dim

Returns the number of dimensions in use. This is the value given to the work_dim argument specified in clEnqueueNDRangeKernel.
返回使用的维度数目。这是 clEnqueueNDRangeKernel 中指定的 work_dim 的参数值。

uint get_work_dim()

返回线程调度的维度数，表示 NDRange 的维度数。

2.2 get_global_size

Returns the number of global work-items specified for dimension identified by dimindx. This value is given by the global_work_size argument to clEnqueueNDRangeKernel.
返回在 dimindx 所标识的维度上指定的全局作业项的数目。该值由 clEnqueueNDRangeKernel 的 global_work_size 参数提供。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_global_size() returns 1.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_global_size 返回 1。

size_t get_global_size(uint dimindx)

返回对应维度上全局工作项的数量，即所请求维度上 work-item 的总数。在不考虑多维度的情况下，返回全局计算任务数，即 work-item 总数。

2.3 get_global_id

Returns the unique global work-item ID value for dimension identified by dimindx. The global work-item ID specifies the work-item ID based on the number of global work-items specified to execute the kernel.
返回工作项在 dimindx 所标识的维度上的唯一全局 ID。全局工作项 ID 根据为执行内核指定的全局工作项数目来指定工作项 ID。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_global_id() returns 0.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_global_id() 返回 0。

size_t get_global_id(uint dimindx)

返回对应维度上对应全局工作项索引，即返回在所请求的维度上当前 work-item 在全局空间中的索引。在不考虑多维度的情况下，返回全局中当前索引位置。

2.4 get_local_size

Returns the number of local work-items specified in dimension identified by dimindx. This value is at most the value given by the local_work_size argument to clEnqueueNDRangeKernel if local_work_size is not NULL; otherwise the OpenCL implementation chooses an appropriate local_work_size value which is returned by this function. If the kernel is executed with a non-uniform work-group size (i.e. the global_work_size values specified to clEnqueueNDRangeKernel are not evenly divisible by the local_work_size values for each dimension.), calls to this built-in from some work-groups may return different values than calls to this built-in from other work-groups.
返回在 dimindx 所标识的维度上指定的局部工作项的数目。如果 clEnqueueNDRangeKernel 的参数 local_work_size 不是 NULL，则返回的就是此参数的值；否则 OpenCL 实现会选择一个恰当的 local_work_size 并将其返回。如果内核以非统一的 work-group size 执行 (即指定给 clEnqueueNDRangeKernel 的 global_work_size 值不能被每个维度的 local_work_size 值整除。)，则从某些工作组调用此内置函数可能返回与从其他工作组调用此内置函数不同的值。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_local_size() returns 1.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_local_size() 返回 1。

size_t get_local_size(uint dimindx)

返回在所请求维度上 work-group 的大小。在不考虑多维度的情况下，返回当前 work-group 内所含 work-item 的数量。

2.5 get_local_id

Returns the unique local work-item ID, i.e. a work-item within a specific work-group for dimension identified by dimindx.
返回工作项在工作组内 dimindx 所标识的维度上的唯一局部 ID。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_local_id() returns 0.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_local_id() 返回 0。

size_t get_local_id(uint dimindx)

返回在所请求的维度上，当前 work-item 在 work-group 中的索引。在不考虑多维度的情况下，返回当前位置在当前 work-group 内索引。

2.6 get_num_groups

Returns the number of work-groups that will execute a kernel for dimension identified by dimindx.
返回执行此内核的工作组在 dimindx 所标识的维度上的数目。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values of dimindx, get_num_groups() returns 1.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_num_groups() 返回 1。

size_t get_num_groups(uint dimindx)

返回在所请求维度上 work-group 的数目，这个值等于 get_global_size 除以 get_local_size，返回组数。

2.7 get_group_id

get_group_id returns the work-group ID which is a number from 0 ... get_num_groups(dimindx) - 1.
所返回的工作组 ID 取值范围为 0 ... get_num_groups(dimindx) - 1。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values, get_group_id() returns 0.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_group_id() 返回 0。

size_t get_group_id(uint dimindx)

返回在所请求的维度上当前 work-group 在全局空间中的索引。在不考虑多维度的情况下，返回当前组在所有组中的索引。

2.8 get_global_offset

get_global_offset returns the offset values specified in global_work_offset argument to clEnqueueNDRangeKernel.
返回 clEnqueueNDRangeKernel 的 global_work_offset 参数中指定的偏移值。

Valid values of dimindx are 0 to get_work_dim() - 1. For other values, get_global_offset() returns 0.
dimindx 的合法取值范围为 0 到 get_work_dim() - 1。对于其他 dimindx 值，get_global_offset() 返回 0。

Requires support for OpenCL C 1.1 or newer.

size_t get_global_offset(uint dimindx)

References

Khronos OpenCL Registry
https://www.khronos.org/registry/OpenCL/

OpenCL 3.0 Reference Pages
https://www.khronos.org/registry/OpenCL/sdk/3.0/docs/man/html/

OpenCL C Language Specification
https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html