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

  • All the operations described in this topic must be performed by one account in the same region.
  • We strongly recommend that you use an f1 instance as a RAM user. To avoid unwanted operations, you must authorize the RAM user to perform required actions only. You must create a role for the RAM user and grant temporary permissions to the role to access the OSS buckets. If you want to encrypt the IP address, grant the RAM user to use Key Management Service (KMS). If you want the RAM user to check permissions, authorize the RAM user to view the resources of an account. Before you begin, complete the following:


  • Create an f1 instance and add a security group rule to allow Internet access to SSH Port 22 of the instance.
    Note Only the image we share with you can be used on an f1 instance. For more information, see Create an f1 instance.
  • Log on to the ECS console to obtain the instance ID.
  • Create an OSS bucket to upload your custom bitstream files. The OSS bucket and the f1 instance must be owned by one account and in the same region.
  • To encrypt your bitstream, activate Key Management Service (KMS).
  • To operate an f1 instance as a RAM user, you must do the following operations:


To configure the environment of FPGA Server Example, follow these steps.

Step 1. Connect to your f1 instance

Connect to the Linux instance.

Step 2. Install the basic environment

Run the following script to install the base environment.

source /opt/dcp1_1/script/            

Step 3. Download the OpenCL Example

Follow these steps to download the official opencl example.

  1. Create the /opt/tmp directory, and change the current directory to it.
    mkdir -p /opt/tmp
    cd /opt/tmp                    
    Now, you are at the /opt/tmp directory.

  2. Run the commands one by one to download and decompress the OpenCL Example file.
    tar -zxvf exm_opencl_matrix_mult_x64_linux.tgz                    
    The following figure displays the directory after decompression.

  3. Change the current directory to the matrix_mult directory and run the command for compilation.
    cd matrix_mult
    aoc -v -g --report ./device/                    

    The process of compilation takes several hours. You can open a new console, and run the top command to monitor processes and system resource usage on the instance and view the status of the compilation process.

Step 4. Upload the configuration file to the OSS bucket

Follow these steps to upload the configuration file.

  1. Run the commands to initialize the faascmd.
    # If needed, add the environment variable and grant the permission to run the commands
    export PATH=$PATH:/opt/dcp1_1/script/
    chmod +x /opt/dcp1_1/script/faascmd
    # Replace hereIsYourSecretId with your AccessKey ID. Replace hereIsYourSecretKey with your AccessKey Secret
    faascmd config --id=hereIsYourSecretId --key=hereIsYourSecretKey
    # Replace hereIsYourBucket with the bucket name of your OSS in the Region China (Hangzhou).
    faascmd auth --bucket=hereIsYourBucket                    
  2. Change the current directory to the matrix_mult/output_files directory, and upload the configuration file.
    cd matrix_mult/output_files # Now you are accessing/opt/tmp/matrix_mult/matrix_mult/output_files
    faascmd upload_object --object=afu_fit.gbs --file=afu_fit.gbs                    
  3. Use gbs to create an FPGA image.
    # Replace hereIsYourImageName with your image name. Replace hereIsYourImageTag with your image tag.
    faascmd create_image --object=dma_afu.gbs --fpgatype=intel --name=hereIsYourImageName --tags=hereIsYourImageTag --encrypted=false --shell=V1.1                    
  4. Run the faascmd list_images command to check whether the image is created. In the returned result, if "State":"success" is displayed, it means the image is created. Record the FpgaImageUUID.

Step 5. Download the image to your f1 instance

To download the image to your f1 instance, follow these steps:

  1. Run the command to obtain FPGA ID.
    # Replace hereIsYourInstanceId with your f1 instance ID.
    faascmd list_instances --instanceId=hereIsYourInstanceId                    
    Returned results sample: Record FpgaUUID in the returned result.

  2. Run the command to download the image to your f1 instance.
    # Replace hereIsYourInstanceID with your f1 instance ID. Replace hereIsFpgaUUID with your FPGA UUID. Replace hereIsImageUUID with your image UUID.
    faascmd download_image  --instanceId=hereIsYourInstanceID --fpgauuid=hereIsFpgaUUID --fpgatype=intel --imageuuid=hereIsImageUUID --imagetype=afu --shell=V0.11                    
  3. Run the command to check whether the image is downloaded.
    # Replace hereIsYourInstanceID with your f1 instance ID. Replace hereIsFpgaUUID with your FPGA UUID.
    faascmd fpga_status --fpgauuid=hereIsFpgaUUID --instanceId=hereIsYourInstanceID                    
    If "TaskStatus": "operating" exists in the returned result, it means the image is downloaded.

Step 6. Download the FPGA image to an FPGA chip

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

  1. Open the console in Step 1. If it is closed, repeat Step 1.
  2. Run the following command to configure the runtime environment for OpenCL.
    sh /opt/dcp1_1/opencl/opencl_bsp/linux64/libexec/                    
  3. Run the command to go back to the parent directory.
    cd .. /.. # Now, you are at the /opt/tmp/matrix_mult directory                   
  4. Run the command to compile.
    # Output the environment configuration
    cp matrix_mult.aocx ./bin/matrix_mult.aocx
    cd bin
    host matrix_mult.aocx                    

    If the following result is returned, it means the configuration is successful. Note that the last line must be Verification: PASS.

    [root@iZbpXXXXXZ bin]# ./host matrix_mult.aocx
    Matrix sizes:
      A: 2048 x 1024
      B: 1024 x 1024
      C: 2048 x 1024
    Initializing OpenCL
    Platform: Intel(R) FPGA SDK for OpenCL(TM)
    Using 1 device(s)
      skx_fpga_dcp_ddr : SKX DCP FPGA OpenCL BSP (acl0)
    Using AOCX: matrix_mult.aocx
    Generating input matrices
    Launching for device 0 (global size: 1024, 2048)
    Time: 40.415 ms
    Kernel time (device 0): 40.355 ms
    Throughput: 106.27 GFLOPS
    Computing reference output
    Verification: PASS