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

ID 683846
Date 12/19/2022
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.

The following sections describe the API functions for bound cl_mem objects:

clReadPipeIntelFPGA Function

This function reads a data packet from a pipe with the following characteristics:

  • Created with the CL_MEM_HOST_READ_ONLY flag.
  • 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.

Syntax
cl_int clReadPipeIntelFPGA (cl_mem pipe, 
                            gentype *ptr);

Return Values

The clReadPipeIntelFPGA function returns CL_SUCCESS if the read is successful. Otherwise, it returns one of the following errors:

Table 4.  Return Values for clReadPipeIntelFPGA Function
Return Value Description
CL_INVALID_MEM_OBJECT Pipe was not created with the clCreatePipe function or if the CL_MEM_HOST_READ_ONLY flag is not used when creating the pipe.
CL_INVALID_KERNEL Pipe is not bound to a kernel argument using the clSetKernelArg function.
CL_INVALID_VALUE The ptr attribute is NULL.
CL_PIPE_EMPTY Pipe is empty with no data, and therefore there were no valid packets to read.

clWritePipeIntelFPGA Function

This function writes a data packet to a pipe with the following characteristics:

  • Created with the CL_MEM_HOST_WRITE_ONLY flag.
  • 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. Data eventually is available for reading by the kernel, assuming that any previously mapped buffers on the host pipe are unmapped.

Syntax
cl_int clWritePipeIntelFPGA (cl_mem pipe, 
                             gentype *ptr);

Return Values

The clWritePipeIntelFPGA function returns CL_SUCCESS if the write is successful. Otherwise, it returns one of the following errors:

Table 5.  Return Values for clWritePipeIntelFPGA Function
Return Value Description
CL_INVALID_MEM_OBJECT Pipe is not created with clCreatePipe function or if the CL_MEM_HOST_WRITE_ONLY flag is not used when creating the pipe.
CL_INVALID_KERNEL Pipe is not bound to a kernel argument using the clSetKernelArg function.
CL_INVALID_VALUE The ptr attribute is NULL.
CL_PIPE_FULL Pipe is already full of data and cannot accept further packets without one being read by a kernel. The packet capacity of the pipe is specified as an argument to the clCreatePipe function.

clMapHostPipeIntelFPGA Function

This function 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 argument 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 does not overlap with that returned by the first call.

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

Return Values

The clMapHostPipeIntelFPGA function returns a valid non-NULL address and CL_SUCCESS is returned in errcode_ref if the host pipe is mapped successfully. Otherwise, it returns NULL and errcode_ret is set with one of the following values:

Table 6.  Error Values Set in errcode_ret
Description Error Values
This error is returned when the:
  • Pipe is not created with the clCreatePipe function.
  • CL_MEM_HOST_WRITE_ONLY or CL_MEM_HOST_READ_ONLY flag is not used when creating a pipe.
  • Pipe has been released.
CL_INVALID_MEM_OBJECT
Pipe is not bound to a kernel argument using the clSetKernelArg function. CL_INVALID_KERNEL
The requested_size attribute is not a multiple of the packet size that is specified to the clCreatePipe function. CL_INVALID_VALUE
The mapped_size attribute is NULL.
Runtime cannot provide buffer space for the host to read or write. This may occur when a new mapping is requested before data is transferred to or from the device from a previous clUnmapHostPipeIntelFPGA function call, so attempting to map again may succeed. CL_OUT_OF_RESOURCES
Runtime is unable to allocate the host addressable memory. CL_OUT_OF_HOST_MEMORY

clUnmapHostPipeIntelFPGA Function

This function signals to the runtime that the host no 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 the clUnmapHostPipeIntelFPGA function 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 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.

Syntax
cl_int clUnmapHostPipeIntelFPGA (cl_mem pipe, 
                                 void * mapped_ptr,
                                 size_t size_to_unmap,
                                 size_t * unmapped_size);

Return Values

The clUnmapHostPipeIntelFPGA function returns CL_SUCCESS on successful unmapping. Otherwise, it returns the following error:

Table 7.  Return Values for clUnmapHostPipeIntelFPGA Function
Return Value Description
CL_INVALID_VALUE The mapped_ptr attribute is not a valid pointer returned by a clMapHostPipeIntelFPGA function call associated with the pipe, or if the mapped_ptr has already been fully unmapped.
The requested_size attribute is not a multiple of the packet size that was specified to the clCreatePipe function.
The requested_size attribute is larger than the remaining unmapped bytes in the mapped_ptr buffer.
The unmapped_size attribute is NULL.

Recommendations for Using Host Pipes Efficiently

To use host pipes efficiently, Intel® recommends the following:

  • Use map or unmap with multiple packets rather than single packet with read or write.
  • Use two threads to simultaneously map and unmap.
  • Ensure kernel can read or write data to host pipe in every clock cycle.

Recommendations for Avoiding Hangs, Stalls or Deadlocks

To avoid hangs, stalls, or deadlocks situation, Intel® recommends the following:

  • Packets may get lost when enqueuing kernels from different cl_programs. Use a single cl_program object in the host application.
  • Ensure that the same amount of data is written and read on kernel and host.