OpenCL™规范 5.4.2. 管道对象查询

5.4.2. Pipe Object Queries

5.4.2. 管道对象查询

To get information that is common to all memory objects, use the clGetMemObjectInfo function described in Memory Object Queries.

​要获取所有内存对象通用的信息，请使用“内存对象查询”中描述的clGetMemObjectInfo函数。

To get information specific to a pipe object created with clCreatePipe, call the function

​若要获取特定于使用clCreatePipe创建的管道对象的信息，请调用函数

// Provided by CL_VERSION_2_0
cl_int clGetPipeInfo(
    cl_mem pipe,
    cl_pipe_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

clGetPipeInfo is missing before version 2.0. clGetPipeInfo在版本2.0之前丢失。

• pipe specifies the pipe object being queried.

• pipe指定要查询的管道对象。

• param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetPipeInfo is described in the Pipe Object Queries table.

• ​param_name指定要查询的信息。支持的param_name类型列表以及clGetPipeInfo以param_value返回的信息在管道对象查询表中进行了描述。

• param_value is a pointer to memory where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

• param_value是一个指向内存的指针，在内存中返回所查询的适当结果。如果param_value为NULL，则忽略它。

• param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Pipe Object 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，则忽略它。

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

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

• CL_INVALID_MEM_OBJECT if pipe is a not a valid pipe object.

• 如果管道不是有效的管道对象，则为CL_INVALID_MEM_OBJECT。

• CL_INVALID_VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the Pipe Object Queries table and param_value is not NULL.

• CL_INVALID_VALUE如果param_name无效，或者param_value_size指定的字节大小小于管道对象查询表中描述的返回类型的大小，并且param_value不为NULL。

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

• CL_OUT_OF_RESOURCES，如果在设备上分配OpenCL实现所需的资源失败。

• 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实现所需的资源失败。

Table 36. List of supported param_names by clGetPipeInfo

​表36 clGetPipeInfo支持的参数名称列表

Pipe Info 管道信息	Return type 返回类型	Description 描述
CL_PIPE_PACKET_SIZE missing before version 2.0.	cl_uint	Return pipe packet size specified when pipe is created with clCreatePipe. ​返回使用clCreatePipe创建pipe时指定的管道数据包大小。
CL_PIPE_MAX_PACKETS missing before version 2.0.	cl_uint	Return max. number of packets specified when pipe is created with clCreatePipe. ​ 返回使用clCreatePipe创建管道时指定的最大数据包数。
CL_PIPE_PROPERTIES missing before version 3.0.	cl_pipe_properties[]	Return the properties argument specified in clCreatePipe. 返回clCreatePipe中指定的属性参数。 ​ If the properties argument specified in clCreatePipe used to create pipe was not NULL, the implementation must return the values specified in the properties argument in the same order and without including additional properties. 如果用于创建pipe的clCreatePipe中指定的属性参数不是NULL，则实现必须以相同的顺序返回属性参数中指定的值，并且不包括其他属性。 ​ If the properties argument specified in clCreatePipe used to create pipe was NULL, the implementation must return param_value_size_ret equal to 0, indicating that there are no properties to be returned. ​如果在用于创建pipe的clCreatePipe中指定的properties参数为NULL，则该实现必须返回等于0的param_value_size_ret，表示没有要返回的属性。