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:
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.
- 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>


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

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

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