Intel® FPGA SDK for OpenCL™ Standard Edition: Programming Guide

ID 683342
Date 4/22/2019
Public
Document Table of Contents

5.5.6.2. API Functions for Interacting with cl_mem Pipe Objects Bound to Host-Accessible Pipe Kernel Arguments

Including the clReadPipeIntelFPGA, clWritePipeIntelFPGA, clMapHostPipeIntelFPGA, and clUnmapHostPipeIntelFPGA host API functions allows the host program to read from and write to the cl_mem pipe objects that have been bound (using clSetKernelArg argument) to host-accessible pipe kernel arguments.
  • clReadPipeIntelFPGA and clWritePipeIntelFPGA functions operate on single words of the pipe’s width.
  • clMapHostPipeIntelFPGA function is an advanced mechanism to reduce latency and overhead when performing many word reads or writes on a host pipe.
  • clUnmapHostPipeIntelFPGA function allows the host program to signal to the OpenCL runtime that it has written to or read from either a portion of or the entire mapped region that was created through a previous clMapHostPipeIntelFPGA function call.
Table 1.  API Functions for Bound cl_mem Objects
Function Description
cl_int clReadPipeIntelFPGA (cl_mem pipe, 
                            gentype *ptr);

Reads a data packet from a pipe with the following characteristics:

  1. Created with the CL_MEM_HOST_READ_ONLY flag
  2. Bound to a kernel argument that has the write_only definition and the intel_host_accessible kernel argument attribute

Each clReadPipeIntelFPGA function call reads one packet from the pipe. The operation is non-blocking; it does not wait until data is available in the pipe to successfully read before returning.

cl_int clWritePipeIntelFPGA (cl_mem pipe, 
                             gentype *ptr);

Writes a data packet to a pipe with the following characteristics:

  1. Created with the CL_MEM_HOST_WRITE_ONLY flag
  2. Bound to a kernel argument that has the read_only definition and the intel_host_accessible kernel argument attribute

Each clWritePipeIntelFPGA function call writes one packet to the pipe. The operation is non-blocking; it does not wait until there is a capacity in the pipe to successfully write before returning. A return status of CL_SUCCESS does not imply that data is available to the kernel for reading. The data will eventually be available for reading by the kernel, assuming that any previously mapped buffers on the host pipe are unmapped.

void * clMapHostPipeIntelFPGA (cl_mem pipe,
                    cl_map_flags map_flags,
                    size_t requested_size,
                    size_t * mapped_size,
                    cl_int * errcode_ret);

Returns a void * in the host address space. The pipe can write data to this address space if it was created with the CL_MEM_HOST_WRITE_ONLY flag. The pipe can read data from this address space if it was created with the CL_MEM_HOST_READ_ONLY flag.

The mapped_size argument specifies the maximum number of bytes that the host can access, as determined by the runtime in the memory. The value specified by mapped_size is less than or equal to the value of the requested_size argument that the caller specifies.

After writing to or reading from the returned void *, the host must execute one or more clUnmapHostPipeIntelFPGA function calls to signal to the runtime that data is ready for transfer to the device (on a write), and that the runtime can reclaim the memory for reuse (on a read or write). If the clMapHostPipeIntelFPGA function is called before the clUnmapHostPipeIntelFPGA function unmaps all memory mapped by a previous clMapHostPipeIntelFPGA function call, the buffer returned by the second clMapHostPipeIntelFPGA call will not overlap with that returned by the first call.

cl_int clUnmapHostPipeIntelFPGA (
                            cl_mem pipe, 
                            void * mapped_ptr,
                            size_t size_to_unmap,
                            size_t * unmapped_size
							);
Signals to the runtime that the hostno longer uses size_to_unmap bytes of a host-addressable buffer that the clMapHostPipeIntelFPGA function has returned previously. In the case of a writeable host pipe, calling clUnmapHostPipeIntelFPGA allows the unmapped data to become available to the kernel. If the size_to_unmap value is smaller than the mapped_size value specified by the clMapHostPipeIntelFPGA function, then multiple clUnmapHostPipeIntelFPGA function calls are necessary to unmap the full capacity of the buffer. You may include multiple clUnmapHostPipeIntelFPGA function calls to unmap successive bytes in the buffer returned by a clMapHostPipeIntelFPGA function call, up to the mapped_size value defined by the clMapHostPipeIntelFPGA call.