Use the RTL design on an f3 instance - Best Practices| Alibaba Cloud Documentation Center

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

Prerequisites

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 Elastic Compute Service (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 FaaS administrator account has read and write permissions on the bucket. We recommend that you only store information that is related to FaaS.
You must complete the following operations before you can manage FPGA-accelerated instances 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 user include AliyunECSReadOnlyAccess, AliyunOSSFullAccess, and AliyunRAMFullAccess.
- Go to the Cloud Resource Access Authorization page to authorize FaaS to access your resources.
- 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 Resource Access Management (RAM) user. We recommend that you grant only the RAM user 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, the role is used by FaaS to access resources that are hosted in other cloud services. The AliyunFAASRolePolicy policy of the role includes permissions on Key Management Service (KMS) for you to encrypt IP addresses.

Procedure

Connect to an f3 instance.

Note The compilation process can take two to three hours to complete. We recommend that you use nohup or Virtual Network Computing (VNC) to connect to the instance to avoid unexpected disconnections.
Download and decompress the RTL design.
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 this 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 this command each time you open a new terminal window.
```
Note The environment set-up process involves installing the xdma or xocl driver, setting the vivado environment variable, checking the vivado license, checking the aliyun-f3 sdaccel platform, configuring 2018.2 runtime, and checking the faascmd version.

Specify an OSS bucket.

faascmd config --id=<hereIsYourSecretId> --key=<hereIsYourSecretKey> #Replace <hereIsYourSecretId> with the AccessKey ID of the RAM user, and replace <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.

Run the following command to compile the RTL project:

cd <Directory where the decompressed RTL design resides>/hw/ # Access the hw directory in which the decompressed RTL design resides.
sh compiling.sh

Note The compilation process takes about two to three hours to complete.

Upload the netlist files and download the FPGA image.
You can use faascmd to upload the netlist files and download the FPGA image. For more information about how to use the faascmd command, 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>                      
```
2. Run the following command to check whether the FPGA image can be downloaded:
```
faascmd list_images
```
  The command output is returned:
  - If "State":"compiling" is displayed, the FPGA image is being compiled.
  - If "State":"success" is displayed, the FPGA image can be downloaded. You must find and record the FpgaImageUUID value.
3. Run the following command. Find and record the FpgaUUID value 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 FpgaUUID value that you recorded. Replace <hereIsImageUUID> with the FpgaImageUUID value that you recorded.
faascmd download_image --instanceId=<hereIsYourInstanceId> --fpgauuid=<hereIsFpgaUUID> --fpgatype=xilinx --imageuuid=<hereIsImageUUID> --imagetype=afu --shell=<hereIsShellVersionOfFpga>
```
5. Run the following command to check whether the image is downloaded:
```
# Replace <hereIsFpgaUUID> with the FpgaUUID value that you recorded. 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 FpgaImageUUID value in the command output is the same as the FpgaImageUUID value that you recorded, and if "TaskStatus":"valid" is displayed, the image is downloaded.

FAQ

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

If an exception occurs in your project when you upload an image, you can run the command to view the compilation log file. For example, if an error message is returned on the cloud compilation server, you can view the compilation log file: sh /root/xbinst_oem/tool/faas_checklog.sh <bit.tar.gz the file name of the compressed package that is uploaded>.

Question 2: How do I reload an image?

You can perform the following operations to reload an image.

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.

Download the image.

faascmd download_image --instanceId=hereIsYourInstanceId --fpgauuid=hereIsFpgaUUID --fpgatype=xilinx --imageuuid=hereIsImageUUID --imagetype=afu --shell=hereIsShellVersionOfFpga

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
```