This topic describes how to use Open Computing Language (OpenCL) on an f1 instance to create an image and download the image to a Field Programmable Gate Array (FPGA).

Prerequisites

  • An Alibaba Cloud account is created. To create an Alibaba Cloud account, go to the Alibaba Cloud official website.
  • An f1 instance is created and can access the Internet.
    Note Only FaaS F1 basic images from Alibaba Cloud Marketplace can be used in f1 instances. For more information, see Create an f1 instance.
  • The rule for allowing traffic on SSH port 22 is configured for the security groups where the f1 instance resides.
  • The ID of the f1 instance is obtained from the Instances page in the ECS console.
  • An OSS bucket for FaaS is created.

    The OSS bucket and the f1 instance must be in the same account and the same region. For more information, see Create buckets.

  • To encrypt files, activate Key Management Service (KMS) first.

    For more information, see Activate Key Management Service (KMS).

  • You must complete the following operations before you can manage FPGA-based instance as a RAM user:
    • Create a RAM user and grant permissions to the RAM user. For more information, see Create a RAM user and Grant permissions to a RAM user.

      The permissions you must grant to the RAM users include AliyunECSReadOnlyAccess, AliyunOSSFullAccess, and AliyunRAMFullAccess.

    • Click here to grant permissions to FaaS.
    • Obtain the AccessKey ID and AccessKey secret of the RAM user.

Background information

Before you perform the operations, take note of the following items:

  • All operations described in this topic must be performed by a single account within the same region.
  • We strongly recommend that you manage FaaS instances 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 specified OSS bucket. Then, you can download the original DCP project from the OSS bucket and manage the FPGA image. If you want to encrypt the IP address, you must authorize the RAM user to use Key Management Service (KMS). If you want the RAM user to check permissions of Alibaba Cloud accounts, you must authorize the RAM user to view the resources of Alibaba Cloud accounts.

Procedure

Step 1. Connect to an f1 instance

For more information, see Connect to a Linux instance by using a username and password.

Step 2. Install the basic environment

Run the following script to install the basic environment:
source /opt/dcp1_1/script/f1_env_set.sh

Step 3. Download the OpenCL example

  1. Run the following commands in sequence to create and switch to the /opt/tmp directory:
    mkdir -p /opt/tmp         
    cd /opt/tmp            
    You are now in the /opt/tmp directory. Enter the tmp directory
  2. Run the following commands in sequence to download and decompress the example file:
    wget https://www.altera.com/content/dam/altera-www/global/en_US/others/support/examples/download/exm_opencl_matrix_mult_x64_linux.tgz   
    tar -zxvf exm_opencl_matrix_mult_x64_linux.tgz        
    The following figure shows the directory after decompression. Decompress the example file
  3. Run the following commands in sequence to access the matrix_mult directory for compilation:
    cd matrix_mult             
    aoc -v -g --report ./device/matrix_mult.cl             
    The compilation process may take a few hours. You can start another session, and run the top command to monitor system resource usage and view the compilation status.

Step 4. Upload the configuration file

  1. Run the following commands in sequence to initialize the faascmd tool:
    #Configure the environment variable.
    export PATH=$PATH:/opt/dcp1_1/script/
    #Grant execute permissions to the faascmd tool.
    chmod +x /opt/dcp1_1/script/faascmd
    #Replace <hereIsYourSecretId> in the command with your AccessKey ID. Replace <hereIsYourSecretKey> with your AccessKey secret.
    faascmd config --id=<hereIsYourSecretId> --key=<hereIsYourSecretKey>
    #Replace <hereIsYourBucket> in the command with your bucket name.
    faascmd auth --bucket=<hereIsYourBucket>
  2. Run the following commands in sequence to access the matrix_mult/output_files directory and upload the configuration file:
    cd matrix_mult/output_files         

    You are now in the /opt/tmp/matrix_mult/matrix_mult/output_files directory.

    faascmd upload_object --object=afu_fit.gbs --file=afu_fit.gbs           
  3. Run the following command to use the GBS file to create an FPGA image:
    #Replace <hereIsYourImageName> in the command 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 following command to check whether the image is created:
    faascmd list_images
    If "State":"success" is displayed in the command output, the image is created. Record the value of FpgaImageUUID in the command output to be used in a later step.The image is created

Step 5. Download the image to the f1 instance

  1. Run the following command to obtain the ID of your FPGA instance:
    #Replace <hereIsYourInstanceId> in the command with the ID of your FPGA instance.
    faascmd list_instances --instanceId=<hereIsYourInstanceId>                 
    The following figure shows the command output. Record the value of FpgaUUID.fpgaUUID
  2. Run the following command to download the image to the f1 instance.
    #Replace <hereIsYourInstanceID> in the command with the instance ID that you recorded. Replace <hereIsFpgaUUID> with the value of FpgaUUID that you recorded. Replace <hereIsImageUUID> with the value of FpgaImageUUID that you recorded.
    faascmd download_image  --instanceId=<hereIsYourInstanceID> --fpgauuid=<hereIsFpgaUUID> --fpgatype=intel --imageuuid=<hereIsImageUUID> --imagetype=afu --shell=V0.11                 
  3. Run the following command to check whether the image is downloaded:
    # Replace <hereIsYourInstanceID> in the command with the instance ID that you recorded. Replace <hereIsFpgaUUID> with the value of FpgaUUID that you recorded.
    faascmd fpga_status --fpgauuid=<hereIsFpgaUUID> --instanceId=<hereIsYourInstanceID>            
    If "TaskStatus":"operating" is displayed in the command output, the image is downloaded.The image is downloaded

Step 6. Download the FPGA image to an FPGA

  1. Open the environment window in Step 2. If the window is closed, perform the operations in Step 2 again.
  2. Run the following command to configure the runtime environment for OpenCL:
    sh /opt/dcp1_1/opencl/opencl_bsp/linux64/libexec/setup_permissions.sh                 
  3. Run the following command to go back to the parent directory:
    cd .. /..           

    You are now in the /opt/tmp/matrix_mult directory.

  4. Run the following command for compilation:
    make
    # Show the environment configuration.
    export CL_CONTEXT_COMPILER_MODE_ALTERA=3
    cp matrix_mult.aocx ./bin/matrix_mult.aocx
    cd bin
    host matrix_mult.aocx               
    If the following output is displayed, the configuration is completed. 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
    Verifying
    Verification: PASS