基于 Altera® SoC FPGA 构建 Linux 系统流程 (Yocto Poky 篇)
本文主要介绍了 Altera® SoC FPGA 系统参考环境 (GSRD：黄金系统参考设计) 中使用的 Yocto Poky 参考 Linux 环境的构建过程。
Linux 的构建过程不需要 Altera® SoC FPGA 嵌入式开发套件 (SoC EDS)，因此您无需担心是否已安装 SoC EDS 或其版本。虽然 SoC EDS 的最新的正式版本是 v20.1 标准版和 v20.1 专业版，但即使使用的是早期版本的 SoC EDS，也依然可以使用此方法构建 Linux 环境。
有关官方构建说明，请参阅 Rocketboards.org 或 Altera® FPGA 开发人员网站 (altera-fpga.github.io) 上每个设备系列的 GSRD 页面。
Cyclone V SoC GSRD - Rebuilding the GSRD Binaries
Arria 10 SoC GSRD ‐ Building the GSRD
Stratix® 10 SX SoC Development Kit - Rebuild the GSRD
Agilex™ 7 F-Series SoC Development Kit - Rebuild the GSRD
Agilex™ 7 I-Series FPGA Development Kit - Build GSRD for XX
Agilex™ 7 M-Series HBM2e Development Kit - Build the GSRD
Agilex™ 5 E-Series Premium Development Kit - Rebuilding the GSRD
Agilex™ 5 E-Series Modular Development Kit - Rebuilding the GSRD
官方文档通常提供自动化脚本，简化了构建过程，因此需要阅读并理解这些脚本才能了解细节。本文不使用官方脚本，而是直接在终端中执行构建所需的命令。大家可以将本文作为理解 Yocto 构建流程的参考。
构建流程概览：
- 准备主机
- Yocto 环境配置 - 获取软件包配置 (仅限首次)
- 脚本执行和环境设置 (仅限首次)
- 运行构建 (bitbake)
- 检查构建结果
虽然本教程以 Agilex™ 5 为例进行说明，但其步骤和原理也适用于 Altera® SoC FPGA 器件系列 (Cyclone® V / Arria® V / Arria® 10 / Stratix® 10 / Agilex™ 7 / Agilex™ 5 / Agilex™ 3)。
准备主机
准备一台基于 Linux 的主机。您也可以在虚拟机上构建，但请注意至少需要 50GB 的可用磁盘空间。不过实际操作中建议准备100GB 以上空间，因为仅构建一种镜像就会耗尽 50GB 的可用空间。虽然内存要求未作说明，但经测试发现，8GB 可以保证构建过程流畅运行。
要准备主机，请从 Yocto 项目官方文档中列出的环境中选择一个 Linux 发行版。本文所述步骤已在 Ubuntu 20.04 (LTS) 和 Ubuntu 22.04 (LTS) 上验证过。
需注意，最新版本的 Yocto 似乎也兼容 Windows 子系统 Linux 版 (WSL)。但是，它似乎与 WSLv1 不兼容，因此如果想尝试使用 WSL，则必须在 WSLv2 中构建环境。官方文档也明确指出，使用 WSL 的步骤是非官方的。若尝试在 WSL 中构建环境，请自行承担风险。
以下是准备主机所需的步骤 (适用于 Ubuntu 20.04/22.04 (LTS))。
※ 注意：本文所述命令均假设在用户权限终端 (以 $ 开头的提示符) 下执行。请务必避免误用 root 权限终端 (以 # 开头的提示符)。
执行以下命令以更新和安装构建所需的软件包。这些软件包是构建镜像所需的最低软件包。
此外，请安装以下软件包。最后一个软件包“g++-multilib”在官方文档中未提及。它是为了解决之前使用 dunfell (Yocto 3.1.7) 构建时出现的错误而添加到说明中的。其他软件包的安装说明请参见 Yocto 官方文档。
对于 Ubuntu 20.04/22.04 (LTS)，至此主机机器的准备工作已完成。如果您使用的是其他发行版，请查看官方文档中的所需软件包。
另外，请注意以下每个软件包的版本，并确保它们满足您的要求。
- Git 1.8.3.1 或更高版本
- tar 1.28 或更高版本
- Python 3.6.0 或更高版本 (*Yocto 版本 4.2 (mickledore) 及更高版本需要 Python 3.8.0 或更高版本)
- GNU make 4.0 或更高版本 (*这是从 Yocto 版本 4.1 (langdale) 开始添加的要求)
- gcc 7.5 或更高版本 (*Yocto 版本 4.2 (mickledore) 及更高版本要求更改为 gcc 8.0 或更高版本)
※ 官方文档中还提供了针对未满足上述要求的发行版用户的安装指南，其中包含安装符合要求的工具版本的 buildtools，请根据需要参考。
设置 Yocto 环境——获取软件包配置 (仅限首次)
执行以下命令，将包含 Yocto 包 (构建工具) 和包含构建过程指令的配置文件 (.bbclass、.bb) 等的元数据层结构，提取到工作目录“poky-socfpga”下的 layers 目录中。工作目录“poky-socfpga”可以是任意名称。
以下是 Yocto 5.0.5 (scarthgap) 的示例：
※ git clone 命令的 -b 选项中指定的分支名称是 Yocto 版本名称 (例如 nanbield、kirkstone、dunfell 等)。如果要指定最新版本，请使用 -b master (在上面的示例中，可以通过更改 export 中设置的环境变量 YOCTO_VER 来实现)。
重要提示：名为 meta-xxxx 的文件夹用于存储配置，这些文件夹被称为元层。每个元层都包含一个名为 conf/layer.conf 的配置文件，其中包含有关该层的信息。layer.conf 文件以 LAYERSERIES_COMPAT_meta-xxxx 的格式指定该层支持的 Yocto 版本。因此，如果您使用的是不同的 Yocto 版本，则必须注意 layer.conf 的内容。
例如，meta-intel-fpga 层可能有一个类似“LAYERSERIES_COMPAT_meta-intel-fpga = "master honister"”的设置，这意味着该层支持 master (最新版本) 和 honister (Yocto 3.4)。支持多个 Yocto 版本的层也可能列出多个不同的版本，例如“LAYERSERIES_COMPAT_meta-intel-fpga = "dunfell gatesgarth hardknott"”。
脚本执行和环境设置 (仅限首次)
请注意：Yocto从 3.3 版本 (hardknott) 切换到 3.4 版本 (honister) 时，构建所需的配置文件 (配方) 格式发生了部分变化。因此，受此变化影响的某些步骤将以两种方式描述：“Yocto 版本 3.4 (honister) 及更高版本”和“3.3.x (hardknott) 及更早版本”。
以下是 Yocto 的版本和状态信息列表 (截至 2024 年 12 月)：
版本 | 代号 | 状态/附加信息 |
5.2 | walnascar | 开发中 |
5.1 | styhead | 当前版本（稳定版） |
5.0 | scarthgap | 当前版本（长期支持版本，有效期至 2028 年 4 月）/ 用于最新版 GSRD |
4.3 | nanbield | 先前版本（EOL） |
4.2 | mickledore | 先前版本（EOL） |
4.1 | langdale | 先前版本（EOL） |
4.0 | kirkstone | 当前版本（长期支持至 2026 年 4 月） |
3.1 | dunfell | 当前版本（长期支持至 2024 年 4 月） |
有关 Yocto 以及如何自定义环境的更多信息，请参阅 Yocto 官方文档：
Yocto Project – It's not an embedded Linux distribution – it creates a custom one for you
Welcome to the Yocto Project Documentation — The Yocto Project ® documentation
Supported Release Manuals — The Yocto Project ® documentation
Outdated Release Manuals — The Yocto Project ® documentation
Linux 构建设置 (所有设备系列通用)
执行以下命令来设置构建环境。
首先，运行位于 poky 目录下的名为 oe-init-build-env 的设置脚本。运行此脚本将设置构建所需的环境变量，并将当前目录移动到 poky-socfpga/build 目录。同时，将在 build/conf 目录下生成名为 bblayers.conf 和 local.conf 的配置文件。
使用以下命令重写 build/conf/bblayers.conf 中的设置。
在这里，我们添加了将 poky 以外获取的层结构 (meta-intel-fpga、meta-intel-fpga-refdes、meta-openembedded/meta-xxxx) 纳入到构建对象中的设置。
使用以下命令重写 build/conf/local.conf 中的设置。local.conf 文件包含各种变量，用于指定各种构建选项。
※ 注意：以下针对 Yocto 3.4 (honister) 及更高版本的说明，是以 Yocto 4.3 (nanbield) 为目标编写的。meta-intel-fpga 中包含的配方会根据您指定的 Yocto 版本 (分支) 而有所不同，因此可以指定的 Linux 版本和引导加载程序版本也会有所不同。
对于新环境：Yocto 3.4 (honister) 及更高版本
对于旧版环境：Yocto 3.3.x (hardknott) 及更早版本
这里主要规定了以下内容：
・MACHINE：指定要构建的目标机型 (对于 SoC FPGA，请从 cyclone5 / arria5 / arria10 / stratix10 / agilex 中选择)。
* 如果您的目标机型是 4.1 版本 (langdale) 或更高版本的 agilex，则需要从多个选项中选择并指定机型。
[适用于4.1版本 (langdale)]
- agilex_fm61 ... Intel Agilex® 7 FPGA F-Series Transceiver-SoC Development Kit (P-Tile and E-Tile)
- agilex_fm86 ... Intel Agilex® 7 FPGA F-Series Development Kit (2x F-Tile)
- agilex_fm87 ... Intel Agilex® 7 FPGA I-Series Transceiver-SoC Development Kit (4x F-Tile)
[适用于4.2及以上版本(mickledore)]
- agilex7_dk_si_agf014ea/agf014eb ... Intel Agilex® 7 FPGA F-Series Transceiver-SoC Development Kit (P-Tile and E-Tile)
- agilex7_dk_si_agi027fa/agi027fb ... Intel Agilex® 7 FPGA I-Series Transceiver-SoC Development Kit (4x F-Tile)
- agilex7_dk_dev_agf027f1es ... Intel Agilex® 7 FPGA F-Series Development Kit (2x F-Tile)
- agilex7_dv_dev_agm039fes ... Intel Agilex® 7 FPGA M-Series Development Kit - HBM2e Edition (3x F-Tile & 1x R-Tile)
※ 自 5.0.5 版本 (scarthgap) 起，agilex5 的选项数量有所增加。指定 MACHINE 时，请参考以下信息。请注意，如果您使用 Yocto 以外的流程构建引导加载程序和 Linux，则无需指定目标板的详细信息。至于根文件系统，只要设备系列正确，就可以将其用于其他板。
MACHINE 可指定的字符串由 meta-intel-fpga 层中 conf/machine 目录下的文件名决定。具体内容请参阅以下链接，也可以使用如下图 (图2) 所示页面右上角的下拉菜单和切换按钮选择 Yocto 版本。
- PREFERRED_PROVIDER_virtual/kernel, PREFERRED_VERSION_linux-socfpga-lts：指定 Linux 内核版本 (从 meta-intel-fpga/recipes-kernel 下的配方中选择要构建的内核版本)。
- DISTRO_FEATURES:append，VIRTUAL-RUNTIME_init_manager：指定使用“systemd”进行 Linux 启动和系统管理。
- IMAGE_FSTYPES：指定要生成的文件系统的格式。
※ 注意：在 3-1-1 版本新环境的配置过程中，通过在 local.conf 文件中指定“IMAGE_FSTYPES:remove = "multiubi"”不会生成 UBIFS 文件系统。此更改旨在防止生成的镜像文件较大时，UBIFS 超出大小限制而导致的错误。因此，如果您需要生成 UBIFS 文件系统，请删除相应的语句。
以下选项用于整理工作目录下的配置结构 (可选)：
- DL_DIR：指定构建执行时获取 (下载) 的文件的存储位置。
- DEPLOY_DIR：指定构建执行后生成的映像的存储位置。
其他选项同样非必需内容，如有疑问请查阅 Yocto 官方文档。
高级设置：引导加载程序构建设置 (V 系列可选，其他系列必需)
当目标平台为 Arria® 10、Stratix® 10、Agilex™ 7 或 Agilex™ 5 时，还需要进行以下设置。当目标平台为 V 系列并使用 Yocto 构建引导加载程序时，也需要进行此设置。
所需的设置因启动流程而异。如果目标平台是 V 系列或 Arria® 10，则只需要 U-Boot 设置。对于 Stratix® 10、Agile™® 7 或 Agilex™ 5，除了 U-Boot 设置外，还需要指定 Arm Trusted Firmware (ATF) 版本。这里，我们将为所有系列指定 U-Boot 和 ATF 的版本。请注意，如果命令中指定了设备系列 (例如“require conf/machine/agilex5-*.conf”)，请根据您使用的目标平台将其替换为 cyclone5 或 arria10。
对于新环境：Yocto 3.4 (honister) 及更高版本 (U-Boot 和 ATF 配置)
截至 2024 年 2 月，如果您使用的是 Yocto 4.3 (nanbield) 并且目标平台是 Arria® 10 或 Stratix® 10，请同时配置以下内容：
如果您使用的是 Yocto 4.1 (langdale) 或 Yocto 4.2 (mickledore) 并且目标平台是 Cyclone® V，请同时配置以下内容：
此设置 (RBO_RELEASE_VER)指定 Rocketboards.org 发布站点上 rbf-source 文件夹的位置。指定“2022.10”将使用位于 /2022.10/rbf-source/ (rocketboards.org) 的 FPGA 配置数据 (.rbf) 。
*Yocto 4.3 (nanbield) 不需要此设置。
对于旧环境：Yocto 3.3.x (hardknott) 及更早版本 (U-Boot 和 ATF 配置)
这里主要规定了以下内容：
- PREFERRED_PROVIDER_virtual/bootloader, PREFERRED_VERSION_u-boot-socfpga：指定 U-Boot 版本 (从 meta-intel-fpga/recipes-bsp/u-boot 下的配置中选择要构建的 U-Boot 版本)。
- PREFERRED_VERSION_arm-trusted-firmware：指定 ATF 版本 (从 meta-intel-fpga/recipes-bsp/arm-trusted-firmware 下的配置中选择要构建的 ATF 版本)。
- require conf/machine/xxxx-extra.conf (xxxx-gsrd.conf)：指定包含引导加载程序相关设置的扩展配置文件。
- UBOOT_CONFIG：用于在构建 U-Boot 时选择默认配置。(可选配置项包括“agilex7_dk_si_agf014ea-socdk-atf”、“stratix10-socdk-atf”、“arria10-socdk”和“cyclone5-socdk”。其他选项请参见配方说明。)
- IMAGE_TYPE：对于评估板的参考设计 (Golden System Reference Design)，请指定“gsrd”。(通常情况下，请指定“gsrd”。如果目标设计是其他类型，则可能需要指定“gsrd”以外的其他值。)
运行构建 (bitbake)
Yocto 使用名为 bitbake 的工具来运行构建。构建过程首先在上一步运行 setup 脚本的终端中运行 bitbake 命令。如果您启动一个新的终端并想在之前构建的 Yocto 环境中再次运行构建，请务必事先运行 setup 脚本 (poky/oe-init-build-env)。
如果要更改选项或配方，请在运行设置脚本后，在运行 bitbake 之前，用文本编辑器编辑 build/conf/local.conf 和 layers 下的文件。
在“<指定目标镜像>”部分，根据构建目标指定以下内容：
- U-Boot...... virtual/bootloader
- Linux 内核.......... virtual/kernel
- Linux 根文件系统…… gsrd-console-image、console-image-minimal 等 (请从 recipes-images 下的 recipes 中选择)。
您还可以按如下方式指定多个值：
构建 Linux 根文件系统时，您还需要 Linux 内核，因此无需指定 virtual/kernel。(Linux 内核也会自动构建。)
接下来只需等待构建完成。根据机器配置和网络速度，构建整个 GSRD 环境 (包括 Linux 根文件系统) 可能需要三个多小时。如果出现错误，请使用终端中的消息和日志文件来查找原因，消息会指示要参考的日志文件。解决问题后，再次运行 bitbake。
如果构建过程顺利完成，则以“NOTE: Tasks Summary:”开头的消息将显示“all succeeded. ”，如下图 (图3) 所示：
检查构建结果
如果构建成功，镜像文件将生成在以下位置：(请根据目标设备将下面的 agilex5 替换为 arria5 或 cyclone5。)
/poky-socfpga/deploy/images/agilex5/
所需文件如下：
Root Filesystem
gsrd-console-image-agilex5.rootfs.tar.gz ... 还会生成一个 jffs2 格式的文件
gsrd-console-image-agilex5.rootfs.manifest ... 根文件系统中包含的软件包列表
Linux Kernel
Image, Image.lzma ... 其他设备系列可能使用不同的格式，例如 zImage
Linux Module格式驱动程序 (.ko) 将以以下名称归档并输出：
modules-agilex5.tgz
Linux 设备树 (.dtb)
socfpga_agilex5_socdk.dtb 等
Linux FIT (Flattened uImage Tree) Image (仅当使用基于 FIT 镜像的启动方法时才需要)
kernel.itb；将内核和设备树合并到单个文件中的镜像
Linux 启动选项文件 (仅当使用 extlinux 兼容的启动加载程序时才需要)
extlinux.conf
剩下的工作就是基于上述镜像文件创建启动 SD 卡镜像。有关创建 SD 卡镜像的信息，请参阅以下页面：
Creating and Updating SD Card
如何为 SoC FPGA 启动创建 SD 卡镜像
总结
按照本文所述的步骤，您可以成功地构建出与 GSRD 等效的 Linux 镜像。构建原始环境时，了解如何自定义 Yocto 环境至关重要，详情请参阅 Yocto 官方文档。
欲了解关于更多 Altera 相关方案或技术信息，请与骏龙科技当地的办事处联系或点击下方「联系我们」，提交您的需求，骏龙科技公司愿意为您提供更详细的技术解答。
更多信息：
相关链接
Copyright 2026 Macnica Cytech Limited
