📚 课程目录第3章开发环境搭建

3. 开发环境搭建

UEFI固件开发与普通应用开发最大的差异在于：代码运行在平台初始化早期，没有操作系统、没有标准C库、没有调试器可直接附加。因此，开发环境搭建不是“装个IDE”那么简单，而是要把源码、工具链、模拟器、真实平台调试通道四件事串成一条可复现的链路。本节按这条链路展开，先讲EDK II源码获取与目录认知，再讲编译工具链配置，最后讲模拟器与真实平台的调试环境搭建方法。

一、核心原理：EDK II的构建模型

EDK II采用“包（Package）+ 模块（Module）+ 平台描述（DSC/FDF/INF）”的构建模型。源码树中每个Package包含若干Module，Module由INF描述其源文件、依赖库和编译选项；平台由DSC描述组件集合与库实例，由FDF描述固件卷布局。构建时，build工具读取DSC/FDF，调用底层编译器和链接器，最终生成.efi、.fd等产物。理解这一点，才能明白为什么“换一个平台”往往只需要换DSC/FDF，而不是重写代码。

二、EDK II源码获取与目录认知

EDK II源码由多个仓库组成，核心是edk2，平台相关代码在edk2-platforms，非开源硬件描述在edk2-non-osi。推荐使用Git递归克隆，并固定到某个稳定Tag，避免上游变动导致构建失败。

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

# 平台仓库
git clone https://github.com/tianocore/edk2-platforms.git
git clone https://github.com/tianocore/edk2-non-osi.git

源码树中需要重点关注的目录：MdePkg提供基础库与协议定义，MdeModulePkg提供通用驱动，BaseTools是构建工具，OvmfPkg是QEMU虚拟平台，EmulatorPkg是宿主模拟器。首次构建前必须先编译BaseTools，否则build命令不可用。

# Linux 下编译 BaseTools
make -C BaseTools
source edksetup.sh

建议把edksetup.sh的source写进开发容器的启动脚本，保证每次进入环境时WORKSPACE、PACKAGES_PATH、EDK_TOOLS_PATH都已正确设置。

三、编译工具链配置

EDK II支持GCC、Clang、Visual Studio等工具链。Linux下最常用的是GCC，需要安装gcc、nasm、iasl、python3、uuid-dev等依赖。工具链配置集中在Conf/target.txt，关键参数如下表。

参数	含义	示例值
ACTIVE_PLATFORM	目标平台DSC文件	OvmfPkg/OvmfPkgX64.dsc
TARGET	构建目标类型	DEBUG / RELEASE
TARGET_ARCH	目标架构	X64 / AARCH64 / IA32
TOOL_CHAIN_TAG	工具链标识	GCC5 / CLANGDWARF
MAX_CONCURRENT_THREAD_NUMBER	并行编译线程数	8

配置完成后，用一条命令即可构建OVMF：

build -a X64 -t GCC5 -p OvmfPkg/OvmfPkgX64.dsc -b DEBUG

常见误区：直接修改target.txt后忘记source edksetup.sh，导致环境变量未刷新；或在Windows下使用GCC却未安装nasm，构建在汇编阶段报错。建议先用build -h确认工具链可用。

四、模拟器与真实平台调试环境

模拟器调试是最高效的入门方式。以QEMU+OVMF为例，构建出OVMF.fd后，用QEMU加载并开启GDB端口：

qemu-system-x86_64 -bios Build/OvmfX64/DEBUG_GCC5/FV/OVMF.fd \
  -serial mon:stdio -s -S -m 1024

另开终端用GDB连接localhost:1234，即可对固件进行源码级单步。EmulatorPkg则把固件编译成宿主可执行文件，直接在Linux/Windows上运行，适合验证驱动逻辑而不依赖QEMU。

真实平台调试依赖两条通道：一是串口日志，通过DebugLib输出到UART，是最基础的排障手段；二是硬件调试器，如JTAG/OCD配合SourceLevelDebugPkg，可实现断点、单步和寄存器查看。真实平台调试前，务必确认串口波特率、引脚复用和调试器时钟配置正确，否则会出现“有日志但无断点”或“断点命中但变量错乱”的现象。

推荐工作流：先在EmulatorPkg中验证驱动逻辑，再在QEMU+OVMF中验证启动流程，最后在真实平台上验证硬件交互。三层递进，能把问题定位范围逐层缩小。

五、复盘：环境搭建的常见坑

源码版本不匹配：edk2与edk2-platforms的Tag不一致，导致DSC引用路径失效。应统一使用同一稳定版本。
BaseTools未编译：直接执行build报“command not found”，先make -C BaseTools。
工具链路径未加入PATH：GCC交叉编译器未导出，构建时找不到aarch64-linux-gnu-gcc。
调试符号缺失：RELEASE构建默认不含调试信息，GDB无法映射源码，调试应使用DEBUG构建。
串口无输出：检查PcdDebugPrintErrorLevel和串口初始化顺序，早期PEI阶段可能尚未初始化UART。