Xilinx FPGA_as_a_Service 概述

FPGA_as_a_Service仓库分为四个子仓库：Xilinx Base Runtime（预装了Xilinx运行时和setup、flash Alveo加速卡的Docker镜像）、Containerization（为多种云供应商提供脚本build Docker镜像）、k8s-fpga-device-plugin（在k8s集群中运行FPGA容器，节点部署发现FPGA Daemonset）、XRM（Xilinx FPGA硬件资源管理）

Xilinx Base Runtime - Xilinx Runtime Base Image Deployment Docker Solution

Docker是一组平台即服务（PaaS）产品，它们使用操作系统级虚拟化来交付Xilinx_Base_Runtimed容器。 容器使开发人员可以将应用程序所需的所有部分（如库和其他依赖项）打包在一起，并将它们全部打包为一个软件包。 有关更多Docker信息，请参阅Docker文档。

对于运行FPGA应用程序的docker容器，有几个前提条件：

• 在服务器上安装Xilinx Alveo FPGA硬件（Alveo U200，Alveo U250或Alveo U280）。
• 在主机上安装XRT（Xilinx运行时）（此存储库中提供的脚本）。
• 执行主机上的FPGA的Flash Shell（也包含在此版本库的脚本中）。
• 以特权模式运行docker FPGA容器或同时映射管理设备和用户设备*。
  默认情况下，Docker容器是“非特权”的，例如，不能在Docker容器内运行Docker守护程序。这是因为默认情况下，不允许容器访问任何设备，但是授予“特权”容器访问所有设备的权限（请参阅cgroups设备上的文档）。如果要限制对特定设备的访问，可以使用–device标志。它允许您指定一个或多个在容器内可访问的设备。对于Xilinx Alveo FPGA，它具有管理功能和用户功能。 Docker将把这两个功能用作映射的两个设备。

用户可以做一下操作：Setup Host (install driver and flash the cards)、Run Base Docker Image、Customize Docker Image for new Application。

Setup Host

为了在主机上安装XRT和平台并刷新加速卡，提供了带有两个参数（平台和版本）的单个命令（请参阅host_setup.sh）。
Installation Example
Run host_setup.sh as root. 使用root用户运行host_setup.sh
Clone repository from Xilinx GitHub 从Xilinx GitHub克隆仓库 root@machine:~$ git clone https://github.com/Xilinx/Xilinx_Base_Runtime.git
Go to Xilinx_Base_Runtime directory root@machine:~$ cd Xilinx_Base_Runtime
According to demand, choose deployment shell base on version.

#  ./host_setup.sh     --version 
#  ./host_setup.sh      -v       
#        : 2018.3 / 2019.1 / 2019.2 / 2020.1
root@machine:~$ ./host_setup.sh -v 2019.1 

Wait until installation completed. During the period you may need press [Y] to continue. Please Note: If you choose flashing FPGA, you need to cold reboot local machine after installation completed to load the new image on FPGA. 等待安装完成。 在此期间，您可能需要按[Y]才能继续。 请注意：如果选择闪存FPGA，则安装完成后需要冷重启本地计算机，以将新映像加载到FPGA上。

Run Base Docker Image

Docker是一组平台即服务（PaaS）产品，它们使用操作系统级虚拟化来交付Xilinx_Base_Runtimed容器。 在容器内部，您可以具有隔离的运行时环境，该环境具有预安装的XRT（Xilinx Runtime）和依赖项。但是，容器无法访问主机内核。 因此，您需要在主机上安装相同版本的XRT作为驱动程序，并在容器内使用XRT作为运行时。 并且应使用指定的Shell刷新FPGA。 您可以从Xilinx产品页面找到所有安装软件包，或通过该项目进行安装。 请参阅设置主机。
Runtime Example
Clone repository from Xilinx GitHub user@machine:~$ git clone https://github.com/Xilinx/Xilinx_Base_Runtime.git
Go to Xilinx_Base_Runtime directory user@machine:~$ cd Xilinx_Base_Runtime
Run run.sh with corresponding arguments: xrt version and os version

#  ./run.sh     --version  --os-version 
#  ./run.sh      -v         -o          
#        : 2018.3 / 2019.1 / 2019.2 /2020.1
#     : ubuntu-18.04 / ubuntu-16.04 / centos
user@machine:~/Xilinx_Base_Runtime$ ./run.sh -v 2019.1 -o ubuntu-18.04

Inside docker container, run xbutil list or xbutil dmatest for listing cards or testing dma. Or copy your own application and xclbin files to container and run for test. 在docker容器中，运行xbutil list或xbutil dmatest来列出卡或测试dma。 或将您自己的应用程序和xclbin文件复制到容器中并运行以进行测试。
root@fc33db3f6ed6:/$ /opt/xilinx/xrt/bin/xbutil list
root@fc33db3f6ed6:/$ /opt/xilinx/xrt/bin/xbutil dmatest

Build docker application by using base image

该项目提供的所有docker映像都可以用作构建自己的docker应用程序的基础映像，因为它们都安装了XRT和依赖项。 这是Dockerfile的一个简单示例。

# Choose one of images as base image based on platform, version and OS version
FROM xilinx/xilinx_runtime_base:alveo-2019.2-ubuntu-18.04

# Configure environment what your application needs, for example
apt-get install [dependencies]

# Copy your application and xclbin files
COPY [application_file] [path_of_application_file]
COPY [xclbin_file] [path_of_xclbin_file]

Then you can use docker build -t [tag] -f [Dockerfile] to build your own docker application.

FAQ
如果XRT已安装在容器内，为什么要在主机上安装XRT？
XRT包含多种内容：驱动程序，运行时，实用程序等。Docker容器无法直接访问主机内核。 因此，容器内的XRT是运行时，主机上的XRT与内核作为驱动程序对话。 目前，XRT不支持向后兼容。 您需要确保主机XRT和容器XRT的版本应该相同。

我不想在特权模式下运行docker。如何将management function and user function管理功能和用户功能作为设备映射到Docker容器？
您可以使用docker run --device标志。管理功能的路径为/dev/xclmgm[num_mgmt]，用户功能的路径为/dev/dri/renderD[num_user]。对于num_mgmt，运行/ opt / xilinx / xrt / bin / xbmgmt扫描，您将看到类似以下内容的东西：[0] mgmt：[03：00.1]：0x5000：0x000e：[xclmgmt：2.2.2173，ff6624c6d72c6ca68d6b123c9d76e49e55c09097：769数字[0]是FPGA的索引（您可能安装了多个卡），最后一个数字：769是num_mgmt对于num_user，请运行/ opt / xilinx / xrt / bin / xbutil scan，您将看到类似以下内容：[0 ]用户：[30：00.0]：0x5001：0xe000：[xocl：2.2.2173，ff6624c6d72c6ca68d6b123c9d76e49e55c09097：128]请确保索引与mgmt相同，最后一个数字：128为num_user找出num_mgmt和num_user之后，您可以像这样运行docker：docker run --rm -it --device = / dev / xclmgmt769：/ dev / xclmgmt769 --device = / dev / dri / renderD128：/ dev / dri / renderD128 xilinx / xsds：alveo-u200- 2019-1-ubuntu-1604

OS版本对docker映像意味着什么？
Docker可以提供OS级虚拟化。 您可以在Ubuntu服务器上运行基于CentOS的Docker容器。 它为客户构建应用程序提供了便利，而无需考虑不同的OS版本。

如果我在主机上安装了多功能FPGA卡，那么在Docker容器中可以访问哪些卡？
他们全部。 run.sh脚本将扫描所有FPGA设备并将它们映射到docker容器。 如果要限制特定的卡，请参阅问题2。 请注意，映射设备并不意味着该容器专有。

注意：此Xilinx_Base_Runtime以Docker映像（“映像”）的形式提供给您。使用此映像，即表示您代表您自己和您的雇主（如果适用）受此信息以及适用于该映像的Xilinx_Base_Runtimede和此映像（如果适用）的Xilinx_Base_Runtimeributing的许可协议的约束，但需要运行此映像映像，并在执行Docker构建实用程序脚本（“脚本”）后从Internet下载。如果您选择通过输入必要的命令来执行脚本，则您承认从Image或从Internet上安装的各种Xilinx_Base_Runtimed均已安装在Image中，并且您同意由您独自负责查看和遵守以下条款：管理此类Xilinx_Base_Runtime Docker可执行文件并安装到Image中的许可协议。 Xilinx_Base_Runtimets可以在Image下载站点的“ LICENSE”文件中，Xilinx_Base_Runtimehe Image的源代码中查看，也可以使用（i）操作系统Xilinx_Base_Runtimets（主要社区开源）查看。项目网页，以及（ii）Xilinx_Base_Runtime互联网，位于原始网页提供给您的URL，可以从其中下载Xilinx_Base_Runtime。如果您不同意，则不应“单击”接受通知，也不应输入脚本命令，也不应以其他方式访问，下载，安装或使用映像。
免责声明：此图像按“原样”提供，并且XILINX不作任何明示，暗示或法定的担保和条件，包括但不限于对任何特定目的的适销性，非侵权性或适用性的担保。 Xilinx对与该图像相关，由其产生或与之相关的任何种类或性质的任何损失或损害（包括合同或侵权行为，包括过失，或根据任何其他责任理论）概不负责。直接，间接，特殊，偶发或后果性损失或损害（包括由于第三方提起的任何诉讼而遭受的数据，利润，商誉或任何类型的损失或损害），即使此类损害或损失为可以合理预见或告知Xilinx这样做的可能性。

k8s-fpga-device-plugin

用于Kubernetes的Xilinx FPGA设备插件是部署在Kubernetes（k8s）集群上的Daemonset，它使您能够：发现插入集群的每个节点中的FPGA，并公开有关FPGA的信息，例如FPGA的数量，Shell（目标平台）类型等；在k8s集群中运行FPGA可访问的容器
如果您已经拥有docker和kubernetes环境，则可以按照快速入门在您自己的集群上测试k8s-fpga-device-plugin。 如果要构建docker，kuberetes集群环境并从一开始就测试k8s-fpga-device-plugin，可以查看完整教程。
有关k8s-fpga-device-plugin，Docker和Kubernetes的详细信息，您可以使用以下链接：

Detailed Info	Description
Kubernetes device plugin	Kubernetes community documentation about Kubernetes plugin
AWS Kubernetes FPGA Plugin	Install and test k8s-fpga-device-plugin on AWS FPGA
Kubernetes Docker tutorial	Build docker image and test with k8s-fpga-device-plugin
Quick Start	Quick start on how to install and test k8s-fpga-device-plugin
K8S FPGA Device Plugin Full tutorial	Step by step tutorial starts from install docker and Kubernetes cluster
FAQ	Frequently asked questions

先决条件
所有FPGA都具有已经刷新的Shell（目标平台）。
在插入了FPGA的所有工作程序节点上安装XRT（版本不早于2018.3）
k8s中的容器运行时是docker
k8s版本> = 1.17（所有测试已在版本1.17上运行。旧版本可能会或可能无法工作）

github地址：https://github.com/Xilinx/FPGA_as_a_Service
https://github.com/Xilinx/Xilinx_Base_Runtime