QEMU 黑屏无串口输出:用 query-chardev 与 query-status 分流四类根因
命令敲下去,QEMU 进程起来了,终端却一片漆黑,连 OpenSBI 的启动横幅都没有——这是上手 RISC-V 虚拟平台时最容易卡住的第一道坎。QEMU 串口控制台接线:-nographic、-serial mon:stdio 与 -serial null 的区别 讲的是接线之前如何选后端,本篇解决接线之后的问题:同样是「没有串口输出」,背后可能是四套完全不同的机制,靠盯着终端发呆分辨不出来,必须让 QEMU 自己开口交代内部状态。全篇用一台 virt 机器、同一套内置 OpenSBI 固件,复现四类现场,并通过 QMP(QEMU Machine Protocol,QEMU 机器协议)的 query-chardev 和 query-status 两条查询命令取结构化证据,给出一条可以照抄的分流路径。
本文要回答的问题
- 终端黑屏时,怎么判断是串口接错了地方,还是客户机根本没开始执行?
query-chardev返回的vc、file、stdio三种后端,各自对应什么现象?- 串口接线完全正确,为什么依然一个字节都看不到?
cannot use stdio by multiple character devices这条报错是谁和谁在抢终端?- 排查这类问题有没有固定的取证顺序,而不是凭直觉改参数碰运气?
一、黑屏不是一种故障,而是四种现场
先建立一个关键认知:「没有输出」是一个观测结果,不是一个故障点。串口数据从客户机固件到你的终端,要经过虚拟 UART(通用异步收发器)发送寄存器、chardev 字符设备后端、宿主进程标准输出三道关口,任何一道断开,终端都是黑的。区别在于断开的位置不同,取证命令看到的东西完全不同。
本篇四组实验覆盖了实践中绝大多数静默现场:漏接串口导致后端默认为 vc(虚拟控制台)、-serial file 把输出写进文件、-S 冻结 CPU 让固件一条指令没跑、-nographic 与 -monitor stdio 同时抢占标准输入输出。下面这张流程卡给出排查顺序,核心思想是先查接线、再查 CPU、最后查终端复用冲突,每一步都有明确的判定字段,不靠猜。
读这张卡抓住一条主线:取证顺序不能反。query-chardev 回答「字节本该流向哪里」,是成本最低的第一步;只有它确认接线指向 stdio、终端链路本身没问题,才值得动用 query-status 往客户机执行层追查;而第四类现场进程根本没活下来,查询命令无从下发,只能直接读启动报错。
二、分流全景:一张排查图看清四条岔路
把四组实验的判定逻辑压成下面这张分流图。红色是现象与根因节点,蓝色是两个取证动作,橙色是对应修复,紫色是排查收尾后的预防动作。实际排障时从最左侧的红色现象节点进入,沿边标签上的字段值走,每个根因节点都只对应一个修复节点,不存在模糊地带。
图中上方两条岔路是「接线类」问题,特征是 QEMU 进程活着、QMP 有问有答,只是字节去了别处;中间一条是「执行类」问题,接线无可挑剔却依然静默,病根在 CPU 没有运行;最下方一条独立于查询链路,因为进程在初始化阶段就死掉了,属于「启动类」问题。三类问题的修复动作互不通用——把 -S 删掉救不了 vc 误接,把串口改接 stdio 也救不了 stdio 争抢,这正是必须先分流再动手的原因。
三、第一判据:query-chardev 看串口接在了哪里
前三组实验都通过 Unix domain socket 挂载 QMP,启动后下发查询命令,同时统计终端捕获文件里 OpenSBI 横幅出现的次数。终端实录如下,三组证据连续排列,方便对照字段差异。
第一组 vc-backend 模拟最常见的新手写法:用 -display none 关掉图形窗口,却没有加 -nographic,也没有显式 -serial。query-chardev 的返回里 serial0 的 filename 是 vc,即虚拟控制台——一个需要图形窗口承载的后端。窗口已经被 -display none 关掉,固件写出的每个字节都落进了一个看不见的缓冲区,终端侧横幅计数为 0。值得注意的是 QEMU 全程不报错,从进程状态看虚拟机「运行正常」,这也是这类问题最迷惑人的地方。
第二组 serial-file 是自动化脚本里的常见接法:-serial file:... 把串口明确导向日志文件。返回中 filename 为 file、label 为 serial0,终端横幅计数为 0,但文件内横幅计数为 1。输出一个字节都没丢,只是终端和文件两个落点你看的是前者。这类现场严格说不是故障,而是预期错位——想实时看输出就改接 stdio,想留日志就去文件里读,不要在终端前空等。
四、第二判据:接线正确再用 query-status 查 CPU
第三组 cpu-frozen 把接线类嫌疑彻底排除:启动参数用了 -nographic,query-chardev 明明白白显示 serial0 的 filename 是 stdio,终端链路完全正确。但横幅计数仍是 0。这时轮到 query-status 上场,返回的 "status": "prelaunch" 说明虚拟 CPU 还停在启动前的冻结态——元凶是命令行里的 -S 参数,它让 QEMU 创建好机器后不自动开始执行,等待调试器或监视器放行。
这组实验把「输出链路」和「执行状态」两件事干净地分离开了:UART 芯片完好、后端接线完好,只是 CPU 一条指令都没执行,固件自然没有机会往串口写任何东西。修复有两个方向,交互式调试场景下去掉 -S 让虚拟机直接跑起来;如果保留 -S 是为了等 gdbstub 连接,那就连上调试器后继续执行,或在 QEMU 监视器入门:运行时掌控虚拟机的控制通道 介绍的监视器里执行 cont,横幅立刻就会出现。
五、启动即死:stdio 被多个字符设备抢占
第四组现场走不到任何查询步骤,因为 QEMU 在初始化阶段就退出了。-nographic 本身已经把第一路串口接到 stdio,再叠加一个 -monitor stdio,等于让两个字符设备前端同时独占同一个标准输入输出,QEMU 直接拒绝启动。
日志里的两条报错要连起来读:cannot use stdio by multiple character devices 是总因,指出 stdio 不能被多个字符设备复用;could not connect serial device to character backend 'stdio' 是后果,串口连接后端失败,进程以退出码 1 终止。修复方式是给监视器另找一条通道:要么删掉 -monitor stdio,靠 -nographic 隐含的 mux 复用,用 Ctrl+A C 在串口和监视器之间切换;要么把监视器挂到 QMP socket 上,终端留给串口专用。四组现场的判据汇总如下。
| 现场 | query-chardev 关键字段 | query-status | 终端横幅计数 | 根因类别 | 修复动作 |
|---|---|---|---|---|---|
| vc-backend | filename: vc | 可正常查询 | 0 | 接线类 | 改用 -nographic 或 -serial mon:stdio |
| serial-file | filename: file | 可正常查询 | 0(文件内为 1) | 接线类 | 改接 stdio,或直接读日志文件 |
| cpu-frozen | filename: stdio | prelaunch | 0 | 执行类 | 去掉 -S,或监视器执行 cont |
| stdio-conflict | 进程启动即退出,无法查询 | 无法查询 | 无进程 | 启动类 | 删除 -monitor stdio,监视器改走 QMP |
排查时可以把 QMP 查询封装成固定动作:启动命令里挂一个 -qmp unix:./qmp.sock,server,nowait,然后用 nc -U ./qmp.sock 连上,先发送 {"execute":"qmp_capabilities"} 进入命令模式,再依次下发 query-chardev 与 query-status。这套手法与 QEMU 用户态网络:SLiRP 端口转发与宿主机互通 里用 QMP 管理运行时设备的思路一致,都是不打断虚拟机就能取回内部状态。每个参数的逐段含义还可以对照 QEMU 命令行参数精读:一条启动命令的逐段注解。
代码获取:本篇四组实验的可复现脚本见公开仓库 derekzhuo/geek-doc.cn 的
experiments/qemu-no-serial-output/。克隆后在该目录执行bash run.sh即可依次复现 vc 误接、文件后端、CPU 冻结与 stdio 冲突四种现场,脚本自动通过 QMP 采集查询结果并统计 OpenSBI 横幅计数,输出与本篇两处终端实录逐行对应。
实验环境
- 机器/系统:macOS 本机(Darwin 25.5.0)
- 工具版本:QEMU 11.1.2(全系统模拟
qemu-system-riscv64,内置 OpenSBI 固件-bios default)、nc(与 QMP Unix domain socket 交互) - 日期:2026-11-20
- 完整命令:四组启动与 QMP 查询均封装在公开仓库
experiments/qemu-no-serial-output/run.sh,执行方式bash run.sh,原始输出即本篇两处终端实录引用的日志
这一篇在知识体系里的位置
本篇是串口主题的「排错侧」。往基础侧走,QEMU 串口控制台接线 建立了 UART 与 chardev 的两层模型,讲清 stdio、mux、null 三种后端如何选择,本篇则在模型之上给出静默现场的分流判据;往控制面走,query-status、query-chardev 与 cont 都属于监视器和 QMP 能力,完整命令体系在 QEMU 监视器入门 展开;往参数侧走,-S、-nographic、-serial、-monitor 的逐段注解见 QEMU 命令行参数精读。掌握这条「先查接线、再查执行、最后查资源争抢」的取证顺序后,后续 gdbstub 调试、裸机程序加载等实验遇到无输出时,都可以用同一套查询命令在几分钟内定位断点层级。
总结
QEMU 黑屏无串口输出不是单一故障,而是四类现场的共同外观:query-chardev 显示 vc 说明输出进了被关闭的虚拟控制台,显示 file 说明字节完好地躺在日志文件里,两者都是接线类问题,改挂 stdio 即可;接线显示 stdio 却仍静默时,query-status 的 prelaunch 会指出 -S 冻结了 CPU,固件根本没跑;若进程启动即死并报 cannot use stdio by multiple character devices,则是 -nographic 与 -monitor stdio 争抢终端,删掉其一、让监视器改走 QMP 就收敛。记住这条取证链:先问接线,再问 CPU,最后问终端归谁——让 QEMU 的查询命令交代状态,而不是让猜测消耗时间。