4. UEFI 工程结构解析

UEFI 固件开发的核心是 EDK2（EFI Development Kit II）框架。理解其工程结构是进行模块开发与平台移植的基础。本章将深入剖析 EDK2 的目录布局、三大核心描述文件（.dsc、.dec、.fdf）以及 Package 与 Module 的层次关系。

4.1 EDK2 顶层目录结构

一个标准的 EDK2 工作区（Workspace）通常包含以下顶层目录。开发者需熟悉每个目录的职责，以便快速定位代码与配置文件。

4.2 Package 与 Module 的概念

EDK2 采用 Package（包） 和 Module（模块） 两层组织架构。Package 是逻辑上的功能集合，Module 是具体的可编译单元。

• Package（.dec 文件定义）：包含一组相关的 Module、Library、Protocol、PPI 和 GUID 声明。例如 MdePkg 是一个 Package，它定义了所有 UEFI 规范中的基础类型。
• Module（.inf 文件定义）：一个独立的可编译单元，可以是驱动（DXE/SMM/UEFI Driver）、应用程序（Shell App）或库（Library Instance）。每个 Module 必须有一个 .inf 文件描述其源文件、依赖和编译选项。

4.3 三大核心描述文件详解

EDK2 的构建系统依赖三个关键描述文件：.dsc（平台描述）、.dec（包声明）、.fdf（固件描述）。它们共同决定了固件的组成、布局和编译方式。

4.3.1 .dec 文件（Package Declaration File）

.dec 文件定义了一个 Package 对外提供的接口，包括 GUID、Protocol、PPI、PCD 和 Library Class。它是 Package 的“头文件索引”。

# MdePkg/MdePkg.dec 示例片段
[Defines]
  DEC_SPECIFICATION              = 0x00010005
  PACKAGE_NAME                   = MdePkg
  PACKAGE_GUID                   = 1E73767F-8A52-4b2c-BF0C-DB83E8E2B7B1
  PACKAGE_VERSION                = 1.08

[Includes]
  Include                        # 公共头文件路径

[LibraryClasses]
  BaseLib|Include/Library/BaseLib.h
  UefiLib|Include/Library/UefiLib.h

[Guids]
  gEfiGlobalVariableGuid         = {0x8BE4DF61, 0x93CA, 0x11d2, {0xAA, 0x0D, 0x00, 0xE0, 0x98, 0x03, 0x2B, 0x8C}}

[Protocols]
  gEfiSimpleTextInProtocolGuid   = {0x387477C1, 0x69C7, 0x11d2, {0x8E, 0x39, 0x00, 0xA0, 0xC9, 0x69, 0x72, 0x3B}}

4.3.2 .inf 文件（Module Information File）

每个 Module 必须有一个 .inf 文件，描述其源文件、依赖的 Library、定义的 GUID 以及编译选项。

# MdeModulePkg/Universal/DiskIoDxe/DiskIoDxe.inf 示例
[Defines]
  INF_VERSION                    = 0x00010005
  BASE_NAME                      = DiskIoDxe
  FILE_GUID                      = 6B38F7B4-AD98-4e3f-BD30-5DEEC0B2E5C0
  MODULE_TYPE                    = UEFI_DRIVER
  ENTRY_POINT                    = DiskIoDriverEntryPoint

[Sources]
  DiskIo.c
  DiskIo.h

[Packages]
  MdePkg/MdePkg.dec
  MdeModulePkg/MdeModulePkg.dec

[LibraryClasses]
  UefiDriverEntryPoint
  UefiLib
  MemoryAllocationLib
  BaseLib

[Protocols]
  gEfiDiskIoProtocolGuid         ## PRODUCES
  gEfiBlockIoProtocolGuid        ## CONSUMES

4.3.3 .dsc 文件（Platform Description File）

.dsc 文件是整个平台固件的“构建清单”。它指定了要包含哪些模块、使用哪些库实例、PCD 默认值以及全局编译选项。

# OvmfPkg/OvmfPkgX64.dsc 示例片段
[Defines]
  PLATFORM_NAME                  = Ovmf
  PLATFORM_GUID                  = 5a9e7754-8270-4b8e-9b0f-9f3d5f7b9c1a
  PLATFORM_VERSION               = 0.1
  DSC_SPECIFICATION              = 0x00010005
  OUTPUT_DIRECTORY               = Build/OvmfX64
  SUPPORTED_ARCHITECTURES        = X64
  BUILD_TARGETS                  = DEBUG|RELEASE
  SKUID_IDENTIFIER               = DEFAULT

[LibraryClasses]
  BaseLib|MdePkg/Library/BaseLib/BaseLib.inf
  UefiLib|MdePkg/Library/UefiLib/UefiLib.inf
  # 平台特定库覆盖
  SerialPortLib|OvmfPkg/Library/SerialPortLib/SerialPortLib.inf

[Components]
  # 包含的模块列表
  MdeModulePkg/Universal/DiskIoDxe/DiskIoDxe.inf
  MdeModulePkg/Universal/ConSplitterDxe/ConSplitterDxe.inf
  NetworkPkg/TcpDxe/TcpDxe.inf
  OvmfPkg/PlatformDxe/PlatformDxe.inf

[PcdsFixedAtBuild]
  gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel|0x80000000
  gEfiMdeModulePkgTokenSpaceGuid.PcdFlashNvStorageVariableBase|0xFFE00000

4.3.4 .fdf 文件（Flash Description File）

.fdf 文件定义了固件镜像在 Flash 中的物理布局，包括 FV（Firmware Volume）、FFS（Firmware File System）以及各个模块在镜像中的偏移地址。

# OvmfPkg/OvmfPkgX64.fdf 示例片段
[FD.BFV]
BaseAddress   = 0xFFE00000
Size          = 0x00200000
ErasePolarity = 1

[FV.SECFV]
FvAlignment        = 16
ERASE_POLARITY     = 1
MEMORY_MAPPED      = TRUE
STICKY_WRITE       = TRUE
LOCK_CAP           = TRUE
LOCK_STATUS        = TRUE
READ_DISABLED_CAP  = FALSE
READ_ENABLED       = TRUE
READ_STATUS        = TRUE
READ_LOCK_CAP      = TRUE
READ_LOCK_STATUS   = TRUE
WRITE_DISABLED_CAP = FALSE
WRITE_ENABLED      = TRUE
WRITE_STATUS       = TRUE
WRITE_LOCK_CAP     = TRUE
WRITE_LOCK_STATUS  = TRUE

  INF  OvmfPkg/Sec/SecMain.inf

[FV.DXEFV]
FvAlignment        = 16
ERASE_POLARITY     = 1

  INF  MdeModulePkg/Universal/DiskIoDxe/DiskIoDxe.inf
  INF  MdeModulePkg/Universal/ConSplitterDxe/ConSplitterDxe.inf
  INF  NetworkPkg/TcpDxe/TcpDxe.inf

4.4 构建系统工作流程

EDK2 的构建过程可以概括为以下步骤：

1. 解析 .dsc：读取平台描述文件，确定要编译的模块列表、库实例和 PCD 配置。
2. 解析 .dec：加载所有依赖 Package 的接口声明，建立 GUID 和 Protocol 的映射表。
3. 解析 .inf：对每个模块，读取其源文件列表、依赖库和编译选项。
4. 编译：调用编译器（如 GCC、MSVC、ICC）编译每个模块的源文件，生成 .efi 文件。
5. 链接与打包：根据 .fdf 定义的布局，将 .efi 文件打包成 FFS，再组合成 FV，最终生成完整的固件镜像 .fd 文件。

4.5 常见问题与避坑指南