F3实例OpenCL开发流程

注意事项

• 本文中所有操作都必须由同一个账号在同一地域里执行。
• 如果您为普通用户，建议管理员将镜像中/root/xbinst_oem目录拷贝至用户根目录下。
• 如果您为普通用户，请联系管理员给普通用户添加/dev/virtio-ports/FaaS.agent的使用权限。
• 建议您使用RAM用户操作FaaS实例。您需要为FaaS管理账号创建一个角色，并授予临时权限，让FaaS管理账号能访问指定的OSS Bucket。
• 本文以2018.2版本的SDAccel开发环境为例，若您使用其他版本的SDAccel开发环境，步骤和命令可能会稍有差异。

步骤一：配置环境

1. 远程连接F3实例。
   说明 后面步骤中的编译工程可能会持续数小时，建议您使用screen或者nohup等方式登录，防止ssh超时退出。
2. 运行以下命令安装screen。

   yum install screen -y

3. 运行以下命令进入screen。

   screen -S f3opencl

4. 运行以下命令配置环境。

   sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl  #每打开一个终端窗口就需要执行该命令一次

   配置环境时，请注意以下说明：

   • 配置环境主要包括安装xocl驱动、设置vivado环境变量、检查vivado license、检测aliyun-f3 sdaccel平台、授予2018.2 runtime配置。
   • 如果您要运行vivado的仿真，请勿运行以上命令配置环境，您只需要单独设置vivado环境变量即可。
   • 推荐您使用Makefile方式仿真。
5. 前往Xilinx，下载并安装补丁y2k22_patch-1.2.zip。
   说明 该补丁用于修复Xilinx年限溢出缺陷。

步骤二：编译二进制文件

编译vadd二进制文件和kernel_global_bandwidth二进制文件的操作如下所示：

示例一：编译vadd二进制文件

1. 复制examples目录。

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

2. 进入vadd目录。

   cd examples/vadd/

3. 运行命令cat sdaccel.mk | grep "XDEVICE="查看XDEVICE的值，确保其配置为XDEVICE=xilinx_aliyun-f3_dynamic_5_0。
4. 按以下步骤修改common.mk文件。
   1. 运行vim ../common/common.mk命令打开该文件。
   2. 在第61行代码（参数可能在60~62行，视您的文件而定）的末尾添加编译参数--xp param:compiler.acceleratorBinaryContent=dcp，修改后的代码如下所示。

      CLCC_OPT += $(CLCC_OPT_LEVEL) ${DEVICE_REPO_OPT} --platform ${XDEVICE} ${KERNEL_DEFS} ${KERNEL_INCS} --xp param:compiler.acceleratorBinaryContent=dcp

      说明 由于您必须向编译服务器提交DCP文件，所以需要添加--xp param:compiler.acceleratorBinaryContent=dcp编译参数，使得Xilinx® OpenCL™ Compiler（xocc）编译生成一个布局布线后的DCP文件，而不是bit文件。
5. 运行以下命令编译程序。

   make -f sdaccel.mk xbin_hw

   如果您看到如下界面，说明二进制文件编译已经开始。编译过程可能会持续数个小时，请您耐心等待。

示例二：编译kernel_global_bandwidth二进制文件

1. 依次运行以下命令克隆xilinx 2018.2 examples。

   git clone https://github.com/Xilinx/SDAccel_Examples.git

   cd SDAccel_Examples/

   git checkout 2018.2

   说明 git分支必须为2018.2版本。
2. 运行cd getting_started/kernel_to_gmem/kernel_global_bandwidth/命令进入目录。
3. 按以下步骤修改Makefile文件。
   1. 运行vim Makefile命令打开该文件。
   2. 设置DEVICES=xilinx_aliyun-f3_dynamic_5_0。
   3. 在第33行代码中添加编译参数--xp param:compiler.acceleratorBinaryContent=dcp，修改后的代码如下所示。

      CLFLAGS +=--xp "param:compiler.acceleratorBinaryContent=dcp" --xp "param:compiler.preserveHlsOutput=1" --xp "param:compiler.generateExtraRunData=true" --max_memory_ports bandwidth -DNDDR_BANKS=$(ddr_banks)

4. 运行以下命令编译程序。

   make TARGET=hw

   如果您看到该界面，说明二进制文件编译已经开始。编译过程可能会持续数小时，请您耐心等待。

步骤三：检查打包脚本

file /home/user1/xbinst_oem/sdaccel_package.sh

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

步骤四：制作镜像

1. 初始化faasutil工具并配置OSS环境。
   1. 运行以下命令，设置RAM账号的AccessKey信息。

      #将<HereIsYourSecretId>和<HereIsYourSecretKey>替换为您的RAM用户AK信息
      faasutil config --id=<HereIsYourSecretId> --key=<HereIsYourSecretKey>

   2. 运行以下命令，设置FaaS服务要使用的OSS Bucket。

      #将<hereIsYourBucket>替换为您创建的OSS Bucket名称
      faasutil auth --bucket=<hereIsYourBucket>

2. 运行ls，获取后缀为.xclbin的文件名。
   
3. 运行以下命令，打包好二进制文件。

   /home/user1/xbinst_oem/sdaccel_package.sh -xclbin=/opt/Xilinx/SDx/2018.2/examples/vadd/bin_vadd_hw.xclbin

   打包完成后，您会在同一目录下看到一个打包好的文件，如下图所示。

步骤五：下载镜像

本步骤介绍如何使用faasutil工具上传网表文件并下载FPGA镜像。关于faasutil命令的用法，请参见使用faasutil。

1. 依次运行以下命令，将压缩包上传到您个人的OSS Bucket，再将存放在您个人OSS Bucket中的压缩包上传到FaaS管理单元的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)
   faasutil create_image --object=bit.tar.gz --fpgatype=xilinx --name=<HereIsFPGAImageName> --tags=<HereIsFPGAImageTag> --encrypted=false --shell=<hereIsShellVersionOfFPGA>       #<HereIsFPGAImageTag>可选（镜像Tag）  encrypted可选，镜像加密   <HereIsShellVersionOfFPGA>默认版本

   
2. 运行以下命令，查看FPGA镜像是否处于可下载状态。

   faasutil list_images

   在返回结果中：

   • 如果FPGA镜像的"State"为"compiling"，表示FPGA镜像处于编译状态，您需要继续等待。
   • 如果FPGA镜像的"State"为"success"，表示FPGA镜像已经可以下载，您需要找到并记录FpgaImageUniqueId，用于后续下载镜像（download_image）时使用。
3. 运行以下命令，在命令返回结果中，找到并记录fpga bdf。

   faasutil list_instances

   
4. 运行以下命令，下载FPGA镜像。

   faasutil download_image --bdf=<fpga_bdf> --fpgaImageUniqueId=<image_uuid>  #<fpga_bdf>由上一步所得  <image_uuid>镜像uuid

   
5. 运行以下命令，查看镜像是否下载成功。

   faasutil fpga_status --bdf=<fpga_bdf>

   以下为返回结果示例。如果显示的imageuuid与您获取的FpgaImageUniqueId一致，并且fpgaStatus参数显示valid，说明镜像下载成功。

步骤六：运行Host程序

1. 运行以下命令配置环境。

   sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl  #每打开一个终端窗口就需要执行该命令一次

2. 配置sdaccel.ini文件。
   在host二进制文件所在目录下，运行vim sdaccel.ini命令，创建sdaccel.ini文件并输入下列内容。

   [Debug]
   profile=true
   [Runtime]
   runtime_log = "run.log"
   hal_log = hal.log
   ert=false
   kds=false

3. 运行host。
   • vadd运行命令如下：

     make -f sdaccel.mk host

     sudo ./vadd bin_vadd_hw.xclbin

   • kernel_global_bandwidth运行命令如下：

     sudo ./kernel_global

   如果返回结果中出现Test Passed，说明测试通过。

常用操作

这里介绍FPGA实例的部分常用操作。