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.
- 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.
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:
- 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:
- 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 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. - For vadd, run the following commands:
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.