基于f3实例的RTL开发流程 - FPGA云服务器

本文介绍基于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
```