6.15.18. Pipe Functions
6.15.18. 管道功能
| The functionality described in this section requires support for OpenCL C 2.0, or OpenCL C 3.0 or newer and the 本节中描述的功能需要支持OpenCL C 2.0、OpenCL C 3.0或更高版本以及 |
A pipe is identified by specifying the pipe keyword with a type. The data type specifies the type of each element in the pipe. The pipe keyword is a type specifier. When it is applied to another type T, the result is a pipe type whose elements (or packets) are of type T. The packet type T may be any supported OpenCL C scalar and vector integer or floating-point data types, or a user-defined type built from these scalar and vector data types.
通过使用类型指定pipe关键字来标识管道。数据类型指定管道中每个元素的类型。pipe关键字是一个类型说明符。当它应用于另一种类型T时，结果是一个管道类型，其元素（或数据包）的类型为T。数据包类型T可以是任何支持的OpenCL C标量和向量整数或浮点数据类型，也可以是由这些标量和矢量数据类型构建的用户定义类型。
Examples:
示例：
pipe int4 pipeA; // a pipe with int4 packets
pipe user_type_t pipeB; // a pipe with user_type_t packetsThe read_only (or __read_only) and write_only (or __write_only) qualifiers must be used with the pipe specifier when a pipe is a parameter of a kernel or of a user-defined function to identify if a pipe can be read from or written to by a kernel and its callees and enqueued child kernels. If no qualifier is specified, read_only is assumed.
当pipe是内核或用户定义函数的参数时，read_only（或__read_only）和write_only（或__write_only）限定符必须与pipe说明符一起使用，以标识管道是否可以由内核及其被调用者和入队子内核读取或写入。如果没有指定限定符，则假定为read_only。
A kernel cannot read from and write to the same pipe object. Using the read_write (or __read_write) qualifier with the pipe specifier is a compilation error.
内核不能对同一管道对象进行读写操作。使用带有管道说明符的read_write（或__read_write）限定符是一个编译错误。
In the following example
在以下示例中
kernel void
foo (read_only pipe fooA_t pipeA,
write_only pipe fooB_t pipeB)
{
...
}pipeA is a read-only pipe object, and pipeB is a write-only pipe object.
pipeA是只读管道对象，pipeB是只写管道对象。
The macro CLK_NULL_RESERVE_ID refers to an invalid reservation ID.
宏CLK_NULL_RESERVE_ID引用了无效的保留ID。
6.15.18.1. Restrictions
6.15.18.1. 限制
-
Pipes can only be passed as arguments to a function (including kernel functions). The C operators cannot be used with variables declared with the pipe specifier.
-
管道只能作为参数传递给函数（包括内核函数）。C运算符不能与用管道说明符声明的变量一起使用。
-
The
pipespecifier cannot be used with variables declared inside a kernel, a structure or union field, a pointer type, an array, global variables declared in program scope or the return type of a function. -
pipe说明符不能与内核内声明的变量、结构体或共用体字段、指针类型、数组、程序范围内声明的全局变量或函数的返回类型一起使用。
6.15.18.2. Built-in Pipe Read and Write Functions
6.15.18.2. 内置管道读写功能
The OpenCL C programming language implements the following built-in functions that read from or write to a pipe. We use the generic type name gentype to indicate the built-in OpenCL C scalar or vector integer or floating-point data types [85] or any user defined type built from these scalar and vector data types can be used as the type for the arguments to the pipe functions listed in the following table.
OpenCL C编程语言实现了以下从管道读取或向管道写入的内置函数。我们使用泛型类型名称gentype来表示内置的OpenCL C标量或矢量整数或浮点数据类型[85]，或者由这些标量和矢量数据类型构建的任何用户定义类型都可以用作下表中列出的管道函数的参数类型。
| Function 函数 | Description 描述 |
|---|---|
| int read_pipe(read_only pipe gentype p, gentype *ptr) | Read packet from pipe p into ptr. Returns 0 if read_pipe is successful and a negative value if the pipe is empty. 将数据包从管道p读取到ptr。如果read_pipe成功，则返回0；如果管道为空，则返回负值。 |
| int write_pipe(write_only pipe gentype p, const gentype *ptr) | Write packet specified by ptr to pipe p. Returns 0 if write_pipe is successful and a negative value if the pipe is full. 将ptr指定的数据包写入管道p。如果write_pipe成功，则返回0；如果管道已满，则返回负值。 |
| int read_pipe(read_only pipe gentype p, reserve_id_t reserve_id, uint index, gentype *ptr) | Read packet from the reserved area of the pipe referred to by reserve_id and index into ptr. 从reserve_id引用的管道的保留区域读取数据包，并将其index到ptr中。 The reserved pipe entries are referred to by indices that go from 0 … num_packets - 1. 保留的管道条目由从0到num_packets-1的索引引用。 Returns 0 if read_pipe is successful and a negative value otherwise. 如果read_pipe成功，则返回0，否则返回负值。 |
| int write_pipe(write_only pipe gentype p, reserve_id_t reserve_id, uint index, const gentype *ptr) | Write packet specified by ptr to the reserved area of the pipe referred to by reserve_id and index. 将ptr指定的数据包写入reserve_id和index引用的管道的保留区域。 The reserved pipe entries are referred to by indices that go from 0 … num_packets - 1. 保留的管道条目由从0到num_packets-1的索引引用。 Returns 0 if write_pipe is successful and a negative value otherwise. 如果write_pipe成功，则返回0，否则返回负值。 |
| reserve_id_t reserve_read_pipe(read_only pipe gentype p, uint num_packets) | Reserve num_packets entries for reading from or writing to pipe p. Returns a valid reservation ID if the reservation is successful. 保留num_packets条目，用于从管道p读取数据或向管道p写入数据。如果预订成功，则返回有效的预订ID。 |
| void commit_read_pipe(read_only pipe gentype p, reserve_id_t reserve_id) | Indicates that all reads and writes to num_packets associated with reservation reserve_id are completed. 表示与预订reserve_id关联的num_packets的所有读写操作均已完成。 |
| bool is_valid_reserve_id(reserve_id_t reserve_id) | Return true if reserve_id is a valid reservation ID and false otherwise. 如果reserve_id是有效的预订id，则返回true，否则返回false。 |
6.15.18.3. Built-in Work-group Pipe Read and Write Functions
6.15.18.3. 内置工作组管道读写函数
The OpenCL C programming language implements the following built-in pipe functions that operate at a work-group level. These built-in functions must be encountered by all work-items in a work-group executing the kernel with the same argument values; otherwise the behavior is undefined. We use the generic type name gentype to indicate the built-in OpenCL C scalar or vector integer or floating-point data types [86] or any user defined type built from these scalar and vector data types can be used as the type for the arguments to the pipe functions listed in the following table.
OpenCL C编程语言实现了以下在工作组级别运行的内置管道函数。使用相同的参数值执行内核的工作组中的所有工作项都必须遇到这些内置函数；否则行为未定义。我们使用泛型类型名称gentype来表示内置的OpenCL C标量或矢量整数或浮点数据类型[86]，或者由这些标量和矢量数据类型构建的任何用户定义类型都可以用作下表中列出的管道函数的参数类型。
| Function 函数 | Description 描述 |
|---|---|
| reserve_id_t work_group_reserve_read_pipe(read_only pipe gentype p, uint num_packets) | Reserve num_packets entries for reading from or writing to pipe p. Returns a valid reservation ID if the reservation is successful. 保留num_packets条目，用于从管道p读取数据或向管道p写入数据。如果预订成功，则返回有效的预订ID。 The reserved pipe entries are referred to by indices that go from 0 … num_packets - 1. 保留的管道条目由从0到num_packets-1的索引引用。 |
| void work_group_commit_read_pipe(read_only pipe gentype p, reserve_id_t reserve_id) void work_group_commit_write_pipe(write_only pipe gentype p, reserve_id_t reserve_id) | Indicates that all reads and writes to num_packets associated with reservation reserve_id are completed. 表示与预订reserve_id关联的num_packets的所有读写操作均已完成。 |
| The read_pipe and write_pipe functions that take a reservation ID as an argument can be used to read from or write to a packet index. These built-ins can be used to read from or write to a packet index one or multiple times. If a packet index that is reserved for writing is not written to using the write_pipe function, the contents of that packet in the pipe are undefined. commit_read_pipe and work_group_commit_read_pipe remove the entries reserved for reading from the pipe. commit_write_pipe and work_group_commit_write_pipe ensures that the entries reserved for writing are all added in-order as one contiguous set of packets to the pipe. 将保留ID作为参数的read_pipe和write_pipe函数可用于读取或写入数据包索引。这些内置程序可用于一次或多次读取或写入数据包索引。如果保留用于写入的数据包索引未使用write_pipe函数写入，则管道中该数据包的内容未定义。commit_read_pipe和work_group_commitread_pipe将从管道中删除保留用于读取的条目。commit_write_pipe和workgroup_comit_write_pape确保为写入保留的条目都作为一组连续的数据包按顺序添加到管道中。 |
There can only be the value of the CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS device query reservations active (i.e. reservation IDs that have been reserved but not committed) per work-item or work-group for a pipe in a kernel executing on a device.
对于在设备上执行的内核中的管道，每个工作项或工作组只能有CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS设备查询保留的值处于活动状态（即已保留但未提交的保留ID）。
Work-item based reservations made by a work-item are ordered in the pipe as they are ordered in the program. Reservations made by different work-items that belong to the same work-group can be ordered using the work-group barrier function. The order of work-item based reservations that belong to different work-groups is implementation-defined.
工作项所做的基于工作项的预订在管道中的顺序与在程序中的顺序相同。可以使用工作组屏障功能对属于同一工作组的不同工作项进行预订。属于不同工作组的基于工作项的保留顺序由实现定义。
Work-group based reservations made by a work-group are ordered in the pipe as they are ordered in the program. The order of work-group based reservations by different work-groups is implementation-defined.
工作组所做的基于工作组的预订在管道中的顺序与在程序中的顺序相同。不同工作组基于工作组的预订顺序由实施定义。
6.15.18.4. Built-in Pipe Query Functions
6.15.18.4. 内置管道查询功能
The OpenCL C programming language implements the following built-in query functions for a pipe. We use the generic type name gentype to indicate the built-in OpenCL C scalar or vector integer or floating-point data types [87] or any user defined type built from these scalar and vector data types can be used as the type for the arguments to the pipe functions listed in the following table.
OpenCL C编程语言为管道实现了以下内置查询函数。我们使用泛型类型名称gentype来表示内置的OpenCL C标量或矢量整数或浮点数据类型[87]，或者由这些标量和矢量数据类型构建的任何用户定义类型都可以用作下表中列出的管道函数的参数类型。
aQual in the following table refers to one of the access qualifiers. For pipe query functions this may be read_only or write_only.
下表中的aQual是指其中一个访问限定符。对于管道查询函数，这可以是read_only或write_only。
| Function 函数 | Description 描述 |
|---|---|
| uint get_pipe_num_packets(aQual pipe gentype p) | Returns the number of available entries in the pipe. The number of available entries in a pipe is a dynamic value. The value returned should be considered immediately stale. 返回管道中可用条目数。管道中可用条目数是一个动态值。返回的值应被视为立即过时。 |
| uint get_pipe_max_packets(aQual pipe gentype p) | Returns the maximum number of packets specified when pipe was created. 返回创建pipe时指定的最大数据包数。 |
6.15.18.5. Restrictions
6.15.18.5. 限制
The following behavior is undefined
以下行为未定义
-
A kernel fails to call reserve_pipe before calling read_pipe or write_pipe that take a reservation ID.
-
内核在调用带有保留ID的read_pipe或write_pipe之前无法调用reserve_pipe。
-
A kernel calls read_pipe, write_pipe, commit_read_pipe or commit_write_pipe with an invalid reservation ID.
-
内核使用无效的保留ID调用read_pipe、write_pipe，commit_read_pipe或commit_write_pipe。
-
A kernel calls read_pipe or write_pipe with an valid reservation ID but with an index that is not a value in the range [0, num_packets-1] specified to the corresponding call to reserve_pipe.
-
内核使用有效的保留ID调用read_pipe或write_pipe，但index不是为相应的reserve_pipe调用指定的[0，num_packets-1]范围内的值。
-
A kernel calls read_pipe or write_pipe with a reservation ID that has already been committed (i.e. a commit_read_pipe or commit_write_pipe with this reservation ID has already been called).
-
内核使用已提交的保留ID调用read_pipe或write_pipe（即，已调用具有此保留ID的commit_read_pipe或者commit_write_pipe）。
-
A kernel fails to call commit_read_pipe for any reservation ID obtained by a prior call to reserve_read_pipe.
-
内核无法为之前调用reserve_read_pipe获得的任何保留ID调用commit_read_pipe。
-
A kernel fails to call commit_write_pipe for any reservation ID obtained by a prior call to reserve_write_pipe.
-
内核无法为之前调用reserve_write_pipe获得的任何保留ID调用commit_write_pipe。
-
The contents of the reserved data packets in the pipe are undefined if the kernel does not call write_pipe for all entries that were reserved by the corresponding call to reserve_pipe.
-
如果内核没有为相应的reserve_pipe调用保留的所有条目调用write_pipe，则管道中保留的数据包的内容是未定义的。
-
Calls to read_pipe that takes a reservation ID and commit_read_pipe or write_pipe that takes a reservation ID and commit_write_pipe for a given reservation ID must be called by the same kernel that made the reservation using reserve_read_pipe or reserve_write_pipe. The reservation ID cannot be passed to another kernel including child kernels.
-
对于给定的保留ID，调用带有保留ID的read_pipe和带有保留ID和commit_write_pipe的commit_read_pipe或write_pipe必须由使用reserve_read_pipes或reserve_write_pipes进行保留的同一内核调用。保留ID不能传递给包括子内核在内的另一个内核。
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
