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

  • 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.


  • Create an f3 instance.
    • Only the image we share with you can be used on an f3 instance.
    • Select Assign public IP when creating an instance, so that the instance can access the Internet.
    • The security group of the f3 instance has added the rule for allowing access to the SSH (22) port.
  • Log on to the ECS console and obtain the instance ID of your f3 instance.
  • Creat an OSS Bucket in the same region as your f3 instance by using the same account. For details, see Sign up for OSS and Create a bucket.
  • To operate FPGA as a RAM user, do the following in advance:


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.
    vim /root/xbinst_oem/

  3. Run the command to install Screen.
    yum install screen -y
  4. Run the command to open a new screen.
    screen -S f3opencl
  5. Run the command to set up a secured environment to download a file.
    source /root/xbinst_oem/ xocl

Step 2. Compile a binary file

To compile a binary file, follow these steps.

  1. Run the command to change the directory.
    cd /opt/Xilinx/SDx/2017.4.op/examples/vadd
  2. Run the cat | 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 vim command to modify the file.
    vim ../common/

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



    CLCC_OPT += $(CLCC_OPT_LEVEL) ${DEVICE_REPO_OPT} --platform ${XDEVICE} -o ${XCLBIN} ${KERNEL_DEFS} ${KERNEL_INCS} --xp param:compiler.acceleratorBinaryContent=dcp
  4. Run the command to compile the program.
    export XILINX_SDX=/opt/Xilinx/SDx/2017.4.op
    make -f 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.

Step 3:  Check the packaging script

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

file /root/xbinst_oem/

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.


Step 4:  Create an image

To create an image, follow these steps.

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

  3. Run the command to package the binary file.
    /root/xbinst_oem/ -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.
      sh /root/xbinst_oem/tool/ 

    2. Download the image file.
      sh  /root/xbinst_oem/tool/ <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:

      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.
      faascmd upload_object --object=bit.tar.gz --file=bit.tar.gz
      faascmd create_image --object=bit.tar.gz --fpgatype=xilinx --name=hereIsFPGAImageName --tags=hereIsFPGAImageTag --encrypted=false --shell=f30001

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

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

    3. Run the command to find and note down FpgaUUID in the returned message.
      faascmd list_instances --instanceId=hereIsYourInstanceId # Replace hereIsYourInstanceId with the f3 instance ID
    4. Run the command to download the FPGA image.
      faascmd download_image --instanceId=hereIsYourInstanceId --fpgauuid=hereIsFpgaUUID --fpgatype=xilinx --imageuuid=hereIsImageUUID --imagetype=afu --shell=f30001
      # 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.
      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.

make -f host
./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 ./ help
Run software simulation Make-F./sdaccel. mk maid
Run hardware simulation make -f ./ run_hw_em
Compile the host code only make -f ./ host
Compile and generate files for downloading make -f xbin_hw
Clear a job directory make -f clean
Force clear a job directory make -f cleanall
Note During simulation, follow the Xilinx simulation process. You do not need to set up the F3_env_setup environment.