edit-icon download-icon

Use OpenCL on an f2 instance

Last Updated: Jul 21, 2018

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

Note:

  • All the operations described in this article must be performed by one account in the same region.
  • We strongly recommend that you use an f2 instance as a RAM user. To avoid unwanted operations, you must authorize the RAM user to run required actions only. 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 f2 instance and download it to an FPGA chip, follow these steps.

Step 1. Set up the environment

To set up the environment on an f2 instance, follow these steps.

  1. Connect to an f2 instance.

  2. Run the vim /root/xbinst_oem/setup.sh command to modify the file: comment out the unset XILINX_SDX line (Line 5), and save the file.

    modify the setup.sh file

  3. Run the command to install Screen to keep the terminal session persistent.

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

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

    1. source /root/xbinst_oem/F2_env_setup.sh

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.2/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-ku115-f2:4ddr-xpr:4.2.

  3. Run the vim ../common/common.mk command to modify the common.mk file: Replace Line 63

    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:

    • The parameters may be in lines between Line 60 and Line 62, which is determined by your file.
    • 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.2
    2. make -f sdaccel.mk xbin_hw

    If the following information is displayed, it means the compilation of the binary file is in progress. The process may take several hours. Please be patient.

    Compile the binary file

Step 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

Note: A returned message containing cannot open (No such file or directory) means no packaging script exists. Then, 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 own AccessKeyID, AccessKeySecret, and OSS Bucket name
    2. faascmd config --id=hereIsMySecretId --key=hereIsMySecretKey
    3. faascmd auth --bucket=hereIsMyBucket
  2. Run the ls command to obtain the file name.

    Obtain the file name

  3. Run the command to package the binary file.

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

    After the packaging is completed, you have a packaged file in the same directory, such as 17_10_28-021904_SDAccel_Kernel.tar.gz in this example.

    Check the packaged file

  4. Run the command to upload the packaged file to your own OSS bucket.

    1. # Replace the file name with the name of the packaged file
    2. faascmd upload_object --object=bit.tar.gz --file=bit.tar.gz
  5. Run the command to create an image.

    1. # Replace bit.tar.gz, hereIsFPGAImageName, and hereIsFPGAImageTag with the name of the packaged file, the image name, and the image tag
    2. faascmd create_image --object=bit.tar.gz --fpgatype=xilinx --name=hereIsFPGAImageName --tags=hereIsFPGAImageTag --encrypted=false --shell=20171121

    The example returned result is displayed as follows. The "State":"queued" means the task is in the queue, and the image creation is in progress.

    Queued_Start creating the image

    Note: Creation of an image consumes time. You can run the faascmd list_images command to check the image status. In the returned result, if "State":"success" displays, it means the image is created successfully.
    Check the image status

    Record the FpgaImageUUID.

Step 5. Download the image

To download the image to an FPGA chip, follow these steps.

  1. Run the command to obtain the FpgaUUID.

    1. # Replace hereIsYourInstanceId with your f2 instance ID
    2. faascmd list_instances --instanceId=hereIsYourInstanceId

    Obtain FpgaUUID

    Note: Record the FpgaUUID.

  2. Run the command to download the image.

    1. # Replace hereIsYourInstanceID with your f2 instance ID. Replace hereIsFpgaUUID with the recorded FpgaUUID. Replace hereIsImageUUID with the recorded FpgaImageUUID
    2. faascmd download_image --instanceId=hereIsYourInstanceId --fpgauuid=hereIsFpgaUUID --fpgatype=xilinx --imageuuid=hereIsImageUUID --imagetype=afu --shell=20171121

    The example returned result is displayed as follows. The "State":"committed" means the image is downloaded successfully.

    Image downloaded successfully

    Note: You can run the command to check whether the image is downloaded successfully or not.

    1. # Replace hereIsYourInstanceID with your f2 instance ID. Replace hereIsFpgaUUID with your recorded FpgaUUID
    2. faascmd fpga_status --instanceId=hereIsYourInstanceID --fpgauuid=hereIsFpgaUUID

    The example returned result is displayed as follows. If "TaskStatus":"valid" exists and the displayed FpgaImageUUID is your image FpgaImageUUID, the image is downloaded successfully.

    Check the image download status

Step 6. Run the Host program

Run the commands to run 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 ake -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 of sdx2017.2, the device must be xilinx_aliyun-ku115-f2_4ddr-xpr_4_2.
  • During simulation, run the Xilinx simulation process. You do not need to set up the F2_env_setup environment.
Thank you! We've received your feedback.