edit-icon download-icon

Use OpenCL on an f1 instance

Last Updated: May 24, 2018

This article 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 article 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:


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 script to install the basic environment.

  1. source /opt/dcp1_0/script/f1_env_set.sh

Step 3. Download the OpenCL Example

To download the OpenCL Example, follow these steps:

  1. Create the /opt/tmp directory, and change the current directory to it.

    1. mkdir -p /opt/tmp
    2. cd /opt/tmp

    Now, you are at the /opt/tmp directory.
    View the  /opt/tmp directory

  2. Run the commands one by one to download and decompress the OpenCL Example file.

    1. wget https://www.altera.com/content/dam/altera-www/global/en_US/others/support/examples/download/exm_opencl_matrix_mult_x64_linux.tgz
    2. tar -zxvf exm_opencl_matrix_mult_x64_linux.tgz

    The following figure displays the directory after decompression.
    The /opt/tmp directory

  3. Change the current directory to the matrix_mult directory and run the command for compilation.

    1. cd matrix_mult
    2. aoc -v -g --report ./device/matrix_mult.cl

    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

  1. Run the commands to initialize the faascmd.

    1. # If needed, add the environment variable and grant the permission to run the commands
    2. export PATH=$PATH:/opt/dcp1_0/script/
    3. chmod +x /opt/dcp1_0/script/faascmd
    4. # Replace hereIsMySecretId with your AccessKey ID. Replace hereIsMySecretKey with your AccessKey Secret
    5. faascmd config --id=hereIsMySecretId --key=hereIsMySecretKey
    6. # Replace hereIsMyBucket with the bucket name of your OSS in the Region China East 1.
    7. faascmd auth --bucket=hereIsMyBucket
  2. Change the current directory to the matrix_mult/output_files directory, and upload the configuration file.

    1. cd matrix_mult/output_files # Now you are accessing /opt/tmp/matrix_mult/matrix_mult/output_files
    2. faascmd upload_object --object=afu_fit.gbs --file=afu_fit.gbs
  3. Use gbs to create an FPGA image.

    1. # Replace hereIsFPGAImageName with your image name. Replace hereIsFPGAImageTag with the tag of your image.
    2. faascmd create_image --object=afu_fit.gbs --fpgatype=intel --name=hereIsFPGAImageName --tags=hereIsFPGAImageTag --encrypted=false --shell=V0.11
  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.
    Check whether the image is successfully created

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.

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

    Record FpgaUUID in the returned result.
    Obtain the FPGA ID

  2. Run the command to download the image to your f1 instance.

    1. # Replace hereIsYourInstanceID with your f1 instance ID. Replace hereIsFpgaUUID with your FpgaUUID. Replace hereIsImageUUID with your FpgaImageUUID.
    2. 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.

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

    If "TaskStatus": "operating" exists in the returned result, it means the image is downloaded.
    Check whether the image is downloaded successfully

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.

    1. sh /opt/dcp1_0/opencl/opencl_bsp/linux64/libexec/setup_permissions.sh
  3. Run the command to go back to the parent directory.

    1. cd ../.. # Now, you are at the /opt/tmp/matrix_mult directory
  4. Run the command to compile.

    1. make
    2. # Output the environment configuration
    4. cp matrix_mult.aocx ./bin/matrix_mult.aocx
    5. cd bin
    6. 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.

    1. [root@iZbpXXXXXZ bin]# ./host matrix_mult.aocx
    2. Matrix sizes:
    3. A: 2048 x 1024
    4. B: 1024 x 1024
    5. C: 2048 x 1024
    6. Initializing OpenCL
    7. Platform: Intel(R) FPGA SDK for OpenCL(TM)
    8. Using 1 device(s)
    9. skx_fpga_dcp_ddr : SKX DCP FPGA OpenCL BSP (acl0)
    10. Using AOCX: matrix_mult.aocx
    11. Generating input matrices
    12. Launching for device 0 (global size: 1024, 2048)
    13. Time: 40.415 ms
    14. Kernel time (device 0): 40.355 ms
    15. Throughput: 106.27 GFLOPS
    16. Computing reference output
    17. Verifying
    18. Verification: PASS
Thank you! We've received your feedback.