How to 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.
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 RAM users.
  You must grant the AliyunOSSFullAccess permission to the RAM user.
- Obtain the AccessKey ID and AccessKey secret of the RAM user. For more information, see Obtain 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 on 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

When you set up the environment, take note of the following items:

The environment setup process involves the following operations: install the xocl driver, configure 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 only run a Vivado emulator, do not perform steps 2 to 4 when you set up the environment. To run a Vivado emulator, you need to only configure the Vivado environment variables.
We recommend that you use Makefile for emulation.

Connect to the f3 instance.
For more information, see Connect to a Linux instance by using a username and password.
Important
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:

# Run this command each time you open a new terminal window. 
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl

Download and install the y2k22_patch-1.2.zip patch.
Download URL: Xilinx. The y2k22_patch-1.2.zip patch is used to fix the timestamp overflow bug in Xilinx.

Step 2: Compile a binary file

The following examples show how to compile the vadd and kernel_global_bandwidth binary files.

Example 1: Compile the vadd binary file

Run the following command to copy the examples directory:
```
cp -rf /opt/Xilinx/SDx/2018.2/examples ./
```
Run the following command to go to the vadd directory:
```
cd examples/vadd/
```
Run the following command to check the value of XDEVICE:
```
cat sdaccel.mk | grep "XDEVICE="
```
Make sure that the value of XDEVICE is xilinx_aliyun-f3_dynamic_5_0.
Modify the common.mk file.
1. Run the following command to open the common.mk file:
```
vim ../common/common.mk
```
2. Add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp.
  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 instead of a .bit file after the placement and routing are complete. Then, you can submit the DCP file to the compilation server.
Run the following command to compile the binary file:
```
make -f sdaccel.mk xbin_hw
```
Important
The compilation process may take several hours. Wait until the compilation is complete.
If information similar to the following example is displayed, the vadd binary file is being compiled.

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 following command to go to the kernel_global_bandwidth directory:
```
cd getting_started/kernel_to_gmem/kernel_global_bandwidth
```
Modify the Makefile file.
1. Run the following command to open the Makefile file:
```
vim Makefile
```
2. Set DEVICES to xilinx_aliyun-f3_dynamic_5_0.
3. Add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp.
  At the end of 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 binary file:
Important
The compilation process may take several hours. Wait until the compilation is complete.
```
make TARGET=hw
```
If information similar to the following example is displayed, the kernel_global_bandwidth binary file is being compiled.

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 created.
faasutil auth --bucket=<hereIsYourBucket>

Run the following command to obtain the file with the file name extension .xclbin:
```
ls
```
The following information is returned.
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 an OSS bucket:

Run the following command to upload the package to your OSS bucket:

faasutil put_object --object=bit.tar.gz --file=bit.tar.gz  #--object(Object file in oss bucket) --file(Local file need to put)

The following information is returned.

f3_0opencl

Run the following command to upload the package from your OSS bucket to the OSS bucket in the FaaS administrative unit:

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.

The following information is returned.

f3_opencl-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 the image UUID to download the FPGA image by running the faasutil download_image command.
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> # Replace <fpga_bdf> with the value obtained in the previous step, and <image_uuid> with 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 basic environment:

# Run this command each time you open a new terminal window.
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl

Configure the sdaccel.ini file.
In the directory in which the host binary file resides, run the following command to create the sdaccel.ini file:
```
vim sdaccel.ini
```
After the sdaccel.ini file is created, 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.

Common commands

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 directly download the SDAccel runtime and SDAccel development platform.