简介：《一个UEFI引导程序的实现》是一份PDF电子书，其中UEFI即统一可扩展固件接口，资源面向操作系统底层开发学习者、软件工程师与业余爱好者，系统讲解从零编写引导程序的完整方法。全书首先对比统一可扩展固件接口与传统基本输入输出系统在结构组成、启动流程上的差异，说明新型固件接口取代旧固件的必然原因；随后基于可扩展固件接口开发套件搭建实践环境，依次介绍命令行编译、全局唯一标识分区表布局、系统分区文件系统、入门程序编写、镜像文件与系统表、调用约定与协议；最后分步骤实现显示模式配置、可用物理内存获取、存储介质文件读取，以及在六十四位处理器平台上引导操作系统内核启动。资源共含1个PDF文件，压缩包大小约2.36MB，便于下载后离线研读；目前已有2376人学习下载。书中结合源代码与运行效果图讲解，附有参考资料，能帮助读者打通操作系统引导的理论与实践，为后续学习内核源代码奠定基础。
1. 别把UEFI引导程序当成裸机程序来写
真正的UEFI引导程序出现时，固件已经完成了平台初始化：内存控制器、PCI总线、根复合体、中断都处于可用状态，分页和长期模式也可能已经开启。很多人按旧式引导程序的习惯去写，一上来就关中断、改GDT，结果连一屏调试输出都看不到。UEFI引导程序的核心工作其实只有三件事：从固件手里拿到一份可靠的内存映射，把内核镜像加载到约定地址，然后退出启动服务、建立自己的页表并跳转。这篇笔记围绕一个UEFI引导程序的实现展开，讲清楚从最小.efi工程到跳进内核的完整路径，以及OVMF和真机之间那些你不太容易提前预判的差异。适合正在写操作系统内核、做嵌入式安全启动或者想搞懂UEFI服务模型的人。如果只是想在裸机上闪烁LED，UEFI不是你的第一选择，那条路请继续走裸机工具链。
2. 最小UEFI引导工程：PE32+与EFI应用程序的构建
UEFI引导程序在固件眼里只是一个EFI应用程序，被加载到内存后由固件调用入口。它不符合传统内核直接链接到固定物理地址的模型，也不像MBR引导代码那样在BIOS中断环境里运行。所以第一个要改掉的习惯是：可执行文件格式、链接方式、入口函数都不一样。
2.1 为什么UEFI引导程序不链接到固定地址
UEFI规范把引导程序、驱动、应用程序统一成PE32+格式。固件加载引导程序时并不知道它原本靠什么基址编译，而是在运行时通过PE的重定位表把镜像放到一个可用地址，再调用入口。因此引导程序必须编译为位置无关代码，不能假设自己运行在0x100000或0x1000之类的固定地址。很多自制引导程序选型时直接沿用裸机ELF的链接脚本，最后固件要么拒绝加载，要么进了入口后凡是带绝对地址的指针全部访问错误。
这个模型带来的另一个约束是：UEFI入口函数不是_start，而是efi_main(EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable)。所有会被固件回调的导出函数都需要EFIAPI宏，x86_64下对应微软x64 ABI，也就是前四个整数参数走RCX/RDX/R8/R9，而不是System V ABI的RDI/RSI。这个差异不会在没开优化时立刻暴露，一旦碰到结构体传参或开了-O2，函数入口处栈和寄存器对不上，崩溃得毫无头绪。
2.2 用GCC和gnu-efi构建最小BootLoader.efi
常见做法是用gnu-efi而不是EDK2来做最小引导程序验证。gnu-efi提供了一套轻量的库和链接脚本，编译命令直观，适合只想把引导流程跑通的场景；EDK2更适合完整固件平台开发，构建系统重，引导程序还没写几行就要先配置一堆包依赖。我的选择是：验证用gnu-efi，正式落地时再把引导参数细节对齐到目标内核的引导协议。
最小入口代码：
#include <efi.h> #include <efidef.h> #include <eficon.h> #include <efilib.h> EFI_STATUS EFIAPI efi_main(EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable) { InitializeLib(ImageHandle, SystemTable); Print(L"UEFI boot loader: entering efi_main\r\n"); // 后续流程从这行开始： // 读内存映射、定位内核、准备页表、跳转 return EFI_SUCCESS; }逻辑说明：InitializeLib是gnu-efi库的初始化入口，它会根据传入的SystemTable绑定全局的ST、BS、RT指针，之后才能直接使用Print和uefi_call_wrapper。EFIAPI必须保留，它不是装饰，而是告诉编译器使用UEFI规范要求的调用约定。省略它，编译器会把ImageHandle放到RDI，而固件跳进来时把它放到RCX，参数错位几乎必然死机。
编译和链接命令：
# 1. 编译目标文件 gcc -I/usr/include/efi -I/usr/include/efi/x86_64 \ -fno-stack-protector -fpic -fshort-wchar -mno-red-zone \ -c boot.c -o boot.o # 2. 链接成可重定位的ELF共享对象 ld -shared -Bsymbolic -L/usr/lib -lefi -lgnuefi \ -T/usr/lib/elf_x86_64_efi.lds \ boot.o -o boot.so # 3. 转成固件认识的PE32+镜像 objcopy -j .text -j .sdata -j .dynamic -j .dynsym \ -j .rel* -j .rela* -j .reloc \ --target=efi-app-x86_64 boot.so boot.efi参数说明：-fno-stack-protector防止插入栈保护canary检查，固件没有为这类检查准备必要符号；-fpic生成位置无关代码，适应固件任意地址加载；-fshort-wchar让wchar_t变成16位，UEFI里的字符串是CHAR16[]，不是C语言默认的32位宽字符；-mno-red-zone禁止使用栈下方的128字节红区，UEFI异步事件和中断服务可能随时使用这块区域。链接时-Bsymbolic让函数内部调用直接绑定符号，减少PIC模式下多余的过程间跳转。elf_x86_64_efi.lds来自gnu-efi，负责把段排布成UEFI可加载的布局。objcopy --target=efi-app-x86_64把ELF共享对象转换成不含DOS头信息的PE32+镜像，固件可以直接解析并重定位。
把生成的boot.efi放进FAT镜像的EFI/BOOT/BOOTX64.EFI路径，QEMU加OVMF固件就能启动：
dd if=/dev/zero of=fat.img bs=1M count=64 mkfs.vfat -F 32 fat.img mmd -i fat.img ::EFI mmd -i fat.img ::EFI/BOOT mcopy -i fat.img boot.efi ::EFI/BOOT/BOOTX64.EFI qemu-system-x86_64 -bios /usr/share/ovmf/OVMF.fd -hdd fat.img这里-F 32必须保证UEFI固件能识别文件系统，64MB镜像足够容纳后续内核和调试工具。mmd和mcopy来自mtools，直接对镜像操作，不需要挂载权限。启动后如果控制台没有输出，优先检查镜像路径大小写和-bios参数，UEFI默认引导路径大小写通常宽容，但有些固件实现会严格区分路径。
2.3 选型细节：gnu-efi和EDK2的取舍
把gnu-efi这种轻量库拿来做引导程序，边界很清楚：它适合单文件、少依赖、快速验证的引导实现；EDK2则适合需要同时管理多个协议驱动、固件卷、变量存储的完整UEFI项目。如果你的目标是做一个能把自己编译进固件启动项的产品，EDK2是更稳的路径；如果你的目标是验证"引导程序能不能在OVMF里跑通、内存映射怎么传、页表怎么跳"，gnu-efi能让你少学一堆包管理概念。
我遇到不少案例是第一次用EDK2，结果时间都花在构建环境上，连Print都没打出来。反过来，也有工程因为用了gnu-efi，到后期需要定制Firmware Volume时发现库缺东西，代码结构也跟EDK2差异太大，不如一开始就选EDK2。这个平衡点主要看你的交付物是引导程序还是固件集成方案。引导程序作为独立.efi交付时，gnu-efi完全够用。但要注意：gnu-efi的efilib封装了部分细节，比如Print，如果要做产品级引导，最好还是直接访问SystemTable->ConOut->OutputString，少让库帮你做决定。
3. 从系统表到内核加载：UEFI服务是引导程序的唯一后台
UEFI引导程序运行的阶段，固件的启动服务还活着，内存分配、定时器、中断重定向、设备协议查询都靠这些服务。它们既是工具，也是枷锁。引导程序在退出启动服务之前所有资源都来自固件，内核要接管系统，必须先把手伸进这张系统表里把关键信息捞出来。
3.1 入口参数多出来的东西：EFI_SYSTEM_TABLE到底给你什么
efi_main的第二个参数SystemTable不是单纯的硬件描述，而是一组功能集合。最常用的成员包括：ConOut简单文本输出协议、BootServices启动服务表、RuntimeServices运行时服务表、配置表数组。启动服务表里装着GetMemoryMap、AllocatePages、AllocatePool、LoadImage、StartImage、ExitBootServices这些函数。运行时服务表里是GetTime、ResetSystem、SetVariable等在退出启动服务后仍然可用的接口。
引导程序主流程关心的是启动服务，但要记住一个原则：BootServices里的函数指针在ExitBootServices执行后全部失效。如果你在跳转内核前还想着调用BS->AllocatePool，那已经是非法访问。这也是为什么很多引导程序会先把所有需要的内存、页表、映射信息准备好，最后一刻才退出启动服务。调试时如果发现某次调用后系统直接死机，第一个怀疑点就是退出时机太早。
3.2 读内存映射：GetMemoryMap是引导程序的主线任务
内核接管CPU后，必须知道物理内存里哪些区域可用、哪些被固件保留、哪些是ACPI数据。UEFI把这组信息通过GetMemoryMap暴露出来。它返回一段数组，每个元素是EFI_MEMORY_DESCRIPTOR，包含类型、物理起始地址、页数、属性。调用方式很特殊，第一次调用一定返回EFI_BUFFER_TOO_SMALL，因为需要先知道缓冲区大小。
EFI_MEMORY_DESCRIPTOR *memory_map = NULL; UINTN map_size = 0; UINTN map_key = 0; UINTN descriptor_size = 0; UINT32 descriptor_version = 0; EFI_STATUS status; status = BS->GetMemoryMap(&map_size, memory_map, &map_key, &descriptor_size, &descriptor_version); if (status == EFI_BUFFER_TOO_SMALL) { status = BS->AllocatePool(EfiLoaderData, map_size, (VOID **)&memory_map); if (EFI_ERROR(status)) { Print(L"GetMemoryMap: alloc failed %r\r\n", status); return status; } status = BS->GetMemoryMap(&map_size, memory_map, &map_key, &descriptor_size, &descriptor_version); }逻辑说明：第一次调用时memory_map为NULL，map_size为0，所以固件返回缓冲区太小，同时把需要的字节数写进map_size。第二次调用前用AllocatePool分配内存，类型选EfiLoaderData，这意味着这块缓冲区在内核接管后可以被当作可释放的加载数据。descriptor_size不一定等于sizeof(EFI_MEMORY_DESCRIPTOR)，固件有权限在描述符尾部填充对齐字段，所以遍历时必须按descriptor_size步进，直接用结构体大小步进会读错内存。
拿到映射后，引导程序要遍历描述符，找出EfiConventionalMemory类型条目，这就是可用物理内存。内核镜像拷贝目标地址、页表内存、临时栈都从这里选，一般策略是选取最高的连续区域，避免和固件占用的低端内存冲突。这里踩过一个大坑：有人的内核要求加载地址低于4GB，但UEFI固件把4GB以上的可用内存排在前面，如果不做筛选，直接选第一个EfiConventionalMemory段，内核跳进去后访问的地址与约定不符，启动直接失败。
3.3 加载和启动内核镜像：LoadImage与StartImage的正确姿势
如果内核本身是EFI应用程序，比如带efistub的Linux内核，引导程序可以把加载工作交给固件。LoadImage负责解析PE32+格式、重定位、分配内存，StartImage则真正调用内核入口：
EFI_HANDLE kernel_handle = NULL; EFI_DEVICE_PATH_PROTOCOL *kernel_path = NULL; UINTN exit_data_size = 0; CHAR16 *exit_data = NULL; status = BS->LoadImage(FALSE, ImageHandle, kernel_path, NULL, 0, &kernel_handle); if (EFI_ERROR(status)) { Print(L"LoadImage failed: %r\r\n", status); return status; } status = BS->StartImage(kernel_handle, &exit_data_size, &exit_data);逻辑说明：LoadImage的第三个参数是EFI_DEVICE_PATH_PROTOCOL，指向内核文件所在的设备路径，固件必须能根据这个路径找到文件。如果内核不是EFI应用程序，而是裸露的ELF二进制，这条路走不通，LoadImage会返回EFI_UNSUPPORTED。自制内核多半没有efistub，引导程序就要自己当ELF loader：读取文件头，遍历program header，把可加载段的文件偏移拷贝到对应的物理地址，注意对齐和bss清零。
我一般推荐自制内核保留一个简单的64位ELF入口，引导程序手动加载。这样减少了固件的黑匣子成分，内存映射和入口参数都在自己掌控里。代价是要处理ELF解析的边界条件，比如段重叠、文件偏移越界、虚拟地址与物理地址不一致。另一个问题是LoadImage之后，固件会占用一块EfiLoaderCode类型内存存放内核镜像，这块内存在ExitBootServices后被标记为已分配，但内核接管后如果不主动复用，它就白白丢失。手动loader则可以精确控制镜像放哪、后续怎么回收。
4. 退出启动服务、建立页表、跳进内核：这一跳没有后悔药
从固件手里接过控制权这一步是整个引导程序里最没有安全感的一段。ExitBootServices之前还有固件兜底，之后所有异常都只能自己处理。页表错了、GDT错了、中断没关干净，表现都是复位或死机，而且不会给你打印日志的机会。
4.1 为什么ExitBootServices只有一次机会
ExitBootServices(ImageHandle, MemoryMapKey)需要传一个MemoryMapKey，这个key来自最近一次成功的GetMemoryMap调用。关键点是：key会在内存分配之后立刻失效。如果你先拿到了内存映射，然后又调用AllocatePages去分配内核栈，key就已经变了，再用旧key调用ExitBootServices会得到EFI_INVALID_PARAMETER，更麻烦的是固件可能已经进入半退出状态，后续行为不可预测。
正确顺序是：先把内核镜像、页表、GDT、临时栈全部准备好，最后一次调用GetMemoryMap，取得最新map_key，紧接着调用ExitBootServices。中间不要插入任何内存分配动作。如果失败，常见处理方式是重新执行整个准备流程再试一次，但第二次的MemoryMapKey必须重新取，不能沿用失败前那次。我的习惯是把所有分配逻辑封装成独立函数，在退出启动服务前统一执行，最后只留一次GetMemoryMap和紧随其后的ExitBootServices，中间只保留寄存器级别的操作。
4.2 关闭中断并重建页表：用汇编完成模式切换
UEFI固件把控制权交给引导程序时，x86_64平台通常已经开启了分页和长模式，但页表是固件建的。固件退出启动服务后，可能会回收自己的内存、修改页表项或保留一些直接映射，继续用旧页表是不可靠的。引导程序必须准备好自己的页表和GDT，在最后一刻切换。
# 关闭中断，固件退出后IRQ不再被处理 cli # 切到自建页表，基址由C代码传入RDI movq %rdi, %cr3 # 确保PAE和PGE打开 movq %cr4, %rax orq $0x0000000000000600, %rax movq %rax, %cr4 # 设置EFER.LME，保持长模式 movq $0xC0000080, %rcx rdmsr btsq $8, %rax wrmsr # 打开CR0.PG和CR0.PE movq %cr0, %rax orq $0x8000000000000001, %rax movq %rax, %cr0 # 加载自建GDT，远跳转进入内核 lgdt gdt64_ptr(%rip) pushq $0x08 leaq kernel_entry(%rip), %rax pushq %rax retfq这段汇编的控制顺序很讲究。cli必须放在最前面，因为固件的定时器事件可能在退出启动服务后仍然触发，但中断向量表已经被固件控制，一个时钟中断就可能把执行流带到未知位置。cr3切换意味着接下来所有地址翻译都走新页表，所以在切换前必须保证新页表已经覆盖当前指令所在区域、栈所在区域、内核入口和GDT所在区域。EFER.LME的置位要在打开CR0.PG之前完成，否则处理器认为长模式没有开启，会产生#GP。retfq负责同时切换代码段选择子和RIP，这条指令执行后CPU正式在内核入口处运行。
这里有一个非常容易忽略的寄存器状态问题。跳进内核前，RDI、RSI这些寄存器里放什么，必须和目标内核约定好。有些内核要求RDI指向内存映射指针，RBX为空，RSI是引导参数结构地址；另一些则直接约定好固定地址。跳转前最后一刻用寄存器把参数传给内核，而不是指望内核从栈里找数据。栈在切换页表后内容仍在，但旧页表已经废弃，谁能保证内核入口处的栈映射就是你给的那份？稳定做法是给内核入口传寄存器参数，并把栈指针切到自建临时栈范围内。
5. UEFI引导程序避坑指南：从OVMF到真机的几个典型问题
这一章把我在调试自制UEFI引导程序时遇到的高频问题整理出来。每条都凑齐了现象、原因和解决思路，你能直接照着排查。
5.1 内存映射键变化导致的ExitBootServices失败
现象：程序运行到ExitBootServices时返回EFI_INVALID_PARAMETER，或者固件直接卡死。OVMF下偶尔成功，真机上几乎每次失败。
原因：MemoryMapKey在你执行任何内存分配函数之后都会改变。最常见的错误是先调GetMemoryMap拿到key，又用AllocatePages分配内核加载空间，然后拿旧key去退出启动服务。固件认为你的key和当前状态不匹配，拒绝移交控制权。
解决：把所有分配动作挪到最后一次GetMemoryMap之前。准备工作的执行顺序是：加载内核到内存、分配页表内存、分配临时栈、构建页表和GDT，最后才调用GetMemoryMap获取最新key，并立即调用ExitBootServices。一旦key失效，不要试着用旧key重试，应该回到准备阶段再做一次完整的映射读取。
5.2 屏幕没有输出时，先查ConOut再查GOP
现象：OVMF下能看到打印信息，换到某厂商固件后黑屏。程序没有死，通过QEMU串口能看到执行流，但屏幕一个字都没有。
原因：UEFI固件允许把ConOut绑定到串口、虚拟终端或图形设备的文本层，不同固件实现差异很大。Print输出到的可能是串口而不是显示器。另外，固件在BDS阶段可能没有自动切换到图形输出协议，引导程序需要显式查询Graphics Output Protocol并设置模式。
解决：在InitializeLib之后立刻打印一段带版本号和入口地址的信息，确认输出通道正常。如果需要图形输出，通过BS->LocateProtocol查找GOP，调用QueryMode选一个合适分辨率，然后SetMode。不要把Print当作最终状态依据，引导程序越接近跳转阶段越应该用自己的像素绘制函数做状态反馈。
5.3 优化选项让引导程序崩溃：EFIAPI与-fno-stack-protector
现象：-O0编译一切正常，改成-O2后进入efi_main没几行就死机，或者连续多次调用固件服务后在返回地址处出错。
原因：两个叠加因素。一是efi_main或者回调函数漏了EFIAPI，编译器在O2下可能对参数传递、栈布局做更激进的重新安排，与固件期望的MS x64 ABI冲突；二是开启了栈保护，编译器插入__stack_chk_fail调用，而固件加载器没有为该符号提供重定位支持。
解决：所有导出给固件回调的函数统一加EFIAPI。编译选项保留-fno-stack-protector。排查时先打开-O1看是否复现，再二分查找问题函数。如果打开优化后只有某一次调用崩溃，优先怀疑结构体传参和调用约定，而不是内存访问。
5.4 OVMF能过但真机起不来：固件实现比规范更重要
现象：同一份boot.efi在OVMF下稳定启动，换到某品牌主板固件后，或重启后直接白屏，或卡在加载内核阶段。
原因：OVMF是参考实现，对规范执行相对宽松；真机固件会根据平台设计做出差异。常见差异包括：EfiLoaderData内存被提前回收、FAT文件路径大小写处理不一致、某些内存区域被保留但不在内存映射描述符中体现、AllocatePages返回地址与固件预期不符。
解决：引导程序不要依赖固件的"良好习惯"。内核映像和页表用AllocatePages显式申请，而不是用临时栈变量或BSS数组。内核加载地址校准到至少4KB对齐，并避开低端1MB区域。多准备几台不同固件的机器做回归测试，OVMF只是第一关，不是标准答案。
5.5 忘了给内核构造引导参数
现象：跳进内核后，内核第一个动作是读取引导参数结构，结果直接从空指针或物理地址0取数据，打印出一串乱码后复位。
原因：自制内核通常要求引导程序在约定地址填写魔数、协议版本、内存映射指针、命令行参数。很多人在汇编跳转前只想着RDI传地址，却忘了在内存里把结构体填完整。
解决：在内核镜像入口地址附近预留一个参数页，跳转前由C代码填充。至少要写：魔数值、协议版本、内存映射指针、映射描述符大小、映射键、内核镜像物理起始地址和长度。汇编跳转前最后一段代码只负责把这些关键值加载到寄存器并远跳。养成习惯后，这部分反而是整个引导程序里最不容易出问题的，因为结构由内核单方面定义，照着协议填就行。
6. 用OVMF和QEMU验证UEFI引导程序：调试到源码行的一个小技巧
OVMF加上QEMU是最合适的UEFI引导程序验证环境，比真机好调试太多。基础用法是前面提到的-bios OVMF.fd -hdd fat.img。启动时加一个-debugcon stdio可以看到固件自身的调试日志，OVMF会把加载镜像、协议定位、内存分配等事件打印出来。引导程序里的Print输出如果走了串口，也可以在QEMU的串口终端里看到。
更实用的技巧是用QEMU的GDB调试能力配合符号文件。启动命令加-s -S，QEMU会在1234端口等GDB连入，并且一开始暂停在固件复位入口。接着在GDB里target remote :1234，理论上可以打断点。难点是UEFI引导程序是运行时重定位的，boot.efi里的符号地址不是固件实际加载的地址。直接file boot.efi之后打efi_main断点基本无效，因为符号表里写的是链接地址。
我的办法是在引导程序入口自己打印加载地址：
Print(L"efi_main @ 0x%lx, SystemTable @ 0x%lx\r\n", (UINT64)efi_main, (UINT64)SystemTable);拿到这个地址后，在GDB里就可以算出重定位偏移。假设efi_main符号在boot.so里的链接地址是0x1000，固件实际加载到0x3f00000，那偏移量就是0x3eff000。用add-symbol-file把保留调试符号的boot.so按这个偏移加载到GDB，断点就能落在源码行上：
add-symbol-file boot.so 0x3eff000 b efi_main c这样断点生效后，si单步可以跟到页表切换那几行汇编。但要注意：在ExitBootServices之后，GDB的软件断点依赖int3指令替换目标内存，如果那段内存被页表切换改变或执行流跳到全新映射，断点可能失效。硬件断点更可靠，数量有限但也够用。我靠这个方法在模拟项目X里定位过一个典型的GDT段属性错误：lgdt之后远跳转直接#GP，用GDB看到RIP停在跳转指令后第一条，同时检查GDT内存才发现段属性里的可执行位没有设置。
从那以后我养成了习惯：每个阶段都在屏幕上打一条带地址的状态行，OVMF里跑一遍，再用GDB验证关键的跳转点，最后才上真机。UEFI引导程序的黑匣子多，但验证路径比裸机清晰得多——只要把服务调用顺序守好，剩下的基本都是可排查的小坑。希望帮到你。
本文还有配套的精品资源，点击获取
