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

ID 683846
Date 12/19/2022
Public
Document Table of Contents

6.6.4. Programming an FPGA via the Host

The Intel® FPGA SDK for OpenCL™ Offline Compiler is an offline compiler that compiles kernels independently of the host application. To load the kernels into the OpenCL™ runtime, include the clCreateProgramWithBinary function in your host application.
CAUTION:
If your host system consists of multiple processors, only one processor can access the FPGA at a given time. Consider an example where there are two host applications, corresponding to two processors, attempting to launch kernels onto the same FPGA at the same time. The second host application receives an error message indicating that the device is busy. The second host application cannot run until the first host application releases the OpenCL context.
  1. Compile your OpenCL kernel with the offline compiler to create the .aocx file.
  2. Include the clCreateProgramWithBinary function in your host application to create the cl_program OpenCL program objects from the .aocx file.
  3. Include the clBuildProgram function in your host application to create the program executable for the specified device.
    Below is an example host code on using clCreateProgramWithBinary to program an FPGA device:
    size_t lengths[1];
    unsigned char* binaries[1] ={NULL};
    cl_int status[1];
    cl_int error;
    cl_program program;
    const char options[] = "";
    
    FILE *fp = fopen("program.aocx","rb");
    fseek(fp,0,SEEK_END);
    lengths[0] = ftell(fp);
    binaries[0] = (unsigned char*)malloc(sizeof(unsigned char)*lengths[0]);
    rewind(fp);
    fread(binaries[0],lengths[0],1,fp);
    fclose(fp);
    
    program = clCreateProgramWithBinary(context,
                                        1,
                                        device_list,
                                        lengths,
                                        (const unsigned char **)binaries,
                                        status,
                                        &error);
    clBuildProgram(program,1,device_list,options,NULL,NULL);
    If the clBuildProgram function executes successfully, it returns CL_SUCCESS.
  4. Create kernel objects from the program executable using the clCreateKernelsInProgram or clCreateKernel function.
  5. Include the kernel execution function to instruct the host runtime to execute the scheduled kernel(s) on the FPGA.
    • To enqueue a command to execute an NDRange kernel, use clEnqueueNDRangeKernel.
    • To enqueue a single work-item kernel, use clEnqueueTask.
    Attention:

    Intel® recommends that you release an event object when it is not in use. The SDK keeps an event object live until you explicitly instruct it to release the event object. Keeping an unused event object live causes unnecessary memory usage.

    To release an event object, call the clReleaseEvent function.

    You can load multiple FPGA programs into memory, which the host then uses to reprogram the FPGA as required.

For more information about these OpenCL host runtime API calls, refer to the OpenCL Specification version 1.0.