This topic describes how to use Open Computing Language (OpenCL) on an f3 instance to create an image and download the image to a field programmable gate array (FPGA).
Prerequisites
- An f3 instance is created and assigned a public IP address.
For more information, see Create an f3 instance.
Note Only images shared by Alibaba Cloud can be used on f3 instances. - 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 reside in the same region. For more information, 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 a 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.
- Create a RAM user and grant permissions to the RAM user. For more information, see
Create a RAM user and Grant permissions to a RAM user.
Background information
- All operations described in this topic can be performed only by one account in the same region.
- We recommend that you manage the f3 instance as a Resource Access Management (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 vary.
Procedure
Step 1. Set up the environment
Step 2. Compile a binary file
Perform the following operations to compile the vadd and kernel_global_bandwidth binary files:
- Example 1: vadd
- Copy the example 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 vim ../common/common.mk command to open the file.
- At the end of code line 61, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The parameter can be added in code line 60, 61, or 62. The following section shows
the modified code:
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 DCP file after the placement and routing are completed. 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 displayed is similar to the following example, the binary file is being compiled. The compilation process can take several hours.
- Copy the example directory.
- Example 2: kernel_global_bandwidth
- Run the following commands in sequence to clone
xilinx 2018.2 example
: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 access the directory.
- Perform the following operations to modify the Makefile file:
- Run the vim Makefile command to open the file.
- Set
DEVICES
to xilinx_aliyun-f3_dynamic_5_0. - In code line 33, add the compilation parameter --xp param:compiler.acceleratorBinaryContent=dcp. The following section shows the modified code:
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 displayed is similar to the following example, the binary file is being compiled. The compilation process can take several hours.
- Run the following commands in sequence to clone
Step 3. Check the packaging script
file /root/xbinst_oem/sdaccel_package.sh
wget http://fpga-tools.oss-cn-shanghai.aliyuncs.com/sdaccel_package.sh
Step 4. Create an image
Step 5. Download the image
- 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 is downloadable:
faascmd list_images
The following section shows the command output:- If "State":"compiling" is displayed, the FPGA image is being compiled.
- If "State":"success" is displayed, the FPGA image is downloaded. You must find and record the value of
FpgaImageUUID.
- Run the following command. Find and record the value of FpgaUUID 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 value of FpgaUUID that you recorded. Replace <hereIsImageUUID> with the value of FpgaImageUUID 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:
faascmd fpga_status --fpgauuid=<hereIsFpgaUUID> --instanceId=<hereIsYourInstanceId> #Replace <hereIsFpgaUUID> with the value of FpgaUUID that you recorded earlier. Replace <hereIsYourInstanceId> with the ID of the f3 instance.
The following figure shows the command output. If the value of FpgaImageUUID in the command output is the same as the FpgaImageUUID value that you recorded and "TaskStatus":"valid" is displayed, the image is downloaded.
Step 6. Run the host program
Other common commands
The following table describes some common commands for f3 instances.
Operation | 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 work directory | make -f sdaccel.mk clean |
Forcibly clean a work directory | make -f sdaccel.mk cleanall |
- 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.