FPGA云原生 Mailbox通信

Mailbox Subdevice Driver

这是添加到现有xclmgmt/xocl驱动程序中的邮箱子设备驱动程序，以便用户pf和mgmt pf可以向/从对等方发送和接收任意长度的消息。 该驱动程序是根据pg114文档（https://www.xilinx.com/support/documentation/ip_documentation/mailbox/v2_1/pg114-mailbox.pdf）的规范编写的。 硬件提供一个TX通道和一个RX通道，它们彼此完全独立地运行。 可以将数据DWORD单元以FIFO方式推入或读取通道。

Packet 数据包层
该驱动程序实现了两个传输层-数据包和消息层（请参见下文）。数据包是固定大小的数据块，可以通过TX通道发送或从RX通道检索。 TX和RX中断发生在数据包边界，而不是DWORD边界。在同级读取前一个数据包之前，驱动程序不会尝试发送下一个数据包。同样，在对等方将完整的数据包写入硬件之前，驱动程序将不会尝试从硬件读取数据。在正常操作模式下，数据传输完全由中断驱动。因此，为了使邮箱驱动程序正常运行，需要在mgmt和用户pf上都启用中断功能。在设备热重置期间，此驱动程序可能会在轮询模式下工作很短的时间，直到完成重置为止。
数据包定义为struct Mailbox_pkt。数据包主要有两种：msg起始数据包和msg-body数据包。两者都可以携带msg结束标志，以指示该数据包是当前msg中的最后一个。msg起始数据包包含一些与整个msg相关的元数据，例如msg ID，msg标志和msg大小。严格来说，这些信息属于msg层，但是它可以帮助接收端在看到第一个数据包而不是整个msg之后为传入的msg有效载荷准备缓冲区。这是msg接收的优化。msg正文包仅包含msg有效负载。

Message层
消息是任意长度的数据缓冲区。驱动程序会将消息分解为多个数据包，然后将其发送给对等方，后者再将它们组合成完整的消息，然后再传递给上层进行进一步处理。一个消息需要至少一个数据包传输到对等方（带有msg结束标志的msg起始数据包）。每条消息都有一个唯一的临时u64 ID（有关更多详细信息，请参见下面的通信模型）。该ID仅在msg开始数据包中显示。因此，在数据包层，假设相邻数据包属于同一消息，除非下一个是另一个msg起始数据包。因此，在消息层，驱动程序将不会尝试发送下一条消息，直到完成当前消息的发送为止。即，我们为消息TX通道实现了一个FIFO。驱动程序按照从上层接收到的顺序发送所有消息。如果需要，我们可以稍后实现不同优先级的消息。在RX端，接收消息没有特定的顺序。由对等方决定哪个消息首先进入其自己的TX队列，然后在另一侧首先接收。
如果TX消息在2秒内未完成发送，则视为已超时（对于msg大于1MB，每MB 2秒）。发送相应的TX消息20秒后，RX消息被视为超时。msg超时后将无法重试。错误将简单地传播回上层。
消息定义为structmailbox_msg。它带有一个标志，指示它是请求消息还是响应消息。响应消息必须在接收者的RX队列中等待着足够大的消息缓冲区。请求消息没有等待的消息缓冲区。上层可以在提供回调时选择异步将消息排队等待TX或RX，或者在没有提供回调时同步等待。

Communication层
在最高层，驱动程序实现请求-响应通信模型。在此模型中，可以发送/接收三种类型的msg：需要响应的请求消息、不需要响应的通知消息、响应消息，用于响应请求。
请求的OP代码确定是请求还是通知。如果提供，则响应消息必须通过消息ID与请求消息相匹配，否则将被静默删除。而且没有响应。通信会话始终以请求开始，并以0或1个响应结束。请求缓冲区或响应缓冲区将用单个msg包装。这意味着一个会话最多包含2个msg，并且msg ID用作会话ID。
邮箱驱动程序为mgmt和用户pf提供了一些内核API，以便在此层相互通信（有关详细信息，请参见mailbox_ops）。当请求或通知消息排队进入TX通道进行发送时，系统会自动为其分配一个消息ID。对于请求消息，由调用方提供的用于接收响应的缓冲区也将入队到RX通道中。排队的响应消息将具有与相应请求消息相同的消息ID。响应消息（如果提供）将始终在请求消息被排队之前被排队，以避免争用情况。
当收到来自对等方的新请求或通知时，驱动程序将分配一个msg缓冲区并将其复制到该缓冲区中，然后通过xocl_peer_listen（）API将其传递给上层（mgmt或用户pf驱动程序）提供的回调，以进行进一步处理。当前，驱动程序为RX通道（RX线程）实现一个内核线程，为TX通道（TX线程）实现一个内核线程，以及一个用于处理传入请求的线程（REQ线程）。RX线程负责接收传入的消息。如果是请求消息或通知消息，则将其打断到REQ线程进行处理，然后依次调用mgmt pf驱动程序（xclmgmt_mailbox_srv（））或用户pf驱动程序（xocl_mailbox_srv（））提供的回调它。如果是响应，它将简单地唤醒等待线程（当前，所有响应消息均由调用方同步等待）TX线程负责发送消息。完成后，TX线程会简单地唤醒等待的线程（如果这是需要响应的请求），或者在消息为通知或响应消息而不需要任何响应的情况下调用默认回调来释放消息。

Software communication channel
可以通过硬件邮箱通道或通过在用户域中实现的守护程序（软件通信守护程序）来发送或接收消息。等待从用户pf向mgmt pf发送msg的守护程序称为MPD。另一个是MSD，它负责从mgmt pf向用户pf发送msg。每个邮箱子设备驱动程序在/ dev下创建一个设备节点。守护程序（MPD或MSD）可以阻止并在read（）接口中等待，以获取发送到对等方的传出msg。或者，它可以阻止并在poll（）/ select（）接口中等待，并且在准备好发送出去的msg时将其唤醒。然后，它可以通过read（）接口获取味精。完全由守护进程来处理味精。它可以将其传递给对等方或完全以自己的方式处理。
如果守护程序希望将msg（请求或响应）传递给邮箱驱动程序，则可以通过调用write（）驱动程序接口来实现。它可能会阻塞并等待，直到RX线程消耗了先前的味精，然后才能完成传输自己的味精并返回到用户域。守护程序和邮箱之间的接口定义为struct sw_chan。有关详细信息，请参考mailbox_proto.h。

通讯协议
如上所述，在此文件中，数据包层和msg层通信协议分别定义为struct Mailbox_pkt和struct Mailbox_msg。 在mail_proto.h中定义了用于在通信层进行通信的协议。软件通信通道仅在通信层进行通信，该通信层仅看到请求和响应缓冲区。 它仅应实现邮箱_proto.h中定义的协议。在通信层定义的当前协议遵循以下规则：从用户pf发起的所有请求都需要响应，而从mgmt pf发出的所有请求都不需要响应。 这应该避免从每一端派生的任何可能的死锁阻塞并等待对等方的响应。

Mailbox Inter-domain Communication Protocol

MSD/MPD and Plugins

在基于VM（IaaS）或基于容器（PaaS）的云供应商处部署FPGA时，需要解决一些常见问题：FPGA的MGMT PF和USER PF分开。云供应商拥有MGMT PF，而用户拥有USER PF。用户在USER PF上进行的任何操作均不应损坏或损害MGMT PF的操作。xclbin文件需要保护。一些xclbin文件是由第三方ISV提供的，它们不希望用户访问其xclbin文件，而是间接使用它们。也就是说，用户VM或容器中的xclbin文件不是在卡上运行的真实文件。相反，它们是伪造的，其中删除了BITSTREAM部分。在VM中的虚假xclbin文件上下载xclbin会导致对真实的xclbin文件进行编程，而无需任何用户感知。云供应商对xclbin下载过程具有更多控制权。下载xclbin涉及VM或容器与主机之间的对话。云供应商相信他们有自己的方式来做到这一点。

Mailbox, Message Service Daemon(MSD) and Message Proxy Daemon(MPD)

用户从xbutilcmdline或OpenCLAPI下载xclbin --> shim层调用icotl操作xocl driver --> xocl驱动子设备icap向mailbox子设备发送请求（xclbin文件在主机内存中，请求数据量很小）–> mailbox通过hw mailbox向xclmgmt的对等方传送请求–>xclmgmt驱动子设备mailbox将请求发送给子设备icap->xclmgmt驱动子设备icap接收req，获得内存中的xclbin，向icap编程–>响应通过相反路径返回给用户。

XRT的xclmgmt和xocl驱动程序分开。邮箱是2个驱动程序之间的通信通道，用户可以使用该通道对VM中的USER PF进行一些管理工作。下载xclbin。但是，HW邮箱在设计上具有非常低的带宽，这使得传输一百兆字节的xclbin文件非常慢。 SW邮箱是邮箱框架的补充，可以克服此问题，对于没有可用的HW邮箱的情况，它也有帮助。SW邮箱依赖于MSD / MPD。 MSD驻留在安装xclmgmt驱动程序的计算机（即主机）的用户空间中，而MPD驻留在安装xocl驱动程序的计算机（即VM）的用户空间中。他们与相应驱动程序中的邮箱subdev对话。 MSD / MPD可以通过外部网络连接，例如。以太网，并使下载xclbin更快
注意：为了使用SW邮箱，云供应商必须在主机和VM之间设置网络连接。该模型提供了更快的xclbin下载，但不提供xclbin保护

建立网络连接后，还需要以下配置

# In host, make sure the IP address configured is the one VM talks to
Host>$ sudo xbmgmt config --show

# If the IP address is not correct, change it by running
Host>$ sudo xbmgmt config --daemon --host <host-or-ip>

# Start MSD in host
Host>$ sudo systemctl start msd

# Start MPD in VM
VM>$ sudo systemctl start mpd

用户从xbutilcmdline或OpenCLAPI下载xclbin --> shim层调用icotl操作xocl driver --> xocl驱动子设备icap向mailbox子设备发送请求–> mailbox使用maibox message向MPD传输请求和xclbin–>MPD将maibox message发送给MSD->MSD向xclmgmt驱动子设备maibox传输mailbox消息–>xclmgmt驱动子设备mailbox向子设备icap发送请求–>xclmgmt驱动子设备icap接收请求，编程icap接收请求，编程icap–>响应通过相反路径返回给用户。

Enhancement to MPD
MSD / MPD以邮箱消息为中心。 他们专注于传递邮箱消息，并且不对其进行解释。 为了保护xclbin文件，在这种情况下，用户将虚假的xclbin文件提供给xocl，然后插件得到真实的文件，然后再重新提供给xclmgmt，MSD / MPD必须解释和理解下载的xclbin消息。 MPD的增强功能解释邮箱消息并调用供应商特定的插件来下载xclbin
插件的输入是用户在VM或容器中提供的xclbin文件-它可能是伪造的xclbin文件。 该插件调用特定于云供应商的API进行实际下载。 这是云供应商的责任

将真实的xclbin文件保存在专用数据库中,从伪造的一个中检索真正的xclbin,确定下载本身的合法性,与MGMT PF（xclmgmt驱动程序）交谈以下载实际的xclbin

Example MPD plugin
该示例插件针对在裸机上运行的容器。在这种情况下，MGMT PF和USER PF都在同一个域中，因此插件在检索到真正的xclbin之后可以直接在xclmgmt上调用ioctl到程序ICAP。这是Nimbix的用例
该插件被构建为共享对象– libcontainer_mpd_plugin.so，并且当用户安装容器pkg时，“ so”文件将安装在/ opt / xilinx / xrt / lib，而软链接文件– libmpd_plugin.so将在以下目录下创建链接到插件共享对象的相同文件夹。 MPD启动时会尝试对共享库进行dlopen（3）
默认情况下，此交付的容器插件仅使用输入xclbin文件作为输出（这意味着没有xclbin保护），展示了如何实现此插件。它确实包含示例代码，如何保存真实的xclbin，如何从伪造的xclbin中检索真实的xclbin以及如何下载受保护的xclbin，以供用户参考.该插件也可以用于MPD和邮箱的内部测试

# install xrt pkg
$ sudo apt install /opt/xrt_201920.2.3.0_18.04-xrt.deb

# install xrt pkg
$ sudo apt install /opt/xrt_201920.2.3.0_18.04-container.deb

# config mailbox channel switch
# this has to be manually configurated to ensure download xclbin going through SW mailbox
$ sudo echo 0x100 > /sys/bus/pci/devices/0000\:65\:00.0/config_mailbox_channel_switch

# When cloud vendor (eg. Nimbix) wants to enable its own xclbin protection mechanism, this
# plugin needs to be rebuilt and the built 'so' needs to be copied to /opt/xilinx/xrt/lib
# eg
$ sudo cp libcontainer_mpd_plugin.so /opt/xilinx/xrt/lib
$ sudo systemctl restart mpd