This topic describes how to implement the Register Transfer Level (RTL) design on an f3 instance.

Prerequisites

  • An Alibaba Cloud account is created. To create an Alibaba Cloud account, go to the Alibaba Cloud official website.
  • An f3 instance is created and can access the Internet. For more information, see Create an f3 instance.
  • A rule is added to the security group to which the f3 instance belongs to allow access over SSH port 22. For more information, see Add security group rules.
  • The ID of the f3 instance is obtained on the Instances page of the ECS console.
  • An Object Storage Service (OSS) bucket dedicated to FPGA as a Service (FaaS) is created in the China (Shanghai) region. For more information, see Create buckets.
    Note The bucket grants read and write permissions to the FaaS administrator account. We recommend that you do not store information that is not related to FaaS.
  • 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 recommend that you perform operations on an f3 instance as a RAM user. We recommend that you grant the RAM user necessary permissions based on the principle of least privilege, such as permissions to access DCP/xclbin files in OSS buckets, upload the Vivado compilation log, and manage specified ECS instances. You must also specify the RAM role AliyunFAASDefaultRole. By default, FaaS uses the role to access resources hosted in other cloud services. The AliyunFAASRolePolicy policy of the role includes the permissions on Key Management Service (KMS) through which you can encrypt IP addresses.

Procedure

  1. Connect to an f3 instance.
    Note The compilation process may take two to three hours. We recommend that you use nohup or Virtual Network Computing (VNC) to connect to the instance to avoid unexpected disconnection.
  2. Download and decompress the RTL design.
  3. Set up the environment.
    • If the driver is xdma, run the following command to set up the environment:
      source /root/xbinst_oem/F3_env_setup.sh xdma #Run the command each time you open a new terminal window.  
    • If the driver is xocl, run the following command to set up the environment:
      source /root/xbinst_oem/F3_env_setup.sh xocl #Run the command each time you open a new terminal window.
    Note The process to set up the environment involves installing the xdma or xocl driver, setting the vivado environment variable, checking the vivado license, detecting the aliyun-f3 sdaccel platform, configuring 2018.2 runtime, and checking the faascmd version.
  4. Specify an OSS bucket.
    faascmd config --id=<hereIsYourSecretId> --key=<hereIsYourSecretKey> #Replace <hereIsYourSecretId> with the AccessKey ID, and <hereIsYourSecretKey> with the AccessKey secret of the RAM user.
    faascmd auth --bucket=hereIsYourBucket # Replace <hereIsYourBucket> with the name of the OSS bucket that you created.                        
  5. Run the following command to compile the RTL project:
    cd <decompressed directory>/hw/ # Access your decompressed hw directory.
    sh compiling.sh               
    Note The compilation process takes about two to three hours.
  6. Upload the netlist files and download the FPGA image. You can use a scripted or step-by-step process to complete this step.
    • Scripted process: This process applies only to f3 instances with a single FPGA.
      1. Run the following command to upload the package and generate the image file:
        sh /root/xbinst_oem/tool/faas_upload_and_create_image.sh <package to be uploaded>
        upload_image_file
      2. Download the image file.
        sh /root/xbinst_oem/tool/faas_download_image.sh <package name> <0/1> # The last number <0/1> stands for the FPGA serial number in the instance.

        0 indicates the first FPGA of the f3 instance. For single-FPGA instances, the FPGA serial number is always 0. For instances with multiple FPGAs, such as an instance with four FPGAs, the serial numbers are 0, 1, 2 and 3.

        If you want to download the same image to multiple FPGAs, add the serial number to the end of each command line. For example, run the following commands to download the same image to four FPGAs:

        sh /root/xbinst_oem/tool/faas_download_image.sh <package name> 0
        sh /root/xbinst_oem/tool/faas_download_image.sh <package name> 1
        sh /root/xbinst_oem/tool/faas_download_image.sh <package name> 2
        sh /root/xbinst_oem/tool/faas_download_image.sh <package name> 3
    • Step-by-step process: Use the faascmd tool to perform operations. For more information, see Use faascmd.
      1. Run the following commands in sequence to upload the package to your OSS bucket, and then upload the GBS file from 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=<hereIsShellVersionOfFPGA>                      
        upload_objectcreate_image
      2. Run the following command to check whether the FPGA image can be downloaded:
        faascmd list_images
        The command output is as follows:
        • If "State":"compiling" is displayed, the FPGA image is being compiled.
        • If "State":"success" is displayed, the FPGA image is downloaded. You must find and record the value of FpgaImageUUID.
        list_images
      3. Run the following command. Find and record the value of FpgaUUID in the command output.
        faascmd list_instances --instanceId=<hereIsYourInstanceId> # Replace <hereIsYourInstanceId> with the ID of the f3 instance.
      4. Run the following command to download the FPGA image:
        #Replace <hereIsYourInstanceId> with the ID the f3 instance. 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=xilinx --imageuuid=<hereIsImageUUID> --imagetype=afu --shell=<hereIsShellVersionOfFpga>
        download_image
      5. Run the following command to check whether the image is downloaded:
        # Replace <hereIsFpgaUUID> with the value of FpgaUUID. Replace <hereIsYourInstanceId> with the ID of the f3 instance.
        faascmd fpga_status --fpgauuid=<hereIsFpgaUUID> --instanceId=<hereIsYourInstanceId> 

        The following figure shows the command output. If the value of FpgaImageUUID in the command output is the same as that of FpgaImageUUID that you recorded, and "TaskStatus":"valid" is displayed, the image is downloaded.

        fpga_status

FAQ

Questions 1: How do I view the details of errors that occur during the image upload?

If your project reports errors during the image upload, such as compilation errors, you can view the details of errors by using one of the following methods:
  • Check faas_compiling.log. When the upload script faas_upload_and_create_image.sh is used, faas_compiling.log is automatically downloaded and displayed onto the terminal if the compilation fails.
  • Run the sh /root/xbinst_oem/tool/faas_checklog.sh <bit.tar.gz - previously uploaded package name> command to view the log file.

Question 2: How do I reload the image?

You can perform the following operations to reload the image:

  1. Uninstall the driver.
    • If you installed the xdma driver, run the sudo rmmod xdma command in the instance to uninstall the driver.
    • If you installed the xocl driver, run the sudo rmmod xocl command in the instance to uninstall the driver.
  2. Download the image.
    You can use one of the following methods to download the image:
    • Use the script:
      sh faas_download_image.sh bit.tar.gz <0/1> #The last number stands for the FPGA serial number in the instance.
    • Use faascmd:
      faascmd download_image --instanceId=hereIsYourInstanceId --fpgauuid=hereIsFpgaUUID --fpgatype=xilinx --imageuuid=hereIsImageUUID --imagetype=afu --shell=hereIsShellVersionOfFpga
  3. Install the driver.
    • Run the following commands to install the xdma driver:
      sudo depmod
      sudo modprobe xdma
    • Run the following commands to install the xocl driver:
      sudo depmod 
      sudo modprobe xocl