2023年12月8日发(作者：)
UEFI原理与编程第二章学习-UEFI标准应用工程模块文件介绍及编译流程
标准应用程序工程模块
标准应用程序工程模块是其他应用程序工程模块的基础，也是UEFI中常见的一种应用程序工程模块。每个工程模块分为两部分：工程
文件和源文件，标准应用程序工程模块也不例外。其中，源文件包括：C/C++文件、.asm汇编文件，也可以包括.uni（字符串资源文件）
和 .vfr（窗口资源文件）等资源文件。
一个简单的标准应用程序工程模块应该包含一个C程序模块（本例中为Main.c）以及一个工程文件（），接下来逐部分编写一
个简单的标准应用程序的各个模块。
1、入口函数
//简单的标准应用程序
#include
EFI_STATUS UefiMain(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)
{
SystemTable->ConOut->OutputString(SystemTable->ConOut, L"HelloWorldn");
return EFI_SUCCESS;
}
一般来说标准应用程序至少要包含以下两个部分：
1. 头文件 ：所有的UEFI程序都要包含头文件Uefi.h。Uefi.h定义了UEFI基本数据类型以及核心数据结构。
2. 入口文件 ：UEFI标准应用程序入口函数可以由开发者自行指定，但通常命名为UefiMain。入口函数由工程文件
指定。虽然入口函数的函数名可以变化，但其函数签名（即返回值类型和参数列表类型）不能变化。
入口函数返回值与参数讲解：
1. 入口函数的返回值类型是EFI_STATUS。
1. 在UEFI程序中基本所有返回值类型都是EFI_STATUS。EFI_STATUS本质上是无符号程序长整数型变量。
2. 在最高位为1时值为错误代码，为0时表示没有错误的状态值或返回值。通过宏EFI_ERROR(Status)可以判
断返回值Status是否为错误码。若Status是错误吗，则EFI_ERROR的返回值为TRUE，否则为False。
3. EFI_SUCCESS为预定义常量，其值为0，表示没有错误的状态或是返回值。
2. 入口函数的参数是ImageHandle和SystemTable。
1. .efi文件（UEFI应用程序或UEFI驱动程序）加载到内存后生成的对象称为Image映像。ImageHandle是
Image对象的句柄，作为模块入口函数，它表示模块自身加载到内存后生产的Image对象。
2. SystemTable是程序同UEFI内核交互的桥梁，程序通过SystemTable可以获得UEFI提供的各种服务，如启
动（BS）服务和运行时（RT）服务。SystemTable时UEFI内核中的一个全局结构体。
向标准输出设备打印字符串是通过SystemTable的ConOut提供的服务完成的。ConOut是
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL的一个实例。而EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL的主要功能是控
制字符输出设备。向输出设备打印字符串是通过ConOut提供的OutputString服务完成的。该服务（函数）第一个参数是
This指针，指向EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL实列（此处为ConOut）本身；第二个参数是Unicode字符
串。这条打印语句的流程是通过SystemTable->ConOut->OutputString五福将字符串L"HelloWorld"打印到
SystemTable->ConOut所控制的字符输出设备。
2、工程文件
在编写Main.c文件的同时，需要编写.inf（Module Information File）文件。.inf文件时模块的工程文件，其作用类似于Visual
Studio的.proj文件，用于指导EDK2编译工具自动编译模块。
工程文件分为很多个块，每个块以“[块名]”开头，“[块名]”必须单独占一行。有的块是所有工程文件都必需的块，还有另一部
分的块仅在用的时候需要编写。
必须块
[Defines]
[Sources]
[Packages]
[LibraryClasses]
块描述
定义本模块的属性变量及其他变量，这些变量可在其他块中引用
列出本模块的所有源文件及资源文件
列出本模块引用到的所有包的包声明文件
列出本模块要链接的库模块
非必须块
[Protocols]
[Guids]
[Pcd]
[PcdEx]
[FixedPcd]
[FeaturePcd]
[PatchPcd]
[BuildOptions]
块描述
列出本模块用到的Protocol
列出本模块用到的GUID
列出本模块用到的Pcd变量，这些Pcd变量可被整个UEFI系统访问
列出本模块用到的Pcd变量，这些Pcd变量可被整个UEFI系统访问
列出本模块用到的Pcd编译期常量
用于列出本模块用到的Pcd常量
写出的Pcd变量进本模块可以使用
指定编译和链接选项
1. [Defines] 块：
[Defines]块用于定义模块的属性和其他变量，块内定义的变量可被其他块引用。
(1)属性定义的语法
属性名=属性值
(2)属性
块内必须定义的属性包括：
1. INF_VERSION： INF标准的版本号。EDK2的build会检查INF_VERSION的值，并根据这个值解释.inf文件。通常将
INF_VERSION的值设置为0x00010005，其中前半部分为主版本号，后半部分为次版本号。
2. BASE_NAME：模块名字符串，不能包含空格。它通常也是输出文件的名字。例如，BASE_NAME=UefiMain，则最
终生成的文件为。
3. FILE_GUID：每个工程文件必须有一个8-4-4-4-12格式的GUID，用于生产固件。例如，FILE_GUID=6987936E-
GUID-UEFI-AE86-。
4. VERSION_STRING：模块的版本号字符串。例如，可以设置为 VERSION_STRING=1.0。
5. MODULE_TYPE：定义模板的模板类型，可以是SEC、PEI_CORE、PEIM、DXE_CORE、DEX_SAL_DRIVER、
UEFI_APPLICATION、BASE中的一个。对标准应用程序工程模块来说，MODULE_TYPE的值为
UEFI_APPLICATION。
6. ENTRY_POINT：定义模块的入口函数。模块的入口函数就是通过设置ENTRY_POINT的值进行配置的。
[Defines]块示例代码：
[Defines]
INF_VERSION = 0x00010005
BASE_NAME = UefiMain
FILE_GUID = 6987936E-GUID-UEFI-AE86-
MODULE_TYPE = UEFI_APPLICATION
VERSION_STRING = 1.0
ENTRY_POINT = UefiMain
2. [Sources] 块
2. [Sources] 块
(1)语法
块内每一行代表一个文件，文件使用相对路径，根路径是工程文件所在的目录。这次编写的简单标准应用程序工程模块仅含
有一个源文件。 [Sources]块如下所示：
[Sources.$(Arch)]
UefiMain.c
(2)体系结构相关块
.$(Arch)是可选项，可以是IA32、X64、IPF、EBC、ARM中的一个，表示本模块适用的体系结构。[Sources]块适用于任
何体系结构。例如，编译32位模块时（即，在build命令选项中选择使用 -a IA32选项），工程将包含[Sources]和
[32]中的源文件，编译64位模块时，工程将包含[Sources]和[Sources.X64]中的源文件。
(3)示例
示例包含了三个块：[Sources]块、[32]块、[Sources.X64]块。在编译32位的模块时，模块包含
[32]中的Cpu32.c文件和[Sources]中的Common.c文件；在编译64位系统时，模块包含文件[Sources.X64]
中的Cpu64.c和[Sources]中的Common.c。
[Sources]块、[32]块、[Sources.X64]块示例：
[Sources]
common.c
[32]
Cpu32.c
[Sources.X64]
Cpu64.c
(4)编译工具链相关的源文件
有时文件名后面会有一个“|”符号，该符号后面会跟工具链名字，如下例所示：
工具链相关的源文件：
[Sources]
TimerWin,c | MSFT
TimerLinux.c | GCC
这表示TimerWin.c仅在使用 Visual Studio 编译器时有效，TimerLinux.c仅在使用GCC编译器时有效。处理MSFT和GCC
外，EDK2还定义了INTEL和RVCT两种工具链。INTEL工具链是ICC编译器或Intel EFI 字节码编译器；RVCT是ARM编译
器。
3. [Packages] 块
[Packages]块列出了本模块引用到的所有包的包声明文件（类似C++开头的import），即.dec文件。
(1)[Packages]语法
[packages]块内每一行列出一个文件，文件使用相对路径，相对路径的根路径位EDK2的根目录。如果[Sources]块内列出
了源文件，则在[Packages]块内必须列出MdePkg/MdePkg。.dec,并将其放在本块的首行（详见示例）。
(2)示例
由于编写的简单标准应用工程模块示例（ 块）中， UefiMain.c仅引用了MdePkg中的头文件Uefi.h，因此[Packages]仅列
出MdePkg/即可，示例如下：
[Packages]
MdePkg/
4. [LibraryClasses] 块
[LibraryClasses]块的功能是列出本模块要链接的库模块。
(1)语法
块内每一行声明一个要链接的库（库定义在包的 .dsc文件中），语法如下：
[LibraryClasses]
库名称
(2)常用库
应用程序工程模块必须链接UefiApplicationEntryPoint库；驱动模块必须链接UefiDriverEntryPoint库。
(3)示例
这次尝试编写的简单应用程序工程模块中，UefiMain.c文件的UefiMain函数没有调用除UefiApplicationEntryPoint以外的
其他库函数，因此只需要在[LibraryClasses]块中列出UefiApplicationEntryPoint即可，示例如下：
[LibraryClasses]
UefiApplicationEntryPoint
5. [Protocols]块
[Protocols]块中列出的是在模块中使用到的Protocol对应的GUID。如果模块中未使用任何Protocol，则[Protocols]块为
空。
(1)语法
块内的每一行声明一个在本模块中引用的Protocol。语法格式如下：
[LibraryClasses]
Protocol 的 GUID
(2)示例
如果在程序中使用了某个Protocol的GUID。例如，源程序中使用了类似代码：
Status = gBS->LocateProtocol ( &gEfiHiiDatabaseProtocolGuid, NULL, (VOID**) &HiiDatabsa);
则在[Protocols]块中必须要列出gEfiHiiDatabaseProtocolGuid，示例如下：
[LibraryClasses]
gEfiHiiDatabaseProtocolGuid
6. [BuildOptions]块
[BuildOptions]块制定了本模块的编译和链接选项。
(1)语法
[BuildOptions]
[编译器家族]: [$(Target)]_[TOOL_CHAIN_TAG]_[$(Arch)]_[CC|DLINK]_FLAGS [=|==] [选项]
各选项说明如下：
1. [编译器家族]：可以是MSFT（Visual Studio编译器家族）、INTEL（Intel编译器家族）、GCC（GCC编译器家族）
和RVCT（ARM编译器家族）中的某一个。
2. [Target]：值可以是DEBUG、RELEASE和*中的任意一个，*为通配符，表示对DEBUG和RELEASE都有效。
3. [TOOL_CHAIN_TAG]：是编译器的名字。编译器的名字在文件中的第60行。预定的编译器名字可以
是：VS系列（VS2010、VS2015、VS2017等）、GCC系列（GCC45、GCC46等）、可以是CYGGCC或是ICC
等，还可以使用通配符*表示对所有编译家族内的所有编译器都适用。
4. [Arch]：是体系结构，可以IA32、X64、IPF、EBC、ARM或*，其中*表示对所有体系结构都有效。
5. [CC|DLINK]：CC表示编译选项。DLINK表示链接选项。
5. [CC|DLINK]：CC表示编译选项。DLINK表示链接选项。
6. [=|==]：=表示将选项附加到默认选项后；==表示仅使用所定义的选项，弃用默认选项。
7. [选项]：此项为编译选项或连接选项。
(2)示例
示例6.1 使用’='的[BuildOptions]块，编写用Visual Studio编译器进行编译，且在编译时添加/wd4804编译选项，连接
时添加/BASE:0选项。
[BuildOptions]
MSFT:*_*_*_CC_FLAGS = /wd4804
MSFT:*_*_*_DLINK_FLAGS = /BASE:0
示例6.2 使用"=="的[BuildOptions]块，编写是使用Visual Studio编译器进行编译32位的DEBUG版本仅使用指定的编译选
项，并忽略所有默认的编译选项。
[BuildOptions]
MSTF:DEBUG_VS2010_IA32_CC_FLAGES == /nologo /c /WX /GS- /W4 /Gs32768 /DUNICODE /Olib2 /GL /EHs-c- /GR- /GY /Zi /Gm /D EF
I_SPECIFCATION_VERSION = 0x0002000A /D TIANO_RELEASE_VERSION = 0x00080006 /FAs /Oi-
等上述代码块都编译好后，将其放在一起，组成完整的标准应用程序工程文件，示例如下：
示例，标准应用程序HelloWorld的完整工程文件
[Defines]
INF_VERSION = 0x00010005
BASE_NAME = UefiMain
FILE_GUID = 6987936E-GUID-UEFI-AE86-
MODULE_TYPE = UEFI_APPLICATION
VERSION_STRING = 1.0
ENTRY_POINT = UEFIMAIN
[Sources]
main.c
[Packages]
MdePkg/
[LibraryClasses]
UefiApplicationEntryPoint
UefiLib
3、编译和运行
源文件和工程都编写完成后，将的相对（uefi）路径添加到或的[Components]部分，示例
代码如下（uefi在EDK2文件夹中）：
[Components]
uefi/book/infs/
添加完成后打开BaseTools下的build工具进行编译即可
Windows下执行下列命令进行编译：
C:EDK2> --nt32
C:EDK2>build -p -a （IA32||X64）
Linux下执行下例命令进行编译：
$>source ./ BaseTools
$>source -p Unixpkg/ -a IA32
※4、标准应用程序的加载过程
1. 应用程序被编译成 .efi 文件
1）UefiMain.c首先被编译成目标文件。
2）连接器将目标文件和其他库连接成。
3）GenFw工具将转换成。
以上整个过程由build命令自动完成，2）、3）阶段执行的命令如下：
由图可以看出，连接器在生产文件时使用了/dll/entry:_ModuleEntryPoint。.efi文件是遵循PE32格式的二进
制文件，_ModuleEntryPoint是这个二进制文件的入口。
2. 将文件加载到内存
在Shell中执行时，Shell首先用gBS->LoadImage()将文件加载到内存生成Image对象，然后调用
gBS->StartImage(Image)启动这个Image。具体加载过程代码如下：
//@file ShellPkgApplicationShellShellProtocol.c
EFI_STATUS EFIAPI InternalShellExecuteDevicrPath(
IN CONST EFI_HANDLE*ParentImageHandle,
IN CONST EFI_DEVICE_PATH_PROTOCOL *DevicePath, //
的设备路径
IN CONST CHAR16 *CommandLine OPTIONAL, //
应用程序所需的命令行参数
IN CONST CHAR16 **Environmrnt OPTIONAL, //UEFI
环境变量
OUT EFI_STATUS *StatusCode OPTIONALa //
程序
的返回值
)
{
//
定义参数：
EFI_STATUS Status;
EFI_HANDLE NewHandle;
EFI_LOADED_IMAGE_PROTOCOL *LoadedImage;
LIST_ENTRY OrigEnvs;
EFI_SHELL_PARAMETERS_PROTOCOL ShellParamsProtocol;
...
/*
第一步：将
文件加载到内存，生成
Image
对象，
NewHandle
为其句柄
句柄：
1
、特殊的智能指针（当一个应用程序要引用其他系统管理的内存块或对象时）
2
、
Windows
编程的基础。句柄指的是使用一个唯一的
4
字节型整数值，来标识应用程序中
的不同对象和同类中的不同示例。应用程序能通过句柄访问相应对象的信息，但这种句柄
不是指针，应用程序不能通过句柄直接阅读文件中的信息。句柄是
Windows
系统用来标识
应用程序中建立的或是使用的资源的唯一整数。
使用
gBS->LoadImage()
函数，将加载结果返回给
Status
参数，同时改变
NewHand
的值。
使用
EFI_ERROR()
函数判断是否加载成功。
*/
Status = gBS->LoadImage(
FALSE,
*ParentImageHandle,
(EFI_DEVICE_PATH_PROTOCOL*)DevicePath,
NULL,
NULL,
0,
&NewHandle);
if (EFI_ERROP(Status))
{
if (NewHandle != NULL)
gBS->UnloadImage(NewHandle); //
这里为什么要
UnloadImage
？
return (Status);
}
/*
第二步：获取命令行参数，并将获取的命令行参数交给
的
Image
对象，即句柄
NewHandle
gBS->OpenProtocol()
函数传入所得的信息和
NewHandle
。
*/
Status = gBS->OpenProtocol(
NewHandle,
&gEfiLoadedImageProtocolGuid,
(VOID**) &LoadedImage,
gImageHandle,
NULL,
EFI_OPEN_PROTOCOL_GET_PROTOCOL);
if(!EFI_ERROR(Status))
{
ASSERT(LoadedImage->LoadOptionsSize == 0;
if (NULL != CommandLine)
{
LoadedImage->LoadOptionsSize = (UINT32)StrSize(CommandLine));
LoadedImage->LoadOptions = (VOID*)CommandLine;
}
}
...
/*
第三步：启动加载的
Image
gBS->StartImage()
函数根据所传入的
NewHandle
启动相应的
Image
。
*/
if (!EFI_ERROR(Status))
{
if (StatusCode != UNLL)
*StatusCode = gBS->StartImage(NewHandle, NULL, NULL);
else
Status = gBS->StartImage(NewHandle, NULL, NULL);
}
...
//
退出应用程序后清理资源
}
加载应用程序中最重要的一步就是gBS->StartImage(NewHandle, NULL, NULL)，程序通过这一步启动所加载的Image。
StartImage的主要租用作用是找出可执行程序映像（Image）的入口函数并执行gBS->StartImage是函数指针，实际指向
CoreStartImage函数。
3. 进入映像函数的入口函数
CoreStartImage的主要作用是调用映像的入口函数。具体代码清单：
//@file MdeModulePkgCoreDxeImageImage.c
EFI_STATUS EFIAPI CoreStartImage (
IN EFI_HANDLE ImageHandle,
OUT NINTN *ExitDataSize,
OUT NINTN *ExitDataSize,
OUT CHAR16 **ExitData OPTIONDAL
)
{
//
定义参数
EFI_STATUS Status;
LOADED_IMAGE_PRIVATE_DATA *Image;
LOADED_IMAGE_PRIVATE_DATA *LastImage;
UINT64 HandleDatabaseKey;
UINTN SetJumpFlag;
UINT64 Tick;
EFI_HANDLE Handle;
//
设置
LongJump
，用于退出此程序
Image->JumpBuffer = AllocatePool (sizeof (BASE_LIBRARY_JUMP_BUFFER) + BASE_LIBRARY_JUMP_BUFFER_ALLGNMENT);
if(Image->JumpBuffer == NULL)
return EFI_OUT_OF_RESOURCES;
Image->JumpContext = ALIGN_POINTER (Image->JumpBuffer, BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT);
SetJumpFlage = SetJump(Image->JumpContest);
//
首次调用
SetJump()
返回
0
。通过
LongJump(Image->JumpCOntext)
跳转到此处时，返回非零值。
if (0 == SetJumpFlag)
{
//
调用
Image
的入口函数
Image->Started = TRUE;
Image->Status = Image->ENtryPoint(ImageHandle,Image->Table);
//
设置
Image
执行后的状态，然后通过
LongJump
跳到应用程序退出点。
CoreExit(ImageHandle, Image->Status, 0, NULL);
}
/*
此处是应用程序退出点。
程序通过
LongJump
跳转到此处，然后根据
Image->Status
进行错误处理。
*/
...
}
在gBS->StartImage中，SetJump/LongJump为应用程序的执行提供了一种错误处理机制，执行流程如图所示：
gBS->StartImage的核心是Image->EntryPoint(···)，它是程序映像（Image）的入口函数，应用程序的入口函数是
_ModuleEntryPoint。进入_ModuleEntryPoint后，控制权才转交给应用程序（此例的应用程序指
），_ModuleEntryPoint的代码如下：
//@file MdePkgUefiApplicationEntryPointApplicationEntryPoint.c
EFI_STATUS EFIAPI _ModuleEntryPoint (IN EFI_HANDLE ImageHandle, IN EFI _SYSTEM_TABLE *SystemTable )
{
EFI_STATUS Status;
if (0 != _gUefiDriverRevision)
{
//
确保系统平台的
UEFI
版本号大于等于
ImageHandle
的
UEFI
版本号
if (SystemTable->on < _gUefiDriverRevision)
return EFI_INCOMPATIBLE_VERSION;
}
//
（调用）所有将被调用的库的构造函数，进行初始化。
ProcessLibraryConstructorList(ImageHandle, SystemTable);
//
调用
Image
的入口函数
Status = ProcessModuleEntryPointList(ImageHandle, SystemTable);
//
所有库的析构函数
ProcessLibraryDestructorList (ImageHandle, SystemTable);
return Status;
}
_ModuleEntryPoint主要处理一下三件事：
1. 初始化：在初始化函数ProcessLibraryConstructorList中会调用一系列构造函数。
2. 调用本模块的入口函数：在ProcessModuleEntryPointList调用应用程序工程模块真正的入口函数（即在 .inf 文
件中定义的入口函数UefiMain）。
3. 析构：在析构函数ProcessLibraryDestructorList函数中会调用一系列的析构函数。
这三个Process*函数是在系统执行build命令时，build命令解析模块的工程文件（即.inf文件），然后生成AutoGen.h
和AutoGen.c，其中AutoGen.c中便含有这三个函数。一般而言，在.inf文件的[LibraryClass]段声明了某个库后，如果这个
库由构造函数，AutoGen便会在ProcessLibraryConstructorList中加入这个库的构造函数。另外
ProcessLibraryConstructorList还会自动加入启动服务(BS)和运行时服务(RT)的构造函数。
工程模块HelloWorld的ProcessLibraryConstructorList函数代码如下：？
VOID EFIAPI ProcessLibraryConstructorList(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)
{
EFI_STATUS Status;
//
初始化全局变量
gBS
、
gST
和
gImageHandle
Status = UefiBootServicesTableLibConstructor(ImageHanle, SystemTable);
ASSERT_EFI_ERROR(Status);
//
初始化全局变量
gRT
Status = UefiRuntimeServicesTableLibConstructor (ImageHandle, SystemTable);
ASSERT_EFI_ERROR(Status);
//
初始化
UefiLib
，
函数是在
UefiLib
中实现的
Status = UefiLibConstructor(ImageHandle, SystemTable);
ASSERT_EFI_ERROR(Status);
}
gBS指向启动服务表，gST指向系统表(System Table)，指向正在执行的驱动或应用程序。gRT指向运行时服务表。这
几个全局变量在开发应用程序和驱动时会经常用到。 使用gBS、gST、gImageHandle前需要
#include
#include
与构造函数相似，AutoGen会在析构函数中调用相应Library的析构函数。HelloWorld标准应用程序工程模块的析构函数
ProcessLibraryDestructorList为空，这是因为UefiBootServicesTableLib、UefiRuntimeServicesTableLib、UefiLib
这三个Library都没有析构函数。
标准应用程序工程HelloWorld的析构函数ProcessLibraryDestructorList，代码如下：
VOID EFIAPI ProcessLibraryDesturctorList (IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)
{
}
4. 进入模块入口函数
在ProcessModuleEntryPointList中，调用了应用程序工程模块的真正入口函数UefiMain，代码如下：
EFI_STATUS EFIAPI ProcessModuleEntryPointList(IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)
{
return UefiMain(ImageHandle, SystemTable);
}
5. 总结：
标准应用工程模块入口函数的整个调用过程为：
->PLCL ：运行所有构造函数
LoadImage->StartImage->_ModuleEntryPoint->PMEP-UefiMain ：执行入口函数
->PLDL ：运行所有析构函数
5、总结
本篇介绍了标准应用程序工程的模块的组成、入口函数UefiMain的结构，以及.inf文件的结构
发布评论