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
ifplatform
is not a valid platform. 如果platform
無效。CL_INVALID_DEVICE_TYPE
ifdevice_type
is not a valid value. 如果device_type
無效。CL_INVALID_VALUE
ifnum_entries
is equal to zero anddevices
is not NULL or if bothnum_devices
anddevices
are NULL. 如果num_entries
等於零且devices
不是NULL
,或者num_devices
和devices
都是NULL
。CL_DEVICE_NOT_FOUND
if no OpenCL devices that matcheddevice_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
ifdevice
is not valid. 如果device
無效。CL_INVALID_VALUE
ifparam_name
is not one of the supported values or if size in bytes specified byparam_value_size
is less than size of return type as shown in the table above andparam_value
is not a NULL value or ifparam_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 實現分配資源時失敗。