Use OpenCL on an f3 instance

Procedure

Step 1. Set up the environment

1. Connect to an f3 instance.
   Note The compilation process can take several hours. We recommend that you log on by using Screen or nohup to avoid a forced logout due to an SSH timeout.
2. Run the following command to install Screen:

   yum install screen -y                        

3. Run the following command to start Screen:

   screen -S f3opencl                        

4. Run the following command to set up the environment:

   source /root/xbinst_oem/F3_env_setup.sh xocl  #Run this command each time you open a new terminal window.

   Note

   • To set up the environment, you need to install the xocl driver, configure the vivado environment variable, check the vivado license, detect the aliyun-f3 sdaccel platform, configure the 2018.2 runtime, and check the faascmd version.
   • If you want to run an emulated version of Vivado, do not run the preceding commands to set up the environment. You need to separately configure the environment variable only for Vivado.
   • We recommend that you use Makefile for emulation.

Step 2. Compile a binary file

Perform the following operations to compile the vadd and kernel_global_bandwidth binary files:

• Example 1: vadd
  1. Copy the example directory.

     cp -rf /opt/Xilinx/SDx/2018.2/examples ./

  2. Go to the vadd directory.

     cd examples/vadd/

  3. Run the cat sdaccel.mk | grep "XDEVICE=" command to check the value of XDEVICE. Make sure that the value is xilinx_aliyun-f3_dynamic_5_0.
  4. Perform the following operations to modify the common.mk file:
     1. Run the vim ../common/common.mk command to open the file.
     2. At the end of code line 61, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The parameter can be added in code line 60, 61, or 62. The following section shows the modified code:

        CLCC_OPT += $(CLCC_OPT_LEVEL) ${DEVICE_REPO_OPT} --platform ${XDEVICE} ${KERNEL_DEFS} ${KERNEL_INCS} --xp param:compiler.acceleratorBinaryContent=dcp

        Note You must add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp so that Xilinx® OpenCL™ Compiler (xocc) can generate a DCP file after the placement and routing are completed. The file cannot be a bit file. Then, you can submit the DCP file to the compilation server.
  5. Run the following command to compile the program:

     make -f sdaccel.mk xbin_hw

     If the information displayed is similar to the following example, the binary file is being compiled. The compilation process can take several hours.
• Example 2: kernel_global_bandwidth
  1. Run the following commands in sequence to clone xilinx 2018.2 example:

     git clone https://github.com/Xilinx/SDAccel_Examples.git

     cd SDAccel_Examples/

     git checkout 2018.2

     Note The Git branch version must be 2018.2.
  2. Run the cd getting_started/kernel_to_gmem/kernel_global_bandwidth/ command to access the directory.
  3. Perform the following operations to modify the Makefile file:
     1. Run the vim Makefile command to open the file.
     2. Set DEVICES to xilinx_aliyun-f3_dynamic_5_0.
     3. In code line 33, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The following section shows the modified code:

        CLFLAGS +=--xp "param:compiler.acceleratorBinaryContent=dcp" --xp "param:compiler.preserveHlsOutput=1" --xp "param:compiler.generateExtraRunData=true" --max_memory_ports bandwidth -DNDDR_BANKS=$(ddr_banks)

  4. Run the following command to compile the program:

     make TARGET=hw

     If the information displayed is similar to the following example, the binary file is being compiled. The compilation process can take several hours.

     

Step 3. Check the packaging script

file /root/xbinst_oem/sdaccel_package.sh

wget http://fpga-tools.oss-cn-shanghai.aliyuncs.com/sdaccel_package.sh

Step 4. Create an image

1. Initialize the faascmd tool and set up the OSS environment.
   1. Run the following command to configure the AccessKey pair of the RAM user:

      #Replace <hereIsYourSecretId> with the AccessKey ID of the RAM user, and <hereIsYourSecretKey> with the AccessKey secret of the RAM user.
      faascmd config --id=<hereIsYourSecretId> --key=<hereIsYourSecretKey>  

   2. Run the following command to configure the OSS bucket dedicated to FaaS:

   #Replace <hereIsYourBucket> with the name of the OSS bucket that you created.
   faascmd auth --bucket=<hereIsYourBucket>  

2. Run the ls command to obtain the file with the suffix .xclbin.
   
3. Run the following command to package the binary file:

   /root/xbinst_oem/sdaccel_package.sh -xclbin=/opt/Xilinx/SDx/2018.2/examples/vadd/bin_vadd_hw.xclbin

   After the binary file is packaged, you can find the packaged file in the same directory, as shown in the following figure.

Step 5. Download the image

Step 6. Run the host program

1. Run the following command to set up the environment:

   source /root/xbinst_oem/F3_env_setup.sh xocl  #Run the command each time you open a new terminal window.

2. Configure the sdaccel.ini file.
   In the directory where the Host binary file is located, run the vim sdaccel.ini command to create the sdaccel.ini file and enter the following content:

   [Debug]
   profile=true
   [Runtime]
   runtime_log = "run.log"
   hal_log = hal.log
   ert=false
   kds=false

3. Run the host program.
   • For vadd, run the following commands:

     make -f sdaccel.mk host

     ./vadd bin_vadd_hw.xclbin

   • For kernel_global_bandwidth, run the following command:

     ./kernel_global

   If Test Passed is displayed in the command output, the test is passed.

Other common commands

The following table describes some common commands for f3 instances.