基於f3執行個體的RTL開發流程 - FPGA as a Service

本文介紹基於F3執行個體的RTL（Register Transfer Level）的開發流程。

前提條件

已建立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使用者操作FPGA執行個體。為了最大程度地保護您資料的安全性，建議您按照必要且最小化原則對RAM使用者進行授權，用於操作指定的ECS執行個體。

操作步驟

遠端連線Linux執行個體。
重要
編譯工程時需要2~3小時。建議您使用nohup或者VNC串連執行個體，以免編譯時間意外退出。
下載並解壓RTL參考設計。
配置環境。
- 如果驅動為xdma，則需要運行以下命令來配置環境。
```
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xdma #每開啟一個終端視窗就需要執行該命令一次
```
- 如果驅動為xocl，則需要運行以下命令來配置環境。
```
sudo source /home/user1/xbinst_oem/F3_env_setup.sh xocl #每開啟一個終端視窗就需要執行該命令一次
```
說明
配置環境主要包括安裝xdma驅動或安裝xocl驅動、設定vivado環境變數、檢查vivado license、檢測aliyun-f3 sdaccel平台、授予2018.2 runtime配置。

指定OSS儲存空間。

faasutil config --id=<HereIsYourSecretId> --key=<HereIsYourSecretKey> #將<HereIsYourSecretId>和<HereIsYourSecretKey>替換為您的RAM使用者AK資訊
faasutil auth --bucket=<HereIsYourBucket> # 將<HereIsYourBucket>替換為您建立的OSS Bucket名稱

運行以下命令，編譯RTL工程。
```
cd <您之前解壓的路徑>/hw/ #進入解壓後的hw路徑
sh compiling.sh
```
說明
編譯工程需要2~3小時，請您耐心等待。
編譯完成後，顯示如下所示：
上傳網表檔案，並下載FPGA鏡像。
使用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，說明鏡像下載成功。

FAQ

上傳鏡像時出現異常，如何查看異常詳情？

如果您的工程在上傳產生鏡像的過程中出現異常，例如雲上編譯伺服器編譯報錯，您可以通過faasutil工具查看編譯log檔案。

如何重新載入鏡像？

卸載驅動。
- 如果您安裝了xdma驅動，則需要在執行個體中運行sudo rmmod xdma命令卸載驅動。
- 如果您安裝了xocl驅動，則需要在執行個體中運行sudo rmmod xocl命令卸載驅動。

下載鏡像。

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

安裝驅動。
- 如果您需要安裝xdma驅動，請運行以下命令。
```
sudo depmod
sudo modprobe xdma
```
- 如果您需要安裝xocl驅動，請運行以下命令。
```
sudo depmod 
sudo modprobe xocl
```