摘要：本文系统梳理 QEMU 源码的目录结构，从顶层目录概览、核心子目录详解、构建系统与辅助目录三个层面展开。重点介绍 target/、tcg/、hw/、softmmu/、include/、qom/ 与 qapi/ 等关键目录的职责划分，帮助开发者快速定位代码、理解模块间依赖关系，为源码阅读与二次开发打下基础。
1. 引言
QEMU 是一款功能强大的开源模拟器与虚拟机监控器，支持多种 CPU 架构与设备模拟，被广泛应用于系统开发、嵌入式调试、云计算与虚拟化测试等场景。对于希望深入理解 QEMU 工作原理、参与二次开发或进行源码阅读的开发者来说，熟悉其源码目录结构是第一步。QEMU 的源码规模庞大、模块众多，目录组织方式直接反映了其架构设计思路：target/ 承载架构差异，tcg/ 负责动态翻译，hw/ 实现设备模拟，softmmu/ 提供系统级公共逻辑，qom/ 与 qapi/ 则构成对象模型与管理接口。本文将从顶层目录、关键子目录和核心模块三个层面，系统梳理 QEMU 源码的组织方式，帮助读者建立整体认知，为后续的源码阅读与二次开发打下坚实基础。
2. 顶层目录概览
QEMU 源码根目录下包含多个顶层目录与文件，它们各自承担不同的职责。下表列出了主要顶层目录及其作用：
| accel/ | 加速器相关代码，如 KVM、TCG、Hax 等 |
| audio/ | 音频后端与音频设备模拟 |
| block/ | 块设备层，包括块驱动、I/O 调度与快照 |
| chardev/ | 字符设备模拟，如串口、并口 |
| configs/ | 各目标架构的默认配置文件 |
| crypto/ | 加密与哈希相关实现 |
| disas/ | 反汇编器，用于调试输出 |
| docs/ | 开发文档与用户手册 |
| fsdev/ | 文件系统设备（9p）相关代码 |
| gdb-xml/ | GDB 远程调试所需的 XML 描述文件 |
| hw/ | 硬件设备模拟，按总线与设备类型划分 |
| include/ | 公共头文件，按模块分子目录 |
| io/ | 通用 I/O 通道与网络服务框架 |
| libdecnumber/ | 十进制浮点运算库 |
| linux-headers/ | Linux 内核头文件副本，用于编译 |
| migration/ | 虚拟机迁移与快照保存/恢复 |
| monitor/ | QEMU 监视器（HMP/QMP）实现 |
| nbd/ | NBD（Network Block Device）客户端与服务端 |
| net/ | 网络后端与网络设备模拟 |
| pc-bios/ | 预编译的固件与 BIOS 镜像 |
| plugins/ | TCG 插件接口与示例 |
| python/ | QEMU 自带的 Python 工具与库 |
| qapi/ | QAPI 定义文件，用于生成 QMP 接口 |
| qobject/ | QEMU 对象模型（QOM）基础数据结构 |
| qom/ | QEMU 对象模型核心实现 |
| replay/ | 执行记录与回放（record/replay） |
| roms/ | 外部固件与 BIOS 源码子模块 |
| scripts/ | 构建、测试与辅助脚本 |
| scsi/ | SCSI 子系统相关代码 |
| semihosting/ | 半主机（semihosting）支持 |
| slirp/ | 用户态网络协议栈（libslirp） |
| softmmu/ | 系统模式（softmmu）公共代码 |
| storage-daemon/ | QEMU 存储守护进程入口 |
| target/ | 各目标 CPU 架构的翻译与执行逻辑 |
| tcg/ | Tiny Code Generator，动态二进制翻译核心 |
| tests/ | 单元测试、集成测试与工具测试 |
| tools/ | 辅助工具，如 qemu-img、qemu-nbd |
| trace/ | 跟踪（trace）框架 |
| ui/ | 用户界面后端，如 GTK、SDL、VNC、SPICE |
| util/ | 通用工具函数，如内存分配、字符串处理 |
3. 核心子目录详解
在顶层目录中，有几个目录对理解 QEMU 的架构最为关键，下面逐一展开说明。
3.1 target/：CPU 架构支持
target/ 目录按 CPU 架构分子目录，每个子目录包含该架构的 CPU 定义、指令翻译规则、系统寄存器模拟等代码。常见的子目录包括：
- target/i386/：x86 与 x86-64 架构支持。
- target/arm/：ARM 与 AArch64 架构支持。
- target/riscv/：RISC-V 架构支持。
- target/loongarch/：LoongArch 架构支持。
- target/mips/：MIPS 架构支持。
- target/ppc/：PowerPC 架构支持。
每个架构子目录下通常包含 cpu.h、helper.c、translate.c 等文件，分别负责 CPU 状态定义、辅助函数和指令翻译。
3.2 tcg/：动态二进制翻译核心
tcg/ 是 QEMU 动态翻译引擎的核心，负责将目标架构的指令翻译为宿主机可执行的中间代码。其主要子目录包括：
- tcg/i386/、tcg/aarch64/ 等：宿主机后端代码生成。
- tcg/optimize.c：中间代码优化。
- tcg/tcg.c：TCG 核心逻辑，包括基本块管理、寄存器分配等。
3.3 hw/：硬件设备模拟
hw/ 目录按设备类型和总线组织，是设备模拟代码的集中地。常见子目录包括：
- hw/arm/、hw/riscv/ 等：特定架构的板级设备。
- hw/block/：块设备，如 virtio-blk、NVMe。
- hw/char/：字符设备，如串口。
- hw/net/：网络设备，如 virtio-net、e1000。
- hw/pci/：PCI 总线与 PCI 设备。
- hw/virtio/：virtio 设备家族。
- hw/display/：显示设备，如 VGA、virtio-gpu。
3.4 softmmu/：系统模式公共代码
softmmu/ 目录包含系统模拟模式下的公共逻辑，例如内存管理、中断控制器、设备总线初始化等。它是连接 CPU 核心、设备模拟和监视器的枢纽。
3.5 include/：公共头文件
include/ 目录存放所有模块共享的头文件，其子目录结构与源码目录基本对应。例如：
- include/hw/：设备模拟相关头文件。
- include/qemu/：通用工具与数据结构头文件。
- include/qom/：对象模型头文件。
- include/sysemu/：系统模拟相关头文件。
3.6 qom/ 与 qapi/：对象模型与接口定义
qom/ 实现了 QEMU 对象模型（QOM），这是设备与对象动态创建、属性访问的基础框架。qapi/ 则存放 QAPI 模式定义文件，用于自动生成 QMP（QEMU Machine Protocol）的服务器端与客户端代码，是外部管理 QEMU 的主要接口。
4. 构建系统与辅助目录
QEMU 使用 Meson 作为构建系统，根目录下的 meson.build 是构建入口。此外，以下几个目录在开发过程中也经常涉及：
- scripts/：包含代码格式化、补丁检查、构建辅助等脚本。
- tests/：包含 qtest、unit、avocado 等测试框架与用例。
- tools/：提供 qemu-img、qemu-nbd、qemu-io 等命令行工具。
- docs/：包含开发者文档、系统架构说明与用户手册。
5. 总结
QEMU 的源码目录结构体现了其模块化设计思想：target/ 负责架构差异，tcg/ 负责动态翻译，hw/ 负责设备模拟，softmmu/ 负责系统级公共逻辑，qom/ 与 qapi/ 提供对象模型与管理接口。理解这些目录的职责划分，有助于快速定位代码、理解模块间依赖关系，并为后续的二次开发打下坚实基础。
6. 参考资料
以下资料覆盖 QEMU 官方文档、源码仓库以及架构分析类技术文章，可作为进一步阅读与深入研究的入口：
- QEMU 官方文档：https://www.qemu.org/docs/，涵盖系统模拟、用户模式、设备模拟与开发指南等权威说明，是查阅目录结构与模块职责的第一手资料。
- QEMU 源码仓库：QEMU / QEMU · GitLab，官方主仓库，可结合本文目录梳理直接阅读各模块源码，验证目录职责划分。
- QEMU Internals 系列（QEMU 官方 Wiki）：Making sure you're not a bot!，从整体架构角度介绍 TCG、设备模拟与系统模式等核心机制，有助于理解目录背后的设计动机。
- 《QEMU, a Fast and Portable Dynamic Translator》（Fabrice Bellard 论文）：https://www.usenix.org/legacy/event/usenix05/tech/general/full_papers/bellard/bellard.pdf，QEMU 作者关于动态二进制翻译的经典论文，是理解 tcg/ 目录设计原理的重要参考。
- QEMU 架构分析技术博客（QEMU 源码分析系列）：https://www.qemu.org/community/，社区博客与邮件列表汇聚了大量源码分析文章，可帮助读者从实战角度理解各目录的协作方式。
