OpenCL - clGetPlatformIDs - clGetPlatformInfo

OpenCL - clGetPlatformIDs - clGetPlatformInfo

1. clGetPlatformIDs

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

Obtain the list of platforms available.
获取可用平台的列表。

cl_int clGetPlatformIDs(cl_uint num_entries,
 	                    cl_platform_id *platforms,
 	                    cl_uint *num_platforms)

1.1 Parameters

• num_entries

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

• platforms

Returns a list of OpenCL platforms found. The cl_platform_id values returned in platforms can be used to identify a specific OpenCL platform. If platforms argument is NULL, this argument is ignored. The number of OpenCL platforms returned is the mininum of the value specified by num_entries or the number of OpenCL platforms available.
返回找到的 OpenCL 平台的列表。platforms 中的每个 cl_platform_id 都用来标识某个特定的 OpenCL 平台。如果 platforms 参数为 NULL，则忽略此参数。返回的 OpenCL 平台数量是 num_entries 和实际数目中较小的那个。

• num_platforms

Returns the number of OpenCL platforms available. If num_platforms is NULL, this argument is ignored.
返回可用的 OpenCL 平台数。 如果 num_platforms 是 NULL，则忽略该参数。

1.2 Errors

Returns CL_SUCCESS if the function is executed successfully. Otherwise it returns CL_INVALID_VALUE if num_entries is equal to zero and platforms is not NULL, or if both num_platforms and platforms are NULL.
如果函数执行成功，则返回 CL_SUCCESS。否则，如果 num_entries 等于零且 platforms 不为 NULL，或者 num_platforms 和 platforms 均为 NULL，则返回CL_INVALID_VALUE。

Returns CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.
如果无法在主机上分配 OpenCL 实现所需的资源，则返回 CL_OUT_OF_HOST_MEMORY。

2. clGetPlatformInfo

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

Get specific information about the OpenCL platform.
获取有关 OpenCL 平台的特定信息。

cl_int clGetPlatformInfo(cl_platform_id platform,
 	                     cl_platform_info param_name,
 	                     size_t param_value_size,
 	                     void *param_value,
 	                     size_t *param_value_size_ret)

2.1 Parameters

• platform

The platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.
platform 即 clGetPlatformIDs 所返回的平台 ID，指明要查询哪个平台，也可以是 NULL。而如果是 NULL，其行为依赖于具体实现。

• param_name

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

• param_value

A pointer to memory location where appropriate values for a given param_value will be returned. Possible param_value values returned are listed in the table below. If param_value is NULL, it is ignored.
指向内存位置的指针，将返回给定 param_value 的适当值。下表列出了可能返回的 param_value 值。如果 param_value 为 NULL，则将其忽略。
param_value 是一个指针，所指內存用來存储 param_name 所对应的信息。

• 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，则将其忽略。

OpenCL Platform Queries - OpenCL 平台查询

cl_platform_info	Return Type	Description
CL_PLATFORM_NAME	char[]	Platform name string. 平台名字。
CL_PLATFORM_VENDOR	char[]	Platform vendor string. 平台供应商的名字。

• CL_PLATFORM_PROFILE - char[]

OpenCL profile string. Returns the profile name supported by the implementation. The profile name returned can be one of the following strings:
OpenCL 配置文件字符串。返回实现支持的配置文件名称。返回的配置文件名称可以是以下字符串之一：
FULL_PROFILE - if the implementation supports the OpenCL specification (functionality defined as part of the core specification and does not require any extensions to be supported). 如果实现支持 OpenCL 规范 (功能定义为核心规范的一部分，并且不需要任何扩展支持)。
EMBEDDED_PROFILE - if the implementation supports the OpenCL embedded profile. The embedded profile is defined to be a subset for each version of OpenCL. 如果实现支持 OpenCL 嵌入式配置文件。嵌入式配置文件定义为每个 OpenCL 版本的子集。

• CL_PLATFORM_VERSION - char[]

OpenCL version string. Returns the OpenCL version supported by the implementation. This version string has the following format:
OpenCL 版本字串。返回所支持的 OpenCL 版本。其格式如下：
OpenCL<space><major_version.minor_version><space><platform-specific information>
The major_version.minor_version value returned will be 1.2.
所返回的 major_version.minor_version 将是 1.2。

• CL_PLATFORM_EXTENSIONS - char[]

Returns a space-separated list of extension names (the extension names themselves do not contain any spaces) supported by the platform. Extensions defined here must be supported by all devices associated with this platform.
返回以空格分隔的扩展名列表 (扩展名本身不包含任何空格)。与该平台关联的所有设备都必须支持此处定义的扩展。

A null terminated string is returned by OpenCL query function calls if the return type of the information being queried is a char[].
如果查询的信息的返回类型为 char[]，则 OpenCL 查询函数调用将返回以 null 结尾的字符串。

2.3 Errors

Returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns the following:
如果函数执行成功，则返回 CL_SUCCESS。否则，它将返回以下内容：

• CL_INVALID_PLATFORM if platform is not a valid platform (如果 platform 不是有效的平台).
• 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 and param_value is not a NULL value. (如果 param_name 不是受支持的值之一，或者 param_value_size 指定的字节大小小于返回类型的大小，并且 param_value 不是 NULL 值。)
• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host (如果无法在主机上分配 OpenCL 实现所需的资源).