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

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

Prerequisites

An f3 instance is created. For more information, see Create an f3 instance.
Note Use the community image of Alibaba Cloud whose ID is m-uf62gw9ckos5os056xum to create the 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 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 Resource Access Management (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.
  You must grant the RAM user the AliyunOSSFullAccess permission.
- Obtain the AccessKey ID and AccessKey secret of the RAM user. For more information, see Obtain an AccessKey pair.

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, we recommend that you contact an administrator and apply for the permissions to use the /dev/virtio-ports/FaaS.agent directory.
We recommend that you manage an FPGA-accelerated instance as a RAM user. You must create a role for the RAM user and grant the role temporary permissions to access the specified OSS bucket.
The operations and commands described in this topic are based on version 2018.2 of the SDAccel development environment. If you use the SDAccel development environment of other versions, the operations and commands may vary.

Step 1: Set up the environment

Connect to the f3 instance. For more information, see Connect to a Linux instance by using a password.
Note The compilation process may take several hours. To prevent an unexpected disconnection due to an SSH timeout, we recommend that you use Screen or nohup to connect to the instance.
Run the following command to install Screen:
```
yum install screen -y
```
Run the following command to start Screen:
```
screen -S f3opencl
```
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.
```
When you set up the environment, take note of the following items:
- The environment setup process involves the following operations: install the xocl driver, set the Vivado environment variables, check the Vivado license, check the Alibaba Cloud f3 SDAccel platform, and configure the 2018.2 runtime.
- If you want to run a Vivado emulator, do not run the preceding command to set up the environment. Instead, you need to only set the Vivado environment variables.
- We recommend that you use Makefile for emulation.
Go to the Xilinx website, and download and install the y2k22_patch-1.2.zip patch.
Note This patch is used to fix the timestamp overflow bug in Xilinx.

Step 2: Compile a binary file

Perform the following operations to compile the vadd or kernel_global_bandwidth binary file:

Example 1: Compile the vadd binary file

Copy the examples directory.

cp -rf /opt/Xilinx/SDx/2018.2/examples ./

Go to the vadd directory.
```
cd examples/vadd/
```
Run the cat sdaccel.mk | grep "XDEVICE=" command to check the value of XDEVICE. Make sure that the value is xilinx_aliyun-f3_dynamic_5_0.
Perform the following operations to modify the common.mk file:
1. Run the vim ../common/common.mk command to open the common.mk file.
2. At the end of code line 60, 61, or 62, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The code line in which you need to add the compilation parameter varies based on the content of your common.mk file. The following sample code provides an example:
```
CLCC_OPT += $(CLCC_OPT_LEVEL) ${DEVICE_REPO_OPT} --platform ${XDEVICE} ${KERNEL_DEFS} ${KERNEL_INCS} --xp param:compiler.acceleratorBinaryContent=dcp
```
  Note You must add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp so that Xilinx OpenCL Compiler (xocc) can generate a design checkpoint (DCP) file after the placement and routing are complete. The file cannot be a .bit file. Then, you can submit the DCP file to the compilation server.
Run the following command to compile the program:
```
make -f sdaccel.mk xbin_hw
```
If the information similar to the following example is displayed, the binary file is being compiled. The compilation process may take several hours.

Example 2: Compile the kernel_global_bandwidth binary file

Run the following commands in sequence to clone xilinx 2018.2 examples:
```
git clone https://github.com/Xilinx/SDAccel_Examples.git
```
```
cd SDAccel_Examples/
```
```
git checkout 2018.2
```
Note The Git branch version must be 2018.2.
Run the cd getting_started/kernel_to_gmem/kernel_global_bandwidth/ command to go to the kernel_global_bandwidth directory.
Perform the following operations to modify the Makefile file:
1. Run the vim Makefile command to open the file.
2. Set DEVICES to xilinx_aliyun-f3_dynamic_5_0.
3. In code line 33, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The following sample code provides an example:
```
CLFLAGS +=--xp "param:compiler.acceleratorBinaryContent=dcp" --xp "param:compiler.preserveHlsOutput=1" --xp "param:compiler.generateExtraRunData=true" --max_memory_ports bandwidth -DNDDR_BANKS=$(ddr_banks)
```
Run the following command to compile the program:
```
make TARGET=hw
```
If the information similar to the following example is displayed, the binary file is being compiled. The compilation process may take several hours.

Step 3: Check the packaging script

Run the following command to check whether the packaging script exists:

file /home/user1/xbinst_oem/sdaccel_package.sh

If cannot open (No such file or directory) is displayed in the command output, the script does not exist. You must run the following command to manually download the packaging script:

wget http://fpga-tools.oss-cn-shanghai.aliyuncs.com/sdaccel_package.sh

Step 4: Create an image

Initialize the faasutil tool and set up the OSS environment.

Run the following command to configure the AccessKey pair of the RAM user:

# Replace <HereIsYourSecretId> with the AccessKey ID of the RAM user, and <HereIsYourSecretKey> with the AccessKey secret of the RAM user.
faasutil config --id=<HereIsYourSecretId> --key=<HereIsYourSecretKey>

Run the following command to configure the OSS bucket dedicated to FaaS:

# Replace <hereIsYourBucket> with the name of the OSS bucket that you create.
faasutil auth --bucket=<hereIsYourBucket>

Run the ls command to obtain the file with the suffix .xclbin.
Run the following command to package the binary file:
```
/home/user1/xbinst_oem/sdaccel_package.sh -xclbin=/opt/Xilinx/SDx/2018.2/examples/vadd/bin_vadd_hw.xclbin
```
After the binary file is packaged, you can find the packaged file in the same directory. The following figure shows an example.

Step 5: Download the image

This step describes how to use the faasutil tool to upload netlist files and download an FPGA image. For more information about how to use faasutil, see Use faasutil.

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.

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.
Run the following command. Find and record the value of fpga_bdf in the command output.
```
faasutil list_instances
```

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 3 of Step 5. The value of <image_uuid> indicates the UUID of the image.

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.

Step 6: Run the host program

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.

Configure the sdaccel.ini file.
In the directory where the host binary file is located, run the vim sdaccel.ini command to create the sdaccel.ini file. Add the following content to the file:
```
[Debug]
profile=true
[Runtime]
runtime_log = "run.log"
hal_log = hal.log
ert=false
kds=false
```
Run the host program.
- For vadd, run the following commands:
```
make -f sdaccel.mk host
```
```
sudo ./vadd bin_vadd_hw.xclbin
```
- For kernel_global_bandwidth, run the following command:
```
sudo ./kernel_global
```
If Test Passed is displayed in the command output, the test is passed.

What to do next

The following table describes some common commands that you can run to perform operations on FPGA-accelerated instances.


Task	Command
View the help documentation	`make -f ./sdaccel.mk help`
Run software emulation	`make -f ./sdaccel.mk run_cpu_em`
Run hardware emulation	`make -f ./sdaccel.mk run_hw_em`
Compile only the host code	`make -f ./sdaccel.mk host`
Compile and generate downloadable files	`make -f sdaccel.mk xbin_hw`
Clean a working directory	`make -f sdaccel.mk clean`
Forcibly clean a working directory	`make -f sdaccel.mk cleanall`

Note

During emulation, follow the Xilinx emulation process. You do not need to configure the F3_env_setup environment.
The SDAccel runtime and SDAccel development platform are available in the official f3 images that are provided by Alibaba Cloud. You can also click SDAccel runtime and SDAccel development platform to download the images.