整理标注为 20251217 的草稿时我意识到内容已经不只是简单的 RISC-V 启动记录。这几年围绕 RISC-V 和 QEMU 的讨论从开放指令集能不能用变成了如何更快地跑起来、更准确地调试、更可靠地集成到日常开发流程里。模拟器的角色也因此发生了微妙变化——它不再是没拿到开发板之前的临时替代品而是一个真正意义上的虚拟验证环境可以随时打断执行、查看每一个处理器状态位、甚至主动注入异常来观察系统的行为。这份内容就当作一次完整的过程复盘把从零搭建 RISC-V QEMU 环境的关键环节、坑点以及背后逻辑一起梳理清楚。1. RISC-V 与 QEMU 的组合解决的其实是尽早调试的问题1.1 为什么 RISC-V 项目普遍习惯从模拟器起步RISC-V 的指令集是开放的但它并不是一个脱离现实的抽象标准。真正要跑系统级软件你仍然需要一个执行平台。买开发板当然可以但硬件调试的启动周期很长固件、内核、驱动这些层面的问题往往在没有硬件之前就存在了。QEMU 在 RISC-V 生态里的价值就是把这些还没有硬件就已经存在的问题提前暴露出来。无论你是裸机开发、跑 RTOS、裁剪 Linux 内核还是在做编译器后端验证QEMU 都能提供一个接近真实机器行为的运行环境。更重要的是虚拟平台不会因为反复烧写、异常断电而损坏这在高频迭代的场景下是非常实际的效率优势。另外RISC-V 的处理器定制自由度很高。同一个指令集下不同核的中断控制器、内存映射甚至特权级行为都有差异。QEMU 默认提供的 virt 机器本质上是一套标准的虚拟参考平台它把很多细节固定下来让软件层面的开发不需要依赖某款具体芯片的硬件手册就能推进。1.2 用户模式与系统模式两条不同的使用路径QEMU 对 RISC-V 的支持分两个层次。第一层是用户模式对应qemu-riscv64这个可执行文件作用是直接在主机上运行一个静态编译的 RISC-V 可执行文件。它不模拟完整机器而是把目标程序的系统调用翻译为主机系统调用适合验证纯计算逻辑、跑单元测试。第二层是系统模式对应qemu-system-riscv64这才是真正模拟整个 SoC 和内存系统的模式。内核、设备树、根文件系统、外设控制器都跟着一起被模拟出来。系统模式下你能观察到特权级切换、中断响应、外设访问这些底层行为这也是我这次记录的重点。选择哪条路径取决于你要解决的问题。比如做编译器优化验证用户模式最快但做内核驱动开发、Bootloader 定制、中断控制器验证就必须用系统模式。很多人第一次上手 QEMU 就卡在区分这两个模式上实际上只需要记住一句话用户模式只模拟 CPU 和系统调用系统模式模拟整台计算机。1.3 虚拟机的标准机器与真实开发板的关系QEMU 为 RISC-V 提供的最常用机器类型是 virt。它是一个为虚拟化设计的通用平台内存、外设、中断控制器的布局相对固定设备树由 QEMU 动态生成。virt 机器的好处在于通用性和稳定性适合快速启动、通用内核调试。但你也要理解一点virt 机器并不是某个真实开发板的完整镜像。真实板卡会有自己的内存映射差异、私有外设、特殊中断路由这些在 virt 机器上不一定复现。因此它更适合作为软件调试的第一站而不是最终硬件适配的唯一验证环境。我曾经遇到过一种情况内核在 QEMU virt 上完全正常换到真实开发板后网络驱动加载失败。原因就是真实板卡的 PCIe 枚举时序和 virt 机器差异较大。这个教训说明QEMU 可以帮你排除大量纯软件层面的问题但硬件相关的问题终究需要在硬件上验证。两者配合才是一个健康的 RISC-V 开发流程。2. QEMU 编译落地发行版自带版本与源码构建的实际差距2.1 为什么我最终选择从源码编译 QEMU传统发行版的软件源里基本都带 QEMU直接安装看起来很省事。但 RISC-V 的支持迭代速度非常快发行版自带的 QEMU 版本往往滞后半年甚至更久。如果你恰好需要一项新加入的 RISC-V 扩展支持或者某个 virt 平台的外设修正老版本就可能成为挡路的坎。举个例子RISC-V 的向量扩展支持在早期版本里只是个雏形很多实现细节到后续版本才逐渐稳定。如果只是跑一个最小启动流程旧版问题不大但要验证向量指令的行为旧版 QEMU 的模拟结果可能直接误导你。所以我倾向于从源码构建一个特定版本的 QEMU至少保证行为可预期、可追溯。另一个理由是构建选项的可控性。发行版的 QEMU 编译时通常会附带大量其他架构的支持体积大、依赖多。而自己编译时完全可以只保留 RISC-V 相关的目标缩短编译时间也能减少潜在的依赖冲突。2.2 configure 参数与依赖库处理的完整过程QEMU 的构建流程本质上是一个经典的 Autotools/C 项目流程configure 阶段会根据主机环境检查一系列依赖。RISC-V 目标本身不要求太多额外东西但你至少要保证以下基础依赖存在glib、pixman、zlib以及构建工具链如 ninja、python3。如果缺了某个库configure 阶段往往不会立即报错而是在生成配置头文件时输出一段让人摸不着头脑的 message。我自己编译时的参数大概是这样./configure \ --prefix/opt/qemu-riscv \ --target-listriscv64-softmmu,riscv32-softmmu \ --disable-werror \ --enable-debug--target-list这里做减法非常重要。默认情况下 QEMU 会编译几十种目标架构时间和磁盘占用都非常可观。只保留riscv64-softmmu和riscv32-softmmu编译速度会快很多。--disable-werror是为了兼容新版编译器带来的告警因为某些版本的 QEMU 源码在老编译器或特别新编译器下会有构造告警而默认启用了-Werror会让整个构建直接中断。加上这个参数后告警只是告警不至于阻塞构建过程。--enable-debug会保留更多调试符号对后续用 GDB 调试硬件状态有帮助。如果只是日常运行可以不加因为调试符号会显著增加 QEMU 自身的体积。configure 通过之后执行编译make -j$(nproc) make installQEMU 的编译比较吃内存建议并发参数不要超过物理核心数太多否则有概率触发 OOM 导致编译失败。第一次编译时如果报glib-2.56 or newer required直接确认系统里的 glib 开发包是否安装比如 pkg-config 是否指向了正确的库路径。这种问题通常不是版本不够新而是开发头文件缺失。2.3 多架构需求下的目标裁剪与动态软链接如果你的 RISC-V 开发环境里同时还需要 ARM 或者其他架构支持可以在--target-list里用逗号追加。但我更习惯的做法是单独维护一个 RISC-V 专用目录避免多架构构建之间的配置参数互相干扰。编译安装完成后需要注意 PATH 顺序。如果系统里同时存在发行版安装的 QEMU 和源码安装的 QEMU两者版本完全可能不一样。我在调试时踩过这个坑进入终端后执行qemu-system-riscv64结果调用的仍是系统老版本导致内核启动行为不一致。后来我统一在项目脚本里显式写明 QEMU 的绝对路径不再依赖 PATH 解析问题立刻消失。对于经常同时使用交叉编译工具链的情况还可以顺手把riscv64-linux-gnu-*工具链的路径加入环境变量。虽然这一步和 QEMU 本身无关但几乎每个 RISC-V 项目都要用到它提前配置能省去后续大量时间。3. 从零启动一个最小 RISC-V 系统OpenSBI、Linux 内核与 rootfs 的三层接力3.1 启动链路的基本分工谁在什么时候干活的RISC-V 系统模式的启动过程和 x86 有很大区别。x86 平台有固件、有传统 BIOS/UEFI 约定而 RISC-V 的启动更依赖固件和内核之间的显式约定。QEMU virt 平台默认会加载一个 OpenSBI 固件它运行在最高的机器模式也就是 M 模式下负责最基本的硬件初始化和运行时服务然后跳转到 S 模式运行 Linux 内核。这里要理解的关键点是特权级。RISC-V 有多种特权模式机器模式权限最高监管者模式次之用户模式最低。OpenSBI 跑在 M 模式Linux 内核跑在 S 模式这意味着内核不能直接访问所有硬件资源需要借助 OpenSBI 提供的接口。QEMU 把这种多级特权关系都模拟出来了因此你在启动日志里能看到完整的固件加载和跳转过程。QEMU 启动参数里-kernel指定的文件会被加载到特定内存地址。默认情况下 QEMU 会结合 OpenSBI 的跳转约定完成加载你不需要手动计算物理地址。但如果完全不用固件也就是传-bios none就需要自己在裸机代码里处理所有 M 模式的初始化门槛高不少。3.2 内核镜像与根文件系统的准备为了让最小系统跑起来我们需要三样东西内核镜像、设备树、根文件系统。设备树在 QEMU virt 平台上由 QEMU 自动生成只要内核开启了对应驱动支持通常不用手动指定。内核编译时如果使用默认的 RISC-V 配置很多 virt 平台相关驱动会作为模块编译而不是内建到内核镜像里。对于 QEMU 快速启动来说最好把 virtio 相关的驱动直接编进内核。因为 QEMU 的块设备和网络设备默认都是 virtio 类型如果驱动是模块启动过程中还需要先从磁盘加载模块形成一个先有鸡还是先有蛋的循环。实际操作中常见做法是make ARCHriscv CROSS_COMPILEriscv64-linux-gnu- defconfig make ARCHriscv CROSS_COMPILEriscv64-linux-gnu- menuconfig make ARCHriscv CROSS_COMPILEriscv64-linux-gnu- -j8 Image在 menuconfig 里需要确认VIRTIO_PCI、VIRTIO_BLK、VIRTIO_NET都编译进内核。defconfig 有时候不会把网络功能全部打开如果后续要测试网络启动流程这一步特别容易忽略。根文件系统可以用最小的 busybox 来构造。交叉编译完 busybox 后安装目录就是最终的 rootfs 内容。再补充/dev、/proc、/sys这些挂载点目录以及一个 inittab 文件mkdir -p rootfs/{bin,sbin,etc,dev,proc,sys} cp -a _install/* rootfs/ echo console::respawn:/bin/sh rootfs/etc/inittab find rootfs | cpio -o -H newc --ownerroot:root | gzip rootfs.cpio.gz这里使用 initramfs 方案意思是内核启动时直接把 cpio 压缩包展开到内存里作为根文件系统。优点是简单可靠不需要额外的磁盘镜像非常适合快速验证。3.3 完整启动命令与预期日志万事俱备后启动命令如下qemu-system-riscv64 \ -M virt \ -smp 2 \ -m 512M \ -kernel linux/arch/riscv/boot/Image \ -initrd rootfs.cpio.gz \ -append rdinit/sbin/init consolettyS0 \ -nographic启动后预期能看到 OpenSBI 的版本信息、内核解压日志最终得到一个可交互的 shell。如果你的内核是经过压缩处理的 Image.gzQEMU 也可以直接识别。但使用 Image 格式最稳妥避免解压逻辑带来的额外变量。这里-append里的consolettyS0是关键它告知内核使用串口作为控制台。QEMU virt 机器的串口在启动时会被映射到标准输入输出配合-nographic参数我们不需要图形窗口就能直接操作虚拟机的控制台。这套流程如果正常跑通恭喜你已经拥有一个最小可用的 RISC-V 虚拟开发环境。再往上加网络、加存储、加设备树定制都只是在这个基础上做增量。3.4 网络端口的挂载与宿主机互访很多场景下内核启动只是第一步真正跑业务时会需要网络通信。QEMU 提供了多种网络方案最常用的是 user 模式网络。virt 机器默认带一个 PCIe 总线我们可以在命令里追加网络设备-device virtio-net-pci,netdevnet0 \ -netdev user,idnet0,hostfwdtcp:127.0.0.1:2222-:22这样就把宿主机的 2222 端口转发到虚拟机的 22 端口。如果系统里启动了 SSH 服务就可以直接远程进入虚拟机。这种做法的好处是不需要额外的管理员权限也不涉及虚拟网桥配置特别适合本地调试。但要注意user 模式网络的性能一般大流量吞吐会明显慢于网桥模式。如果要做网络性能测试应该改用-netdev tap并配合网桥配置。开发阶段用 user 模式足够性能不是首要考虑因素。4. 把 QEMU 当作可暂停的评估板GDB 单步、CSR 与中断现场4.1 让 QEMU 在启动入口等待调试器模拟器相比真实开发板最大的优势大概就是可以暂停时间。通过在启动命令里加上-s和-S两个参数可以做到系统在刚开始执行前就停在第一个指令处等待 GDB 连接-s表示开启 1234 端口的 GDB 服务-S表示启动时不自动执行。然后使用支持 RISC-V 架构的调试器连接riscv64-linux-gnu-gdb vmlinux (gdb) target remote :1234如果觉得 GDB 版本不够新导致识别 RISC-V 架构有问题也可以安装多架构版本。连接成功后_start处已经停住这时随便下断点、单步、查看寄存器都会非常顺手。和真实硬件最大的区别是这里的一切操作都不会烧坏任何东西。4.2 单步执行时的寄存器与 CSR 观察技巧RISC-V 的通用寄存器是 x0 到 x31其中 x0 永远是 0写它的操作会被丢弃。代码里常见的 ra、sp、gp 这些名字是 ABI 别名对应不同的 x 寄存器。GDB 连接后执行info registers可以快速浏览这些寄存器。除了通用寄存器RISC-V 还有很多 CSR 寄存器例如 mstatus、mtvec、mcause、mepc、satp 等。它们控制着中断向量、页表转换、特权级状态在调试系统级代码时比通用寄存器更重要。GDB 对 CSR 的支持程度取决于调试器版本和架构描述文件有些 CSR 通过info registers是看不到的。这时候可以切换到 QEMU 的 monitor 界面。在-nographic模式下按Ctrl-A然后按C就会进入 QEMU 的 monitor 命令行在那里输入info registers能看到的寄存器信息比 GDB 里完整得多包括几乎全部的 CSR。看完之后用quit或再次Ctrl-A C切回串口终端。我在调一个异常处理问题时就是靠 monitor 的info registers确认了 mcause 的值指向的异常类型才知道固件代码把异常委托给 S 模式之后S 模式的中断使能位并没有正确打开。这种问题如果只盯着通用寄存器很难快速定位。4.3 主动注入异常验证中断向量与返回路径调试中断处理代码时不一定非要借助外部设备触发中断。QEMU monitor 里可以通过向 PTB 寄存器写值或者直接修改 CSR来模拟异常发生的瞬间。最简单的验证方式是在目标代码里设置一个断点让程序在某个位置停下来然后用 GDB 直接修改 pc 寄存器的值使其跳往一个非法地址人为制造取指异常。执行继续后系统会进入异常处理流程此时观察 mcause 和 mepc就能确认异常向量是否被正确响应。我更常用的做法是配合-d int,cpu_reset参数启动 QEMU它会在日志里输出每次中断和异常的发生记录。配合 course 日志可以精确定位中断嵌套、优先级反转这类难缠问题。日志量会比较大建议先定向输出到文件再分析。5. 性能边界与测试误区什么时候 QEMU 会骗你5.1 TCG 动态翻译机制带来的性能错觉QEMU 在默认情况下使用 TCG 机制执行客户机代码。TCG 会把 RISC-V 指令翻译成宿主机指令然后在宿主机上执行。这种动态翻译机制在功能上做到了高度兼容但在性能表现上并不等同于真实 CPU 模拟。启动一个最小 Linux 系统QEMU 的耗时通常比真实开发板慢一到两个数量级。有些基准测试在模拟器上的相对表现和真实硬件完全不同原因在于外围设备的行为差异、缓存行为的缺失以及翻译块边界的影响。如果你只是验证功能逻辑QEMU 的性能完全足够。但如果看到某个优化方案在 QEMU 上表现出显著的性能提升先不要急着高兴至少要在另一套执行环境中做对照验证。性能对比的结论放在模拟器上样本量越大越容易得出错误推论。5.2 多线程模拟参数与执行确定性QEMU 支持多线程 TCG 模式通过-accel tcg,threadmulti可以启用让多核客户机在多个宿主线程上并行执行。多核模拟性能会有提升但也带来新的不确定性中断响应顺序、共享变量访问时序都会出现更多变化。对于调试场景我反而推荐使用单线程模式-accel tcg,threadsingle。单线程模式下执行顺序是确定性的同样的输入重复运行会得到相同的行为序列这对复现 bug 非常有帮助。多线程模式下问题可能时隐时现排查难度会高很多。如果你想进一步追求执行确定性可以配合-icount参数对指令计数进行控制它会强制 QEMU 按客户机指令数推进虚拟时间。这对模拟中断时序、外设定时这类场景很有用但是会显著降低吞吐性能不适合普通日常启动。5.3 基准测试的真实性困境QEMU 的另一个问题是虚拟时间与真实时间的差距。客户机里看到的时间戳计数器、定时器中断在 QEMU 里往往以另一种方式模拟出来。如果你的测试程序用clock_gettime这类接口来获取时间你会得到客户机视角的虚拟时间它不等于宿主机实际消耗的时间。对于嵌入式 NVRAM、实时操作系统这类强时间依赖的软件QEMU 的模拟结果只能作为参考。例如一个任务调度器的截止时间判断可能在 QEMU 上显得很宽裕换到真实硬件上却频繁超时原因就在于中断延迟和定时器精度的差异。所以我的习惯是功能验证和逻辑调试在 QEMU 上跑涉及时序、功耗、性能指标的测试一律留到真实硬件或 FPGA 原型上做。两者分工明确才不会互相误导。下表是我自己总结的适用场景参考任务类型QEMU 适用性说明内核启动流程验证高便于观察启动日志修改代码快速迭代设备驱动逻辑调试中可使用 virtio 设备但真实时序有差异中断处理代码验证中可注入异常但嵌套时序未必精确性能基准测试低不具备真实缓存和外设性能特征功耗评估低完全不适合与硬件功耗无直接对应多核调度逻辑开发中可跑通流程单线程模式下更可预测6. 夹在文档与源码之间的实际经验写到这里我想把几个容易忽略的具体操作细节单独拎出来这些内容在官方文档里分散在不同角落通常要踩过坑才有印象。首先是启动参数里的-bios。QEMU RISC-V 默认会加载一个内嵌的 OpenSBI 固件。如果你有自己的固件例如想调试自己移植的 OpenSBI 版本可以用-bios /path/to/fw_jump.elf替换。不加这个参数的好处是开箱即用但要意识到默认固件版本的微妙差异。其次是内核镜像格式。Linux 内核为 RISC-V 编译产物至少有两种格式分别是 ELF 格式的 vmlinux 和 raw 格式的 Image。QEMU 对 ELF 和 raw 格式都能加载但行为略有不同ELF 会按照文件里的段信息加载raw 则按固定偏移加载。调试时用 vmlinux 配 GDB 更友好启动时可以指定 Image两者不冲突甚至可以先用 Image 启动然后用 vmlinux 加载调试符号。还有一个是-nographic与-serial的关系。加了-nographic之后串口会被重定向到标准输入输出此时如果再指定-serial file:output.log串口就会输出到文件里反而在终端看不到交互界面。有些自动化脚本会同时用这两个参数结果卡在等待输入上。正确做法是二选一或者通过-monitor单独指定 monitor 通道。调试信息输出方面-d guest_errors参数值得常用。它会把客户机执行过程中访问的非法地址、异常指令记录到日志里。很多裸机程序的问题其实在第一次非法内存访问时就埋下了只是没有被注意到。关于内核启动参数earlycon在 RISC-V virt 平台上也可以尝试。它不需要完整的串口驱动初始化就能输出早期日志对定位内核早期崩溃非常有帮助。追加参数可以这样写-append earlyconuart8250,mmio,0x10000000 consolettyS0 rdinit/sbin/init0x10000000 是 QEMU virt 平台上默认 UART 的地址。如果平台不同这个地址可能变化但 virt 机器基本固定。这一步能省掉很多内核卡住没有任何输出的排查时间。我自己的体会是QEMU 作为 RISC-V 开发工具最大的价值反而不是省了买开发板的钱而是把所有跟系统初始化和底层执行相关的问题都变成可以用调试器和精确日志逐步审视的对象。对一个需要深入理解处理器行为的人来说这种透明度远比运行速度快几个点重要。后续你也可以按自己的业务需求在最小启动流程之上逐步叠加网络、图形、虚拟化等能力整个过程都值得完整记录成自己的系列笔记。