edit-icon download-icon

Use OpenCL on an f3 instance

Last Updated: Sep 05, 2018

This article introduces how to use Open Computing Language (OpenCL) to create an image, and then download the image to an FPGA chip.

Note

  • All the operations described in this article must be performed by one account in the same region.
  • We recommend that you use an f3 instance as a RAM user. You must create a role for the RAM user and grant temporary permissions to the role to access the OSS buckets.

Prerequisites

Before you begin the procedure, you must do the following:

Procedure

To create an image by using OpenCL on an f3 instance and download it to an FPGA chip, follow these steps.

Step 1. Set up the environment

To set up the environment, follow these steps.

  1. Connect to an f3 instance.

  2. Run the command below to open the installation script. Add # to line 5 to comment out unset XILINX_SDX and then save the file.

    1. vim /root/xbinst_oem/setup.sh

    修改setup.sh文件

  3. Run the command to install Screen.

    1. yum install screen -y
  4. Run the command to open a new screen.

    1. screen -S f3opencl
  5. Run the command to set up a secured environment to download a file.

    1. source /root/xbinst_oem/f3_env_setup.sh xocl

Step 2. Compile a binary file

To compile a binary file, follow these steps.

  1. Run the command to change the directory.

    1. cd /opt/Xilinx/SDx/2017.4.op/examples/vadd
  2. Run the cat sdaccel.mk | grep "XDEVICE=" command to check the configuration of the XDEVICE parameter. Make sure it is set to xilinx_aliyun-f3_dynamic_5_0.

  3. Run the command to modify the common.mk file.

    1. vim ../common/common.mk

    Replace Line 63 (parameters may be in lines 60 - 62, depending on the file):

    1. CLCC_OPT += $(CLCC_OPT_LEVEL) ${DEVICE_REPO_OPT} --platform ${XDEVICE} -o ${XCLBIN} ${KERNEL_DEFS} ${KERNEL_INCS}

    With:

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

    Note: You must submit a DCP file, not a bit file, to the compilation server. Therefore, you must add the parameter --xp param:compiler.acceleratorBinaryContent=dcp to enable Xilinx® OpenCL™ Compiler (xocc) to generate a DCP file.

  4. Run the command to compile the program.

    1. export XILINX_SDX=/opt/Xilinx/SDx/2017.4.op
    2. make -f sdaccel.mk xbin_hw

    If the following information is displayed, the compilation of the binary file has started. The process may take several hours. Please be patient.

    compilation

3. Check the packaging script

Run the command to check whether the packaging script exists or not.

  1. file /root/xbinst_oem/sdaccel_package.sh

If the returned message contains cannot open (No such file or directory), the file does not exist. You need to download the script by running the following command.

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

Step 4. Create an image

To create an image, follow these steps.

  1. Run the command to set up the OSS environment.
    1. # Replace hereIsMySecretId, hereIsMySecretKey and hereIsMyBucket with your AccessKeyID, AccessKeySecret and Bucket name
    2. faascmd config --id=hereIsMySecretId --key=hereIsMySecretKey
    3. faascmd auth --bucket=hereIsMyBucket
  2. Run the lscommand to obtain the file name suffixed by .xclbin.

    获取文件名

  3. Run the command to package the binary file.

    1. /root/xbinst_oem/sdaccel_package.sh -xclbin=/opt/Xilinx/SDx/2017.4.op/examples/vadd/bin_vadd_hw.xclbin

    After the packaging is completed, you get a packaged file in the same directory, as shown below.

    查看打包好的文件

Step 5. Create an image

You can use a scripted process or step by step process to upload the package file and download the FPGA image.

  • Scripted process: Only applicable to f3 instances with one FPGA card.
    1. Run the command to upload the packaged file and create an image.

      1. sh /root/xbinst_oem/tool/faas_upload_and_create_image.sh <bit.tar.gz - the packaged file to upload>

      上传并生成镜像文件脚本运行结果

    2. Download the image file.

      1. sh /root/xbinst_oem/tool/faas_download_image.sh <bit.tar.gz - the packaged file> 0 # The last number is the FPGA serial No. of the instance

      Note: 0 indicates the first FPGA of the f3 instance. For single-FPGA instances, the FPGA serial No. is always 0. For instances with multiple FPGAs, such as an instance with four FPGAs, the serial No. are 0, 1, 2 and 3.

      To download the same image to multiple FPGAs, add the serial No. to the end:

      1. sh faas_download_image.sh bit.tar.gz 0 1 2
  • Step by step process:
    1. Run the command to upload the package to your OSS Bucket. Then, upload gbs in your OSS Bucket to the OSS Bucket in the FaaS administrative unit.

      1. faascmd upload_object --object=bit.tar.gz --file=bit.tar.gz
      2. faascmd create_image --object=bit.tar.gz --fpgatype=xilinx --name=hereIsFPGAImageName --tags=hereIsFPGAImageTag --encrypted=false --shell=f30001

      upload_object示例

      create_image

    2. Run the command to view if the FPGA image is downloadable.

      1. faascmd list_images

      If the returned message shows "State":"success", the FPGA image is ready for downloading. Find FpgaImageUUID and note it down.

      list_images返回结果

    3. Run the command to find and note down FpgaUUID in the returned message.

      1. faascmd list_instances --instanceId=hereIsYourInstanceId # Replace hereIsYourInstanceId with the f3 instance ID
    4. Run the command to download the FPGA image.

      1. faascmd download_image --instanceId=hereIsYourInstanceId --fpgauuid=hereIsFpgaUUID --fpgatype=xilinx --imageuuid=hereIsImageUUID --imagetype=afu --shell=f30001
      2. # Replace hereIsYourInstanceId with the f3 instance ID, hereIsFpgaUUID with the FpgaUUID, and hereIsImageUUID with the FpgaImageUUID

      下载镜像

    5. Run the command to view if the image is downloaded successfully.

      1. faascmd fpga_status --fpgauuid=hereIsFpgaUUID --instanceId=hereIsYourInstanceId # Replace hereIsFpgaUUID with the FpgaUUID, and hereIsYourInstanceId with the f3 instance ID.

      Below is an example of the returned message. If the FpgaImageUUID in the message is the same as the FpgaImageUUID you note down and the message shows "TaskStatus":"valid", the image is downloaded successfully.

      镜像下载成功

Step 6. Run the Host program

Run the commands to execute the Host program.

  1. make -f sdaccel.mk host
  2. unset XILINX_SDX
  3. ./vadd bin_vadd_hw.xclbin

If Test Passed is returned, the test is successful.

Other common commands

In this section, some common commands for an FPGA instance are introduced.

Task Command
View the help document make -f ./sdaccel.mk help
Run software simulation make -f ./sdaccel.mk run_cpu_em
Run hardware simulation make -f ./sdaccel.mk run_hw_em
Compile the host code only make -f ./sdaccel.mk host
Compile and generate files for downloading make -f sdaccel.mk xbin_hw
Clear a job directory make -f sdaccel.mk clean
Force clear a job directory make -f sdaccel.mk cleanall

Note: During simulation, follow the Xilinx simulation process. You do not need to set up the F3_env_setup environment.

Thank you! We've received your feedback.