Perform RTL development on an f3 Instance - FPGA as a Service

This topic describes how to perform Register Transfer Level (RTL) development on an f3 instance.

Prerequisites

An f3 instance is created.
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 a security group rule.
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. For more information, see Create buckets.
The faasutil CLI tool is obtained. For more information, see Obtain faasutil.
The following operations are performed before you 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.
  You must grant the RAM user the AliyunOSSFullAccess permission.
- Obtain the AccessKey ID and AccessKey secret of the RAM user. For more information, see Create an AccessKey pair.
  Warning
  You can only access field programmable gate array (FPGA) as a Service (FaaS) by using the AccessKey pair as a RAM user. This minimizes the risk that the AccessKey pair is leaked. We recommend that you do not save your AccessKey pair in plaintext in the code of your project and keep your AccessKey pair confidential. Otherwise, the AccessKey pair may be leaked and the security of resources that belong to your account may be compromised.

Usage notes

All operations described in this topic must be performed by the same account in the same region.
If you perform the operations as a regular user, we recommend that you contact an administrator to copy the /root/xbinst_oem directory in the image to the root directory of the regular user.
If you perform the operations as a regular user, contact an administrator and apply for the permissions to use the /dev/virtio-ports/FaaS.agent directory.
You can manage FPGA-accelerated instances only as a RAM user. To secure your data, we recommend that you adhere to the principle of the least privilege when you authorize the RAM user to manage specified ECS instances.

Procedure

Connect to a Linux instance. For more information, see Connect to a Linux instance by using a username and password.
Important
The compilation process may take 2 to 3 hours to complete. To prevent unexpected disconnections, we recommend that you use nohup or Virtual Network Computing (VNC) to connect to the instance.
Download and decompress the RTL design package.
Set up the environment.
- If the driver is xdma, run the following command to set up the environment:
```
sudo source /home/user1/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:
```
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl #Run this command each time you open a new terminal window.
```
Note
The environment setup process involves the following operations: install the xdma or xocl driver, set the Vivado environment variables, check the Vivado license, check the Alibaba Cloud f3 SDAccel platform, and configure the 2018.2 runtime.

Specify an OSS bucket.

faasutil config --id=<HereIsYourSecretId> --key=<HereIsYourSecretKey> # Replace <HereIsYourSecretId> with the AccessKey ID of the RAM user, and <HereIsYourSecretKey> with the AccessKey secret of the RAM user.
faasutil auth --bucket=<HereIsYourBucket> # Replace <HereIsYourBucket> with the name of the OSS bucket that you created.

Run the following commands to compile the RTL project:
```
cd <Directory where the decompressed RTL design resides>/hw/ # Go to the hw directory in which the decompressed RTL design resides.
sh compiling.sh
```
Note
The compilation process may take 2 to 3 hours to complete.
After the compilation is complete, a success message similar to the following one is displayed.
Upload netlist files and download the FPGA image.
You can use faasutil to upload the netlist files and download the FPGA image. For more information about how to use faasutil, see Use faasutil.
1. Run the following commands in sequence to upload the package to your OSS bucket, and then upload the package from your OSS bucket to the OSS bucket in the FaaS administrative unit:
```
faasutil put_object --object=bit.tar.gz --file=bit.tar.gz  #--object(Object file in oss bucket) --file(Local file need to put)
faasutil create_image --object=bit.tar.gz --fpgatype=xilinx --name=<HereIsFPGAImageName> --tags=<HereIsFPGAImageTag> --encrypted=false --shell=<hereIsShellVersionOfFPGA>       #<HereIsFPGAImageTag>: optional. The tag of the image. encrypted: optional. Specifies whether to encrypt the image. <HereIsShellVersionOfFPGA>: the default version.
```
2. Run the following command to check whether the FPGA image is downloadable:
```
faasutil list_images
```
  In the command output:
  - If the value of "State" is "compiling", the FPGA image is being compiled.
  - If the value of "State" is "success", the FPGA image can be downloaded. Find and record the value of FpgaImageUniqueId. Then, you can use this value to download the FPGA image by running the faasutil download_image command later.
3. Run the following command. Find and record the value of fpga_bdf in the command output.
```
faasutil list_instances
```
4. Run the following command to download the FPGA image:
```
faasutil download_image --bdf=<fpga_bdf> --fpgaImageUniqueId=<image_uuid> # The value of <fpga_bdf> is obtained in Substep c of Step 6. The value of <image_uuid> indicates the UUID of the image. 
```
5. Run the following command to check whether the image is downloaded:
```
faasutil fpga_status --bdf=<fpga_bdf>
```
  A command output similar to the following one is displayed. If the value of imageuuid in the command output is the same as the value of FpgaImageUniqueId that you obtained and the value of fpgaStatus is valid, the image is downloaded.

FAQ

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, for example, if an error is returned on the cloud compilation server, you can use faasutil to view the compilation log file.

How do I reload an image?

Uninstall the driver.
- If you have installed the xdma driver, run the sudo rmmod xdma command on the instance to uninstall the driver.
- If you have installed the xocl driver, run the sudo rmmod xocl command on the instance to uninstall the driver.

Download the image.

faasutil download_image --bdf=<fpga_bdf> --fpgaImageUniqueId=<image_uuid> # The value of <fpga_bdf> is obtained in Substep c of Step 6. The value of <image_uuid> indicates the UUID of the image.

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