走进 EDK II：UEFI/PI 固件开发环境、CI 矩阵与协作规范完全指南

• 固件
• 操作系统
• 驱动开发
• 嵌入式

导读：本文以仓库根目录 ReadMe.rst 为骨架，系统拆解 EDK II 这一现代、功能丰富、跨平台的 UEFI/PI 固件开发环境——从项目定位与许可证体系、Python 工具链前置要求，到覆盖 Windows/Ubuntu 多工具链的 CI 矩阵、平台级固件构建流程（OvmfPkg/EmulatorPkg/ArmVirtPkg），再到子模块管理、代码贡献与 DCO 签署规范。读完本文，你将掌握该仓库的获取与初始化方法、CI 状态图的解读方式、基于 Pytools（stuart）的本地构建工作流，以及向 TianoCore 社区提交补丁的完整礼仪。

一、项目定位：为 UEFI 与 PI 规范而生的现代固件开发环境

ReadMe.rst 开篇将 EDK II 定义为"a modern, feature-rich, cross-platform firmware development environment for the UEFI and PI specifications from www.uefi.org"——即一个面向 UEFI（Unified Extensible Firmware Interface，统一可扩展固件接口）与 PI（Platform Initialization，平台初始化）规范的现代、功能丰富、跨平台固件开发环境。

从仓库目录结构可以直观印证其"跨平台"与"包（Package）化"的组织思路：顶层按功能域划分为数十个 Package，例如：

• MdePkg / MdeModulePkg：UEFI/PI 核心库与模块实现，是整个体系的地基（MdePkg/Include下包含 600+ 头文件，MdePkg/Library下包含 1200+ 文件，覆盖各架构汇编与 C 实现）；
• ArmPkg / ArmPlatformPkg / ArmVirtPkg：面向 ARM 架构与虚拟化平台（QEMU、KVMTOOL、CloudHv、Xen）的支持；
• OvmfPkg：面向 QEMU 虚拟机的开放虚拟固件（OVMF），支持 X64 与 IA32X64 等多种配置；
• EmulatorPkg：可在 Windows/Linux 桌面上以本地进程模拟方式运行的固件环境，适合无硬件调试；
• CryptoPkg / SecurityPkg / NetworkPkg / UefiCpuPkg等：分别承载密码学、安全启动与 TPM、网络协议栈、CPU 初始化等专项能力。

这种"按 Package 组织、以.dec描述包、以.dsc定义构建、以.inf描述模块"的结构，是 EDK II 区别于普通嵌入式工程的显著特征，也是后续所有构建与 CI 流程的基础。

二、环境前置：Python 版本要求与 Pytools 生态

2.1 官方建议的 Python 最低版本

ReadMe.rst 在简介后立即给出一个醒目的徽章信息：CI Minimum Python Version（由edk2-pytool-extensions仓库的pyproject.toml动态解析得出）。它明确说明：

It is recommended to install this Python version to run the full set of scripts that enable CI in the project.

也就是说，要在本地完整运行仓库中的 CI 脚本，需要安装符合该最低版本要求的 Python。其他构建期 Python 依赖，ReadMe 指引读者查看官方"EDK II Build Instructions"中的工具清单。

2.2 pip-requirements.txt：CI 运行的核心 Python 依赖

与 ReadMe 呼应，仓库根目录的 pip-requirements.txt 精确列出了 CI/构建所依赖的 Python 组件：

edk2-pytool-library~=0.23.16 edk2-pytool-extensions~=0.31.1 antlr4-python3-runtime==4.13.2 lcov-cobertura==2.1.1 regex==2026.7.19 pefile

其中最关键的是两个 TianoCore 官方维护的 PIP 模块：

• edk2-pytool-library：提供底层库能力；
• edk2-pytool-extensions：提供stuart_setup、stuart_update、stuart_ci_build、stuart_build等命令行工具（统称 Pytools）。

从 .pytool/Readme.md 可以看到，这套 CI 与测试基础设施正是构建在这两个模块之上的。安装命令为：

pip install --upgrade -r pip-requirements.txt

建议在 Python 虚拟环境中安装，避免污染系统环境。

三、CI 构建状态矩阵：读懂仓库的"健康仪表盘"

ReadMe.rst 用两张状态表格展示项目的持续集成情况：一张是核心 CI（Core CI）构建状态，一张是平台 CI（Platform CI）构建状态。这些状态图由 Azure DevOps 徽章动态渲染，直接反映了 master 分支各工具链组合下的实时构建/测试/覆盖率情况。

3.1 Core CI：五条工具链组合

其中覆盖率一列当前统一标注为 "coming_soon"（即将推出），表明代码覆盖率统计仍在建设阶段；构建与测试徽章则实时反映最新流水线结果。更多底层 CI 细节见 .pytool/Readme.md。

3.2 Platform CI：三大参考平台 × 多种工具链

平台 CI 面向三个真实可运行的平台固件，分别对应 DEBUG / RELEASE / NOOPT 三种构建目标，以及 X64 / AARCH64 架构：

一个值得注意的已知问题（ReadMe 以特殊标记列出）：TCBZ_2639 —— EmulatorPkg 在 Ubuntu GCC 下执行时存在段错误（Segfaults），对应 issue 编号 9905。这说明即便是参考平台，在特定工具链组合下也可能存在已知缺陷，社区正在跟踪处理。

每个平台包都提供了更详细的平台 CI 说明文档，可在仓库内直接查阅：

• ArmVirtPkg/PlatformCI/ReadMe.md
• EmulatorPkg/PlatformCI/ReadMe.md
• OvmfPkg/PlatformCI/ReadMe.md

3.3 各 Package 的 CI 覆盖情况（来自 .pytool/Readme.md）

.pytool/Readme.md 的"Basic Status"表进一步细化到每个 Package 在 Windows VS2026（IA32/X64）与 Ubuntu GCC（IA32/X64/AARCH64）两条核心流水线上的覆盖情况。概括如下：

• 双平台全覆盖：CryptoPkg、DynamicTablesPkg、FatPkg、FmpDevicePkg、MdeModulePkg、MdePkg、NetworkPkg、PcAtChipsetPkg、SecurityPkg、ShellPkg、StandaloneMmPkg、UefiCpuPkg、UnitTestFrameworkPkg 等均已在 Windows 与 Ubuntu 双流水线启用 CI；
• 平台包走独立流程：ArmVirtPkg、EmulatorPkg、OvmfPkg 属于平台级构建，其 CI 定义见各自 Package 内的 PlatformCI 目录（即上文 3.2 的平台矩阵）；
• 部分包尚未接入：EmbeddedPkg、IntelFsp2Pkg、IntelFsp2WrapperPkg、SourceLevelDebugPkg、UefiPayloadPkg 在表中未标记为双流水线启用；
• 已知限制：MdeModulePkg 的 DxeIpl 依赖 ArmPkg、整体依赖 StandaloneMmPkg；ShellPkg 有 3 个模块未通过 DSC 构建；UefiCpuPkg 有 2 个二进制模块未通过 DSC 构建；多个包（CryptoPkg、MdePkg、NetworkPkg、OvmfPkg、SecurityPkg、ShellPkg、UefiCpuPkg 等）的拼写检查以审计模式（audit mode）运行。

四、从 ReadMe 到实操：用 Pytools 搭建可复现的固件构建工作流

虽然 ReadMe.rst 本身只给出了概览，但其链接的.pytool/Readme.md与三个平台包的 PlatformCI ReadMe 共同构成了完整的本地构建实操路径。以 OvmfPkg/PlatformCI/ReadMe.md 为例，完整流程如下。

4.1 准备开发环境

• Git（版本控制）；
• QEMU（运行 OVMF 固件用，需加入 PATH；Windows 上需手动添加，不在安装器自动路径内）；
• EDK II 源码（即本仓库）；
• Ubuntu 额外依赖：apt-get install gcc g++ make uuid-dev。

关键点：使用 Pytools 后，手动执行 edksetup、初始化子模块、手工安装 NASM/iASL 或交叉编译工具链都不是必须的——这些都由 Pytools 构建系统自动处理。

4.2 构建命令序列（OvmfPkg 示例）

# 1. [可选] 创建 Python 虚拟环境（一般每个工作区一次） python -m venv <虚拟环境名> # 2. [可选] 激活虚拟环境（每次打开新 shell 执行） # Linux: source <虚拟环境名>/bin/activate # Windows: <虚拟环境名>/Scripts/activate.bat # 3. 安装 Pytools（虚拟环境创建后或 pip-requirements.txt 变更时） pip install --upgrade -r pip-requirements.txt # 4. 初始化并更新子模块（仅当子模块更新时） stuart_setup -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> # 5. 初始化并更新外部依赖（仅当 ext_deps 变更时） stuart_update -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> # 6. 必要时编译 BaseTools（仅当 BaseTools 的 C 源码变更时） python BaseTools/Edk2ToolsBuild.py -t <ToolChainTag> # 7. 编译固件（X64） stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> # 编译 IA32X64 混合固件（PEI-IA32、DXE-X64） stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py -a IA32,X64 TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> # 8. 构建完成后运行模拟器（二选一） stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashRom # 构建后立即启动 stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py TOOL_CHAIN_TAG=<TOOL_CHAIN_TAG> -a <TARGET_ARCH> --FlashOnly # 仅运行模拟器

实用提示：stuart_build -c ... -h可查看全部附加选项（如--clean）。

4.3 平台构建的自定义选项

以 OvmfPkg 为例，PlatformBuild.py 支持以下自定义构建选项：

• MAKE_STARTUP_NSH=TRUE：向 fs0 映射位置输出startup.nsh脚本。CI 中常与--FlashOnly配合，实现"启动 QEMU 进入 UEFI Shell 后自动执行脚本"的自动化测试；
• QEMU_HEADLESS=TRUE：CI 服务器通常无显示器，设置后 QEMU 以无显示模式运行，避免报错；本地开发无需设置。

4.4 通过BLD_*_前缀传递构建宏

使用 stuart_build 时，传统-D XXX的宏传递方式要改写为BLD_*_前缀形式，且 stuart_build 要求赋值（裸宏需追加=1）。例如启用 TPM2 支持（传统写法-D E1000_ENABLE）应写为：

stuart_build -c OvmfPkg/PlatformCI/PlatformBuild.py BLD_*_E1000_ENABLE=1

4.5 本地运行 CI 插件

.pytool/Readme.md 指出，默认所有 CI 插件均为启用状态，可通过插件名=skip跳过指定插件：

CompilerPlugin=skip # 跳过编译测试 GuidCheck=skip # 跳过 GUID 唯一性检查 SpellCheck=skip # 跳过拼写检查

每个 Package 的详细报告与日志生成在Build目录下。CI 配置按优先级依次来自：命令行参数 → 包级配置文件（<包名>.ci.yaml，例如各包根目录下的MdePkg.ci.yaml、OvmfPkg.ci.yaml）→ 全局配置模块（.pytool/CISettings.py）。

4.6 了解 CI 测试插件能力矩阵

仓库.pytool/Plugin目录实际存放了全套 CI 插件，包括：CharEncodingCheck（非法字符检查）、CompilerPlugin（编译测试）、DependencyCheck（跨包依赖检查）、DscCompleteCheck（模块包含性检查）、EccCheck（EDK II 编码规范）、GuidCheck（GUID 唯一性）、HostUnitTestCompilerPlugin、HostUnitTestDscCompleteCheck（主机单元测试）、LibraryClassCheck（库类声明检查）、LicenseCheck（许可证检查）、MarkdownLintCheck、SpellCheck（cspell 拼写检查）与 UncrustifyCheck（代码格式合规）。这些插件构成了 EDK II 质量保障的多层防线。

五、许可证体系：BSD-2-Clause-Patent 与多许可证组件

5.1 主许可证

ReadMe.rst 明确指出，EDK II 开源项目的绝大部分内容采用BSD-2-Clause Plus Patent License（BSD 双条款 + 专利授权），见 License.txt。该许可证在标准 BSD-2-Clause 文本之外，额外授予与贡献相关的专利许可，兼顾了开源共享与专利保护。

5.2 采用附加许可证的组件（仓库内可验证）

ReadMe 逐项列出了仓库中采用其他许可证的组件：

5.3 以 git 子模块引入的上游项目及其许可证

EDK II 通过 git 子模块方式引入多个上游项目，这些项目使用各自独立的许可证，与本仓库主许可证无关：

• brotli（BaseTools/Source/C/BrotliCompress/brotli、MdeModulePkg/Library/BrotliCustomDecompressLib/brotli）：压缩算法；
• openssl（CryptoPkg/Library/OpensslLib/openssl）：密码学库；
• mbedtls（CryptoPkg/Library/MbedTlsLib/mbedtls）：轻量密码学库；
• oniguruma（MdeModulePkg/Universal/RegularExpressionDxe/oniguruma）：正则表达式引擎；
• cmocka（UnitTestFrameworkPkg/Library/CmockaLib/cmocka）与googletest（UnitTestFrameworkPkg/Library/GoogleTestLib/googletest）、subhook：单元测试与钩子框架；
• jansson（RedfishPkg/Library/JsonLib/jansson）：JSON 库；
• libfdt（MdePkg/Library/BaseFdtLib/libfdt）：扁平设备树库；
• mipisyst（MdePkg/Library/MipiSysTLib/mipisyst）：MIPI Sys-T 库；
• libspdm（SecurityPkg/DeviceSecurity/SpdmLib/libspdm）：SPDM 设备安全协议实现；
• TPM（TcgTpmPkg/Library/TpmLib/TPM）：TPM 参考实现。

这些子模块的完整清单与远端地址记录在仓库根目录的 .gitmodules 中，是理解 EDK II 供应链构成的第一手资料。

六、子模块管理：克隆与更新的标准姿势

6.1 获取完整可构建的仓库

ReadMe.rst 给出了标准克隆流程（注意：ReadMe 中使用的是 tianocore 官方地址，本镜像仓库同样适用如下操作逻辑）：

git clone https://github.com/tianocore/edk2.git cd edk2 git submodule update --init cd ..

6.2 子模块更新流程

当上游子模块有更新时：

cd edk2 git pull git submodule update

6.3 关键注意事项：不要使用--recursive

ReadMe 特别强调：克隆子模块仓库时，不推荐使用--recursive选项。理由有二：

1. EDK II 本身不会使用列出的子模块内部再嵌套的任何代码或功能；
2. 使用--recursive会引入对"我们并不需要其代码"的服务器的可达性依赖，并白白下载用不到的代码。

这一约定能显著减少克隆体积与网络依赖，值得所有 EDK II 使用者遵守。

七、Package 维护者体系：Maintainers.txt 的读取方式

ReadMe 指出：EDK II 项目由若干 Package 组成，每个 Package 的维护者（maintainer）名单记录在 Maintainers.txt 中。该文件采用类 Linux 内核的get_maintainer格式，核心字段含义如下：

• L：相关邮件列表（默认edk2-devel），补丁与问题应发送至此；
• M：Package 维护者，负责评审与推送包变更；
• R：Package 评审者，协助维护者评审代码，但无推送权限；
• W：状态/信息网页；
• T：SCM 树类型与位置（git/svn）；
• S：状态——Supported（有人专职维护）、Maintained（有人维护）、Odd Fixes（维护者时间有限）、Obsolete（已废弃）；
• F：受维护的文件/目录通配符（F: MdeModulePkg/表示含子目录的全部文件；F: MdeModulePkg/*仅顶层；F: */Pci/*任意深度的 Pci 目录）；
• X：明确不受维护的排除规则，后于 F 规则测试。

顶层还列出了 Tianocore Stewards（TianoCore 管家）名单，以及两个当前"需要额外维护者"的包：NetworkPkg与SecurityPkg——这也是社区招募贡献者的活跃信号。

八、代码贡献规范：从提交信息到 DCO 签署

8.1 贡献流程四步走

ReadMe.rst 规定，向 TianoCore 项目贡献代码需遵循：

1. 按下方规定格式撰写变更描述（change description），用于提交日志；
2. 提交信息必须包含Signed-off-by签名；
3. 通过项目网页上记载的流程提交代码；若流程未记载，则提交到项目开发邮件列表；
4. 优先采用与主项目一致的版权许可证提交；若无法一致，可接受以下许可：Apache License 2.0、BSD（2-clause）、BSD（3-clause）、MIT、Python-2.0、Zlib；文档类贡献接受 FreeBSD Documentation License；进入公有领域的代码也可接受；其他许可证可能被接受但需要进一步评审。

8.2 Developer Certificate of Origin（DCO）1.1

所有补丁必须包含Signed-off-by行，以证明贡献者拥有按指定许可证提交的合法权利。DCO 1.1 的核心认证内容为（全文见 ReadMe 原文）：

• (a) 贡献全部或部分由本人创作，且本人有权按开源许可证提交；
• (b) 贡献基于本人所知处于适当开源许可证下的既有成果，本人有权在相同许可证下提交（含修改）；
• (c) 贡献由其他已认证 (a)/(b)/(c) 的人直接提供，且本人未作修改；
• (d) 本人理解并同意项目与贡献是公开的，记录（含提交的全部个人信息）将长期保留，并可按本项目或所涉开源许可证的规定再分发。

8.3 提交信息格式模板与字段定义

ReadMe 给出了标准提交信息样例：

From: Contributor Name <contributor@example.com> Subject: [Repository/Branch PATCH] Pkg-Module: Brief-single-line-summary Full-commit-message Signed-off-by: Contributor Name <contributor@example.com>

各字段定义：

• Repository：补丁所适用仓库的标识，仅当非edk2时提供，例如edk2-BuildSpecification或staging；
• Branch：补丁所适用分支标识，仅当非edk2/master时提供，例如edk2/UDK2015、edk2-BuildSpecification/release/1.27、staging/edk2-test；
• Module：受影响代码/文档的短标识，例如MdePkg、MdeModulePkg/UsbBusDxe、Introduction或EDK II INF File Format；
• Brief-single-line-summary：变更的简短摘要，整个首行应少于约 70 个字符；
• Full-commit-message：详述变更的多行说明，每行也应少于约 70 个字符；
• Signed-off-by：贡献者的真实/法定姓名与邮箱签名。

格式说明：提交信息首行取自邮件主题中[Repository/Branch PATCH]之后的部分，其余内容取自邮件正文；git format-patch是生成该格式的一种方式。

九、资源与社区入口

ReadMe 的 Resources 一节列出了与 EDK II 相关的官方资源入口（以下均为项目官方公开资源，读者可据此深入了解）：

• TianoCore社区主页；
• EDK II 官方 Wiki：涵盖规范、教程与工具链说明；
• Getting Started with EDK II：新手入门教程；
• Mailing Lists：开发者邮件列表（补丁与讨论的主要渠道）；
• How To Contribute：贡献指南；
• Release Planning：版本规划与路线图。

十、快速自检清单：使用本仓库前请确认

1. Python 环境：已安装满足 CI 最低版本要求的 Python，并已pip install --upgrade -r pip-requirements.txt；
2. 子模块：已执行git submodule update --init（切勿加--recursive）；
3. 工具链：已按目标平台准备 GCC / VS / CLANGPDB / CLANGDWARF 中的相应工具链，平台模拟类构建（OvmfPkg/EmulatorPkg）还需将 QEMU 加入 PATH；
4. 构建方式：优先使用 Pytools 工作流（stuart_setup→stuart_update→stuart_build），而非手工 edksetup + NASM/iASL 安装；
5. 贡献礼仪：提交信息含Signed-off-by、遵循 DCO 1.1、标题行与正文行控制在 70 字符内、首行采用Pkg-Module: Brief-summary格式；
6. 已知问题：留意 ReadMe 标记的已知缺陷（如 EmulatorPkg 在 Ubuntu GCC 下的段错误 TCBZ_2639），避开不稳定的工具链组合。

通过以上六个维度的梳理，你已具备从"看懂 EDK II 仓库"到"本地构建固件"再到"参与社区贡献"的完整知识链路；任何一步的细节，都可以沿着文中给出的仓库内文档路径（.pytool/Readme.md、三个平台的 PlatformCI ReadMe、Maintainers.txt、.gitmodules、License.txt等）继续深入。

• 固件
• 操作系统
• 驱动开发
• 嵌入式