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 實現分配資源時失敗。