f3实例OpenCL开发最佳实践

操作步骤

步骤一：配置环境

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

   yum install screen -y                        

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

   screen -S f3opencl                        

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

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

   说明

   • 配置环境主要包括安装xocl驱动，设置vivado环境变量， 检查vivado license， 检测aliyun-f3 sdaccel平台，2018.2 runtime配置和faascmd版本检测。
   • 如果您要运行sdaccel的仿真，请勿运行以上命令配置环境。您只需要单独配置vivado的环境变量即可。
   • 推荐您使用Makefile方式仿真。

步骤二：编译二进制文件

完成以下步骤，编译vadd二进制文件和kernel_global_bandwidth二进制文件：

• 示例一 ：编译vadd二进制文件
  1. 复制example目录。

     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 example。

     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 /root/xbinst_oem/sdaccel_package.sh

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

步骤四：制作镜像

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

      #将<hereIsYourSecretId>和<hereIsYourSecretKey>替换为您的RAM用户AK信息
      faascmd config --id=<hereIsYourSecretId> --key=<hereIsYourSecretKey>  

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

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

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

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

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

步骤五：下载镜像

您可以采用脚本化流程或者单步操作流程来上传网表文件，并下载FPGA镜像。

• 脚本化流程：仅适用于配备单块FPGA卡的f3实例。
  1. 运行以下命令上传并生成镜像文件。

     sh /root/xbinst_oem/tool/faas_upload_and_create_image.sh <bit.tar.gz需要上传的压缩包文件名>

     
  2. 运行以下命令下载镜像文件。

     sh /root/xbinst_oem/tool/faas_download_image.sh <bit.tar.gz压缩包的文件名> <0/1>  #最后的数字<0/1>为实例中fpga的序号

     说明 0为FaaS实例中的第一个FPGA。单芯片实例序号一律为0；多芯片实例，例如，4芯片实例的序号为0，1，2，3。
     如果需要对多个FPGA下载同一个镜像，可以在命令的末尾添加相应的序号。例如，对4芯片FPGA下载同一镜像的命令如下：

     sh /root/xbinst_oem/tool/faas_download_image.sh <bit.tar.gz压缩包的文件名> 0

     sh /root/xbinst_oem/tool/faas_download_image.sh <bit.tar.gz压缩包的文件名> 1

     sh /root/xbinst_oem/tool/faas_download_image.sh <bit.tar.gz压缩包的文件名> 2

     sh /root/xbinst_oem/tool/faas_download_image.sh <bit.tar.gz压缩包的文件名> 3

• 单步操作流程：使用faascmd工具操作。工具详情，请参见使用faascmd工具。
  1. 依次运行以下命令，将压缩包上传到您个人的OSS Bucket，再将存放在您个人OSS Bucket中的gbs上传到FaaS管理单元的OSS Bucket中。

     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>

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

     faascmd list_images

     返回结果中：

     • 如果FPGA镜像的"State"为"compiling"，表示FPGA镜像处于编译状态，您需要继续等待。
     • 如果FPGA镜像的"State"为"success"，表示FPGA镜像已可以下载，您需要找到并记录FpgaImageUUID。
  3. 运行以下命令在返回结果中，找到并记录FpgaUUID。

     faascmd list_instances --instanceId=<hereIsYourInstanceId> #将<hereIsYourInstanceId>替换为f3实例ID

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

     #将<hereIsYourInstanceId>替换为f3的实例ID，<hereIsFpgaUUID>替换为您获取的FpgaUUID，<hereIsImageUUID>替换为您获取的FpgaImageUUID
     faascmd download_image --instanceId=<hereIsYourInstanceId> --fpgauuid=<hereIsFpgaUUID> --fpgatype=xilinx --imageuuid=<hereIsImageUUID> --imagetype=afu --shell=<hereIsShellVersionOfFpga>

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

     faascmd fpga_status --fpgauuid=<hereIsFpgaUUID> --instanceId=<hereIsYourInstanceId> #将<hereIsFpgaUUID>替换为您获取的FpgaUUID，<hereIsYourInstanceId>替换为f3实例ID。

     以下为返回结果示例。如果显示的FpgaImageUUID与您获取的FpgaImageUUID一致，并且显示"TaskStatus":"valid"，说明镜像下载成功。

步骤六：运行Host程序

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

   source /root/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

     ./vadd bin_vadd_hw.xclbin

   • kernel_global_bandwidth运行命令如下：

     ./kernel_global

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

其他操作

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