f3執行個體上OpenCL的開發流程 - FPGA as a Service

本文介紹如何在F3執行個體上使用OpenCL（Open Computing Language）製作鏡像檔案，並燒錄到FPGA晶片中。

前提條件

已建立F3執行個體。
已在F3執行個體所在的安全性群組中添加安全性群組規則，並允許存取SSH（22）連接埠。具體操作，請參見添加安全性群組規則。
已登入ECS管理主控台，並在F3執行個體的詳情頁上擷取執行個體ID。
已建立一個OSS Bucket專門用於FaaS服務。若尚未建立OSS Bucket，具體操作，請參見建立一個OSS Bucket。
已擷取命令列工具faasutil。若尚未擷取faasutil工具，具體操作，請參見擷取faasutil。
使用RAM使用者操作FPGA時，必須先完成以下操作：
- 建立RAM使用者並為RAM使用者授權。具體操作，請參見建立RAM使用者和為RAM使用者授權。
  您需要為RAM使用者授予AliyunOSSFullAccess許可權。
- 擷取AccessKey ID和AccessKey Secret。具體操作，請參見建立AccessKey。
  警告
  僅支援通過RAM使用者的AccessKey使用FaaS服務，可有效降低AccessKey泄露的風險。強烈建議您不要將AccessKey ID和AccessKey Secret明文儲存至工程代碼裡或者任何容易被他人明文擷取到的地方，否則可能導致AccessKey泄露，威脅您帳號下所有資源的安全。

注意事項

本文中所有操作都必須由同一個帳號在同一地區裡執行。
如果您為普通使用者，建議管理員將鏡像中/root/xbinst_oem目錄拷貝至使用者根目錄下。
如果您為普通使用者，請聯絡管理員給普通使用者添加/dev/virtio-ports/FaaS.agent的使用許可權。
建議您使用RAM使用者操作FaaS執行個體。您需要為FaaS管理帳號建立一個角色，並授予臨時許可權，讓FaaS管理帳號能訪問指定的OSS Bucket。
本文以2018.2版本的SDAccel開發環境為例，若您使用其他版本的SDAccel開發環境，步驟和命令可能會稍有差異。

步驟一：配置環境

配置環境時，請注意以下事項：

配置環境主要包括安裝xocl驅動、設定vivado環境變數、檢查vivado license、檢測aliyun-f3 sdaccel平台、授予2018.2 runtime配置。
如果您要運行vivado的模擬，請勿運行步驟2~步驟4的命令來配置環境，您只需要單獨設定vivado環境變數即可。
推薦您使用Makefile方式模擬。

遠程登入F3執行個體。
具體操作，請參見遠端連線F3執行個體。
重要
後面步驟中的編譯工程可能會持續數小時，建議您使用screen或者nohup等方式登入，防止ssh逾時退出。
運行以下命令，安裝screen。
```
yum install screen -y
```
運行以下命令，進入screen。
```
screen -S f3opencl
```

運行以下命令，配置環境。

# 每開啟一個終端視窗就需要執行該命令一次。
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl

下載並安裝補丁y2k22_patch-1.2.zip。
下載地址：Xilinx。其中，y2k22_patch-1.2.zip補丁用於修複Xilinx年限溢出缺陷。

步驟二：編譯二進位檔案

編譯vadd二進位檔案和kernel_global_bandwidth二進位檔案的操作如下所示：

樣本一：編譯vadd二進位檔案

複製examples目錄。

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

進入vadd目錄。
```
cd examples/vadd/
```
運行以下命令，查看XDEVICE的值。
```
cat sdaccel.mk | grep "XDEVICE="
```
您需要確保XDEVICE配置為XDEVICE=xilinx_aliyun-f3_dynamic_5_0。
修改common.mk檔案。
1. 運行以下命令，開啟common.mk檔案。
```
vim ../common/common.mk
```
2. 添加編譯參數--xp param:compiler.acceleratorBinaryContent=dcp。
  在檔案代碼中的第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檔案。
運行以下命令，編譯器。
```
make -f sdaccel.mk xbin_hw
```
重要
編譯過程可能會持續數個小時，請您耐心等待。
顯示結果如下所示，表示二進位檔案（vadd）編譯已經開始。

樣本二：編譯kernel_global_bandwidth二進位檔案

依次運行以下命令，複製xilinx 2018.2 examples。
```
git clone https://github.com/Xilinx/SDAccel_Examples.git
```
```
cd SDAccel_Examples/
```
```
git checkout 2018.2
```
說明
git分支必須為2018.2版本。

運行以下命令進入上述目錄。

cd getting_started/kernel_to_gmem/kernel_global_bandwidth

修改Makefile檔案。
1. 運行以下命令，開啟Makefile檔案。
```
vim Makefile
```
2. 設定DEVICES值，使得DEVICES=xilinx_aliyun-f3_dynamic_5_0。
3. 添加編譯參數--xp param:compiler.acceleratorBinaryContent=dcp。
  在檔案代碼的第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)
```
運行以下命令，編譯器。
重要
編譯過程可能會持續數小時，請您耐心等待。
```
make TARGET=hw
```
顯示頁面如下所示，表示二進位檔案（kernel_global_bandwidth）編譯已經開始。

步驟三：檢查打包指令碼

運行以下命令，檢查打包指令碼是否存在。

file /home/user1/xbinst_oem/sdaccel_package.sh

如果返回結果中包含cannot open (No such file or directory)，說明不存在該檔案，您需要運行以下命令手動下載打包指令碼。

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

步驟四：製作鏡像

初始化faasutil工具並配置OSS環境。

運行以下命令，設定RAM帳號的AccessKey資訊。

# 將<HereIsYourSecretId>和<HereIsYourSecretKey>替換為您的RAM使用者AK資訊
faasutil config --id=<HereIsYourSecretId> --key=<HereIsYourSecretKey>

運行以下命令，設定FaaS服務要使用的OSS Bucket。

# 將<hereIsYourBucket>替換為您建立的OSS Bucket名稱
faasutil auth --bucket=<hereIsYourBucket>

運行以下命令，擷取尾碼為.xclbin的檔案名稱。
```
ls
```
顯示結果如下：
運行以下命令，打包好二進位檔案。
```
/home/user1/xbinst_oem/sdaccel_package.sh -xclbin=/opt/Xilinx/SDx/2018.2/examples/vadd/bin_vadd_hw.xclbin
```
打包完成後，您會在同一目錄下看到一個打包好的檔案，如下圖所示。

步驟五：下載鏡像

本步驟介紹如何使用faasutil工具上傳網表檔案並下載FPGA鏡像。關於faasutil命令的用法，請參見使用faasutil。

依次運行以下命令，將壓縮包上傳和存放在OSS Bucket中。

將壓縮包上傳到您個人的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)

顯示結果如下所示：

f3_0opencl

將存放在您個人OSS Bucket中的壓縮包上傳到FaaS嵌入式管理單元的OSS Bucket中

faasutil create_image --object=bit.tar.gz --fpgatype=xilinx --name=<HereIsFPGAImageName> --tags=<HereIsFPGAImageTag> --encrypted=false --shell=<hereIsShellVersionOfFPGA>        # <HereIsFPGAImageTag>可選（鏡像Tag）  encrypted可選，鏡像加密   <HereIsShellVersionOfFPGA>預設版本

顯示結果如下所示：

f3_opencl-2

運行以下命令，查看FPGA鏡像是否處於可下載狀態。
```
faasutil list_images
```
在返回結果中：
- 如果FPGA鏡像的"State"為"compiling"，表示FPGA鏡像處於編譯狀態，您需要繼續等待。
- 如果FPGA鏡像的"State"為"success"，表示FPGA鏡像已經可以下載，您需要找到並記錄FpgaImageUniqueId，用於後續下載鏡像（download_image）時使用。
運行以下命令，在命令返回結果中，找到並記錄fpga bdf。
```
faasutil list_instances
```

運行以下命令，下載FPGA鏡像。

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

運行以下命令，查看鏡像是否下載成功。
```
faasutil fpga_status --bdf=<fpga_bdf>
```
以下為返回結果樣本。如果顯示的imageuuid與您擷取的FpgaImageUniqueId一致，並且fpgaStatus參數顯示valid，說明鏡像下載成功。

步驟六：運行Host程式

運行以下命令，配置環境。

 # 每開啟一個終端視窗就需要執行該命令一次
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl

配置sdaccel.ini檔案。
在host二進位檔案所在目錄下，運行以下命令，建立sdaccel.ini檔案
```
vim sdaccel.ini
```
建立sdaccel.ini檔案後，需要輸入下列內容。
```
[Debug]
profile=true
[Runtime]
runtime_log = "run.log"
hal_log = hal.log
ert=false
kds=false
```
運行以下命令，運行host程式。
- vadd運行命令如下：
```
make -f sdaccel.mk host
```
```
sudo ./vadd bin_vadd_hw.xclbin
```
- kernel_global_bandwidth運行命令如下：
```
sudo ./kernel_global
```
如果返回結果中出現Test Passed，說明測試通過。

常用操作

這裡介紹FPGA執行個體的部分常用操作。

任務	命令
查看協助文檔	`make -f ./sdaccel.mk help`
軟體模擬	`make -f ./sdaccel.mk run_cpu_em`
硬體模擬	`make -f ./sdaccel.mk run_hw_em`
只編譯host代碼	`make -f ./sdaccel.mk host`
編譯產生可以下載的檔案	`make -f sdaccel.mk xbin_hw`
清理工作目錄	`make -f sdaccel.mk clean`
強力清除工作目錄	`make -f sdaccel.mk cleanall`

說明

模擬時只需要按照Xilinx標準流程操作，不需要配置F3_env_setup環境。
SDAccel runtime和SDAccel開發平台已在阿里雲F3官方鏡像中提供，您也可以直接下載SDAccel runtime和SDAccel開發平台。