Codex CLI + config.yaml 配置踩坑实录：provider 字段和 api_key 优先级，文档没说清的两个坑我填了三遍
2026/10/8 23:22:01
做嵌入式，最怕两件事叠在一起：板子还没到，以及板子到了却烧录、接线、串口抢资源。CI 流水线更头疼——不可能给每个提交搞一块开发板。于是很多人会问：能不能在电脑里「假装」有一台 ARM / RISC-V 机器，把内核、根文件系统、甚至裸机固件先跑起来？
QEMU（Quick Emulator）就是干这个的：一套通用的开源机器模拟器 / 虚拟化器。它可以在你的 PC 上模拟完整计算机（CPU、内存、串口、网卡、Flash……），也可以在加速模式下接近原生速度跑虚拟机。对嵌入式开发者来说，它常常是「没板也能验证」的第一块踏板。
截至 2026 年 9 月，官网维护发布里较新的稳定版本为11.1.2（以 qemu.org/download 实时列表为准）。
- 官网：https://www.qemu.org
- 文档：https://www.qemu.org/documentation
- 源码镜像：github.com/qemu/qemu（正式投稿与发布说明请看官网）
- 许可：以仓库 LICENSE 为准（多为 GPL-2.0 等组合，产品使用请自行核对）
一、它到底是什么
名字有时被念成「Q-EMU」，项目定位写得很直白：a generic and open source machine emulator and virtualizer。
你可以把它理解成三种能力叠在一起：
| 能力 | 在干什么 | 嵌入式里常怎么用 |
|---|---|---|
| 全系统模拟 | 模拟一整台机器，启动 Guest OS / 固件 | 跑 ARM Linux、测启动脚本、联调用户态 |
| 用户态模拟 | 不模拟整机，只翻译「另一种 CPU 的程序」 | 在 x86 电脑上跑arm-linux-gnu编出来的二进制 |
| 虚拟化加速 | 同架构时借 KVM 等接近原生速度 | 服务器 / 桌面虚拟机（和嵌入式仿真是两条常用路） |
它不是 IDE，也不是交叉编译器。交叉工具链负责编出镜像；QEMU 负责在假机器上跑起来。两边经常成对出现：aarch64-linux-gnu-gcc编译 →qemu-system-aarch64启动。
| 等真机 | 只用交叉编译 | QEMU | |
|---|---|---|---|
| 能否执行 | 能，但依赖硬件到货 | 只能看「编过了」 | 能执行、能看串口日志 |
| 外设 | 真实 | 无 | 模拟常见串口/网卡/存储等 |
| CI | 难规模化 | 容易但测不深 | 易挂进流水线做冒烟 |
| 速度 | 真机快慢看板子 | — | 纯模拟偏慢；同架构+KVM 很快 |
二、三个常见误解
≠ 和 VirtualBox / VMware 是同一种东西。
消费级虚拟机产品偏「在 x86 上再开一台 x86 Windows/Linux」。QEMU 更通用：强调跨架构模拟（比如在 x86 笔记本上跑 ARM 机器），也可以配合 KVM 做高性能虚拟化。嵌入式文档里你更常碰到的是qemu-system-arm/qemu-system-riscv64这类命令。
≠ 模拟了就等于板上行为 100% 一致。
定时精度、Wi‑Fi/射频、特殊加速器、厂封 NPU、奇葩 Flash 时序——模拟机和真机总会有缝。QEMU 适合启动、驱动框架、文件系统、网络协议栈、应用逻辑的早期验证；量产标定、射频、极限时序仍要上真机。
≠ 「装了 QEMU 就会自动有板级支持」。
你要选对machine（机器型号）和CPU，还要有能在该机器上启动的镜像（内核 + rootfs，或带设备树的 zImage 等）。Zephyr、Linux、Buildroot、Yocto 文档里通常会写「推荐的 QEMU board / virt 机器」——按文档配对，比自己瞎猜-M参数省事。
三、架构：宿主机上跑一台假电脑
从下往上看，一次「跑起来」大致是这样：
| 层 | 干什么 |
|---|---|
| 宿主机 OS | Linux / macOS / Windows，提供进程、文件、真网卡 |
| QEMU | 翻译或加速 Guest 指令；模拟内存与外设模型 |
| 虚拟机器 | 你选的-M机器：UART、GIC、PCI、virtio 等 |
| Guest | Linux、RTOS、U-Boot、甚至裸机 demo |
全系统模式下，Guest 以为自己在操作真实硬件；其实读写的是 QEMU 实现的外设模型。串口常常接到你终端的 stdio，所以「板子上的 printk」会直接打在你笔记本黑窗口里——这是嵌入式同学最有体感的一刻。
TCG vs KVM（知道即可）：
- TCG（Tiny Code Generator）：把 Guest 指令动态翻译成宿主机指令，跨架构靠它，灵活但更慢。
- KVM（Linux）：Guest 与宿主机同架构时，让 CPU 硬件虚拟化接力，快很多。
嵌入式跨架构仿真，多半走 TCG；在 x86 服务器上开 x86 虚拟机，多半走 KVM。
四、嵌入式场景里它常出现在哪
| 场景 | 你在干什么 |
|---|---|
| 没板先跑 Linux | Buildroot / Yocto / OpenWrt 编出镜像，用virt等机器冒烟 |
| RTOS / Zephyr CI | 官方 board 列表里带 QEMU 的目标，PR 上就能跑 sample |
| 调试启动早期 | 配 GDB stub，看内核解压、挂根文件系统卡在哪 |
| 用户态翻译 | qemu-aarch64 ./my_app，快速试跑交叉编出来的程序 |
| 教学与分享 | 读者不必买板，也能复现「启动成功」的截图 |
五、谁适合用、谁不适合
多半会喜欢的：
- 板子紧缺、样品轮转慢，却要持续合代码
- 想把「能否启动 / 基础网络 / 基础存储」放进 CI
- 做内核、驱动框架、根文件系统，而不是只调射频
- 教学、写公众号、做分享——降低读者复现门槛
建议别神话的：
- 必须验证 Wi‑Fi 吞吐量、天线、产测校准
- 强依赖厂商闭源加速器，模拟器里根本没有对应模型
- 把「QEMU 上跑通」当成「量产可发货」——中间还差真机长跑与兼容性
六、怎么动手
先装好 QEMU
Linux 发行版一般有包装：qemu-system-arm、qemu-system-aarch64、qemu-system-riscv64等。版本以发行版为准；追新可看官网源码包。选一条「官方已经打通」的路径
- 想碰 Linux：Buildroot / Yocto 文档里的 QEMU 目标
- 想碰 RTOS：Zephyr 的
qemu_*board - 想碰最小：官方或社区的
virt机器 + 现成内核/rootfs 示例
先保证串口有打印
第一里程碑不是跑满业务，而是：QEMU启动 → 串口打印 → 能进 shell 或看到 RTOS banner。再挂调试器（可选）
QEMU 提供 GDB 接口后，用gdb-multiarch连上去，和真机远程调试体感接近。最后才谈加速与外设细节
先跑通，再纠结网络后端、virtio、共享目录——否则参数海洋会把人淹死。
七、和同类工具怎么并列理解
| 方案 | 一句话 |
|---|---|
| QEMU | 通用模拟 / 虚拟化，跨架构最常见 |
| 厂商模拟器 / ISS | 往往更贴某颗芯片，但不通用、不一定开源 |
| Renode | 偏物联网多节点、外设建模叙事强 |
| 真机 + CI 农场 | 最终权威，但贵、难维护 |
QEMU 的胜负手是：普及度、文档与周边生态、和开源构建系统的对接。它不是每颗芯片的完美替身，却是多数开源嵌入式项目默认会提到的那一个名字。
八、优缺点
优点
- 开源、跨平台、架构覆盖面大
- 能把「启动与基础功能」从真机依赖里部分解放出来
- 和 GDB、CI、Buildroot/Yocto/Zephyr 故事成熟
- 同一套工具，桌面虚拟化与嵌入式仿真都能碰到
缺点
- 跨架构纯模拟有时很慢
- 外设保真度参差不齐，射频与专有 IP 基本指望不上
- 参数多、机器多，新手容易卡在「镜像和
-M不匹配」 - 跑通 ≠ 量产验证结束
九、写在最后
下次再因为「板子还在路上」而停下手头验证时，不妨多问一句：这一步是必须用真实PCB板，还是只要需要QEMU模拟就行？