Digilent FPGA Demo Git Repositories

本文档描述了Digilent的Github上存储库的git工作流，包含FPGA板的演示项目，包括这些存储库的结构描述，以及使用git使用这些演示项目的说明，以及在适当的工具中加载和重建这些项目的说明。

• 类型的演示
• 库结构
  • 子模块结构
  • 分支结构
• 使用演示的Git源代码
  • 克隆根存储库
  • 浏览存储库
  • Vivado (HW)项目
  • Petalinux (OS)项目
  • 葡萄(SW)工作区

在本文档中描述的结构中，有几种不同类型的演示是受版本控制的。每种类型的演示由一个或多个组成组件，每一个设计都是在一个单一的工具．在本例中，许多工具都是Xilinx为创建Xilinx fpga设计而创建的应用程序。本文档涵盖了Vivado、Petalinux和Vitis中分别开发的硬件、操作系统和软件组件。

纯硬件演示是在Vivado内设计的，并通过Vivado的硬件管理器编程到一块板上。它们在FPGA结构中实现一些功能，并且不以任何方式使用在处理器中运行的软件。

Baremetal软件演示使用在Vivado内部设计的硬件平台，其中包括处理器。然后，在Vitis中创建的软件应用程序在这个平台上运行，通常使用AXI接口与FPGA结构中实现的硬件通信，通常在处理器和电路板上的一些外设之间创建一座桥。

Petalinux软件演示程序在放置在板上的Linux映像中运行软件设计。Vivado用于创建硬件平台，就像使用baremetal演示一样，然后在Petalinux中使用这个硬件平台来配置Linux操作系统将不同的外设映射到不同的驱动程序。Vitis被用来创建一个软件应用程序，它使用这些驱动程序对这些外围设备做一些事情。

为了分离演示的每个组件的开发历史，每个组件使用一个单一的工具，被放置在Github上的一个单独的存储库中，这些存储库通过一个包含一个板的所有演示的单一存储库链接在一起。下面将描述每个存储库的结构以及如何使用它们。

关于使用git使用这些存储库的直接说明可以跳过跳到使用演示的Git源代码章节。

每个Digilent FPGA开发板上都有一个相关的存储库Github，里面包含了所有针对这块板的演示。本节描述这些存储库的结构。

所有digilent创建的硬件项目(hw)、Petalinux项目(os)和用于FPGA演示的软件工作区(sw)都在相应的存储库中进行版本控制。一个根库是用来连接它们的。每个非根存储库(称为组件子模块)对应于单个工具的使用，硬件项目与Vivado一起使用，Petalinux项目与Petalinux一起使用，而软件工作区则在Vitis中使用。

注意:软件工作区依赖于Vivado项目和Petalinux项目，其中操作系统组件是礼物。Petalinux项目依赖于Vivado项目。对依赖项的更改可能需要对依赖项目或工作空间的更改。

有些板可能没有任何使用一些工具的演示。例如，Cmod S7没有使用Petalinux的任何演示。在这些情况下，根存储库中可能存在或不存在相应的组件子模块。空组件子模块的存在并不意味着Digilent近期计划为相应的工具创建演示。

即使演示不需要特定工具的源代码，组件子模块仍然会出现在根存储库中，以使根存储库分支之间的切换更容易。

主题和根存储库有分支机构为板变体和分支菟丝子．有些板有多个变体，每个变体上都加载了不同的引脚兼容FPGA。每个dodder分支对应一个演示。

每个板分支机构可以有以下分支机构:{变体}/主人，{变体}/下一个，变体/{主题}，变体/{菟丝子}/

如果存储库只管理单板的一种变体，则{变体}前缀可以省略。这不是菟丝子的情况:{菟丝子}/主人，{菟丝子}/{主题}

Dodder主分支被认为是稳定的，并且检出一个Dodder主分支头(或者在主分支上标记提交)将导致获得有效的源。

在每个根存储库和组件子模块中使用相同的分支模型。如前所述，当组件子模块在不使用它的演示中仍然存在时，该组件内相应的dodder分支将不存在。未使用的子模块被保存在组件子模块的根提交中，没有源。

通过递归地克隆根存储库:github.com/Digilent/{根}每个板的组件子模块也被克隆，如下所示。根存储库是根据它们所支持的板子命名的，并且名称之间用连字符分隔(例如，可以在以下地址找到Zybo Z7的根存储库github.com/Digilent/Zybo-Z7）.

虽然可以单独克隆包含组件子模块的存储库，但建议通过根存储库访问它们，以便一次在多个组件的分支之间轻松切换。这还提供了关于多个组件中的源是否兼容的信息，如将子模块提交到根repo中的散列所示。

每个组件子模块都可以有额外的子模块存储库，用于引入对多个存储库通用的依赖项，如版本控制脚本、软件库和硬件ip。因此，使用a深度不推荐使用。

注意:如果您已经知道在克隆演示时要检出的演示分支，则可以在克隆期间使用'-b {branch}'参数。

重要!任何用于操作存储库的git命令都必须在存储库中运行cd荷兰国际集团(ing)。

git clone——recursive https://github.com/Digilent/{Root}

git clone——recursive git@github.com:Digilent/ eclipse - z7 .git

如果递归标记在克隆时未指定，子模块必须手动初始化和更新，如下所示。

Git子模块update——init——recursive

注意:就像克隆一样递归标志是自动初始化和更新嵌套子模块所必需的。

根存储库的主分支README中包含根存储库中所有演示的列表，包括相应分支的名称。此外，通过使用下面的命令可以获得存储库中所有分支的列表(包括工作和下一个分支):

git分支——

如果根存储库没有使用分支参数克隆，或者以后在分支之间切换，请在根存储库中使用下面的命令来检出一个演示，并更新子模块以实现正确的提交:

Git checkout {demo branch} Git submodule update——init——recursive

每个演示都记录在wiki页面中，该页面由相应的根存储库分支中的README链接到。

重要!Digilent的FPGA演示只需要支持所使用的每种工具的特定版本。这些版本由放置在各自主分支头部的版本标记指定，并且在使用的每个工具中都是相同的。例如，在一个Petalinux软件演示中，最后一次提交在master上被标记为“2020.1”的后缀只能用于Vivado 2020.1、Petalinux 2020.1和Vitis 2020.1。支持其他版本的以前提交可以在存储库的git历史中找到(或者从它的README链接，如果那些演示最初存在于其他存储库中)。

请注意：由于Petalinux仅在选定版本的Ubuntu中支持，Digilent推荐使用操作系统组件发生在受支持的Linux环境中。Windows用户可以选择双启动设置或虚拟机。

请注意：由于硬件切换文件是版本控制的，因此不需要使用Vivado项目来重建依赖Petalinux项目和Vitis工作空间。

克隆根存储库的“hw”文件夹包含Vivado项目的源代码，该项目用于构建演示的硬件设计。

重要!Digilent的Vivado项目需要安装一个带有Digilent板文件的Vivado。如果没有满足任何一个要求，首先运行安装Vivado, Vitis和Digilent板文件指南。

在使用Vivado项目之前，必须从其源代码重新创建该项目。要创建项目，首先启动受支持的Vivado版本^1）．打开Vivado的TCL控制台，并输入下面的命令。这将重新创建并打开Vivado项目。

设置argv“”;Source {local root repo}/hw/scripts/digilent_vivado_check - out.tcl

用于将Vivado项目检入或检出版本控制的脚本的进一步文档可以在digilent-vivado-scripts自述．这个README的版本与演示中使用的版本相对应，可以在本地根存储库中找到hw /脚本文件夹中。

一旦项目打开，就可以探索和修改设计，可以构建位流，如果SW或操作系统组件使用时，可以从Vivado导出新的XSA文件。项目被放置在本地硬件存储库的proj文件夹中。关闭后，可以通过选择重新打开开放项目在Vivado的欢迎屏幕，并导航到proj文件夹中包含的XPR文件。

如果一个SW或操作系统组件，或两者都被演示使用，硬件设计的更改需要从Vivado导出一个新的硬件定义，以供Petalinux和Vitis使用。在生成位流之后，硬件切换文件(HDF)可以通过文件→导出→导出硬件在Vivado对话框。硬件定义文件(HDF)应该放在本地硬件存储库的“hw_handoff”文件夹中，并且应该包含一个位流。

如果没有SW或操作系统通过使用Vivado的硬件管理器，项目现在可以被编程到一个板上。有关更多信息，请参阅从根存储库的README链接的演示wiki页面。

如果提交到存储库，则在存储库中提供的签入脚本hw /脚本在这个过程中可以使用foldler来帮助。这个脚本并不保证所有的源文件都被检入，并且在使用它时应该注意并进行测试，以确保其他使用您的存储库分支的人得到与您相同的项目。

重要!Digilent的Petalinux项目需要一个兼容的Petalinux安装。如果不满足这一要求，见第2章Xilinx Petalinux 2020.1参考指南(UG1144)有关如何安装Petalinux的更多信息。该文档的旧版本可以在Xilinx的网站上找到。

重要!许多包含软件组件的演示不需要Petalinux。如果您正在使用其中之一，请跳过葡萄(SW)工作区．

Digilent的Petalinux项目包含了所有必要的文件，以便在克隆存储库时开始“开箱即用”地使用Petalinux。

如果在Vivado中修改了硬件平台，可以通过在Petalinux项目(“os”文件夹)中运行以下命令切换出来:

petalinux-config——get-hw-description={包含新XSA的文件夹路径}

可能需要对Petalinux项目进行更改，这取决于对硬件设计的更改。详细说明这些更改超出了本文档的范围。也就是说，对硬件的一些改变需要对设备树的改变{本地根回购}/操作系统/项目规范/ meta-user / recipes-bsp /设备树/文件/ system-user.dtsi．更多信息可以在上面链接的Xilinx UG1144中找到。

Petalinux项目必须重建和重新包装:

Petalinux-build petalinux-package——boot——fsbl {path/to/fsbl}——fpga {path/to/bitstream}——uboot

重要!Digilent的Vitis工作空间需要一个兼容的Vitis安装。如果这个要求没有满足，首先运行安装Vivado, Vitis和Digilent板文件指南。

在使用Vitis工作区之前，必须从其源重新创建它。要填充工作区，首先启动受支持的Vitis版本^1）．本地存储库的使用sw / ws，并应在Vitis启动时选择。

打开Vitis的XSCT控制台(通过Xilinx→XSCT控制台菜单选项)，然后输入下面的命令。这将在当前工作区中重新创建硬件平台、配置其域并重新创建每个应用程序和系统项目。

Source {local root repo}/sw/src/checkout.tcl

可以使用下面提供的备用命令sw / ws文件夹用作软件工作区。这可以用来避免手动输入checkout脚本的完整路径，因为XSCT控制台不支持路径自动完成。

源(getws) / . . / src / checkout.tcl

关于用于Vitis工作空间版本控制的脚本的进一步信息，可以在脚本本身和digilent-vitis-scripts自述．

如果一个新的XSA文件已经从Vivado导出，它可以用来更新硬件平台的硬件规格，下面的下拉式说明:

更新现有的Vitis平台的硬件规格

如果在创建了Vitis应用程序项目之后更改了硬件设计，则必须采取几个步骤，以便使用新导出的XSA文件更新Vitis工作区。XSA文件包含与Vitis有关硬件平台的所有信息，基于此文件更改平台项目规范将自动加载任何更改。这包括为已安装的新IP添加新的驱动程序，并更改定义任何已重命名或已更改其地址的已安装IP的地址和其他细节的文件。

这些步骤假设您已经以创建新的Vitis工作区之前的相同方式重新生成了位流并重新导出了硬件。

---

在葡萄的助理窗格中，找到希望使用新硬件进行更新的平台项目。该项目通常有一个以“_wrapper”结尾的名称，并以文本“[Platform]”标记。

右键单击该项目并选择更新硬件规范．

---

在弹出的对话框中，单击浏览，并导航到希望平台瞄准的XSA文件的位置。点击开放选择此文件。

---

再次检查硬件规范文件路径与要使用的XSA文件匹配，然后单击好吧启动更新平台的自动过程。

完成后，将弹出一个对话框，说明平台项目已更新。点击好吧承认这一点。

---

此时，对硬件规范的更改已经加载到硬件平台中。如果位流被加载到XSA文件中，它将被更新。驱动程序集和xparameters文件将进行更改，以匹配修改后的设计。在将应用程序构建并编程到板上之前，可能需要对软件应用程序进行更改，但是，详细说明可能需要做什么超出了本指南的范围。

---

注意:Digilent建议每个软件存储库使用一个工作区，并提供根存储库的工作区sw / ws文件夹用于此目的。

工作空间文件夹中提供了两个清理脚本，以帮助在签出新工作空间之前删除现有的工作空间。Windows操作系统支持cmd脚本，Linux操作系统支持sh脚本。这些文件不应该被移动，因为它们递归地删除它们所在目录中的所有文件，并且如果使用不当可能损坏计算机文件系统。

如果提交到存储库，Digilent对Vitis工作空间的版本控制方案需要手动编辑与软件工作空间不同部分相对应的TCL脚本，如果需要更改配置选项。如果要向应用程序中添加额外的源，则应该将它们复制到应用程序中src /{应用}/ src文件夹中。另外一个要求是，对XSA文件的任何更改必须与对存储库的任何其他更改分开提交，并且提交消息必须引用HW存储库中更新XSA文件的提交散列。