OpenCL™规范 4.1. 查询平台信息

4.1. Querying Platform Info

4.1. 查询平台信息

The list of platforms available can be obtained with the function:

可用平台列表可以通过以下功能获得：

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

• num_entries is 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.

• num_entries是可以添加到平台的cl_platform_id条目的数量。如果platforms不为NULL，则num_entries必须大于零。

• 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 is NULL, this argument is ignored. The number of OpenCL platforms returned is the minimum of the value specified by num_entries or the number of OpenCL platforms available.

• platforms返回找到的OpenCL平台的列表。在平台中返回的cl_platform_id值可用于标识特定的OpenCL平台。如果platforms为NULL，则忽略此参数。返回的OpenCL平台数是num_entries指定的值或可用OpenCL平台数量的最小值。

• num_platforms returns the number of OpenCL platforms available. If num_platforms is NULL, this argument is ignored.

• num_platforms返回可用的OpenCL平台的数量。如果num_platforms为NULL，则忽略此参数。

clGetPlatformIDs returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

如果函数执行成功，clGetPlatformID将返回CL_SUCCESS。否则，它将返回以下错误之一：

• 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_INVALID_VALUE，如果num_entries等于零并且平台不为NULL，或者如果num_platforms和平台都为NULL。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。

Specific information about an OpenCL platform can be obtained with the function:

有关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);

• platform refers to the platform ID returned by clGetPlatformIDs or can be NULL. If platform is NULL, the behavior is implementation-defined.

• ​platform是指clGetPlatformID返回的平台ID，也可以为NULL。若平台为NULL，则行为由实现定义。

• param_name is an enumeration constant that identifies the platform information being queried. It can be one of the following values as specified in the Platform Queries table.

• ​param_name是一个枚举常量，用于标识所查询的平台信息。它可以是“平台查询”表中指定的以下值之一。

• param_value is a pointer to memory location where appropriate values for a given param_name, as specified in the Platform Queries table, will be returned. If param_value is NULL, it is ignored.

• ​param_value是指向内存位置的指针，在该位置将返回平台查询表中指定的给定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 Platform Queries table.

• ​param_value_size指定param_value指向的内存大小（以字节为单位）。此大小（以字节为单位）必须≥“平台查询”表中指定的返回类型的大小。

• param_value_size_ret returns the actual size in bytes of data being queried by param_name. If param_value_size_ret is NULL, it is ignored.

• param_value_size_ret返回param_name查询的数据的实际大小（以字节为单位）。如果param_value_size_ret为NULL，则忽略它。

The information that can be queried using clGetPlatformInfo is specified in the Platform Queries table.

​可以使用clGetPlatformInfo查询的信息在“平台查询”表中指定。

Table 3. List of supported param_names by clGetPlatformInfo

​表3 clGetPlatformInfo支持的参数名称列表

Platform Info 平台信息	Return Type 返回类型	Description 描述
CL_PLATFORM_PROFILE [2]	char[] [3]	OpenCL profile string. Returns the profile name supported by the implementation. The profile name returned can be one of the following strings: 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). EMBEDDED_PROFILE - if the implementation supports the OpenCL embedded profile. The embedded profile is defined to be a subset for each version of OpenCL. The embedded profile for OpenCL is described in OpenCL Embedded Profile. ​ OpenCL配置字符串。返回实现支持的配置名称。返回的配置名称可以是以下字符串之一： FULL_PROFILE-如果实现支持OpenCL规范（功能定义为核心规范的一部分，不需要支持任何扩展）。 EMBEDED_PROFILE-如果实现支持OpenCL嵌入式配置。嵌入式配置被定义为每个版本的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<space><major_version.minor_version><space><platform-specific information> The major_version.minor_version value returned will be one of 1.0, 1.1, 1.2, 2.0, 2.1, 2.2 or 3.0. OpenCL版本字符串。返回实现支持的OpenCL版本。此版本字符串的格式如下：OpenCL＜space＞＜major_version.minor_version＞＜space＞＜平台特定信息＞返回的major_version.minor-version值将是1.0、1.1、1.2、2.0、2.1、2.2或3.0之一。
CL_PLATFORM_NUMERIC_VERSION missing before version 3.0.	cl_version	Returns the detailed (major, minor, patch) version supported by the platform. The major and minor version numbers returned must match those returned via CL_PLATFORM_VERSION. ​返回平台支持的详细版本（主要、次要、修补程序）。返回的主要版本号和次要版本号必须与通过CL_PLATFORM_VERSION返回的版本号相匹配。
CL_PLATFORM_NAME	char[]	Platform name string. 平台名称字符串。
CL_PLATFORM_VENDOR	char[]	Platform vendor string. 平台供应商字符串。
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. Each extension that is supported by all devices associated with this platform must be reported here. 返回平台支持的以空格分隔的扩展名列表（扩展名本身不包含任何空格）。与此平台相关的所有设备支持的每个扩展都必须在此处报告。
CL_PLATFORM_EXTENSIONS_WITH_VERSION missing before version 3.0.	cl_name_version[]	Returns an array of description (name and version) structures that lists all the extensions supported by the platform. The same extension name must not be reported more than once. The list of extensions reported must match the list reported via CL_PLATFORM_EXTENSIONS. ​返回一个描述（名称和版本）结构数组，该数组列出了平台支持的所有扩展。同一扩展名不能报告多次。报告的扩展列表必须与通过CL_PLATFORM_EXTENSIONS报告的列表匹配。
CL_PLATFORM_HOST_TIMER_RESOLUTION missing before version 2.1.	cl_ulong	Returns the resolution of the host timer in nanoseconds as used by clGetDeviceAndHostTimer. Support for device and host timer synchronization is required for platforms supporting OpenCL 2.1 or 2.2. This value must be 0 for devices that do not support device and host timer synchronization. ​ 返回clGetDeviceAndHostTimer使用的主机计时器的分辨率（以纳秒为单位）。 支持OpenCL 2.1或2.2的平台需要支持设备和主机定时器同步。对于不支持设备和主机计时器同步的设备，此值必须为0。

clGetPlatformInfo returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors [4].

如果函数执行成功，clGetPlatformInfo将返回CL_SUCCESS。否则，它将返回以下错误之一[4]。

• CL_INVALID_PLATFORM if platform is not a valid platform.

• CL_INVALID_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 < size of return type as specified in the OpenCL Platform Queries table, and param_value is not a NULL value.

• 如果param_name不是支持的值之一，或者param_value_size指定的字节大小小于OpenCL平台查询表中指定的返回类型的大小，并且param_value不是NULL值，则CL_INVALID_VALUE。

• CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

• CL_OUT_OF_HOST_MEMORY，如果在主机上分配OpenCL实现所需的资源失败。