尧图网页设计 
1. 为什么我要用 AGENT 来搭 QEMU 实验台第一次接触 RISC-V AI 芯片验证的时候我踩过一个很典型的坑手头只有一份芯片手册和一块还没流片的 RTL想跑一个端到端的推理流程结果发现连最基本的启动环境都搭不起来。后来我意识到与其等硬件回来不如先用 QEMU 把整个软件栈跑通。但 QEMU 的配置项多到让人头皮发麻尤其是涉及 RISC-V 架构、PCIe 设备挂载、AI 加速器模拟这些环节手动敲命令几乎是在赌运气。这时候 AGENT 的价值就体现出来了。我这里说的 AGENT不是那种泛泛而谈的“智能体”概念而是指一套能自主执行任务、根据反馈调整策略、并且能调用外部工具链的自动化代理框架。把它用在 QEMU 环境搭建上核心逻辑是让 AGENT 去读配置、去试参数、去抓日志、去判断启动是否成功失败了就换一组参数重来。人只需要定义目标比如“拉起一块带 PCIe 接口的 RISC-V 虚拟平台能跑 Linux 并识别到 AI 加速器设备”剩下的脏活累活交给 AGENT 循环执行。这套思路解决的核心问题是环境搭建的试错成本太高而试错过程又高度重复。QEMU 的-machine、-cpu、-device、-bios、-kernel这些参数之间存在强耦合一个参数不对可能表现为内核 panic、设备树解析失败、PCIe 枚举卡死甚至 QEMU 直接段错误退出。传统做法是查文档、问社区、反复手敲一轮下来半小时没了。AGENT 的做法是把这些参数空间结构化让它自己去撞撞对了就记录下成功配置撞错了就分析日志里的错误模式缩小下一轮搜索范围。适合谁来参考这套方法如果你正在做 RISC-V 相关的芯片验证、驱动开发、系统软件移植或者你手头有一个 AI 加速器的 RTL 但还没有物理板卡这套 QEMU AGENT 的组合能帮你提前把软件栈跑起来。即使你只是对 RISC-V 感兴趣想在自己的机器上模拟一个带 PCIe 设备的平台这篇文章里的配置思路和避坑经验也能直接抄作业。我实测下来用 AGENT 驱动 QEMU 环境搭建把首次成功启动的时间从平均 3 到 4 小时压缩到了 40 分钟左右而且成功配置可以被固化下来后续换内核、换根文件系统、加设备都能在这个基线上快速迭代。下面我把整个设计思路、核心细节、实操过程和踩过的坑完整拆一遍。2. 整体设计与思路拆解2.1 为什么选 QEMU 而不是其他模拟器做 RISC-V AI 芯片的软件预研可选的模拟器其实不少比如 Spike、Renode、Gem5还有各种厂商自带的 ISS。我最终选 QEMU 作为主实验台理由很实际。Spike 是 RISC-V 官方参考模拟器指令级精度高但它本质上是个 ISA 模拟器外设模型非常有限PCIe 这种复杂总线拓扑基本没法模拟。Renode 在嵌入式外设模拟上很强但它的 RISC-V 支持成熟度不如 QEMU尤其是涉及多核、PCIe 枚举、ACPI 这些偏服务器侧的特性时坑比较多。Gem5 更偏向微架构研究跑一个完整的 Linux 启动流程慢到让人怀疑人生不适合做日常软件栈验证。QEMU 的优势在于它有一套成熟的virt机器模型支持 RISC-V 64 位支持 PCIe 总线支持设备树动态生成而且启动速度足够快。对于 AI 芯片验证来说我们关心的不是周期精确的指令时序而是软件能不能正确识别设备、驱动能不能加载、内存映射和中断路由对不对。QEMU 在这个层面上的抽象程度刚刚好。注意QEMU 的 RISC-Vvirt机器默认使用设备树DTB传递硬件信息而不是 ACPI。如果你的 AI 芯片驱动依赖 ACPI 枚举需要额外确认 QEMU 版本是否支持 RISC-V 的 ACPI 表生成目前这块支持还不完整建议优先走设备树路线。2.2 AGENT 在环境搭建中的角色定位很多人一听到 AGENT第一反应是“让大模型去写代码”。但在环境搭建这个场景里AGENT 的核心能力不是生成代码而是执行、观察、判断、调整这个闭环。我设计的 AGENT 工作流是这样的首先它读取一份结构化的配置模板里面定义了 QEMU 启动所需的各个参数维度比如机器类型、CPU 型号、内存大小、内核镜像路径、设备树附加项、PCIe 设备列表等。然后它按照当前参数组合拼出一条完整的 QEMU 命令行执行启动。启动过程中AGENT 会实时抓取串口输出匹配预设的成功标志比如内核打印出Welcome to Linux或者PCIe bus enumeration complete和失败模式比如Kernel panic、Unable to handle kernel paging request、PCIe link training failed。如果启动成功AGENT 把当前配置写入一个成功配置库并记录启动日志摘要。如果失败它根据错误模式调整参数。比如看到No valid device tree就去检查 DTB 路径和-dtb参数看到PCIe host bridge not found就去调整-device里 PCIe 控制器的挂载方式。这个调整策略可以基于规则也可以让大模型来决策但核心是不要让人类去逐条试错。这里有个关键设计决策AGENT 不直接修改 QEMU 源码也不动态生成设备树二进制。它只操作命令行参数和外部配置文件。这样做的好处是可控、可复现、可审计。每次成功的配置都是一条完整的 QEMU 命令任何人拿到这条命令都能复现同样的环境。如果让 AGENT 去改源码或者动态生成 DTB虽然灵活但复现成本会急剧上升出了问题也很难定位是 QEMU 本身的问题还是 AGENT 生成的内容有问题。2.3 参数空间的结构化拆解QEMU 启动 RISC-V 虚拟平台的参数可以分成几个层次我按耦合程度从高到低排列。第一层是机器与 CPU 层包括-machine virt、-cpu rv64或具体的 CPU 型号、-smp核数、-m内存大小。这一层决定了整个虚拟平台的骨架一旦确定后续设备都挂在这个骨架上。RISC-V 的virt机器支持rv64和rv32两种模式做 AI 芯片验证基本都用rv64因为现代 AI 加速器的驱动和运行时都假设 64 位地址空间。第二层是启动介质层包括-bios指定 OpenSBI 固件、-kernel指定 Linux 内核镜像、-initrd指定初始内存盘、-append传递内核命令行、-dtb指定设备树二进制。这一层的耦合点在于OpenSBI 的版本要和内核版本匹配设备树里的内存节点要和-m参数一致内核命令行里的console参数要和 QEMU 的串口设备对应。第三层是外设与总线层这是最复杂的部分包括 PCIe 主机桥、PCIe 设备、virtio 设备、串口、中断控制器等。RISC-Vvirt机器默认会生成一个 PCIe 主机桥但具体挂什么设备、怎么挂需要仔细配置。比如要模拟一块 AI 加速器可以用-device virtio-pci挂一个 virtio 设备也可以用-device pci-testdev挂一个测试设备或者用-device vfio-pci直通一个物理设备。不同的挂载方式对应的驱动和枚举流程完全不同。第四层是调试与追踪层包括-d系列参数输出 QEMU 内部日志、-trace开启特定事件的追踪、-monitor挂载 QEMU monitor 等。这一层在 AGENT 工作流里非常重要因为 AGENT 判断启动状态的主要依据就是这些日志输出。把这四层拆清楚之后AGENT 的搜索空间就从“无数种可能”变成了“每层几个到几十个选项的组合”。我实测下来第一层和第二层基本可以固定真正需要 AGENT 去试的主要是第三层和第四层。这样搜索效率会高很多。3. 核心细节解析与实操要点3.1 RISC-V virt 机器的 PCIe 拓扑到底长什么样很多人第一次用 QEMU 模拟 RISC-V 的 PCIe 设备时会下意识地按照 x86 的经验去配置结果发现设备死活枚举不出来。根本原因在于 RISC-Vvirt机器的 PCIe 拓扑和 x86 的默认拓扑不一样。在 QEMU 的 RISC-Vvirt机器里PCIe 主机桥是通过GPEXGeneric PCI Express Host Bridge实现的。它默认会创建一个根复合体Root Complex下面挂一个根端口Root Port再下面才是 PCIe 设备。这个拓扑在设备树里会体现为pci30000000节点里面包含interrupt-map、ranges、bus-range等属性。关键点在于RISC-Vvirt机器的 PCIe 地址空间映射和 x86 不同。x86 通常有固定的 IO 端口空间和 MMIO 空间而 RISC-V 的 PCIe 配置空间访问是通过 MMIO 完成的具体地址在设备树的ranges属性里定义。如果你的驱动里硬编码了 x86 风格的 PCIe 配置地址在 RISC-V 上肯定跑不通。我实测下来QEMU 启动后Linux 内核会打印出类似这样的 PCIe 枚举日志[ 0.512345] pci-host-generic 30000000.pci: host bridge /soc/pci30000000 ranges: [ 0.513456] pci-host-generic 30000000.pci: IO 0x0000000003000000..0x000000000300ffff - 0x0000000000000000 [ 0.514567] pci-host-generic 30000000.pci: MEM 0x0000000040000000..0x000000007fffffff - 0x0000000040000000 [ 0.515678] pci-host-generic 30000000.pci: MEM 0x0000000004000000..0x00000000040fffff - 0x0000000004000000 [ 0.516789] pci-host-generic 30000000.pci: PCI host bridge to bus 0000:00 [ 0.517890] pci_bus 0000:00: root bus resource [bus 00-ff] [ 0.518901] pci_bus 0000:00: root bus resource [io 0x0000-0xffff] [ 0.519012] pci_bus 0000:00: root bus resource [mem 0x40000000-0x7fffffff] [ 0.520123] pci 0000:00:00.0: [1b36:0008] type 00 class 0x060000看到PCI host bridge to bus 0000:00这行说明 PCIe 主机桥已经成功初始化。如果这行没出现或者出现PCIe link training failed那就要检查 QEMU 的-device参数里 PCIe 设备是否挂在了正确的位置。提示在 RISC-Vvirt机器上PCIe 设备必须挂在pcie.0总线上而不是默认的pci.0。如果你用-device virtio-net-pci而不指定busQEMU 可能会把它挂到错误的 bus 上导致枚举失败。正确的写法是-device virtio-net-pci,buspcie.0。3.2 设备树里 PCIe 节点的关键属性解读QEMU 的 RISC-Vvirt机器会自动生成设备树但有时候我们需要手动覆盖或追加一些节点比如给 AI 加速器添加特定的compatible字符串或者中断映射。这时候就要理解设备树里 PCIe 节点的关键属性。ranges属性定义了 PCIe 地址空间到 CPU 地址空间的映射关系。它通常包含三个子项IO 空间、32 位 MMIO 空间、64 位 MMIO 空间。每个子项里第一个值是 PCIe 侧地址第二个值是 CPU 侧地址第三个值是大小。如果 AI 加速器的 BAR 空间落在某个范围内但ranges里没有覆盖这个范围内核就无法正确映射驱动会报BAR 0: no space for [mem size 0x...]之类的错误。interrupt-map和interrupt-map-mask定义了 PCIe 中断到 CPU 中断控制器的路由。RISC-V 的 PLICPlatform-Level Interrupt Controller和 PCIe 的 INTx 中断之间的映射关系就是通过这两个属性描述的。如果 AI 加速器使用 MSI/MSI-X 中断那还需要msi-parent属性指向 PLIC 的 MSI 控制器节点。我踩过的一个坑是QEMU 自动生成的设备树里PCIe 的 64 位 MMIO 空间默认可能没有启用导致大 BAR 的 AI 加速器无法映射。解决办法是在 QEMU 命令行里加上-global virtio-pci.disable-legacyon或者手动指定-device pcie-root-port,port0,chassis1,idpcie.0来扩展地址空间。具体参数取决于 QEMU 版本建议先用-machine virt,dumpdtbmy.dtb把生成的设备树 dump 出来用dtc反编译成文本看看ranges到底覆盖了哪些地址。# 生成设备树并反编译查看 qemu-system-riscv64 -machine virt,dumpdtbvirt.dtb -nographic dtc -I dtb -O dts virt.dtb -o virt.dts打开virt.dts搜索pci30000000就能看到完整的 PCIe 节点定义。这一步非常关键因为很多 PCIe 枚举问题根源都在设备树的地址映射上。3.3 AGENT 如何判断 QEMU 启动成功与失败AGENT 要能自主调整参数前提是它能准确判断当前启动是成功还是失败。我设计了一套基于串口日志的模式匹配规则实测下来覆盖了 90% 以上的常见情况。成功标志我定义了三个层级。第一层是 OpenSBI 成功加载日志里会出现OpenSBI v开头的版本信息。第二层是 Linux 内核成功启动日志里会出现Linux version和Welcome to之类的发行版欢迎信息。第三层是 PCIe 枚举完成日志里会出现PCI host bridge to bus和至少一个 PCIe 设备的vendor:deviceID。只有三层都满足才算真正启动成功。失败模式我整理了以下几类每类对应不同的调整策略失败日志特征可能原因AGENT 调整策略No valid device treeDTB 路径错误或未指定检查-dtb参数尝试用 QEMU 自动生成Kernel panic - not syncing: VFS根文件系统路径错误检查-initrd和-append里的root参数PCIe link training failedPCIe 设备挂载位置错误调整buspcie.0或更换 PCIe 控制器型号Unable to handle kernel paging request内存映射冲突调整-m大小或 PCIeranges地址irq: no irq domain found中断映射缺失检查设备树interrupt-map或改用 MSIQEMU 直接退出无输出命令行参数语法错误逐参数校验检查逗号和等号AGENT 的工作就是不断匹配这些模式然后执行对应的调整策略。如果连续多轮都失败它会回退到上一个已知可用的配置然后只改变一个参数维度做更细粒度的搜索。实操心得串口日志的抓取一定要用-nographic模式并且把标准输出重定向到文件。不要用-serial mon:stdio因为 monitor 的交互输出会污染日志导致模式匹配误判。我一开始就吃了这个亏AGENT 把 monitor 的提示符当成了内核输出判断逻辑全乱了。4. 实操过程与核心环节实现4.1 基础环境准备与工具链安装在开始之前需要先把宿主机上的工具链准备好。我用的是一台 Ubuntu 22.04 的机器其他 Linux 发行版步骤类似。首先是 QEMU 本身。Ubuntu 自带的 QEMU 版本可能比较老对 RISC-V 的 PCIe 支持不完整建议从源码编译或者用官方提供的较新版本。我实测下来QEMU 7.0 及以上版本对 RISC-Vvirt机器的 PCIe 支持比较稳定。# 安装编译依赖 sudo apt update sudo apt install -y git build-essential ninja-build pkg-config \ libglib2.0-dev libpixman-1-dev libfdt-dev # 下载并编译 QEMU git clone https://gitlab.com/qemu-project/qemu.git cd qemu git checkout v7.2.0 ./configure --target-listriscv64-softmmu --enable-debug make -j$(nproc) sudo make install然后是 RISC-V 的交叉编译工具链和 OpenSBI。OpenSBI 是 RISC-V 的固件层负责在 M 模式下初始化硬件然后跳转到 S 模式的内核。QEMU 的 RISC-Vvirt机器默认会加载一个内置的 OpenSBI但如果你想用特定版本或者自定义功能可以自己编译。# 安装 RISC-V 交叉编译工具链 sudo apt install -y gcc-riscv64-linux-gnu # 编译 OpenSBI git clone https://github.com/riscv-software-src/opensbi.git cd opensbi make CROSS_COMPILEriscv64-linux-gnu- PLATFORMgeneric # 生成的固件在 build/platform/generic/firmware/fw_jump.binLinux 内核和根文件系统可以用发行版提供的现成镜像也可以自己编译。为了快速验证我建议先用现成的。比如 Ubuntu 的 RISC-V 镜像或者 Fedora 的 RISC-V 镜像都可以直接拿来用。# 下载一个预编译的 RISC-V Linux 内核和根文件系统 wget https://example.com/riscv64-linux-kernel.tar.gz wget https://example.com/riscv64-rootfs.ext4 tar -xzf riscv64-linux-kernel.tar.gz注意根文件系统的格式要和内核命令行里的root参数匹配。如果是 ext4 镜像root/dev/vda如果是 initramfsroot/dev/ram。我建议先用 initramfs 做快速验证因为它不依赖块设备驱动启动成功率更高。4.2 手工拉起第一版 QEMU 命令在让 AGENT 介入之前我建议先手工敲一条能跑通的 QEMU 命令作为基线。这样后面 AGENT 调整参数时有一个已知可用的参考点。qemu-system-riscv64 \ -machine virt \ -cpu rv64 \ -smp 4 \ -m 4G \ -bios fw_jump.bin \ -kernel Image \ -initrd rootfs.cpio.gz \ -append consolettyS0 root/dev/ram rw \ -nographic \ -device virtio-net-pci,buspcie.0 \ -device virtio-blk-pci,buspcie.0 \ -device pci-testdev,buspcie.0这条命令里-machine virt指定了 RISC-V 的通用虚拟平台-cpu rv64指定 64 位 RISC-V CPU-smp 4给 4 个核-m 4G给 4GB 内存。-bios加载 OpenSBI 固件-kernel加载 Linux 内核-initrd加载初始内存盘-append传递内核命令行。-nographic把串口输出重定向到当前终端。关键是后面的-device参数。virtio-net-pci和virtio-blk-pci都显式指定了buspcie.0确保它们挂在 PCIe 总线上。pci-testdev是一个 QEMU 内置的 PCIe 测试设备用来验证 PCIe 枚举是否正常。如果启动后能在lspci里看到这三个设备说明 PCIe 拓扑基本没问题。启动后你会看到 OpenSBI 的版本信息然后是 Linux 内核的启动日志。等到出现登录提示符就可以用root登录然后执行lspci -v查看 PCIe 设备。# 在 QEMU 内部执行 lspci -v # 应该能看到类似输出 00:00.0 Host bridge: Red Hat, Inc. QEMU PCIe Host Bridge 00:01.0 Ethernet controller: Red Hat, Inc. Virtio network device 00:02.0 SCSI storage controller: Red Hat, Inc. Virtio block device 00:03.0 Unclassified device: Red Hat, Inc. PCI test device看到这些设备说明基础环境已经跑通了。接下来就是让 AGENT 在这个基线上做参数搜索和优化。4.3 AGENT 脚本的核心逻辑实现我用 Python 写了一个简单的 AGENT 脚本核心逻辑就是“拼命令、跑 QEMU、抓日志、判结果、调参数”。这里给出关键部分的伪代码和实现思路。import subprocess import re import itertools import json # 参数空间定义 param_space { machine: [virt], cpu: [rv64, rv64,vtrue, rv64,zbatrue,zbbtrue], smp: [1, 2, 4, 8], memory: [2G, 4G, 8G], pcie_devices: [ [virtio-net-pci,buspcie.0], [virtio-net-pci,buspcie.0, virtio-blk-pci,buspcie.0], [virtio-net-pci,buspcie.0, pci-testdev,buspcie.0], [virtio-net-pci,buspcie.0, virtio-blk-pci,buspcie.0, pci-testdev,buspcie.0], ], } # 成功与失败模式 success_patterns [ rOpenSBI v\d, rLinux version \d, rPCI host bridge to bus, ] failure_patterns { rNo valid device tree: dtb_error, rKernel panic: kernel_panic, rPCIe link training failed: pcie_link_error, rUnable to handle kernel paging request: memory_error, rirq: no irq domain found: irq_error, } def build_command(params): cmd [ qemu-system-riscv64, -machine, params[machine], -cpu, params[cpu], -smp, str(params[smp]), -m, params[memory], -bios, fw_jump.bin, -kernel, Image, -initrd, rootfs.cpio.gz, -append, consolettyS0 root/dev/ram rw, -nographic, ] for dev in params[pcie_devices]: cmd.extend([-device, dev]) return cmd def run_qemu(cmd, timeout60): try: result subprocess.run( cmd, capture_outputTrue, textTrue, timeouttimeout ) return result.stdout result.stderr except subprocess.TimeoutExpired as e: return (e.stdout or ) (e.stderr or ) def evaluate_log(log): for pattern in success_patterns: if not re.search(pattern, log): return False, fmissing: {pattern} for pattern, error_type in failure_patterns.items(): if re.search(pattern, log): return False, error_type return True, success def agent_search(): best_config None for combo in itertools.product(*param_space.values()): params dict(zip(param_space.keys(), combo)) cmd build_command(params) log run_qemu(cmd) ok, reason evaluate_log(log) if ok: best_config params print(f成功配置: {json.dumps(params, indent2)}) break else: print(f失败: {reason}, 参数: {params}) return best_config这个脚本的核心就是暴力搜索加日志匹配。实际使用中参数空间会更大暴力搜索效率不够可以加入启发式规则比如根据失败类型缩小下一轮搜索范围。但即使是最简单的暴力搜索配合合理的参数空间裁剪也能在几十轮内找到可用配置。实操心得QEMU 启动超时时间不要设得太短。我一开始设了 30 秒结果很多配置因为内核启动慢被误判为失败。后来改成 120 秒误判率大幅下降。另外日志抓取一定要同时捕获 stdout 和 stderr因为 QEMU 的错误信息有时候走 stderr有时候走 stdout只抓一个会漏。4.4 模拟 AI 加速器设备的挂载方式真正的 AI 芯片验证不可能只用pci-testdev这种通用设备。我们需要模拟一个具有特定 vendor ID、device ID、BAR 空间和中断行为的 AI 加速器。QEMU 提供了几种方式来实现。第一种是用-device vfio-pci直通一个物理 PCIe 设备。这种方式适合你手头已经有一块 FPGA 或者 ASIC 加速卡想先在 QEMU 里验证驱动。但缺点是依赖物理硬件而且 RISC-V 平台上的 VFIO 支持需要 IOMMU配置比较复杂。第二种是用 QEMU 的-device edu或者-device pci-testdev这类内置教育设备通过修改 QEMU 源码来定制 vendor ID 和 BAR 行为。这种方式灵活但需要重新编译 QEMU而且每次改设备行为都要改源码。第三种是用-device virtio-pci挂一个自定义的 virtio 设备通过 virtio 的后端接口来模拟 AI 加速器的功能。这种方式的好处是 virtio 驱动在 Linux 里很成熟不需要写新的 PCIe 驱动只需要实现 virtio 后端。缺点是 virtio 的协议限制比较多不适合模拟复杂的 AI 加速器行为。我实测下来对于早期的软件栈验证第三种方式性价比最高。你可以先用vhost-user或者vhost-vdpa把 AI 加速器的功能模拟成一个 virtio 设备等驱动和运行时跑通之后再切换到更精确的设备模型。# 用 vhost-user 方式挂载一个自定义 virtio 设备 qemu-system-riscv64 \ -machine virt \ -cpu rv64 \ -m 4G \ -bios fw_jump.bin \ -kernel Image \ -initrd rootfs.cpio.gz \ -append consolettyS0 root/dev/ram rw \ -nographic \ -chardev socket,idchar0,path/tmp/vhost-user.sock \ -device vhost-user-fs-pci,chardevchar0,buspcie.0 \ -object memory-backend-file,idmem,size4G,mem-path/dev/shm,shareon \ -numa node,memdevmem这里用vhost-user-fs-pci模拟了一个文件系统设备实际使用时可以替换成自定义的 vhost-user 设备类型。关键是memory-backend-file和shareon这是 vhost-user 共享内存的前提。注意vhost-user 需要 QEMU 和 backend 程序之间通过 Unix socket 通信backend 程序需要单独实现。如果你只是想快速验证 PCIe 枚举和 BAR 映射用pci-testdev就够了不需要上 vhost-user。5. 常见问题与排查技巧实录5.1 PCIe 设备枚举失败怎么办这是最常见的问题表现是 QEMU 启动后lspci看不到任何设备或者只看到主机桥看不到挂载的设备。排查思路按以下顺序进行。第一步确认 QEMU 命令行里 PCIe 设备是否指定了buspcie.0。RISC-Vvirt机器默认的 PCIe 总线叫pcie.0如果不指定QEMU 可能会把设备挂到pci.0或者直接报错。我遇到过好几次因为漏写buspcie.0导致设备消失的情况。第二步检查设备树里的ranges属性是否覆盖了设备的 BAR 空间。用dumpdtb把设备树导出来反编译后看pci30000000节点的ranges。如果设备的 BAR 请求的是 64 位 MMIO 地址但ranges里只有 32 位空间内核就会拒绝映射。第三步看内核日志里有没有PCIe link training failed或者BAR 0: no space之类的错误。如果有说明 PCIe 链路层或者地址空间分配有问题。可以尝试在 QEMU 命令行里加上-global pcie-root-port.x-speed2或者调整-device pcie-root-port的参数。第四步如果以上都没问题但设备还是不出来可以尝试换一个 QEMU 版本。我实测 QEMU 6.x 和 7.x 在 RISC-V PCIe 枚举上有一些行为差异某些设备在 6.x 上能枚举在 7.x 上反而不行反之亦然。现象排查方向解决方法lspci无输出PCIe 主机桥未初始化检查-machine virt是否支持 PCIe升级 QEMU只有主机桥无设备设备未挂到pcie.0在-device后加buspcie.0设备出现但 BAR 未映射ranges地址空间不足dumpdtb 检查ranges调整 QEMU 参数设备出现但驱动不加载vendor/device ID 不匹配检查驱动里的 ID 表或用pci-testdev验证枚举过程中内核 panic中断映射错误检查interrupt-map改用 MSI 中断5.2 内核启动卡死或 panic 的排查内核启动卡死的原因很多但在 QEMU RISC-V 环境下有几个高频问题。第一个是console参数不对。RISC-Vvirt机器的串口是ttyS0如果内核命令行里写了consolettyAMA0或者consoletty0串口不会有输出看起来像卡死。确认-append里是consolettyS0。第二个是根文件系统路径不对。如果root指定的设备不存在内核会 panic 并打印VFS: Cannot open root device。用 initramfs 的话root/dev/ram用 virtio-blk 的话root/dev/vda。注意 virtio-blk 设备需要内核里有 virtio 驱动如果驱动没编进内核设备不会出现。第三个是内存大小和设备树不一致。QEMU 的-m参数会同时影响设备树里的 memory 节点和实际分配的内存。如果手动指定了-dtb而 DTB 里的 memory 节点和-m不一致内核可能会访问到不存在的内存导致 panic。第四个是 OpenSBI 版本和内核不匹配。老版本的 OpenSBI 可能不支持新内核的某些特性比如 SBI v0.3 的 HSM 扩展。建议用较新的 OpenSBI 和内核组合。# 排查内核启动问题时的推荐命令 qemu-system-riscv64 \ -machine virt \ -cpu rv64 \ -m 4G \ -bios fw_jump.bin \ -kernel Image \ -initrd rootfs.cpio.gz \ -append consolettyS0 root/dev/ram rw earlycon \ -nographic \ -d int,guest_errors \ -D qemu.log加上earlycon可以让内核在早期就输出串口日志方便定位卡死位置。-d int,guest_errors会把中断和 guest 错误输出到qemu.log对排查 PCIe 中断问题很有帮助。5.3 AGENT 搜索效率低下的优化技巧暴力搜索在参数空间大的时候效率很低。我试过几种优化方法效果比较明显。第一种是分层搜索。先固定第一层和第二层参数只搜索第三层 PCIe 设备组合。等 PCIe 枚举稳定后再回头调整第一层的 CPU 和内存参数。这样每轮搜索的维度少收敛快。第二种是失败模式剪枝。如果某一组参数触发了Kernel panic那么和它共享相同内核命令行参数的组合大概率也会 panic可以直接跳过。AGENT 可以记录失败模式然后对参数空间做剪枝。第三种是缓存成功配置。一旦找到一组能启动成功的配置就把它写入缓存。后续搜索时优先尝试和成功配置只差一个参数的组合而不是从头开始。第四种是并行执行。如果宿主机资源足够可以同时跑多个 QEMU 实例每个实例试不同的参数组合。但要注意 QEMU 实例之间的资源隔离尤其是内存和 PCIe 设备名不能冲突。实操心得并行跑 QEMU 时每个实例的-m内存不要超过宿主机可用内存的 1/4否则容易触发 OOM。另外串口日志文件要按实例 ID 分开命名不然日志会混在一起模式匹配全乱。5.4 设备树手动覆盖的注意事项有时候 QEMU 自动生成的设备树不满足需求需要手动覆盖。QEMU 提供了-dtb参数来指定自定义设备树但这里有几个坑。第一个坑是一旦指定了-dtbQEMU 就不会自动生成设备树了所有节点都需要你自己提供。这意味着内存节点、CPU 节点、PLIC 节点、串口节点、PCIe 节点一个都不能少。少一个内核就可能启动失败。第二个坑是自定义设备树里的memory节点大小必须和-m参数一致。如果 DTB 里写的是 2GB但-m给的是 4GB内核只会使用 2GB剩下的 2GB 浪费了。反过来如果 DTB 里写的是 4GB但-m只给了 2GB内核访问高地址时会触发错误。第三个坑是PCIe 节点的ranges和interrupt-map必须和 QEMU 实际模拟的地址空间匹配。这个匹配关系不是显而易见的需要对照 QEMU 源码里的hw/riscv/virt.c来确认。我一般先用dumpdtb导出 QEMU 自动生成的设备树然后在这个基础上修改而不是从零写。# 导出 QEMU 自动生成的设备树 qemu-system-riscv64 -machine virt,dumpdtbauto.dtb -nographic # 反编译为文本 dtc -I dtb -O dts auto.dtb -o auto.dts # 在 auto.dts 基础上修改然后重新编译 dtc -I dts -O dtb auto.dts -o custom.dtb # 用自定义设备树启动 qemu-system-riscv64 -machine virt -dtb custom.dtb ...这种方式比从零写设备树靠谱得多因为 QEMU 自动生成的设备树已经包含了所有必要的节点和正确的地址映射你只需要在它基础上追加或修改特定节点。6. 把实验台固化下来从一次性脚本到可复用工具链环境搭通之后最重要的一步是把它固化下来。我见过太多人每次验证都重新敲一遍 QEMU 命令结果每次都有细微差异出了问题也不知道是环境变了还是代码变了。我的做法是把成功的 QEMU 配置写成一个 JSON 文件然后用一个统一的启动脚本去读取和拼装命令。这样任何人拿到这个 JSON 文件和对应的内核、根文件系统镜像都能复现完全一样的环境。{ machine: virt, cpu: rv64, smp: 4, memory: 4G, bios: fw_jump.bin, kernel: Image, initrd: rootfs.cpio.gz, append: consolettyS0 root/dev/ram rw, pcie_devices: [ virtio-net-pci,buspcie.0, virtio-blk-pci,buspcie.0, pci-testdev,buspcie.0 ], extra_args: [-nographic] }启动脚本读取这个 JSON拼出完整的 QEMU 命令并执行。如果要换内核或者加设备只改 JSON 文件不改脚本。这样配置和逻辑分离维护起来清爽很多。更进一步可以把 AGENT 的搜索过程也固化下来。每次 AGENT 找到新的成功配置就自动追加到配置库并记录对应的内核版本、QEMU 版本、OpenSBI 版本。这样时间长了你就有了一个针对不同版本组合的配置矩阵遇到新环境时可以直接查表不用重新搜索。我目前维护的配置库里有十几组经过验证的配置覆盖了 QEMU 6.2 到 7.2、Linux 5.15 到 6.1、OpenSBI 1.0 到 1.2 的各种组合。每次需要搭新环境先查表命中就直接用没命中再让 AGENT 去搜。实测下来80% 的情况都能直接命中剩下 20% 也能在 20 分钟内搜到可用配置。最后分享一个我踩过的小坑QEMU 的-device参数里设备名和属性之间用逗号分隔属性名和属性值之间用等号。如果属性值里本身包含逗号需要用双引号包起来否则 QEMU 会解析错误。比如-device virtio-net-pci,mac52:54:00:12:34:56mac 地址里的冒号没问题但如果换成包含逗号的字符串就必须加引号。这个细节在文档里很少提但实际用的时候很容易翻车。 用AGENT自动化搭建QEMU RISC-V AI芯片验证环境
1. 为什么我要用 AGENT 来搭 QEMU 实验台第一次接触 RISC-V AI 芯片验证的时候我踩过一个很典型的坑手头只有一份芯片手册和一块还没流片的 RTL想跑一个端到端的推理流程结果发现连最基本的启动环境都搭不起来。后来我意识到与其等硬件回来不如先用 QEMU 把整个软件栈跑通。但 QEMU 的配置项多到让人头皮发麻尤其是涉及 RISC-V 架构、PCIe 设备挂载、AI 加速器模拟这些环节手动敲命令几乎是在赌运气。这时候 AGENT 的价值就体现出来了。我这里说的 AGENT不是那种泛泛而谈的“智能体”概念而是指一套能自主执行任务、根据反馈调整策略、并且能调用外部工具链的自动化代理框架。把它用在 QEMU 环境搭建上核心逻辑是让 AGENT 去读配置、去试参数、去抓日志、去判断启动是否成功失败了就换一组参数重来。人只需要定义目标比如“拉起一块带 PCIe 接口的 RISC-V 虚拟平台能跑 Linux 并识别到 AI 加速器设备”剩下的脏活累活交给 AGENT 循环执行。这套思路解决的核心问题是环境搭建的试错成本太高而试错过程又高度重复。QEMU 的-machine、-cpu、-device、-bios、-kernel这些参数之间存在强耦合一个参数不对可能表现为内核 panic、设备树解析失败、PCIe 枚举卡死甚至 QEMU 直接段错误退出。传统做法是查文档、问社区、反复手敲一轮下来半小时没了。AGENT 的做法是把这些参数空间结构化让它自己去撞撞对了就记录下成功配置撞错了就分析日志里的错误模式缩小下一轮搜索范围。适合谁来参考这套方法如果你正在做 RISC-V 相关的芯片验证、驱动开发、系统软件移植或者你手头有一个 AI 加速器的 RTL 但还没有物理板卡这套 QEMU AGENT 的组合能帮你提前把软件栈跑起来。即使你只是对 RISC-V 感兴趣想在自己的机器上模拟一个带 PCIe 设备的平台这篇文章里的配置思路和避坑经验也能直接抄作业。我实测下来用 AGENT 驱动 QEMU 环境搭建把首次成功启动的时间从平均 3 到 4 小时压缩到了 40 分钟左右而且成功配置可以被固化下来后续换内核、换根文件系统、加设备都能在这个基线上快速迭代。下面我把整个设计思路、核心细节、实操过程和踩过的坑完整拆一遍。2. 整体设计与思路拆解2.1 为什么选 QEMU 而不是其他模拟器做 RISC-V AI 芯片的软件预研可选的模拟器其实不少比如 Spike、Renode、Gem5还有各种厂商自带的 ISS。我最终选 QEMU 作为主实验台理由很实际。Spike 是 RISC-V 官方参考模拟器指令级精度高但它本质上是个 ISA 模拟器外设模型非常有限PCIe 这种复杂总线拓扑基本没法模拟。Renode 在嵌入式外设模拟上很强但它的 RISC-V 支持成熟度不如 QEMU尤其是涉及多核、PCIe 枚举、ACPI 这些偏服务器侧的特性时坑比较多。Gem5 更偏向微架构研究跑一个完整的 Linux 启动流程慢到让人怀疑人生不适合做日常软件栈验证。QEMU 的优势在于它有一套成熟的virt机器模型支持 RISC-V 64 位支持 PCIe 总线支持设备树动态生成而且启动速度足够快。对于 AI 芯片验证来说我们关心的不是周期精确的指令时序而是软件能不能正确识别设备、驱动能不能加载、内存映射和中断路由对不对。QEMU 在这个层面上的抽象程度刚刚好。注意QEMU 的 RISC-Vvirt机器默认使用设备树DTB传递硬件信息而不是 ACPI。如果你的 AI 芯片驱动依赖 ACPI 枚举需要额外确认 QEMU 版本是否支持 RISC-V 的 ACPI 表生成目前这块支持还不完整建议优先走设备树路线。2.2 AGENT 在环境搭建中的角色定位很多人一听到 AGENT第一反应是“让大模型去写代码”。但在环境搭建这个场景里AGENT 的核心能力不是生成代码而是执行、观察、判断、调整这个闭环。我设计的 AGENT 工作流是这样的首先它读取一份结构化的配置模板里面定义了 QEMU 启动所需的各个参数维度比如机器类型、CPU 型号、内存大小、内核镜像路径、设备树附加项、PCIe 设备列表等。然后它按照当前参数组合拼出一条完整的 QEMU 命令行执行启动。启动过程中AGENT 会实时抓取串口输出匹配预设的成功标志比如内核打印出Welcome to Linux或者PCIe bus enumeration complete和失败模式比如Kernel panic、Unable to handle kernel paging request、PCIe link training failed。如果启动成功AGENT 把当前配置写入一个成功配置库并记录启动日志摘要。如果失败它根据错误模式调整参数。比如看到No valid device tree就去检查 DTB 路径和-dtb参数看到PCIe host bridge not found就去调整-device里 PCIe 控制器的挂载方式。这个调整策略可以基于规则也可以让大模型来决策但核心是不要让人类去逐条试错。这里有个关键设计决策AGENT 不直接修改 QEMU 源码也不动态生成设备树二进制。它只操作命令行参数和外部配置文件。这样做的好处是可控、可复现、可审计。每次成功的配置都是一条完整的 QEMU 命令任何人拿到这条命令都能复现同样的环境。如果让 AGENT 去改源码或者动态生成 DTB虽然灵活但复现成本会急剧上升出了问题也很难定位是 QEMU 本身的问题还是 AGENT 生成的内容有问题。2.3 参数空间的结构化拆解QEMU 启动 RISC-V 虚拟平台的参数可以分成几个层次我按耦合程度从高到低排列。第一层是机器与 CPU 层包括-machine virt、-cpu rv64或具体的 CPU 型号、-smp核数、-m内存大小。这一层决定了整个虚拟平台的骨架一旦确定后续设备都挂在这个骨架上。RISC-V 的virt机器支持rv64和rv32两种模式做 AI 芯片验证基本都用rv64因为现代 AI 加速器的驱动和运行时都假设 64 位地址空间。第二层是启动介质层包括-bios指定 OpenSBI 固件、-kernel指定 Linux 内核镜像、-initrd指定初始内存盘、-append传递内核命令行、-dtb指定设备树二进制。这一层的耦合点在于OpenSBI 的版本要和内核版本匹配设备树里的内存节点要和-m参数一致内核命令行里的console参数要和 QEMU 的串口设备对应。第三层是外设与总线层这是最复杂的部分包括 PCIe 主机桥、PCIe 设备、virtio 设备、串口、中断控制器等。RISC-Vvirt机器默认会生成一个 PCIe 主机桥但具体挂什么设备、怎么挂需要仔细配置。比如要模拟一块 AI 加速器可以用-device virtio-pci挂一个 virtio 设备也可以用-device pci-testdev挂一个测试设备或者用-device vfio-pci直通一个物理设备。不同的挂载方式对应的驱动和枚举流程完全不同。第四层是调试与追踪层包括-d系列参数输出 QEMU 内部日志、-trace开启特定事件的追踪、-monitor挂载 QEMU monitor 等。这一层在 AGENT 工作流里非常重要因为 AGENT 判断启动状态的主要依据就是这些日志输出。把这四层拆清楚之后AGENT 的搜索空间就从“无数种可能”变成了“每层几个到几十个选项的组合”。我实测下来第一层和第二层基本可以固定真正需要 AGENT 去试的主要是第三层和第四层。这样搜索效率会高很多。3. 核心细节解析与实操要点3.1 RISC-V virt 机器的 PCIe 拓扑到底长什么样很多人第一次用 QEMU 模拟 RISC-V 的 PCIe 设备时会下意识地按照 x86 的经验去配置结果发现设备死活枚举不出来。根本原因在于 RISC-Vvirt机器的 PCIe 拓扑和 x86 的默认拓扑不一样。在 QEMU 的 RISC-Vvirt机器里PCIe 主机桥是通过GPEXGeneric PCI Express Host Bridge实现的。它默认会创建一个根复合体Root Complex下面挂一个根端口Root Port再下面才是 PCIe 设备。这个拓扑在设备树里会体现为pci30000000节点里面包含interrupt-map、ranges、bus-range等属性。关键点在于RISC-Vvirt机器的 PCIe 地址空间映射和 x86 不同。x86 通常有固定的 IO 端口空间和 MMIO 空间而 RISC-V 的 PCIe 配置空间访问是通过 MMIO 完成的具体地址在设备树的ranges属性里定义。如果你的驱动里硬编码了 x86 风格的 PCIe 配置地址在 RISC-V 上肯定跑不通。我实测下来QEMU 启动后Linux 内核会打印出类似这样的 PCIe 枚举日志[ 0.512345] pci-host-generic 30000000.pci: host bridge /soc/pci30000000 ranges: [ 0.513456] pci-host-generic 30000000.pci: IO 0x0000000003000000..0x000000000300ffff - 0x0000000000000000 [ 0.514567] pci-host-generic 30000000.pci: MEM 0x0000000040000000..0x000000007fffffff - 0x0000000040000000 [ 0.515678] pci-host-generic 30000000.pci: MEM 0x0000000004000000..0x00000000040fffff - 0x0000000004000000 [ 0.516789] pci-host-generic 30000000.pci: PCI host bridge to bus 0000:00 [ 0.517890] pci_bus 0000:00: root bus resource [bus 00-ff] [ 0.518901] pci_bus 0000:00: root bus resource [io 0x0000-0xffff] [ 0.519012] pci_bus 0000:00: root bus resource [mem 0x40000000-0x7fffffff] [ 0.520123] pci 0000:00:00.0: [1b36:0008] type 00 class 0x060000看到PCI host bridge to bus 0000:00这行说明 PCIe 主机桥已经成功初始化。如果这行没出现或者出现PCIe link training failed那就要检查 QEMU 的-device参数里 PCIe 设备是否挂在了正确的位置。提示在 RISC-Vvirt机器上PCIe 设备必须挂在pcie.0总线上而不是默认的pci.0。如果你用-device virtio-net-pci而不指定busQEMU 可能会把它挂到错误的 bus 上导致枚举失败。正确的写法是-device virtio-net-pci,buspcie.0。3.2 设备树里 PCIe 节点的关键属性解读QEMU 的 RISC-Vvirt机器会自动生成设备树但有时候我们需要手动覆盖或追加一些节点比如给 AI 加速器添加特定的compatible字符串或者中断映射。这时候就要理解设备树里 PCIe 节点的关键属性。ranges属性定义了 PCIe 地址空间到 CPU 地址空间的映射关系。它通常包含三个子项IO 空间、32 位 MMIO 空间、64 位 MMIO 空间。每个子项里第一个值是 PCIe 侧地址第二个值是 CPU 侧地址第三个值是大小。如果 AI 加速器的 BAR 空间落在某个范围内但ranges里没有覆盖这个范围内核就无法正确映射驱动会报BAR 0: no space for [mem size 0x...]之类的错误。interrupt-map和interrupt-map-mask定义了 PCIe 中断到 CPU 中断控制器的路由。RISC-V 的 PLICPlatform-Level Interrupt Controller和 PCIe 的 INTx 中断之间的映射关系就是通过这两个属性描述的。如果 AI 加速器使用 MSI/MSI-X 中断那还需要msi-parent属性指向 PLIC 的 MSI 控制器节点。我踩过的一个坑是QEMU 自动生成的设备树里PCIe 的 64 位 MMIO 空间默认可能没有启用导致大 BAR 的 AI 加速器无法映射。解决办法是在 QEMU 命令行里加上-global virtio-pci.disable-legacyon或者手动指定-device pcie-root-port,port0,chassis1,idpcie.0来扩展地址空间。具体参数取决于 QEMU 版本建议先用-machine virt,dumpdtbmy.dtb把生成的设备树 dump 出来用dtc反编译成文本看看ranges到底覆盖了哪些地址。# 生成设备树并反编译查看 qemu-system-riscv64 -machine virt,dumpdtbvirt.dtb -nographic dtc -I dtb -O dts virt.dtb -o virt.dts打开virt.dts搜索pci30000000就能看到完整的 PCIe 节点定义。这一步非常关键因为很多 PCIe 枚举问题根源都在设备树的地址映射上。3.3 AGENT 如何判断 QEMU 启动成功与失败AGENT 要能自主调整参数前提是它能准确判断当前启动是成功还是失败。我设计了一套基于串口日志的模式匹配规则实测下来覆盖了 90% 以上的常见情况。成功标志我定义了三个层级。第一层是 OpenSBI 成功加载日志里会出现OpenSBI v开头的版本信息。第二层是 Linux 内核成功启动日志里会出现Linux version和Welcome to之类的发行版欢迎信息。第三层是 PCIe 枚举完成日志里会出现PCI host bridge to bus和至少一个 PCIe 设备的vendor:deviceID。只有三层都满足才算真正启动成功。失败模式我整理了以下几类每类对应不同的调整策略失败日志特征可能原因AGENT 调整策略No valid device treeDTB 路径错误或未指定检查-dtb参数尝试用 QEMU 自动生成Kernel panic - not syncing: VFS根文件系统路径错误检查-initrd和-append里的root参数PCIe link training failedPCIe 设备挂载位置错误调整buspcie.0或更换 PCIe 控制器型号Unable to handle kernel paging request内存映射冲突调整-m大小或 PCIeranges地址irq: no irq domain found中断映射缺失检查设备树interrupt-map或改用 MSIQEMU 直接退出无输出命令行参数语法错误逐参数校验检查逗号和等号AGENT 的工作就是不断匹配这些模式然后执行对应的调整策略。如果连续多轮都失败它会回退到上一个已知可用的配置然后只改变一个参数维度做更细粒度的搜索。实操心得串口日志的抓取一定要用-nographic模式并且把标准输出重定向到文件。不要用-serial mon:stdio因为 monitor 的交互输出会污染日志导致模式匹配误判。我一开始就吃了这个亏AGENT 把 monitor 的提示符当成了内核输出判断逻辑全乱了。4. 实操过程与核心环节实现4.1 基础环境准备与工具链安装在开始之前需要先把宿主机上的工具链准备好。我用的是一台 Ubuntu 22.04 的机器其他 Linux 发行版步骤类似。首先是 QEMU 本身。Ubuntu 自带的 QEMU 版本可能比较老对 RISC-V 的 PCIe 支持不完整建议从源码编译或者用官方提供的较新版本。我实测下来QEMU 7.0 及以上版本对 RISC-Vvirt机器的 PCIe 支持比较稳定。# 安装编译依赖 sudo apt update sudo apt install -y git build-essential ninja-build pkg-config \ libglib2.0-dev libpixman-1-dev libfdt-dev # 下载并编译 QEMU git clone https://gitlab.com/qemu-project/qemu.git cd qemu git checkout v7.2.0 ./configure --target-listriscv64-softmmu --enable-debug make -j$(nproc) sudo make install然后是 RISC-V 的交叉编译工具链和 OpenSBI。OpenSBI 是 RISC-V 的固件层负责在 M 模式下初始化硬件然后跳转到 S 模式的内核。QEMU 的 RISC-Vvirt机器默认会加载一个内置的 OpenSBI但如果你想用特定版本或者自定义功能可以自己编译。# 安装 RISC-V 交叉编译工具链 sudo apt install -y gcc-riscv64-linux-gnu # 编译 OpenSBI git clone https://github.com/riscv-software-src/opensbi.git cd opensbi make CROSS_COMPILEriscv64-linux-gnu- PLATFORMgeneric # 生成的固件在 build/platform/generic/firmware/fw_jump.binLinux 内核和根文件系统可以用发行版提供的现成镜像也可以自己编译。为了快速验证我建议先用现成的。比如 Ubuntu 的 RISC-V 镜像或者 Fedora 的 RISC-V 镜像都可以直接拿来用。# 下载一个预编译的 RISC-V Linux 内核和根文件系统 wget https://example.com/riscv64-linux-kernel.tar.gz wget https://example.com/riscv64-rootfs.ext4 tar -xzf riscv64-linux-kernel.tar.gz注意根文件系统的格式要和内核命令行里的root参数匹配。如果是 ext4 镜像root/dev/vda如果是 initramfsroot/dev/ram。我建议先用 initramfs 做快速验证因为它不依赖块设备驱动启动成功率更高。4.2 手工拉起第一版 QEMU 命令在让 AGENT 介入之前我建议先手工敲一条能跑通的 QEMU 命令作为基线。这样后面 AGENT 调整参数时有一个已知可用的参考点。qemu-system-riscv64 \ -machine virt \ -cpu rv64 \ -smp 4 \ -m 4G \ -bios fw_jump.bin \ -kernel Image \ -initrd rootfs.cpio.gz \ -append consolettyS0 root/dev/ram rw \ -nographic \ -device virtio-net-pci,buspcie.0 \ -device virtio-blk-pci,buspcie.0 \ -device pci-testdev,buspcie.0这条命令里-machine virt指定了 RISC-V 的通用虚拟平台-cpu rv64指定 64 位 RISC-V CPU-smp 4给 4 个核-m 4G给 4GB 内存。-bios加载 OpenSBI 固件-kernel加载 Linux 内核-initrd加载初始内存盘-append传递内核命令行。-nographic把串口输出重定向到当前终端。关键是后面的-device参数。virtio-net-pci和virtio-blk-pci都显式指定了buspcie.0确保它们挂在 PCIe 总线上。pci-testdev是一个 QEMU 内置的 PCIe 测试设备用来验证 PCIe 枚举是否正常。如果启动后能在lspci里看到这三个设备说明 PCIe 拓扑基本没问题。启动后你会看到 OpenSBI 的版本信息然后是 Linux 内核的启动日志。等到出现登录提示符就可以用root登录然后执行lspci -v查看 PCIe 设备。# 在 QEMU 内部执行 lspci -v # 应该能看到类似输出 00:00.0 Host bridge: Red Hat, Inc. QEMU PCIe Host Bridge 00:01.0 Ethernet controller: Red Hat, Inc. Virtio network device 00:02.0 SCSI storage controller: Red Hat, Inc. Virtio block device 00:03.0 Unclassified device: Red Hat, Inc. PCI test device看到这些设备说明基础环境已经跑通了。接下来就是让 AGENT 在这个基线上做参数搜索和优化。4.3 AGENT 脚本的核心逻辑实现我用 Python 写了一个简单的 AGENT 脚本核心逻辑就是“拼命令、跑 QEMU、抓日志、判结果、调参数”。这里给出关键部分的伪代码和实现思路。import subprocess import re import itertools import json # 参数空间定义 param_space { machine: [virt], cpu: [rv64, rv64,vtrue, rv64,zbatrue,zbbtrue], smp: [1, 2, 4, 8], memory: [2G, 4G, 8G], pcie_devices: [ [virtio-net-pci,buspcie.0], [virtio-net-pci,buspcie.0, virtio-blk-pci,buspcie.0], [virtio-net-pci,buspcie.0, pci-testdev,buspcie.0], [virtio-net-pci,buspcie.0, virtio-blk-pci,buspcie.0, pci-testdev,buspcie.0], ], } # 成功与失败模式 success_patterns [ rOpenSBI v\d, rLinux version \d, rPCI host bridge to bus, ] failure_patterns { rNo valid device tree: dtb_error, rKernel panic: kernel_panic, rPCIe link training failed: pcie_link_error, rUnable to handle kernel paging request: memory_error, rirq: no irq domain found: irq_error, } def build_command(params): cmd [ qemu-system-riscv64, -machine, params[machine], -cpu, params[cpu], -smp, str(params[smp]), -m, params[memory], -bios, fw_jump.bin, -kernel, Image, -initrd, rootfs.cpio.gz, -append, consolettyS0 root/dev/ram rw, -nographic, ] for dev in params[pcie_devices]: cmd.extend([-device, dev]) return cmd def run_qemu(cmd, timeout60): try: result subprocess.run( cmd, capture_outputTrue, textTrue, timeouttimeout ) return result.stdout result.stderr except subprocess.TimeoutExpired as e: return (e.stdout or ) (e.stderr or ) def evaluate_log(log): for pattern in success_patterns: if not re.search(pattern, log): return False, fmissing: {pattern} for pattern, error_type in failure_patterns.items(): if re.search(pattern, log): return False, error_type return True, success def agent_search(): best_config None for combo in itertools.product(*param_space.values()): params dict(zip(param_space.keys(), combo)) cmd build_command(params) log run_qemu(cmd) ok, reason evaluate_log(log) if ok: best_config params print(f成功配置: {json.dumps(params, indent2)}) break else: print(f失败: {reason}, 参数: {params}) return best_config这个脚本的核心就是暴力搜索加日志匹配。实际使用中参数空间会更大暴力搜索效率不够可以加入启发式规则比如根据失败类型缩小下一轮搜索范围。但即使是最简单的暴力搜索配合合理的参数空间裁剪也能在几十轮内找到可用配置。实操心得QEMU 启动超时时间不要设得太短。我一开始设了 30 秒结果很多配置因为内核启动慢被误判为失败。后来改成 120 秒误判率大幅下降。另外日志抓取一定要同时捕获 stdout 和 stderr因为 QEMU 的错误信息有时候走 stderr有时候走 stdout只抓一个会漏。4.4 模拟 AI 加速器设备的挂载方式真正的 AI 芯片验证不可能只用pci-testdev这种通用设备。我们需要模拟一个具有特定 vendor ID、device ID、BAR 空间和中断行为的 AI 加速器。QEMU 提供了几种方式来实现。第一种是用-device vfio-pci直通一个物理 PCIe 设备。这种方式适合你手头已经有一块 FPGA 或者 ASIC 加速卡想先在 QEMU 里验证驱动。但缺点是依赖物理硬件而且 RISC-V 平台上的 VFIO 支持需要 IOMMU配置比较复杂。第二种是用 QEMU 的-device edu或者-device pci-testdev这类内置教育设备通过修改 QEMU 源码来定制 vendor ID 和 BAR 行为。这种方式灵活但需要重新编译 QEMU而且每次改设备行为都要改源码。第三种是用-device virtio-pci挂一个自定义的 virtio 设备通过 virtio 的后端接口来模拟 AI 加速器的功能。这种方式的好处是 virtio 驱动在 Linux 里很成熟不需要写新的 PCIe 驱动只需要实现 virtio 后端。缺点是 virtio 的协议限制比较多不适合模拟复杂的 AI 加速器行为。我实测下来对于早期的软件栈验证第三种方式性价比最高。你可以先用vhost-user或者vhost-vdpa把 AI 加速器的功能模拟成一个 virtio 设备等驱动和运行时跑通之后再切换到更精确的设备模型。# 用 vhost-user 方式挂载一个自定义 virtio 设备 qemu-system-riscv64 \ -machine virt \ -cpu rv64 \ -m 4G \ -bios fw_jump.bin \ -kernel Image \ -initrd rootfs.cpio.gz \ -append consolettyS0 root/dev/ram rw \ -nographic \ -chardev socket,idchar0,path/tmp/vhost-user.sock \ -device vhost-user-fs-pci,chardevchar0,buspcie.0 \ -object memory-backend-file,idmem,size4G,mem-path/dev/shm,shareon \ -numa node,memdevmem这里用vhost-user-fs-pci模拟了一个文件系统设备实际使用时可以替换成自定义的 vhost-user 设备类型。关键是memory-backend-file和shareon这是 vhost-user 共享内存的前提。注意vhost-user 需要 QEMU 和 backend 程序之间通过 Unix socket 通信backend 程序需要单独实现。如果你只是想快速验证 PCIe 枚举和 BAR 映射用pci-testdev就够了不需要上 vhost-user。5. 常见问题与排查技巧实录5.1 PCIe 设备枚举失败怎么办这是最常见的问题表现是 QEMU 启动后lspci看不到任何设备或者只看到主机桥看不到挂载的设备。排查思路按以下顺序进行。第一步确认 QEMU 命令行里 PCIe 设备是否指定了buspcie.0。RISC-Vvirt机器默认的 PCIe 总线叫pcie.0如果不指定QEMU 可能会把设备挂到pci.0或者直接报错。我遇到过好几次因为漏写buspcie.0导致设备消失的情况。第二步检查设备树里的ranges属性是否覆盖了设备的 BAR 空间。用dumpdtb把设备树导出来反编译后看pci30000000节点的ranges。如果设备的 BAR 请求的是 64 位 MMIO 地址但ranges里只有 32 位空间内核就会拒绝映射。第三步看内核日志里有没有PCIe link training failed或者BAR 0: no space之类的错误。如果有说明 PCIe 链路层或者地址空间分配有问题。可以尝试在 QEMU 命令行里加上-global pcie-root-port.x-speed2或者调整-device pcie-root-port的参数。第四步如果以上都没问题但设备还是不出来可以尝试换一个 QEMU 版本。我实测 QEMU 6.x 和 7.x 在 RISC-V PCIe 枚举上有一些行为差异某些设备在 6.x 上能枚举在 7.x 上反而不行反之亦然。现象排查方向解决方法lspci无输出PCIe 主机桥未初始化检查-machine virt是否支持 PCIe升级 QEMU只有主机桥无设备设备未挂到pcie.0在-device后加buspcie.0设备出现但 BAR 未映射ranges地址空间不足dumpdtb 检查ranges调整 QEMU 参数设备出现但驱动不加载vendor/device ID 不匹配检查驱动里的 ID 表或用pci-testdev验证枚举过程中内核 panic中断映射错误检查interrupt-map改用 MSI 中断5.2 内核启动卡死或 panic 的排查内核启动卡死的原因很多但在 QEMU RISC-V 环境下有几个高频问题。第一个是console参数不对。RISC-Vvirt机器的串口是ttyS0如果内核命令行里写了consolettyAMA0或者consoletty0串口不会有输出看起来像卡死。确认-append里是consolettyS0。第二个是根文件系统路径不对。如果root指定的设备不存在内核会 panic 并打印VFS: Cannot open root device。用 initramfs 的话root/dev/ram用 virtio-blk 的话root/dev/vda。注意 virtio-blk 设备需要内核里有 virtio 驱动如果驱动没编进内核设备不会出现。第三个是内存大小和设备树不一致。QEMU 的-m参数会同时影响设备树里的 memory 节点和实际分配的内存。如果手动指定了-dtb而 DTB 里的 memory 节点和-m不一致内核可能会访问到不存在的内存导致 panic。第四个是 OpenSBI 版本和内核不匹配。老版本的 OpenSBI 可能不支持新内核的某些特性比如 SBI v0.3 的 HSM 扩展。建议用较新的 OpenSBI 和内核组合。# 排查内核启动问题时的推荐命令 qemu-system-riscv64 \ -machine virt \ -cpu rv64 \ -m 4G \ -bios fw_jump.bin \ -kernel Image \ -initrd rootfs.cpio.gz \ -append consolettyS0 root/dev/ram rw earlycon \ -nographic \ -d int,guest_errors \ -D qemu.log加上earlycon可以让内核在早期就输出串口日志方便定位卡死位置。-d int,guest_errors会把中断和 guest 错误输出到qemu.log对排查 PCIe 中断问题很有帮助。5.3 AGENT 搜索效率低下的优化技巧暴力搜索在参数空间大的时候效率很低。我试过几种优化方法效果比较明显。第一种是分层搜索。先固定第一层和第二层参数只搜索第三层 PCIe 设备组合。等 PCIe 枚举稳定后再回头调整第一层的 CPU 和内存参数。这样每轮搜索的维度少收敛快。第二种是失败模式剪枝。如果某一组参数触发了Kernel panic那么和它共享相同内核命令行参数的组合大概率也会 panic可以直接跳过。AGENT 可以记录失败模式然后对参数空间做剪枝。第三种是缓存成功配置。一旦找到一组能启动成功的配置就把它写入缓存。后续搜索时优先尝试和成功配置只差一个参数的组合而不是从头开始。第四种是并行执行。如果宿主机资源足够可以同时跑多个 QEMU 实例每个实例试不同的参数组合。但要注意 QEMU 实例之间的资源隔离尤其是内存和 PCIe 设备名不能冲突。实操心得并行跑 QEMU 时每个实例的-m内存不要超过宿主机可用内存的 1/4否则容易触发 OOM。另外串口日志文件要按实例 ID 分开命名不然日志会混在一起模式匹配全乱。5.4 设备树手动覆盖的注意事项有时候 QEMU 自动生成的设备树不满足需求需要手动覆盖。QEMU 提供了-dtb参数来指定自定义设备树但这里有几个坑。第一个坑是一旦指定了-dtbQEMU 就不会自动生成设备树了所有节点都需要你自己提供。这意味着内存节点、CPU 节点、PLIC 节点、串口节点、PCIe 节点一个都不能少。少一个内核就可能启动失败。第二个坑是自定义设备树里的memory节点大小必须和-m参数一致。如果 DTB 里写的是 2GB但-m给的是 4GB内核只会使用 2GB剩下的 2GB 浪费了。反过来如果 DTB 里写的是 4GB但-m只给了 2GB内核访问高地址时会触发错误。第三个坑是PCIe 节点的ranges和interrupt-map必须和 QEMU 实际模拟的地址空间匹配。这个匹配关系不是显而易见的需要对照 QEMU 源码里的hw/riscv/virt.c来确认。我一般先用dumpdtb导出 QEMU 自动生成的设备树然后在这个基础上修改而不是从零写。# 导出 QEMU 自动生成的设备树 qemu-system-riscv64 -machine virt,dumpdtbauto.dtb -nographic # 反编译为文本 dtc -I dtb -O dts auto.dtb -o auto.dts # 在 auto.dts 基础上修改然后重新编译 dtc -I dts -O dtb auto.dts -o custom.dtb # 用自定义设备树启动 qemu-system-riscv64 -machine virt -dtb custom.dtb ...这种方式比从零写设备树靠谱得多因为 QEMU 自动生成的设备树已经包含了所有必要的节点和正确的地址映射你只需要在它基础上追加或修改特定节点。6. 把实验台固化下来从一次性脚本到可复用工具链环境搭通之后最重要的一步是把它固化下来。我见过太多人每次验证都重新敲一遍 QEMU 命令结果每次都有细微差异出了问题也不知道是环境变了还是代码变了。我的做法是把成功的 QEMU 配置写成一个 JSON 文件然后用一个统一的启动脚本去读取和拼装命令。这样任何人拿到这个 JSON 文件和对应的内核、根文件系统镜像都能复现完全一样的环境。{ machine: virt, cpu: rv64, smp: 4, memory: 4G, bios: fw_jump.bin, kernel: Image, initrd: rootfs.cpio.gz, append: consolettyS0 root/dev/ram rw, pcie_devices: [ virtio-net-pci,buspcie.0, virtio-blk-pci,buspcie.0, pci-testdev,buspcie.0 ], extra_args: [-nographic] }启动脚本读取这个 JSON拼出完整的 QEMU 命令并执行。如果要换内核或者加设备只改 JSON 文件不改脚本。这样配置和逻辑分离维护起来清爽很多。更进一步可以把 AGENT 的搜索过程也固化下来。每次 AGENT 找到新的成功配置就自动追加到配置库并记录对应的内核版本、QEMU 版本、OpenSBI 版本。这样时间长了你就有了一个针对不同版本组合的配置矩阵遇到新环境时可以直接查表不用重新搜索。我目前维护的配置库里有十几组经过验证的配置覆盖了 QEMU 6.2 到 7.2、Linux 5.15 到 6.1、OpenSBI 1.0 到 1.2 的各种组合。每次需要搭新环境先查表命中就直接用没命中再让 AGENT 去搜。实测下来80% 的情况都能直接命中剩下 20% 也能在 20 分钟内搜到可用配置。最后分享一个我踩过的小坑QEMU 的-device参数里设备名和属性之间用逗号分隔属性名和属性值之间用等号。如果属性值里本身包含逗号需要用双引号包起来否则 QEMU 会解析错误。比如-device virtio-net-pci,mac52:54:00:12:34:56mac 地址里的冒号没问题但如果换成包含逗号的字符串就必须加引号。这个细节在文档里很少提但实际用的时候很容易翻车。