Use Vitis 2020.1 on an f3 instance - FPGA as a Service - Alibaba Cloud Documentation Center

This topic describes how to use Vitis 2020.1 on an f3 instance to create an image and load the image to a field programmable gate array (FPGA).

Prerequisites

An f3 instance that meets the following requirements is created. For more information, see Create an F3 instance.
- The instance is created by using the image FaaS_F30010_VITIS_2020_1. You can submit a ticket to obtain the image.https://workorder-intl.console.aliyun.com/console.htm
- The size of the system disk is equal to or greater than 120 GiB.
- A public IP address is assigned to the f3 instance.
- A rule is added to the security group to which the f3 instance belongs to allow access over SSH port 22.
The ID of the f3 instance is obtained from 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.
The bucket and the f3 instance belong to the same account and are deployed in the same region. For information about how to create a bucket, see Create buckets.
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 the 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.

Step 1: Connect to the f3 instance

A desktop environment and a Virtual Network Console (VNC) server have been configured for the FaaS_F30010_VITIS_2020_1 image. We recommend that you connect to the f3 instance by using the VNC server. For more information, see Connect to a Linux instance by using a password.

Step 2: Initialize the software environment

Each time you create an f3 instance, you must perform the following operations to initialize the software environment.

Run the following command to specify an environment resolution by using the VNC server:
```
vncserver -geometry 2560x1440
```
The following information is returned.
Run the following command to initialize the software environment that is pre-installed in the FaaS platform and is required when you use Vitis in the FaaS_F30010_VITIS_2020_1 image:
```
source /root/faasTools/vitis_setup.sh 
```
If the following information is returned, the software environment is initialized.

Step 3: Create a project

After the environment is ready, you can start Vitis by running the vitis command, and create a project on the GUI of Vitis.

Run the vitis command to start Vitis.

If the following information is returned, Vitis is started.
After the project is started, perform the following steps to create a project on the GUI of Vitis.
1. In the VITIS window, click Create Application Project below PROJECT.
2. In the New Application Project dialog box, choose SW acceleration templates > Vector Addition in the left-side section, and then click Finish in the lower-right corner.

Step 4: Use Vitis for emulation

Vitis supports two emulation modes: Emulation-SW and Emulation-HW.

On the Assistant tab in the GUI of Vitis, choose vadd_system > vadd > Emulation-SW [Software Emulation].
Right-click Emulation-SW [Software Emulation], and select Build from the shortcut menu.
Right-click Emulation-SW [Software Emulation], and choose Run > Default to emulate the model of the project that you created.
The following result is returned.

Step 5: Create an image

By default, the image files that are generated by Vitis include files with the .bit extension. FaaS requires that the files with the .dcp extension be uploaded. Therefore, you must configure the relevant settings before you create an FPGA image.

In the upper-right corner of the Assistant tab, click the icon.
In the Project Settings dialog box, choose vadd_system > vadd.
In the vadd section on the right side, specify the following content for the V++ linker options configuration item. Click Apply, and then click Apply and Close.
```
--advanced.param compiler.acceleratorBinaryContent=dcp
```
Return to the Assistant tab, and choose vadd_system > vadd > Hardware [Hardware].

Right-click Hardware [Hardware], and select Build from the shortcut menu to create the image.

It may take several hours to create the image. After the image is created, you can go to the Hardware directory in the project directory and run the ls command to view the generated binary file vadd that can be executed by the host and the image file binary_container_1.xclbin. The following sample code shows the command output:

[root@iz2zec7rvsxxxxxxx Hardware]# ls
a.xclbin                                  guidance.html
binary_container_1.build                  guidance.pb
binary_container_1-krnl_vadd-compile.cfg  makefile
binary_container_1-link.cfg               package.build
binary_container_1.ltx                    package.cfg
binary_container_1.mdb                    src
binary_container_1.xclbin                 vadd
binary_container_1.xclbin.info            vadd_Hardware.build.ui.log
binary_container_1.xclbin.link_summary    v++_package.log
binary_container_1.xclbin.sh              v++.package_summary
common-config.cfg                         xcd.log

Run the following command to generate a compressed file for uploading the image:

[root@iz2zec7rvsxxxxxxx Hardware]# vitis_xclbin_split.sh binary_container_1.xclbin

The following command output is displayed:

XRT Build Version: 2.6.0 (2020.1)
       Build Date: 2021-03-08 10:50:41
          Hash ID: 80107ebc7376dafc8e1c9f5043c81c6f1dcc9dbb
------------------------------------------------------------------------------
Warning: The option '--output' has not been specified. All operations will
         be done in memory with the exception of the '--dump-section' command.
------------------------------------------------------------------------------
Reading xclbin file into memory.  File: binary_container_1.xclbin

Section: 'BITSTREAM'(0) was successfully written.
Format: RAW
File  : 'faas20210311-092706.dcp'
Leaving xclbinutil.
XRT Build Version: 2.6.0 (2020.1)
       Build Date: 2021-03-08 10:50:41
          Hash ID: 80107ebc7376dafc8e1c9f5043c81c6f1dcc9dbb
------------------------------------------------------------------------------
Warning: The option '--output' has not been specified. All operations will
         be done in memory with the exception of the '--dump-section' command.
------------------------------------------------------------------------------
Reading xclbin file into memory.  File: binary_container_1.xclbin

Section: 'EMBEDDED_METADATA'(2) was successfully written.
Format: RAW
File  : 'faas20210311-092706.xml'
Leaving xclbinutil.
to_aliyun/
to_aliyun/faas20210311-092706.xml
to_aliyun/faas20210311-092706.dcp
Generate Image :Image20210311-092706.tar.gz

The preceding command output shows that the Image20210311-092706.tar.gz file is generated. You can upload the file as an image. For more information, see Use faasutil.

Note The faasutil tool is pre-installed in the FaaS_F30010_VITIS_2020_1 image. You can use the faasutil tool after you run the source /root/faasTools/vitis_setup.sh command.

Step 6: Verify the result

After you use the faasutil tool that is pre-installed in the FaaS_F30010_VITIS_2020_1 image to create an image and load the image to the FPGA, you can verify whether the image is loaded to the FPGA by using the CLI or the GUI.

Use the GUI for verification:
1. On the Assistant tab in the GUI of Vitis, choose vadd_system > vadd > Hardware [Hardware].
2. Right-click Hardware [Hardware], and choose Run > Default.
  The following result is returned. The result shows that the image is loaded to the FPGA.
Use the CLI for verification:
In the Hardware directory of the project directory, run the following command to verify whether the image is loaded to the FPGA:
```
[root@iz2zec7rvsxxxxxxx Hardware]# ./vadd binary_container_1.xclbin
```
The following result is returned. The result shows that the image is loaded to the FPGA.
```
Loading: 'binary_container_1.xclbin'
TEST PASSED
```