| |
| <para> |
| We use the generic type name gentype to indicate the built-in |
| OpenCL C scalar or vector integer or floating-point data types 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 this section. |
| The half scalar and vector types can only be used if the |
| <citerefentry><refentrytitle>cl_khr_fp16</refentrytitle></citerefentry> |
| extension is supported. The <type>double</type> scalar |
| and vector types can only be used if double precision is supported. |
| </para> |
| |
| <bridgehead>General information about pipes</bridgehead> |
| |
| <para> |
| A pipe is identified by specifying the <code>pipe</code> |
| keyword with a type. The data type specifies the |
| size of each packet in the pipe. The <code>pipe</code> |
| keyword is a type modifier. When it is applied to |
| another type <code>T</code>, the result is a pipe type |
| whose elements (or packets) are of type <code>T</code>. The packet |
| type <code>T</code> 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. |
| </para> |
| |
| <para> |
| The |
| <citerefentry href="qualifiers"><refentrytitle>read_only</refentrytitle></citerefentry> |
| (or <code>__read_only</code>) and |
| <citerefentry href="qualifiers"><refentrytitle>write_only</refentrytitle></citerefentry> |
| (or <code>__write_only</code>) qualifiers |
| must be used with the pipe qualifier 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, |
| <citerefentry href="qualifiers"><refentrytitle>read_only</refentrytitle></citerefentry> |
| is assumed. |
| </para> |
| |
| <para> |
| A kernel cannot read from and write to the same pipe object. Using the |
| <citerefentry href="qualifiers"><refentrytitle>read_write </refentrytitle></citerefentry> |
| (or <code>__read_write</code>) qualifier with the pipe qualifier is a compilation error. |
| </para> |
| |
| <para> |
| The macro <constant>CLK_NULL_RESERVE_ID</constant> refers to an invalid reservation ID. |
| </para> |
| |
| <para> |
| NOTE: The |
| <citerefentry><refentrytitle>read_pipe</refentrytitle></citerefentry> and |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> |
| 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 |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> |
| function, the contents of that packet in the pipe are undefined. |
| <citerefentry><refentrytitle>commit_read_pipe</refentrytitle></citerefentry> and |
| <citerefentry><refentrytitle>work_group_commit_read_pipe</refentrytitle></citerefentry> |
| remove the entries reserved for reading from the pipe. |
| <citerefentry><refentrytitle>commit_write_pipe</refentrytitle></citerefentry> and |
| <citerefentry><refentrytitle>work_group_commit_write_pipe</refentrytitle></citerefentry> |
| ensures that the entries reserved for writing are all added in-order |
| as one contiguous set of packets to the pipe. |
| </para> |
| |
| <para> |
| There can only be <constant>CL_DEVICE_PIPE_MAX_ACTIVE_RESERVATIONS</constant> |
| (refer to the list of possible values for <varname>parame_name</varname> |
| for <citerefentry><refentrytitle>clGetDeviceInfo</refentrytitle></citerefentry>(table 4.3)) |
| 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. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <para> |
| 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. |
| </para> |
| |
| <bridgehead>Restrictions</bridgehead> |
| |
| <para> |
| Pipes can only be passed as arguments to a function |
| (including kernel functions). The C |
| <citerefentry><refentrytitle>operators</refentrytitle></citerefentry> |
| (refer to section 6.3 of the OpenCL 2.0 specification) cannot be used with |
| variables declared with the <code>pipe</code> qualifier. |
| </para> |
| |
| <para> |
| The <code>pipe</code> qualifier 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. |
| </para> |
| |
| <para> |
| The following behavior is undefined: |
| </para> |
| |
| <para> |
| <itemizedlist> |
| <listitem> |
| <!-- [sic] spec refers to reserve_pipe, which does not exist --> |
| A kernel fails to call |
| <function>reserve_pipe</function> |
| before calling |
| <citerefentry><refentrytitle>read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> that take a |
| reservation ID. |
| </listitem> |
| |
| <listitem> |
| A kernel calls |
| <citerefentry><refentrytitle>read_pipe</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry>, |
| <citerefentry><refentrytitle>commit_read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>commit_write_pipe</refentrytitle></citerefentry> with |
| an invalid reservation ID. |
| </listitem> |
| |
| <listitem> |
| A kernel calls |
| <citerefentry><refentrytitle>read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> |
| with an valid reservation ID but with an <varname>index</varname> |
| that is not a value from 0 ... <varname>num_packets</varname> - 1 |
| specified to the corresponding call to |
| <function>reserve_pipe</function>. |
| </listitem> |
| |
| <listitem> |
| A kernel calls |
| <citerefentry><refentrytitle>read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> |
| with a reservation ID that has already been committed (i.e. a |
| <citerefentry><refentrytitle>commit_read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>commit_write_pipe</refentrytitle></citerefentry> |
| with this reservation ID has |
| already been called). |
| </listitem> |
| |
| <listitem> |
| A kernel fails to call |
| <citerefentry><refentrytitle>commit_read_pipe</refentrytitle></citerefentry> |
| for any reservation ID obtained by a prior call |
| to <citerefentry><refentrytitle>reserve_read_pipe</refentrytitle></citerefentry>. |
| </listitem> |
| |
| <listitem> |
| A kernel fails to call |
| <citerefentry><refentrytitle>commit_write_pipe</refentrytitle></citerefentry> |
| for any reservation ID obtained by a prior call |
| to <citerefentry><refentrytitle>reserve_write_pipe</refentrytitle></citerefentry>. |
| </listitem> |
| |
| <listitem> |
| The contents of the reserved data packets in the pipe are undefined if the kernel does not |
| call <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> |
| for all entries that were reserved by the corresponding call to |
| <function>reserve_pipe</function>. |
| </listitem> |
| |
| <listitem> |
| Calls to |
| <citerefentry><refentrytitle>read_pipe</refentrytitle></citerefentry> |
| that takes a reservation ID and |
| <citerefentry><refentrytitle>commit_read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>write_pipe</refentrytitle></citerefentry> that |
| takes a reservation ID and |
| <citerefentry><refentrytitle>commit_write_pipe</refentrytitle></citerefentry> |
| for a given reservation ID must be called |
| by the same kernel that made the reservation using |
| <citerefentry><refentrytitle>reserve_read_pipe</refentrytitle></citerefentry> or |
| <citerefentry><refentrytitle>reserve_write_pipe</refentrytitle></citerefentry>. |
| The reservation ID cannot be passed to another kernel including |
| child kernels. |
| </listitem> |
| |
| </itemizedlist> |
| </para> |
| |
| <!-- ================================ EXAMPLE --> |
| |
| <refsect2 id="example1"> |
| <title> |
| Example |
| </title> |
| |
| <para> |
| In the following example |
| </para> |
| |
| <informaltable frame="none"> |
| <tgroup cols="1" align="left" colsep="0" rowsep="0"> |
| <colspec colname="col1" colnum="1" /> |
| <tbody> |
| <row> |
| <entry> |
| kernel void |
| foo (read_only pipe fooA_t pipeA, |
| write_only pipe fooB_t pipeB) |
| { |
| ... |
| } |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| |
| <para> |
| <code>pipeA</code> is a read-only pipe object, |
| and <code>pipeB</code> is a write-only pipe object. |
| </para> |
| </refsect2> |
| |
| <!-- 7-Nov-2015, API ver 2.1 rev 19; Ext ver 2.1 rev 10; C lang ver 2.0 rev 30 --> |
| |