RT-Thread 5.3 在 QEMU virt AArch64 平台上的 BSP 移植与全外设开发验证指南

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

导读

本文围绕 RT-Thread 官方 BSPbsp/qemu-virt64-aarch64，系统讲解如何将 RT-Thread 5.3 移植并运行到 QEMU 的virtAArch64 虚拟机上：从交叉编译工具链配置、scons构建，到qemu.py一键启动、各类存储/图形/音频/网络设备的挂载方式，再到 AMP 异构多核、vfio-user 摄像头等进阶玩法。读完本文，你将掌握一套完整的"无硬件、纯软件"驱动的 VirtIO、PCI 与平台驱动开发验证环境，并能够根据自身需求通过 menuconfig 与qemu.py参数自由裁剪虚拟机外设配置。

1. BSP 概述与默认配置

AArch64 是 ARMv8 架构下执行 A64 指令的 64 位执行状态。本 BSP 将 RT-Thread 移植到 QEMU 的virtAArch64 机器上，整体构建在设备模型（DM）、**Open Firmware（OFW/FDT 设备树）**与PCI 总线框架之上，可作为 VirtIO、PCI 及各类平台驱动的开发与验证平台。

BSP 目录位于 bsp/qemu-virt64-aarch64，其 Kconfig 中通过SOC_VIRT64_AARCH64选项自动选中ARCH_ARMV8、ARCH_CPU_64BIT、RT_USING_CACHE、RT_USING_COMPONENTS_INIT、RT_USING_USER_MAIN等基础配置（见 bsp/qemu-virt64-aarch64/Kconfig）。当前默认配置要点如下表：

从 bsp/qemu-virt64-aarch64/rtconfig.h 可以看到，该 BSP 默认已开启十分丰富的外设能力：串口（PL011 + 8250 PCI）、RTC（PL031）、看门狗（I6300ESB）、MTD NOR CFI、AHCI、NVMe、UFS、SCSI、VirtIO 全套（Block/Console/RNG/RPMSG/SCSI/GPU/Input/Crypto/Sound）、PCI ECAM 与 Generic Host、GICv3 ITS、RAMFB 图形（800×600）、音频（Intel HDA）、RPMSG 与 Mailbox PIC 等，是一份开箱即用的"全外设"开发镜像。

2. 编译说明

2.1 交叉编译工具链

建议使用 ARM Developer GNU 交叉编译工具链（支持 Linux / Windows 平台），下载 x86_64 Hosted 平台对应的xxx-aarch64-none-elf二进制包，解压后将RTT_EXEC_PATH环境变量指向该编译器的bin目录。

在 bsp/qemu-virt64-aarch64/rtconfig.py 中可以看到工具链的默认取值逻辑：

EXEC_PATH = os.getenv('RTT_EXEC_PATH') or '/usr/bin' PREFIX = os.getenv('RTT_CC_PREFIX') or 'aarch64-none-elf-'

即默认编译器前缀为aarch64-none-elf-（CC = aarch64-none-elf-gcc），并会优先读取环境变量RTT_EXEC_PATH/RTT_CC_PREFIX。编译参数方面，DEVICE指定了-march=armv8-a -mtune=cortex-a53，链接脚本为link.lds，debug 构建默认-O0 -gdwarf-2。

2.2 执行 scons 构建

进入rt-thread/bsp/qemu-virt64-aarch64目录执行：

scons

正常生成rtthread.elf与rtthread.bin两个文件（POST_ACTION中通过objcopy -O binary从 ELF 生成裸机二进制rtthread.bin，供 QEMU-kernel直接加载）。

也可通过scons --exec-path="GCC工具链路径"在指定工具链的同时直接编译，无需设置环境变量。

配置修改使用scons --menuconfig（Kconfig 入口在 bsp/qemu-virt64-aarch64/Kconfig），保存后重新执行scons即可增量重建。

3. 运行

本 BSP 使用qemu-system-aarch64模拟器，通过 bsp/qemu-virt64-aarch64/qemu.py 启动。该脚本会读取rtconfig.h自动获取RT_CPUS_NR、检测 QEMU 版本并据此决定是否挂载 UFS 等设备，是理解本 BSP 外设拓扑的最佳入口。

3.1 安装 QEMU

Windows 平台：从 QEMU 官方下载页面获取安装包即可。

Linux 平台（以 Ubuntu、Deepin 为例）：

sudo apt update sudo apt install qemu-system-arm

部分可选功能对 QEMU 版本有要求：

qemu.py内部实现了版本比较类QEMU_VERSION，当检测到版本低于 8.2.0 时，-sound virtio与 UFS 都会报错退出。

3.2 环境变量

3.3 基本启动

在 BSP 目录下执行：

python qemu.py

或：

./qemu.py

首次运行会自动创建各存储设备对应的 64 MBqcow2镜像（脚本遍历virtio/scsi/flash/emmc/nvme/ahci前缀执行qemu-img create -f qcow2 xxx.qcow2 64M，QEMU ≥ 8.2.0 时追加ufs.qcow2）。默认以-nographic模式启动，串口输出到当前终端。

典型启动日志：

heap: [0x40042aa0 - 0x40142aa0] \ | / - RT - Thread Operating System / | \ 5.3.0 build ... 2006 - 2026 Copyright by rt-thread team hello rt-thread msh />

其中hello rt-thread来自 bsp/qemu-virt64-aarch64/applications/main.c 的main()入口，打印后进入 msh 命令行。

3.4qemu.py命令行参数

默认-bootargs：

console=ttyAMA0 earlycon cma=8M coherent_pool=2M root=vda0 rootfstype=elm rootwait rw

从 bsp/qemu-virt64-aarch64/qemu.py 的源码可以看到这些参数的落地方式：-graphic替换-nographic并追加ramfb、virtio-keyboard-device、virtio-tablet-device；-gl追加virtio-gpu-gl-pci -display <后端>,gl=on；-sound virtio追加virtio-sound-pci+ ALSA 后端；-9p则追加-fsdev local,security_model=passthrough与virtio-9p-device，并在 bootargs 末尾追加9p.tag=hostshare 9p.mount=host。

3.5 常用启动示例

图形界面（VirtIO GPU + 键鼠）：

./qemu.py -graphic

QEMU OpenGL 显示（-gl）：

./qemu.py -graphic -gl gtk

说明：-gl仅在 QEMU / 宿主机显示链路侧启用 OpenGL（virtio-gpu-gl-pci+ VirGL）。本 BSP 默认仅包含 VirtIO GPU 2D 帧缓冲驱动，没有 OpenGL / VirGL 用户态与内核侧实现，因此-gl不会带来 RT-Thread 内的 OpenGL 加速；图形演示请使用-graphic（virtio-gpu-device）配合 framebuffer 栈。

GDB 调试：

./qemu.py -debug

更大内存与 GICv3：

./qemu.py -mem 256 -gic 3

挂载 CD-ROM：

./qemu.py -cdrom /path/to/image.iso

VirtIO Sound 音频：

./qemu.py -sound virtio

9P 目录共享（需先启用RT_VIRTIO_9P）：

./qemu.py -9p /path/to/share

AMP 异构多核（RPMSG 从核，须 Smart 版本）：

./qemu.py -dtbo amp.dtsi -mem 300

说明：AMP 示例要求启用Smart 版本（menuconfig 中RT_USING_SMART），且必须使用-mem 300（bsp/qemu-virt64-aarch64/amp.dtsi 内存布局约需 300 MB，默认 128 MB 不足）。qemu.py检测到amp_soc时会将-smp自动加 1（例如RT_CPUS_NR=4时实际以-smp 5启动）。QEMUloader会预先将amp.dtb与rtthread.bin加载到amp.dtsi指定的固定物理地址（如kernel-entry = 0x48480000），主核再通过 PSCI 拉起从核。标准版内核要求在虚拟地址与物理地址相等的区域运行，无法用于从核地址空间。请在 menuconfig 中开启 Smart 后重新编译。

摄像头演示（camera.c叠加画面到 framebuffer，需配合-graphic）：

./qemu.py -graphic -camera /dev/video0

说明：-camera必须传入宿主机 V4L2 设备路径。Linux 下需先安装 libvfio-user（详见 bsp/qemu-virt64-aarch64/qemu-device-camera.c 注释），并确保当前用户对设备节点有读权限（例如sudo usermod -aG video $USER后重新登录，或用ls -l /dev/video0确认权限）。若设备正被其他程序占用，也会打开失败。脚本会在后台编译并启动qemu-device-camera辅助进程，等待/tmp/qemu-device-camera.sock就绪后启动 QEMU，并在 QEMU 退出后结束辅助进程（kill -15 \pidof qemu-device-camera``）。

3.6 控制台与 Telnet

VirtIO Console 连接示例：

telnet 127.0.0.1 4321

从qemu.py源码可见，4321 端口通过-chardev socket,port=4321,server=on,telnet=on+virtserialport,name=org.rt-thread.console提供；4322 端口通过pci-serial挂接 8250 PCI 串口；4323 端口仅在-dtbo模式下以-serial telnet:localhost:4323,server,nowait追加。

3.7 网络

默认使用 user 模式网络（-netdev user），并自动追加hostfwd=tcp::12055-:22将 SSH 转发到本机12055端口（可用-ssh修改）。

TAP 网卡模式示例（以tap0为例）：

./qemu.py -tap

Linux 下需预先配置 TAP 网桥（qemu.py注释中给出了完整的 bridge 建立/拆除命令序列，包括ip link add br0 type bridge、ip tuntap add dev tap0 mode tap等）。Windows / WSL 下 TAP 支持有限。TAP 模式下 SSH 端口转发不可用（脚本会打印Warning: SSH not set in TAP）。

4. QEMU 默认挂载设备

qemu.py默认向虚拟机挂载以下设备（与驱动默认配置对应）。UFS 仅在 QEMU ≥ 8.2.0 时挂载；带触发条件的可选设备在表中标注。

其中基础命令行模板（cmd_base）还包含了-M virt,acpi=on,its=on,gic-version=N、-cpu max、-kernel rtthread.bin、-serial mon:stdio等关键参数，-device edu,dma_mask=0xffffffff用于挂载 QEMU 教学设备。注意 pflash 有 pflash0/pflash1 两个实例：pflash0 用于 BootROM（如 UEFI），因此脚本只使用 pflash1（-drive if=pflash,...,index=1）。

5. 驱动支持情况

5.1 默认已启用

以上配置均可在 bsp/qemu-virt64-aarch64/rtconfig.h 中找到对应的#define（如RT_SERIAL_PL011、RT_RTC_PL031、RT_PIN_PL061、RT_WDT_I6300ESB、RT_ATA_AHCI_PCI、RT_NVME_PCI、RT_USING_UFS、RT_USING_MTD_NOR_CFI、RT_GRAPHIC_FB、RT_USING_MBOX/RT_MBOX_PIC、RT_USING_RPMSG/RT_RPMSG_RT_THREAD_VIRTIO等），可作为判断驱动可用性的权威依据。

5.2 默认未启用但可通过 menuconfig 开启

本 BSP 已启用 PCI 总线与 VirtIO PCI 传输（RT_VIRTIO_TRANSPORT_PCI、RT_USING_PCI），QEMU 中也已挂载对应设备。下列驱动在默认.config中未勾选，开启相应 Kconfig 选项并重新编译后即可使用（无需修改qemu.py）：

说明：凡标注depends on RT_USING_PCI的 PCI 类驱动，均可在此 BSP 上通过 menuconfig 启用；QEMU 侧若未挂载对应设备，需自行在qemu.py中添加-device参数。

5.3 BSP 特有功能（驱动层）

5.4 示例应用（applications/）

main.c：默认应用，系统启动后输出hello rt-thread，随后进入 msh。

amp.c（AMP + RPMSG）：QEMUloader预先将amp.dtb与rtthread.bin加载到 bsp/qemu-virt64-aarch64/amp.dtsi 指定地址，主核再通过amp_soc设备树节点与 PSCI 拉起从核 CPU。主从之间通过 VirtIO RPMSG + Mailbox 通信。主核将 VirtIO Blockvdb的资源信息写入从核 DTB 后启动从核。qemu.py会为这颗额外 CPU 将-smp加 1，并额外挂载virtio-block的 AMP 副本镜像（virtio.amp.qcow2）。

版本要求：须Smart 版本（menuconfig 中RT_USING_SMART），且须使用-mem 300。标准版内核必须在虚拟地址与物理地址一致的映射下运行；AMP 从核加载到独立物理内存区域（见amp.dtsi中amp_memory、kernel-entry等），不满足该约束，因此标准版无法用于 AMP 演示。

启动方式：

./qemu.py -dtbo amp.dtsi -mem 300

从核控制台：telnet localhost 4323。

msh 命令：

系统启动时会自动创建 RPMSG 端点（rpmsg_char0，端点名rpmsg-char，地址 114/514）。从核侧地址互换。在-dtbo模式下，qemu.py会为 bootargs 前置rpmsg.mode=master，并将amp.dts与运行时 DTB 合并（借助tools/dtc.py的dts_to_dtb）后作为最终 DTB 启动 QEMU。

camera.c（摄像头预览）：将 vfio-user PCI 摄像头画面居中叠加到 framebuffer，默认设备camera0→fb0，约 10 秒（300 帧）。

启动方式（Linux 宿主机，已安装 libvfio-user 且存在 V4L2 摄像头）：

./qemu.py -graphic -camera /dev/video0

msh 命令：

camera [摄像头设备] [framebuffer设备]

示例：camera camera0 fb0

6. 存储与分区

• 根文件系统默认挂载在 VirtIO Block 第一个分区vda0，文件系统类型elm（FatFs），对应 bootargs 中的root=vda0 rootfstype=elm rootwait rw。
• 各存储镜像首次运行自动创建为 64 MBqcow2文件，可通过qemu-img扩容或预先替换。
• pflash0 用于 BootROM（如 UEFI），本 BSP 使用 pflash1（flash.qcow2）作为 CFI NOR；pflash0 数据在 QEMU 退出后不保留。
• Linux 下可使用qemu-nbd+fdisk对qcow2镜像分区（Windows 不支持）。qemu.py注释中给出了完整流程：modprobe nbd max_part=12→qemu-nbd --connect=/dev/nbdX ABC.qcow2→fdisk /dev/nbdX→qemu-nbd --disconnect /dev/nbdX。

7. QEMU Monitor 热插拔提示

在 QEMU Monitor 中可动态增删 VirtIO 串口端口：

(qemu) chardev-add socket,host=127.0.0.1,port=4323,server=on,wait=off,telnet=on,id=console2 (qemu) device_add virtserialport,chardev=console2,name=org.rt-thread.port,id=port2 (qemu) device_del port2 (qemu) chardev-remove console2

VirtIO 设备可选参数（在qemu.py中按需添加）：

• 禁用 legacy：-global virtio-mmio.force-legacy=false
• Virtqueue packed：-device virtio-XXX-device,packed=on
• PCI 模式（≥ 1.0）：-device virtio-XXX-pci,disable-legacy=on

8. 修改配置后的注意事项

• 修改 CPU 数量后，重新编译使RT_CPUS_NR与之一致（或用qemu.py -smp覆盖）。-dtbo模式下qemu.py会自动将 CPU 数加 1。
• 超过 8 核时 GIC 自动切换为 v3（qemu.py中if q_smp > 8: q_gic = 3），也可手动指定-gic 3。gic-version=max仅在-el 2且 GICv3 时由脚本内部设置。
• 启用 9P 目录共享需 QEMU 编译时包含 virtfs（--enable-virtfs）。
• 使用-gl需 QEMU 编译时包含 OpenGL / VirGL（--enable-opengl、--enable-virglrenderer）；这与 RT-Thread 是否支持 OpenGL 无关，当前软件栈默认仅 2D 图形。
• AMP（-dtbo）须 Smart 版本内核（RT_USING_SMART）、-mem 300，且自动增加 CPU 数；标准版要求 VA=PA 运行，无法用于从核固定物理地址加载场景。
• -camera须传入宿主机 V4L2 设备路径，仅支持 Linux，且需 libvfio-user；当前用户须能访问该设备（通常加入video组）；-graphic仅camera.cframebuffer 预览演示需要。
• 修改根设备或启动参数时，通过-bootargs覆盖默认参数。

结语

bsp/qemu-virt64-aarch64是 RT-Thread 官方维护的"全外设"虚拟验证 BSP：一方面通过 VirtIO / PCI 总线覆盖了块存储、SCSI、NVMe、AHCI、UFS、网络、GPU、输入、音频、加密、随机数、控制台等主流外设驱动；另一方面借助 QEMU 的动态设备挂载与热插拔能力，配合-dtbo、-camera等扩展参数，还能演练 AMP 异构多核与 vfio-user 设备直通这类高级场景。开发者完全可以基于本文的编译、启动与配置流程，在无实体硬件的情况下完成驱动开发、内核调试与功能验证，是学习 AArch64 平台驱动开发与 RT-Thread 设备模型（DM）/ OFW / PCI 框架的绝佳入口。

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS