动态加载比特流调研

1 主要内容

1.1 Zynq搭载Petalinux后的加载顺序：

1. FLASH/SD
2. 加载zynq_fsbl.elf：建立硬件系统，加载uboot到内核
   • ARM内核启动执行PS的代码，将FLASH/SD卡的第一阶段的bootloader拷贝到DDR3执行，完成FPGA配置（如果没有BIT流就不用配置），初始化MIO，初始化DDR3，初始化时钟，然后加载uboot到DDR3 ）
3. 加载uboot.elf：加载内核到DDR
   • 加载第二阶段bootloader，负责将image.ub加载到DDR3。
4. 加载Image.ub：建立内核系统
   • petalinux的image，包括ramdisk，设备树等

1.2 主要的四种种加载比特流方案：

• ① 裸机下的嵌入式应用开发

• Linux系统下的动态加载

  • ② fpga_manager框架（现在大多使用，基于框架包括多种实现方法）

  • ③ libdfx（资料较少）

  • ④ 使用/dev/字符设备 加载比特流（2018.1后被移除，现已不用）

    • 官方文档
    • 运行脚本介绍
    • 运行脚本介绍2

    （两种方法的介绍博客）

1.3 安全启动

安全启动无论是用哪种方法加载比特流都有提到，为防止提到时不了解因此把概念提前

secure 安全启动是指比特流会经过 AES 等安全模块的验证后，再配置到硬件中。（解释来自此处）

1.4 部分重配置

在 Xilinx 的概念中有两种比特动态重配置概念，一种叫部分重配置区别于普通的重配置。部分重配置并不会重新加载一个完整的比特流，而是重新配置部分逻辑，保持其他逻辑不变（静态逻辑），以提高重配置的速度，最快能达到数毫秒之快。（解释来自此处）

2 裸机下的嵌入式应用开发

2.1 开发思路

软件动态重配置在 Linux 下可以通过 DevCfg 驱动进行(2018.1版本前)，在没有操作系统的情况下，我们也可以在 SDK 中通过用户代码调用DevCfg开发

XILINX官方的BSP裸机例程里有xdevcfg的驱动代码，里面有个例程叫做POLL_EXAMPLE，就是实现PS配置PL比特流的，可以将指定的DDR空间里的数据给FPGA加载，如果这段数据是正确的比特流，那么FPGA就可以成功加载。但是这个代码经过实测，在PL已经CONFIG DONE的情况下是不工作的，我们要对其进行修改。

2.2 有关DONE状态的问题

刚刚开发思路里提到DONE状态，这里官方文档也给了一定的提示

需要注意的是，有时，依赖 XilFPGA 库的裸机应用程序在获取 DONE 状态时可能会产生错误。更多详细信息请参见回答记录70504- https://www.xilinx.com/support/answers/70504.html

2.3 参考开发教程

Zynq SDK 驱动探求（五）软件动态重配置硬件比特流

Zynq动态更新FPGA比特流

3 Linux系统下的动态加载

一定要参考的官方文档：

Solution Zynq PL Programming With FPGA Manager

Solution ZynqMP PL Programming

3.1 Linux系统下加载fpga上的三种主要方案

• fpga manager 原生框架开发：提供3个attributes来事项不同功能， sysfs（比特流加载）、debugfs（回读）、configfs（比特流和 PL 驱动程序的 DTBO一起加载）

• fpgautil应用程序：Xilinx 开发的实用程序为所有 FPGA manager 用例提供了一个易于使用的界面。

• Libdfx：未研究，推测提供多种适用于C中的api

3.2 FPGA Manager驱动

flow：

可以看到FPGA Manager Driver是内核中的驱动，简介完成对XilfpgaLib的调用，最终实现PL的重配置

4 使用FPGA Manager进行的部分重配置

本方案经过实际验证，运行环境在4.1节中进行介绍

部分重配置流程：

• petalinux搭建，配置内核完成对fpgamanage支持

• 对重加载的PL资源的配置

  • bitstream转换为bin格式
  • PL生成dtbo

• zynq加载相应逻辑

  • （简单）使用fpgautil间接操作fpgamanager完成比特流加载
  • （复杂）使用fpga manager驱动的3种接口中的attritude完成对PL部分的加载、(帧)回读
    • sysfs接口
    • debugfs接口
    • configfs接口/使用DTO进行动态加载

4.1 petalinux搭建

petalinx环境搭建参考网上各种教程

zynq的petalinux生成中的fpga manager支持选项可参考后方链接进行检查：Solution Zynq PL Programming With FPGA Manager

zynqMP的petalinux生成中的fpga manager支持选项可参考后方链接进行检查：Solution Zynq PL Programming With FPGA Manager

生成petalinux的要点

（1）环境介绍

成功运行的环境：

• petalinux 2021.2
• vivado 2019.2 （注意生成的是.xsa硬件描述文件，且导出时一定要包含bitstream文件）

注意！在下述环境下找不到fpga manager选项：

• petalinux 2015
• .hdf硬件描述文件

（2）petalinux-config

根据官方wiki，zynq系列生成petalinux时在config界面选择fpga manager后即可完成对该驱动的相关支持的配置，经检查确实在petalinx-config选中fpga manager后wiki中提到的各个选项也配置完全

• petalinux-config中开启fpga manager

（3）其他

其他petalinux生成过程中的配置可参考链接：https://blog.csdn.net/long_fly/article/details/78727813

4.2 bin格式比特流生成

使用bootgen工具完成对动态加载的比特流文件的转换

• bootgen程序在vivado/bin或vitis/bin目录中
• 运行方式

bootgen -image Full_Bitstream.bif -arch zynq -process_bitstream bin

• Full_Bitstream.bif 文件中应该包括

all:
{
        design_1_wrapper.bit /* Bitstream file name */
}

补充：进阶的自动化脚本链接

4.3 使用fpgautil完成对PL的重加载

参考官方文档直接调用即可，能够实现4.4节中的全部功能，使用起来较为简便，fpgautil实现的源码地址fpgautil.c基本上就是在FPGA Manager驱动的一种简化操作。fpgautil操作示例如下：

root@xilinx-zcu102-2018_3:~# fpgautil -h
 
fpgautil: FPGA Utility for Loading/reading PL Configuration in zynqMP
 
Usage:  fpgautil -b <bin file path> -o <dtbo file path>
 
Options: -b <binfile>           (Bin file path)
         -o <dtbofile>          (DTBO file path)
         -f <flags>             Optional: <Bitstream type flags>
                                   f := <Full | Partial >
                                Default: <Full>
          -s <secure flags>     Optional: <Secure flags>
                                   s := <AuthDDR | AuthOCM | EnUsrKey | EnDevKey | AuthEnUsrKeyDDR | AuthEnUsrK>
          -k <AesKey>           Optional: <AES User Key>
          -r <Readback>         Optional: <file name>
                                Default: By default Read back contents will be stored in readback.bin file
          -t                    Optional: <Readback Type>
                                   0 - Configuration Register readback
                                   1 - Configuration Data Frames readback
                                Default: 0 (Configuration register readback)
          -R                    Optional: Remove overlay from a live tree
  
Examples:
(Load Full Bitstream using Overlay)
fpgautil -b top.bit.bin -o can.dtbo
(Load Partial Bitstream through the sysfs interface)
fpgautil -b top.bit.bin -f Partial
(Load Authenticated Bitstream through the sysfs interface)
fpgautil -b top.bit.bin -f Full -s AuthDDR
(Load Parital Encrypted Userkey Bitstream using Overlay)
fpgautil -b top.bit.bin -o pl.dtbo -f Partial -s EnUsrKey -k <32byte key value>
(Read PL Configuration Registers)
fpgautil -b top.bit.bin -r

4.4 使用fpga attritude完成对PL的重加载

Linux FPGA Manager framework provides sysfs (Bitstream loading), debugfs (readback), configfs (Bitstream loading along with DTBO for PL drivers) attributes.

直接操作FPGA Manager驱动的各种接口，以下内容建议直接参考官方文档

4.4.1 sysfs 接口（用于加载比特流）

FPGA Manager Driver在 /sys/class/fpga_manager/<fpga>/位置处提供了控制逻辑和状态信息分别是：firmware，flag，status，name，key

对这些文件操作从而完成比特流的加载、部分加载等功能（懒得写了可以直接参考官方文档）

具体操作请参考官方文档实现

4.4.2 debug 接口（用于readback)

FPGA Manager Driver在 /sys/kernel/debug/fpga/位置处提供了包含提供回读内容的image属性操作文件：readback_type,image

• readback_type（ 是一个模块参数）：声明回读类型，0 - 读取配置寄存器 1 - 读取配置数据
• image（image 是一个 debugfs 属性）：根据 readback_type 模块参数提供回读信息

具体操作请参考官方文档官方文档

（1）读取普通数据的步骤：

（2）读取帧数据的步骤：

4.4.3 configfs接口/使用DTO进行动态加载（用于比特流和 PL 驱动程序的 DTBO一起加载）

Device Tree Overlay(DTO)用于在 Linux 运行时对 FPGA 进行重新编程。DTO 覆盖将添加子节点和来自。在 Bitstream 编程之后，新添加的设备节点/驱动程序将被探测。

具体操作请参考官方文档)实现

---

（1）其中DTO文件应该包括：

• Target FPGA Region
  - “target-path” or “target” - The insertion point where the the contents of the overlay will go into the live tree.
  target-path is a full path, while target is a phandle.
• FPGA Image firmware file name
  - “firmware-name” - Specifies the name of the FPGA image file on the firmware search path.
  The search path is described in the firmware class documentation.
• Image specific information
  - external-fpga-config : boolean, set if the FPGA has already been configured prior to Linux boot up.
• Child devices
  - child nodes corresponding to hardware that will be loaded in this region of the FPGA.

（2）提示：

• 如果用户尝试加载未对齐的位/bin 文件，与对齐（字对齐）位/bin 文件相比，PL 配置需要更长的时间
• 使用覆盖我们可以添加一个新节点或添加/更新现有节点属性。但它不允许替换已经是活动树一部分的现有节点

（3）使用DTO加载完整比特流的步骤

加载步骤（Steps for programming the Full Bitstream using overlay）：

• 复制Full bitstream (.bin)和pl.dtbo文件到固件(firmware)文件夹后进行如下操作：

  • mkdir /configfs

  • mount -t configfs configfs /configfs

  • cd /configfs/device-tree/overlays/

  • mkdir full

  • echo -n “pl.dtbo” > full/path

删除步骤（Steps to remove the drivers got added as part of DTO）：

• rmdir /configfs/device-tree/overlays/full

（4）可能的使用DTO加载部分比特流步骤

加载步骤：

• 复制Partial Bitstream (.bin) 和 rm.dtbo文件到 lib/firmware文件夹后进行如下操作：

  • mkdir /configfs

  • mount -t configfs configfs /configfs

  • cd /configfs/device-tree/overlays/

  • mkdir partial

  • echo 1 > /sys/class/fpga_manager/fpga0/flags

  • echo -n “pl.dtbo” > partial/path

删除步骤（To remove a device tree overlay）:

• rmdir /configfs/device-tree/overlays/partial

4.5 如何生成dtbo文件

官方文档中有这么一段内容：

The Xilinx device tree generator (https://github.com/Xilinx/device-tree-xlnx) currently lacks automated support for device tree overlay generation for Partial Reconfiguration / DFX designs. For systems requiring runtime device tree overlay (eg, Linux device driver support) support, hand-crafted device trees can be deployed and loaded. See the “Working with Device Tree Overlay (DTBO)” section below for details on how to load these at runtime.

Occasionally, bare-metal applications relying on the XilFPGA library may produce an error getting the DONE status. See Answer Record 70504 for more details - https://www.xilinx.com/support/answers/70504.html

Xilinx 设备树生成器(Xilinx device tree generator， https://github.com/Xilinx/device-tree-xlnx )目前缺乏对部分重构/DFX 设计的设备树覆盖生成的自动支持。对于需要运行时设备树覆盖(例如，Linux 设备驱动程序支持)支持的系统，可以部署和加载手工制作的设备树。请参阅下面的“使用设备树覆盖(DTBO)”部分了解如何在运行时加载这些内容的详细信息。

有时，依赖 XilFPGA 库的裸机应用程序在获取 DONE 状态时可能会产生错误。更多详细信息请参见回答记录70504- https://www.xilinx.com/support/answers/70504.html

根据上面内容得出，可能dtx缺少对重构设备树的自动化支持，需要手动制作

但根据4.4.3节中官方提供的dto代码推测可以通过hsi工具从.xsa文件中自动生成，这里有两个文档分别介绍了如何制作dtbo以及hsi工具，可以从这两个文档进一步研究：

• Build Device Tree Blob wiki
• 生成 DTSI 和 DTBO 覆盖文件

5 Libdfx方案

该库是构建在 Linux 驱动程序堆栈之上的轻量级用户空间库，以支持 FPGA 设备编程。这个“C”库可以静态构建，需要与用户应用程序集成。它提供了不同的 API，可以解决 DFX 或 PL 配置数据编程的多个用例。它还通过避免其他方法中涉及的多个缓冲区副本来提供更快的编程能力。

https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/1959854475/libdfx+-+Linux+User+Space+Solution+for+FPGA+Programming