# chuanpen **Repository Path**: herbertee/chuanpen ## Basic Information - **Project Name**: chuanpen - **Description**: 构建Qemu+UEFI+Linux的编译和运行环境，用于UEFI和Kernel（ACPI）的学习 - **Primary Language**: C - **License**: BSD-2-Clause - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 5 - **Created**: 2026-06-08 - **Last Updated**: 2026-06-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # chuanpen ## 1 介绍 最初的设想比较简单：搭建一套基于Qemu+UEFI+Linux的编译与运行环境，用于学习UEFI以及Kernel（ACPI）相关内容。当前选择在Ubuntu 22.04上进行构建与验证，如果在其他操作系统上使用，则需要对部分脚本进行适配和调整。 随着功能的不断完善，这一环境也逐步从最初的个人学习工具，扩展为《芯片时代的UEFI与ACPI编程》一书的配套项目。通过将实验环境与书中内容结合，可以更直观地展示相关机制的实现过程，方便读者进行实践与验证。 ## 2 软件架构 软件架构说明 ``` ~/chuanpen$ tree -L 2 . ├── LICENSE ├── README.md ├── build-pen │   ├── configs #编译所需文件、软件和依赖库安装的脚本等 │   ├── pen_build.sh #编译指定项目，包括UEFI编译,Kerel编译及打包,qemu编译 │   └── pen_download.sh #下载指定的代码库 ├── log #日志存放处 │   └── Reademe.txt ├── run-pen #运行和测试脚本 │   ├── base │   ├── nvme │   ├── oprom │   ├── pcie │   ├── pxe-http │   ├── sata │   ├── secureboot │   ├── systemready │   ├── usb │   └── x86-pcie ├── uefi_gdb #辅助uefi调试的脚本 │   ├── README.md │   ├── efi.md │   ├── efi.py │   └── efi_aarch64.py └── uefi_sh_app #可用于uefi shell和linux shell下运行的一些工具 ├── SimplePciDeviceTest.efi ├── secureboot └── toolsForLinux ``` ## 3 下载和编译使用教程 ### 3.1 下载项目及安装依赖项 下载项目： ``` robin@YBBJ0042:~$ git clone https://gitee.com/chuanpen/chuanpen.git ``` 安装所需软件和依赖库： ``` robin@YBBJ0042:~$ cd chuanpen/build-pen/configs/script/ robin@YBBJ0042:~/chuanpen/build-pen/configs/script$ sudo ./install_prerequisites.sh ``` ### 3.2 下载和编译qemu 主要步骤如下： ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_download.sh qemu robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_build.sh qemu #编译和安装qemu 8.0 robin@YBBJ0042:~/chuanpen/build-pen$ qemu-system-aarch64 --version QEMU emulator version 8.0.0 (v8.0.0-3-g538fc48f71) Copyright (c) 2003-2022 Fabrice Bellard and the QEMU Project developers ``` ### 3.3 下载和编译UEFI 对于UEFI, 给出了各类固件的编译。针对目前书中的示例，主要使用的是BookVirtQemu.其下载和编译步骤如下： 1. 下载UEFI代码和编译工具 ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_download.sh uefi #包含了edk2,edk2-platforms以及相关的编译工具等的下载 ``` 2. 编译BookVirtQemu。**:heavy_exclamation_mark: 注意:需要先准备UEFI的Build工具** ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_build.sh uefi-tools #编译UEFI的Build工具 robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_build.sh uefi-book #编译BookVirtQemu ``` ### 3.4 下载和编译linux，以及打包 主要步骤如下： ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_download.sh kernel #下载linux,grub,busybox以及相关的编译工具 robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_build.sh kernel #编译linux，并自动打包镜像 ``` ## 4 基础测试说明 ### 4.1 run-pen/base目录 base.sh: 基础的运行脚本, 需要UEFI的virt qemu版本、kernel镜像等的支持才可运行。
base_9p.sh: 在base脚本的基础上，添加了virtio 9p的支持。
base_9p.sh的使用说明: 1. 运行base_9p.sh脚本，会自动启动qemu，加载UEFI和kernel镜像。
``` robin@robinlenovo2:~/chuanpen/run-pen/base$ ./base_9p.sh normal ``` 2. 再开一个terminal，执行telnet: ``` robin@robinlenovo2:~$ telnet localhost 8888 ``` 3. 在OS下创建文件夹，并mount 9p的目录: ``` / # mkdir 9p / # mount -t 9p -o trans=virtio,version=9p2000.L hostshare /9p ``` ### 4.2 run-pen/x86-pcie目录 这是针对x86的运行和调试框架，具体参考此目录下HowToDebug.md. 仅用于学习使用，书中没有相关内容展示。 ### 4.3 run-pen/systemready目录 用于体验Arm SystemReady的运行环境, 参考https://developer.arm.com/Architectures/Architectural%20Compliance%20Suite#Technical-Information. 1. 安装swtpm(如果truncate,unzip,xz等命令不存在，也需要先安装) ``` sudo apt install -y swtpm swtpm-tools ``` 2. 下载预编译的acs live image: 在build-pen目录下，执行pen_download.sh脚本，下载systemready的acs工具预编译镜像。 ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_download.sh acs-image ``` 3. 编译测试用的固件: ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_build.sh uefi-sysr ``` 4. 运行sysr.sh脚本，启动qemu，加载uefi和kernel镜像。 ``` robin@YBBJ0042:~/chuanpen/run-pen/systemready$ ./sysr.sh ``` 5. 再开一个terminal，执行telnet: ``` robin@robinlenovo2:~$ telnet localhost 8888 ``` 注意：在目前使用arm的acs live image中，其os没有添加tpm2的相关驱动，因此不支持tpm2的相关测试。 ### 4.4 run-pen/sata & run-pen/usb & run-pen/nvme目录 分别测试sata, usb, nvme的运行环境，这三个运行环境方法一样，下面以sata为例： 1. 运行sata.sh脚本，会自动启动qemu，加载UEFI和kernel镜像。
``` robin@robinlenovo2:~/chuanpen/run-pen/sata$ ./sata.sh normal ``` 2. 再开一个terminal，执行telnet: ``` robin@robinlenovo2:~$ telnet localhost 8888 ``` ### 4.5 run-pen/pcie目录 使用Qemu教学用的PCIe设备edu来进行实验。编译BookVirtQemu的过程从略，采用类似base脚本的方式运行： 1. 运行pcie脚本，会自动启动qemu，加载UEFI和kernel镜像。
``` robin@robinlenovo2:~/chuanpen/run-pen/pcie$ ./pcie.sh log ``` 2. 再开一个terminal，执行telnet: ``` robin@robinlenovo2:~$ telnet localhost 8888 ``` 可以从log日志(/log/ap.log)中查看pcie设备驱动的运行信息。 ### 4.6 run-pen/oprom目录 添加了e1000e，并为其编写了示例的oprom代码。编译BookVirtQemu的过程从略，但是oprom需要编译。主要步骤： 1. 编译oprom代码 ``` robin@YBBJ0042:~/chuanpen/build-pen$ ./pen_build.sh oprom-demo ``` 2. 运行oprom脚本，会自动启动qemu，加载UEFI和kernel镜像。
``` robin@robinlenovo2:~/chuanpen/run-pen/oprom$ ./oprom.sh log ``` 3. 再开一个terminal，执行telnet: ``` robin@robinlenovo2:~$ telnet localhost 8888 ``` 可以从log日志(/log/ap.log)中查看oprom的运行信息。 ### 4.7 run-pen/pxe-http目录 提供了自动搭建pxe服务器和https服务器的脚本，以及测试pex启动和https启动的脚本。其测试过程较复杂，请参考书中的说明进行，这里只是简略介绍。 1. 运行pxe-http目录下的setup_env.sh和netdev.sh脚本，自动搭建pxe服务器和https服务器。 ``` robin@YBBJ0042:~/chuanpen/run-pen/pxe-http$ sudo ./setup_env.sh #自动搭建pxe服务器和https服务器 robin@YBBJ0042:~/chuanpen/run-pen/pxe-http$ sudo ./netdev.sh add #添加网络启动要用的网络设备 ``` 2. 运行netboot .sh脚本，测试pxe启动。
``` robin@YBBJ0042:~/chuanpen/run-pen/pxe-http$ ./netboot.sh ``` 3. 再开一个terminal，执行telnet: ``` robin@robinlenovo2:~$ telnet localhost 8888 ``` 环境搭建完毕，可以测试pxe启动和https启动了。 ## 5 附加功能 ### 5.1 添加静态工具 当前的编译框架中允许添加静态工具。 如果只是向 `build-pen/configs/ramdisk/extra-bin` 中添加静态工具，例如 `cxl`，通常不需要重新编译内核。 可执行： ``` robin@robinlenovo2:~/chuanpen/build-pen$ ./pen_build.sh busybox robin@robinlenovo2:~/chuanpen/build-pen$ ./pen_build.sh prepare_disk_image ``` 其中，busybox 会重新生成包含 extra-bin 工具的 ramdisk；prepare_disk_image 会将新的 ramdisk 写入最终磁盘镜像。 如果不确定当前内核、BusyBox 或 GRUB 是否为最新状态，也可以直接执行完整流程： ``` robin@robinlenovo2:~/chuanpen/build-pen$ ./pen_build.sh kernel ``` ## 参与贡献 1. Robin.Luo uefi_explorer@163.com 2. ## 更新记录 :low_brightness: 20241220 19:33 初步完成了框架，可以自动编译qemu、uefi和kernel，以及kernel的镜像打包
:low_brightness: 20251026 21:34 调整了qemu的编译命令，去除static参数，以防止不同环境对动态库的需求。
:low_brightness: 20251026 22:31 增加对virtio 9p的支持
:low_brightness: 20251230 21:11 提供systemready的测试示例
:low_brightness: 20260105 20:41 增加了usb/sata/nvme的测试示例
:low_brightness: 20260105 20:41 增加了usb/sata/nvme的测试示例
:low_brightness: 20260324 20:11 添加SecureBoot的演示支持
:low_brightness: 20260407 22:11 添加pcie设备驱动的演示支持
:low_brightness: 20260408 22:43 添加oprom的演示支持
:low_brightness: 20260409 22:01 添加pxe和http启动的脚本支持