Programming for SDAccel

1. To set up the OpenCL runtime environment, you need to identify the Xilinx platform using the clGetPlatformIDs and clGetPlatformInfo commands. For example:

   cl_platform_id platform_id;         // platform id
   
   err = clGetPlatformIDs(16, platforms, &platform_count);
       
   // Find Xilinx Platform
   for (unsigned int iplat=0; iplat<platform_count; iplat++) {
     err = clGetPlatformInfo(platforms[iplat], 
       CL_PLATFORM_VENDOR, 
       1000, 
       (void *)cl_platform_vendor,
       NULL);
   
     if (strcmp(cl_platform_vendor, "Xilinx") == 0) { 
     // Xilinx Platform found
     platform_id = platforms[iplat];
     }
   }

2. Identify the Xilinx devices on the platform available for enqueuing kernels, using the clGetDeviceIDs command. Finding the device IDs requires the platform ID discovered in the prior step. For example:

   clGetDeviceIDs(platform_id, CL_DEVICE_TYPE_ACCELERATOR, 1, &device_id, NULL);
   

3. Setup the context using clCreateContext. The context is the environment that work-items execute, and identifies devices to be assigned transactions from the command queue. The example below shows the creation of the context:

   cl_context cntxt = clCreateContext(0, 1, &device_id, NULL, NULL, &err);
   

4. Define the command queue using clCreateCommandQueue. The command queue is a list of commands waiting to be executed to a device. You can setup the command queue to handle commands in the order submitted, or to be out-of-order so that a command can be executed as soon as possible. Use the out-of-order command queue, or multiple in-order command queues, for concurrent kernel execution on the FPGA. An example follows:

   // Create out-of-order Command Queue
   cl_command_queue commands = clCreateCommandQueue(context, device_id, CL_QUEUE_PROFILING_ENABLE | CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE
   , &err);
   

5. Finally, in the host code you need to set up the program, which contains and configures the kernels to be passed to the command queue by the host application. The load_file_to_memory function is used to load the file contents in the host machine memory space. The clCreateProgramWithBinary command downloads the FPGA binary (.xclbin) to the device and returns a cl_program handle. The following example shows the creation of the program using these API calls:

   char *fpga_bin;
   size_t fpga_bin_size;
   fpga_bin_size = load_file_to_memory(binaryName, &fpga_bin);
   
   cl_program program = clCreateProgramWithBinary(context, 1,
   				   (const cl_device_id* ) &device_id, &fpga_bin_size,
   				   (const unsigned char**) &fpga_bin, NULL, &err);
   

1. Create a kernel from the program and the loaded FPGA binary using the clCreateKernel command:

   // Create Kernel
   cl_kernel krnl = clCreateKernel(program, "krnl_idct", &err);
   

2. Set the kernel arguments using the clSetKernelArg. You can use this command to set the arguments for the kernel.

   // Set the kernel arguments
   clSetKernelArg(mKernel, 0, sizeof(cl_mem), &mInBuffer[0]);
   clSetKernelArg(mKernel, 1, sizeof(cl_mem), &mInBuffer[1]);
   clSetKernelArg(mKernel, 2, sizeof(cl_mem), &mOutBuffer[0]);
   clSetKernelArg(mKernel, 3, sizeof(int), &m_dev_ignore_dc);
   clSetKernelArg(mKernel, 4, sizeof(unsigned int), &mNumBlocks64);
   

3. The kernel is scheduled to run on the FPGA by using the clEnqueueTask. The request to execute the kernel is placed into the command queue and either waits for its turn, or is executed when ready, depending on the nature of the queue.

   clEnqueueTask(mQ, mKernel, 1, &inEvVec[mCount], &runEvVec[mCount]);
   

4. Because the clEnqueueTask (and clEnqueueMigrateMemObjects) command is asynchronous in nature, and will return immediately after the command is enqueued in the command queue, you might need to manage the scheduling of events within the host application. To resolve the dependencies among the commands in the host application, you can use clWaitForEvents or clFinish commands to pause or block execution of the host program. For example:

   // Execution waits until all commands in the command queue are finished
   clFinish(command_queue); 
   
   clWaitForEvents(1, &readevent); // Wait for clEnqueueReadBuffer event to finish
   

For more information on setting up the kernel, see the SDAccel Environment Programmers Guide (UG1277).