FPGA as a Service:Use OpenCL on an f3 instance

Usage notes

• All operations described in this topic must be performed by the same account in the same region.

• If you perform the operations as a regular user, we recommend that you contact an administrator to copy the /root/xbinst_oem directory in the image to the root directory of the regular user.

• If you perform the operations as a regular user, contact an administrator and apply for the permissions on the /dev/virtio-ports/FaaS.agent directory.

• We recommend that you manage an FPGA-accelerated instance as a RAM user. You must create a role for the RAM user and grant the role temporary permissions to access the specified OSS bucket.

• The operations and commands described in this topic are based on version 2018.2 of the SDAccel development environment. If you use the SDAccel development environment of other versions, the operations and commands may vary.

Step 1: Set up the environment

When you set up the environment, take note of the following items:

• The environment setup process involves the following operations: install the xocl driver, configure the Vivado environment variables, check the Vivado license, check the Alibaba Cloud f3 SDAccel platform, and configure the 2018.2 runtime.

• If you want to only run a Vivado emulator, do not perform steps 2 to 4 when you set up the environment. To run a Vivado emulator, you need to only configure the Vivado environment variables.

• We recommend that you use Makefile for emulation.

1. Connect to the f3 instance.

   For more information, see Connect to a Linux instance by using a username and password.

   Important

   The compilation process may take several hours. To prevent an unexpected disconnection due to an SSH timeout, we recommend that you use Screen or nohup to connect to the instance.

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:

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

5. Download and install the y2k22_patch-1.2.zip patch.

   Download URL: Xilinx. The y2k22_patch-1.2.zip patch is used to fix the timestamp overflow bug in Xilinx.

Step 2: Compile a binary file

The following examples show how to compile the vadd and kernel_global_bandwidth binary files.

Example 1: Compile the vadd binary file

1. Run the following command to copy the examples directory:

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

2. Run the following command to go to the vadd directory:

   cd examples/vadd/

3. Run the following command to check the value of XDEVICE:

   cat sdaccel.mk | grep "XDEVICE="

   Make sure that the value of XDEVICE is xilinx_aliyun-f3_dynamic_5_0.

4. Modify the common.mk file.

   1. Run the following command to open the common.mk file:

      vim ../common/common.mk

   2. Add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp.

      At the end of code line 60, 61, or 62, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The code line in which you need to add the compilation parameter varies based on the content of your common.mk file. The following sample code provides an example:

      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 design checkpoint (DCP) file instead of a .bit file after the placement and routing are complete. Then, you can submit the DCP file to the compilation server.

5. Run the following command to compile the binary file:

   make -f sdaccel.mk xbin_hw

   Important

   The compilation process may take several hours. Wait until the compilation is complete.

   If information similar to the following example is displayed, the vadd binary file is being compiled.

Example 2: Compile the kernel_global_bandwidth binary file

1. Run the following commands in sequence to clone xilinx 2018.2 examples:

   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 following command to go to the kernel_global_bandwidth directory:

   cd getting_started/kernel_to_gmem/kernel_global_bandwidth

3. Modify the Makefile file.

   1. Run the following command to open the Makefile file:

      vim Makefile

   2. Set DEVICES to xilinx_aliyun-f3_dynamic_5_0.

   3. Add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp.

      At the end of code line 33, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The following sample code provides an example:

      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 binary file:

   Important

   The compilation process may take several hours. Wait until the compilation is complete.

   make TARGET=hw

   If information similar to the following example is displayed, the kernel_global_bandwidth binary file is being compiled.

Step 3: Check the packaging script

file /home/user1/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 faasutil 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.
      faasutil 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.
      faasutil auth --bucket=<hereIsYourBucket>

2. Run the following command to obtain the file with the file name extension .xclbin:

   ls

   The following information is returned.

   

3. Run the following command to package the binary file:

   /home/user1/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. The following figure shows an example.

Step 5: Download the image

This step describes how to use the faasutil tool to upload netlist files and download an FPGA image. For more information about how to use faasutil, see Use faasutil.

1. Run the following commands in sequence to upload the package to an OSS bucket:

   • Run the following command to upload the package to your OSS bucket:

     faasutil put_object --object=bit.tar.gz --file=bit.tar.gz  #--object(Object file in oss bucket) --file(Local file need to put)

     The following information is returned.

     

   • Run the following command to upload the package from your OSS bucket to the OSS bucket in the FaaS administrative unit:

     faasutil create_image --object=bit.tar.gz --fpgatype=xilinx --name=<HereIsFPGAImageName> --tags=<HereIsFPGAImageTag> --encrypted=false --shell=<hereIsShellVersionOfFPGA> # <HereIsFPGAImageTag>: optional. The tag of the image.  encrypted: optional. Specifies whether to encrypt the image. <HereIsShellVersionOfFPGA>: the default version.

     The following information is returned.

     

2. Run the following command to check whether the FPGA image is downloadable:

   faasutil list_images

   In the command output:

   • If the value of "State" is "compiling", the FPGA image is being compiled.

     

   • If the value of "State" is "success", the FPGA image can be downloaded. Find and record the value of FpgaImageUniqueId. Then, you can use the image UUID to download the FPGA image by running the faasutil download_image command.

3. Run the following command. Find and record the value of fpga_bdf in the command output.

   faasutil list_instances

   

4. Run the following command to download the FPGA image:

   faasutil download_image --bdf=<fpga_bdf> --fpgaImageUniqueId=<image_uuid> # Replace <fpga_bdf> with the value obtained in the previous step, and <image_uuid> with the UUID of the image.

   

5. Run the following command to check whether the image is downloaded:

   faasutil fpga_status --bdf=<fpga_bdf>

   A command output similar to the following one is displayed. If the value of imageuuid in the command output is the same as the value of FpgaImageUniqueId that you obtained and the value of fpgaStatus is valid, the image is downloaded.

Step 6: Run the host program

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

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

2. Configure the sdaccel.ini file.

   In the directory in which the host binary file resides, run the following command to create the sdaccel.ini file:

   vim sdaccel.ini

   After the sdaccel.ini file is created, add the following content to the file:

   [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

     sudo ./vadd bin_vadd_hw.xclbin

   • For kernel_global_bandwidth, run the following command:

     sudo ./kernel_global

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

Common commands

The following table describes some common commands that you can run to perform operations on FPGA-accelerated instances.