OpenCL host code for optimized interfacing with Xilinx Devices.
Examples Table
| Example | Description | Key Concepts / Keywords |
|---|---|---|
| concurrent_kernel_execution/ | This example will demonstrate how to use multiple and out of order command queues to simultaneously execute multiple kernels on an FPGA. | Key Concepts - Concurrent execution - Out of Order Command Queues - Multiple Command Queues Keywords - CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE - setCallback |
| copy_buffer/ | This Copy Buffer example demonstrate how one buffer can be copied from another buffer. | Key Concepts - Copy Buffer Keywords - cl::CommandQueue - enqueueCopyBuffer - enqueueWriteBuffer - enqueueReadBuffer - enqueueMigrateMemObjects |
| data_transfer/ | This example illustrates several ways to use the OpenCL API to transfer data to and from the FPGA | Key Concepts - OpenCL API - Data Transfer - Write Buffers - Read Buffers - Map Buffers - Async Memcpy Keywords - enqueueWriteBuffer - enqueueReadBuffer - enqueueMapBuffer - enqueueUnmapMemObject - enqueueMigrateMemObjects |
| debug_profile/ | This is simple example of vector addition and printing profile data (wall clock time taken between start and stop). It also dump a waveform file which can be reloaded to vivado to see the waveform. Run command 'vivado -source ./scripts/open_waveform.tcl -tclargs <device_name>-<kernel_name>..<device_name>.wdb' to launch waveform viewer. User can also update batch to gui in xrt.ini file to see the live waveform while running application. | Key Concepts - Use of Profile API - Waveform Dumping and loading |
| device_only_buffer/ | This example will demonstrate how to create buffers in global memory which are not mapped to host. | Key Concepts - Device only buffer Keywords - CL_MEM_HOST_NO_ACCESS |
| device_query/ | This Example prints the OpenCL properties of the platform and its devices using OpenCL CPP APIs. It also displays the limits and capabilities of the hardware. | Key Concepts - OpenCL API - Querying device properties |
| errors/ | This example discuss the different reasons for errors in OpenCL and how to handle them at runtime. | Key Concepts - OpenCL API - Error handling Keywords - CL_SUCCESS - CL_DEVICE_NOT_FOUND - CL_DEVICE_NOT_AVAILABLE |
| errors_cpp/ | This example discuss the different reasons for errors in OpenCL C++ and how to handle them at runtime. | Key Concepts - OpenCL C++ API - Error handling Keywords - CL_SUCCESS - CL_DEVICE_NOT_FOUND - CL_DEVICE_NOT_AVAILABLE - CL_INVALID_VALUE - CL_INVALID_KERNEL_NAME - CL_INVALID_BUFFER_SIZE |
| hbm_bandwidth/ | This is a HBM bandwidth check design. Design contains 3 compute units of a kernel which has access to all HBM banks (0:31). Host application allocate buffer into all HBM banks and run these 3 compute units concurrently and measure the overall bandwidth between Kernel and HBM Memory. | |
| hbm_bandwidth_pseudo_random/ | This is a HBM bandwidth example using a pseudo random 1024 bit data access pattern to mimic Ethereum Ethash workloads. The design contains 3 compute units of a kernel, reading 1024 bits from a pseudo random address in each of 2 pseudo channels and writing the results of a simple mathematical operation to a pseudo random address in 2 other pseudo channels. To maximize bandwidth the pseudo channels are used in P2P like configuration - See https://developer.xilinx.com/en/articles/maximizing-memory-bandwidth-with-vitis-and-xilinx-ultrascale-hbm-devices.html for more information on HBM memory access configurations. The host application allocates buffers in 12 HBM banks and runs the compute units concurrently to measure the overall bandwidth between kernel and HBM Memory. | Key Concepts - High Bandwidth Memory - Multiple HBM Banks - Random Memory Access - Linear Feedback Shift Register Keywords - HBM - XCL_MEM_TOPOLOGY - cl_mem_ext_ptr_t |
| hbm_simple/ | This is a simple example of vector addition to describe how to use HLS kernels with HBM (High Bandwidth Memory) for achieving high throughput. | Key Concepts - High Bandwidth Memory - Multiple HBM Banks Keywords - HBM - XCL_MEM_TOPOLOGY - cl_mem_ext_ptr_t |
| host_global_bandwidth/ | Host to global memory bandwidth test | |
| mult_compute_units/ | This is simple Example of Multiple Compute units to showcase how a single kernel can be instantiated into Multiple compute units. Host code will show how to use multiple compute units and run them concurrently. | Key Concepts - Multiple Compute Units Keywords - nk |
| multiple_cus_asymmetrical/ | This is simple example of vector addition to demonstrate how to connect each compute unit to different banks and how to use these compute units in host applications | Key Concepts - Multiple Compute Units |
| overlap/ | This examples demonstrates techniques that allow user to overlap Host(CPU) and FPGA computation in an application. It will cover asynchronous operations and event object. | Key Concepts - OpenCL API - Synchronize Host and FPGA - Asynchronous Processing - Events - Asynchronous memcpy Keywords - cl_event - cl::CommandQueue - CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE - enqueueMigrateMemObjects |
| p2p_bandwidth/ | This is simple example to test Synchronous and Asyncronous data transfer between SSD and FPGA. | Key Concepts - P2P - SmartSSD - XDMA Keywords - XCL_MEM_EXT_P2P_BUFFER - pread - pwrite |
| p2p_fpga2fpga/ | This is simple example to explain P2P transfer between two FPGA devices. | Key Concepts - P2P - Multi-FPGA Execution - XDMA Keywords - XCL_MEM_EXT_P2P_BUFFER |
| p2p_fpga2fpga_bandwidth/ | This is simple example to explain performance bandwidth for P2P transfer between two FPGA devices. | Key Concepts - P2P - Multi-FPGA Execution - XDMA Keywords - XCL_MEM_EXT_P2P_BUFFER |
| p2p_simple/ | This is simple example of vector increment to describe P2P between FPGA and NVMe SSD. | Key Concepts - P2P - NVMe SSD - SmartSSD Keywords - XCL_MEM_EXT_P2P_BUFFER - pread - pwrite - O_DIRECT - O_RDWR |
| streaming_custom_datatype/ | This is simple streaming example of RGB to HSV conversion to demonstrate how streams of custom DATA Types needs to be handled on the kernel side. | Key Concepts - Custom Datatype Keywords - struct - #pragma HLS LOOP_TRIPCOUNT - cl_stream - CL_STREAM_EOT |
| streaming_free_running_h2k/ | This is a simple streaming free running kernel that demonstrates how to interact with the host. In this design we showcase multiple stream requests in parallel. | Key Concepts - Free Running Kernel Keywords - cl_stream - CL_STREAM_EOT - CL_STREAM_NONBLOCKING |
| streaming_free_running_k2k/ | This is simple example which demonstrate how to use and configure a free running kernel. | Key Concepts - Free Running Kernel Keywords - ap_ctrl_none - stream_connect |
| streaming_host_bandwidth/ | This is a simple Vector Increment C Kernel design with 1 Stream input and 1 Stream output that demonstrates on how to process an input stream of data for computation in an application and the Host to Device streaming bandwidth test. | Key Concepts - Read/Write Stream - Create/Release Stream Keywords - cl_stream - CL_STREAM_EOT - CL_STREAM_NONBLOCKING |
| streaming_k2k/ | This is a simple kernel to kernel streaming Vector Add and Vector Multiply C Kernel that demonstrates on how to process a stream of data for computation between two kernels. | Key Concepts - Read/Write Stream - Create/Release Stream Keywords - cl_stream - CL_STREAM_EOT - CL_STREAM_NONBLOCKING |
| streaming_k2k_mm/ | This is a simple kernel to kernel streaming Vector Add and Vector Multiply C Kernel design with 2 memory mapped input to kernel 1, 1 Stream output from kernel 1 to input of kernel 2, 1 memory mapped input to kernel 2, and 1 memory mapped output that demonstrates on how to process a stream of data for computation between two kernels. This design also illustrates how to set FIFO depth for AXIS connections i.e. for the stream connecting the two kernels | Key Concepts - Read/Write Stream - Create/Release Stream - AXIS FIFO depth Keywords - stream_connect |
| streaming_mm_mixed/ | This is a simple streaming Vector Addition C Kernel design with 1 Stream input, 1 memory mapped input to the kernel, and 1 stream output that demonstrates on how to process a stream of data along with memory mapped interface. | Key Concepts - Read/Write Stream - Create/Release Stream Keywords - cl_stream - CL_STREAM_EOT |
| streaming_multi_cus/ | This is a simple vadd Kernel design in which multiple compute units of kernel are directly communicating with host using stream interfaces. | Key Concepts - Read/Write Stream - Create/Release Stream Keywords - cl_stream - CL_STREAM_EOT - nk |
| streaming_reg_access/ | This is simple example which demonstrate streaming free-running kernel with scalar input and output. | Key Concepts - Free Running Kernel Keywords - xclRegRead - xclRegWrite |
| streaming_simple/ | This is a simple Vector Add C Kernel design with 2 Stream inputs and 1 Stream output that demonstrates on how streaming kernel can be implemented and how host can directly send data to kernel without global memory. | Key Concepts - Read/Write Stream - Create/Release Stream Keywords - cl_stream - CL_STREAM_EOT - CL_STREAM_NONBLOCKING |