Description

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 types62 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.

[62] The half scalar and vector types can only be used if the cl_khr_fp16 extension is supported and has been enabled. The double scalar and vector types can only be used if double precision is supported.

Table 1. Built-in Pipe Work-group Functions

Function

Description

reserve_id_t work_group_reserve_read_pipe(read_only pipe gentype p, uint num_packets)
reserve_id_t work_group_reserve_write_pipe(write_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.

The reserved pipe entries are referred to by indices that go from 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.

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.

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.

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.

See Also

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C Specification. Fixes and changes should be made to the Specification, not directly.

Copyright (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.