OpenCL - clGetDeviceIDs - clGetDeviceInfo

OpenCL - clGetDeviceIDs - clGetDeviceInfo

1. clGetDeviceIDs

https://www.khronos.org/registry/OpenCL/sdk/1.2/docs/man/xhtml/
Obtain the list of devices available on a platform.
获取平台上可用设备的列表。

cl_int clGetDeviceIDs (cl_platform_id  platform ,
 	cl_device_type  device_type ,
 	cl_uint  num_entries ,
 	cl_device_id  *devices ,
 	cl_uint  *num_devices )

1.1 Parameters

• platform

Refers to the platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.
即 clGetPlatformIDs 所返回的平台 ID，也可能是 NULL。如果 platform 为 NULL，则其行为依赖于具体实现。

• device_type

A bitfield that identifies the type of OpenCL device. The device_type can be used to query specific OpenCL devices or all OpenCL devices available. The valid values for device_type are specified in the following table.
标识 OpenCL 设备类型的位域。device_type 可以用来查询特定的 OpenCL 设备或所有可用的 OpenCL 设备。下表指定了 device_type 的有效值。

cl_device_type	Description
CL_DEVICE_TYPE_CPU	An OpenCL device that is the host processor. The host processor runs the OpenCL implementations and is a single or multi-core CPU. 主机处理器运行 OpenCL 实现，是单核或多核 CPU。
CL_DEVICE_TYPE_GPU	An OpenCL device that is a GPU. By this we mean that the device can also be used to accelerate a 3D API such as OpenGL or DirectX. 这意味着此设备也可以用来加速 3D API (如 OpenGL 或 DirectX)。
CL_DEVICE_TYPE_ACCELERATOR	Dedicated OpenCL accelerators (for example the IBM CELL Blade). These devices communicate with the host processor using a peripheral interconnect such as PCIe. OpenCL 专用加速器 (如 IBM CELL Blade)。这些设置通过外围设备互联总线 (如 PCIe) 与主处理器通信。
CL_DEVICE_TYPE_CUSTOM	Dedicated accelerators that do not support programs written in OpenCL C. 不支持用 OpenCL C 编写的程序的专用加速器。
CL_DEVICE_TYPE_DEFAULT	The default OpenCL device in the system. The default device cannot be a CL_DEVICE_TYPE_CUSTOM device. 系统中的默认 OpenCL 设备。 默认设备不能是 CL_DEVICE_TYPE_CUSTOM 设备。
CL_DEVICE_TYPE_ALL	All OpenCL devices available in the system except CL_DEVICE_TYPE_CUSTOM devices. 系统中所有可用的 OpenCL 设备，CL_DEVICE_TYPE_CUSTOM 设备除外。

• num_entries

The number of cl_device_id entries that can be added to devices. If devices is not NULL, the num_entries must be greater than zero.
可以添加到 devices 中的 cl_device_id 条目的数量。如果 devices 不为 NULL，则 num_entries 必须大于零。

• devices

A list of OpenCL devices found. The cl_device_id values returned in devices can be used to identify a specific OpenCL device. If devices argument is NULL, this argument is ignored. The number of OpenCL devices returned is the mininum of the value specified by num_entries or the number of OpenCL devices whose type matches device_type.
devices 用来返回所找到的 OpenCL 设备。devices 中返回的 cl_device_id 用来标识一个 OpenCL 设备。如果参数 devices 是 NULL，则忽略。所返回的 OpenCL 设备数目为 num_entries 或符合 device_type 的设备数目，取二者中较小的那个。

• num_devices

The number of OpenCL devices available that match device_type. If num_devices is NULL, this argument is ignored.
与 device_type 相匹配的 OpenCL 可用的设备的数量。如果 num_devices 为 NULL，则忽略该参数。

clGetDeviceIDs may return all or a subset of the actual physical devices present in the platform and that match device_type.
clGetDeviceIDs 可能返回 platform 中所有与 device_type 匹配的真正的物理设备，也可能只是其中一个子集。

1.2 Errors

clGetDeviceIDs returns CL_SUCCESS if the function is executed successfully. Otherwise it returns one of the following:
如果函数执行成功，clGetDeviceIDs 返回 CL_SUCCESS。否则，它返回以下之一：

• CL_INVALID_PLATFORM if platform is not a valid platform. 如果 platform 无效。
• CL_INVALID_DEVICE_TYPE if device_type is not a valid value. 如果 device_type 无效。
• CL_INVALID_VALUE if num_entries is equal to zero and devices is not NULL or if both num_devices and devices are NULL. 如果 num_entries 等于零且 devices 不是 NULL，或者 num_devices 和 devices 都是 NULL。
• CL_DEVICE_NOT_FOUND if no OpenCL devices that matched device_type were found. 如果沒有找到任何符合 device_type 的 OpenCL 设备。
• CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. 如果在为设备上的 OpenCL 实现分配资源时失败。
• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host. 如果在为主机上的 OpenCL 实现分配资源时失败。

对于 clGetDeviceIDs 所返回的 OpenCL 设备，应查询其能力，从而決定使用哪些设备。

2. clGetDeviceInfo

https://www.khronos.org/registry/OpenCL/sdk/1.2/docs/man/xhtml/

Get information about an OpenCL device.
获取有关 OpenCL 设备的信息。

cl_int clGetDeviceInfo (cl_device_id  device ,
 	cl_device_info  param_name ,
 	size_t  param_value_size ,
 	void  *param_value ,
 	size_t  *param_value_size_ret)

2.1 Parameters

• device

May be a device returned by clGetDeviceIDs or a sub-device created by clCreateSubDevices. If device is a sub-device, the specific information for the sub-device will be returned. The information that can be queried using clGetDeviceInfo is specified in the table below.
可能是由 clGetDeviceIDs 返回的设备，也可能是由 clCreateSubDevices 创建的子设备。如果 device 是子设备，则将返回该子设备的特定信息。下表指定了可以使用 clGetDeviceInfo 查询的信息。

• param_value

A pointer to memory location where appropriate values for a given param_name as specified in the table below will be returned. If param_value is NULL, it is ignored.
指向内存位置的指针，将返回下表中指定的给定 param_name 的适当值。如果 param_value 为 NULL，则将其忽略。

• param_value_size

Specifies the size in bytes of memory pointed to by param_value. This size in bytes must be ≥ size of return type specified in the table below.
指定 param_value 指向的内存大小 （以字节为单位）。此字节大小必须 ≥ 下表中指定的返回类型的大小。

• param_value_size_ret

Returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.
返回由 param_value 查询的数据的实际大小 （以字节为单位）。如果 param_value_size_ret 为 NULL，则将其忽略。

• param_name

An enumeration constant that identifies the device information being queried. It can be one of the values as specified in the table below.
一个枚举常量，用于标识要查询的设备信息。它可以是下表中指定的值之一。

CL_DEVICE_PROFILE: The platform profile returns the profile that is implemented by the OpenCL framework. If the platform profile returned is FULL_PROFILE, the OpenCL framework will support devices that are FULL_PROFILE and may also support devices that are EMBEDDED_PROFILE. The compiler must be available for all devices i.e. CL_DEVICE_COMPILER_AVAILABLE is CL_TRUE. If the platform profile returned is EMBEDDED_PROFILE, then devices that are only EMBEDDED_PROFILE are supported.
平台配置文件返回由 OpenCL 框架实现的配置文件。如果返回的平台配置文件为 FULL_PROFILE，则 OpenCL 框架将支持 FULL_PROFILE 的设备，也可能支持 EMBEDDED_PROFILE 的设备。编译器必须适用于所有设备，即 CL_DEVICE_COMPILER_AVAILABLE 为 CL_TRUE。如果返回的平台配置文件是 EMBEDDED_PROFILE，则仅支持 EMBEDDED_PROFILE 的设备。

The device queries described the table above should return the same information for a root-level device i.e. a device returned by clGetDeviceIDs and any sub-devices created from this device except for the following queries:
无论对于根级设备 （即 clGetDeviceIDs 所返回的设备） 还是由他创建的子设备，上表所述的设备查询都会返回相同的信息，但以下查询除外：

• CL_DEVICE_GLOBAL_MEM_CACHE_SIZE
• CL_DEVICE_BUILT_IN_KERNELS
• CL_DEVICE_PARENT_DEVICE
• CL_DEVICE_PARTITION_TYPE
• CL_DEVICE_REFERENCE_COUNT

2.2 Errors

clGetDeviceInfo returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:
如果执行成功，clGetDeviceInfo 会返回 CL_SUCCESS。否则，返回下列错误码之一：

• CL_INVALID_DEVICE if device is not valid. 如果 device 无效。
• CL_INVALID_VALUE if param_name is not one of the supported values or if size in bytes specified by param_value_size is less than size of return type as shown in the table above and param_value is not a NULL value or if param_name is a value that is available as an extension and the corresponding extension is not supported by the device. 如果不支持 param_name；或者 param_value_size 的值 < 表中所列返回类别的大小，并且 param_value 不是 NULL；或者 param_name 指的是某个扩展，但是此设备不支持此扩展。
• CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device. 如果在为设备上的 OpenCL 实现分配资源时失败。
• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host. 如果在为主机上的 OpenCL 实现分配资源时失败。