RT-Thread 在 QEMU VExpress-A9 上的运行指南：BSP 编译、启动脚本、SD 卡文件系统与调试全解析

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

本文围绕 RT-Thread 仓库中的bsp/qemu-vexpress-a9板级支持包（BSP），系统讲解如何在一台没有真实 ARM 开发板的 PC 上，通过 QEMU 虚拟机编译、启动并调试 RT-Thread：从 env / Linux 工具链的编译方式、六个 QEMU 启动脚本的参数含义，到 RT-Studio 与命令行两种运行形态、SD 卡文件系统的自动挂载与格式化机制，再到该 BSP 支持的 UART、SDIO、CLCD、键盘鼠标与以太网外设。读完本文，你可以在 Windows 或 Linux 上一键跑起带 msh 控制台、文件系统和网络栈的 RT-Thread，并掌握 QEMU 与源码级的排查手段。

1 BSP 概览：用 QEMU 模拟一块“并不存在”的 ARM 开发板

1.1 Versatile Express 与 QEMU 的软件模拟特性

Versatile Express（VExpress）是 ARM Ltd 提供的一套开发环境，硬件上由 uATX 主板和 CoreTile Express A9x4 子板组成，面向 Cortex-A9 四核处理器。其核心是一套基于 FPGA 的开发环境——Cortex-A 芯片的逻辑本身就是 FPGA 上的硬件逻辑，因此并不存在一颗真实的对应芯片。

QEMU/VExpress-A9 则是 QEMU 模拟器针对 ARM VExpress-A9 FPGA 开发板做的指令级软件虚拟机。因为是纯软件仿真，它可以被配置成多种模式：单核 Cortex-A9、多核 Cortex-A9，乃至多核 Cortex-A15，同时还能模拟出 VExpress FPGA 开发板上绝大多数外设。

本 BSP 正是针对 QEMU/VExpress-A9 的一份移植。需要说明的是，它从未在真实的 VExpress FPGA 开发板上运行过，主要价值是为开发者提供便利，用以使用、验证 RT-Thread 的各类功能；对真实 FPGA 开发板的执行情况不做任何假设。

当前 QEMU/VExpress-A9 对应的硬件特性如下：

| 硬件 | 描述 | | -- | -- | | CPU | ARM Cortex-A9（单核） | | 主频 | NA | | Memory | 128MB（0x60000000 - 0x68000000） |

1.2 BSP 目录构成

该 BSP 目录（bsp/qemu-vexpress-a9）自包含一套完整的 RT-Thread 工程骨架：

• 构建入口：Kconfig、SConstruct、SConscript、rtconfig.py、rtconfig.h；
• 链接脚本：link.lds（普通模式）与link_smart.lds；
• 应用层：applications/main.c（入口打印Hello RT-Thread!）、applications/mnt.c（SD 卡文件系统挂载）、lcd_init.c与lvgl/示例；
• 驱动层：drivers/下的 UART、SDIO、CLCD、键盘、鼠标、SMC911x 以太网、定时器等板级驱动；
• 六个 QEMU 启动脚本：qemu.bat、qemu.sh、qemu-dbg.bat、qemu-dbg.sh、qemu-nographic.bat、qemu-nographic.sh；
• 文档与插图：README.md 及figures/目录。

2 编译：env 与 Linux 工具链两条路径

2.1 推荐方式：env 工具 + scons

推荐使用 RT-Thread env 工具编译工程。在bsp/qemu-vexpress-a9目录中打开 env 环境（Windows 下可右键该目录选择 “ConEmu Here” 打开），运行：

scons -j4

编译正确无误后，目录下会产生rtthread.elf和rtthread.bin两个文件。QEMU 中一般使用 elf 方式运行，所以只需rtthread.elf即可（Windows 的qemu.bat使用rtthread.elf，Linux 脚本则使用rtthread.bin）。rtthread.bin由构建脚本在链接后通过 objcopy 自动生成，见 rtconfig.py 中的POST_ACTION = OBJCPY -O binary $TARGET rtthread.bin。

2.2 工具链版本与 Linux 下的安装

当前 BSP 测试使用的 RT-Thread Env 版本与 GCC 交叉编译工具链版本见figures/下的对应截图。如果在 Linux 下使用，推荐直接用发行版包管理器安装arm-none-eabi工具链——rtconfig.py 中EXEC_PATH默认即为/usr/bin（EXEC_PATH = os.getenv('RTT_EXEC_PATH') or r'/usr/bin'），装好后无需额外配置。以 Debian/Ubuntu 为例：

sudo apt install gcc-arm-none-eabi libstdc++-arm-none-eabi-newlib

其中libstdc++-arm-none-eabi-newlib提供链接阶段-lsupc++所需的库（rtconfig.py的LFLAGS中确实包含-lsupc++ -lgcc -static）。也可以从 Arm GNU Toolchain 官方下载页获取预编译版本，解压后用环境变量RTT_EXEC_PATH指向其bin目录即可，无需改动配置文件。

2.3 编译配置要点（rtconfig.py 解读）

从源码结构看，rtconfig.py 是本 BSP 的编译核心，值得关注的要点：

• 架构声明：ARCH = 'arm'、CPU = 'cortex-a'、CROSS_TOOL = 'gcc'、PLATFORM = 'gcc'；
• 交叉编译前缀：PREFIX = os.getenv('RTT_CC_PREFIX') or 'arm-none-eabi-'，即默认使用arm-none-eabi-gcc系列；
• 设备编译选项：DEVICE = '-march=armv7-a -mtune=cortex-a7 -ftree-vectorize -ffast-math -funwind-tables -fno-strict-aliasing'，并配合软浮点-mfloat-abi=softfp -mfpu=neon；
• 链接脚本：LINK_SCRIPT = 'link.lds'，链接时通过-T link.lds指定；
• 构建模式：BUILD = 'debug'时追加-O0 -gdwarf-2便于 gdb 调试；
• 一个有趣的细节：脚本每次构建前会根据宿主机 MAC 地址自动生成drivers/automac.h，为模拟的网卡分配固定前缀的 MAC 地址（AUTOMAC0..5），这正是 QEMU 中 EMAC 驱动能稳定工作的前提之一。

3 执行脚本：六种启动方式与 QEMU 参数解读

3.1 脚本清单

bsp 目录下已提供如下执行脚本：

3.2 脚本实际内容与参数含义

对比四个 Linux/Windows 脚本的真实内容，可以归纳出 QEMU 命令行参数的含义（Windows 版与 Linux 版逻辑一致，仅创建虚拟 SD 卡镜像的命令不同：Windows 用qemu-img create -f raw sd.bin 64M，Linux 用dd if=/dev/zero of=sd.bin bs=1024 count=65536，两者都是先保证存在一块 64MB 的 raw 磁盘镜像）：

| 参数 | 含义 | | -- | -- | |-M vexpress-a9| 指定模拟的机器型号为 VExpress-A9 | |-smp cpus=2| 以双核 SMP 模式启动（qemu.sh / qemu.bat / qemu-dbg 系列使用） | |-kernel rtthread.bin/rtthread.elf| 指定内核镜像文件 | |-serial stdio| 将串口（RT-Thread 控制台 uart0）重定向到宿主标准输入输出 | |-nographic| 无图形界面的纯文本模式（同样把串口接到 stdio） | |-sd sd.bin| 挂载虚拟 SD 卡镜像 | |-S -s| 调试模式：-S表示启动即暂停等待调试器，-s表示在 tcp:1234 开放 gdbstub 端口 |

例如 qemu-nographic.sh 的内容为：

if [ ! -f "sd.bin" ]; then dd if=/dev/zero of=sd.bin bs=1024 count=65536 fi qemu-system-arm -M vexpress-a9 -smp cpus=2 -kernel rtthread.bin -nographic -sd sd.bin

qemu-dbg.sh 则在末尾追加-S -s，配合arm-none-eabi-gdb rtthread.elf即可在 QEMU 内进行断点调试。顺带说明：虽然脚本用-smp cpus=2启动，但 rtconfig.h 中RT_CPUS_NR为 1，即 RT-Thread 侧默认以单核配置编译；README 硬件特性表也标注 CPU 为单核 Cortex-A9，这一点在实际使用时无需特意修改。

4 三种运行形态详解

4.1 RT-Studio IDE 下运行（推荐学习方式）

RT-Studio 方式简单易用，被 README 推荐用于学习。流程为：

1. 创建 QEMU 工程：新建 RT-Thread 项目时选择“基于开发板”，开发板选择 QEMU-VEXPRESS-A9；
2. 创建完成后选中 qemu-a9 工程并编译工程；
3. 调试工程：程序会停在main函数开头处；
4. 点击全速运行，RT-Thread 即正常运行起来，可在 msh 控制台交互。

该流程的界面截图见bsp/qemu-vexpress-a9/figures/下的image-20220626125511399.png、image-20220626125644099.png、image-20220626125717698.png与image-20220626125837849.png。

4.2 Windows ENV 下运行：启动与退出

启动 QEMU

在 Windows 的 bsp 目录下打开 env，敲入qemu.bat即可直接运行。该脚本默认把串口输出到 stdio（即控制台），所以执行后立刻能看到输出结果。

默认情况下，系统启动后会自动完成 SD 卡的检测与文件系统挂载：

注意：默认情况下 SD 中不存在文件系统，因此首次挂载会失败；程序中检测到挂载失败后会自动执行mkfs对文件系统进行格式化，格式化完成后再次执行mount，文件系统即挂载成功。

挂载成功后可以验证文件系统读写是否正常，例如ls查看根目录、echo写文件、cat读文件：

文件系统的这套“自动格式化重挂载”逻辑并非魔法，而是写在 applications/mnt.c 中，并通过INIT_ENV_EXPORT(mnt_init)在环境初始化阶段自动执行：它先尝试dfs_mount("sd", "/", "elm", 0, 0)，失败后调用dfs_mkfs("elm", "sd")格式化，再重新挂载。这也解释了为何首次运行（空 SD 镜像）与后续运行（已有 FAT 文件系统）的日志不同。

当然，也可以尝试使用其他两个.bat文件（qemu-nographic.bat、qemu-dbg.bat）启动运行。

退出 QEMU

在 msh 提示输入的状态下，按下CTRL+C，出现以下提示后按下y，即可退出 QEMU：

hello rt-thread msh /> msh /> msh />Terminate batch job (Y/N)? y

4.3 Windows VSCode 中运行

该方式可参考 RT-Thread 官方文档《使用 VS Code 开发 RT-Thread》（对应 QEMU/VSCode 应用笔记），其核心思路是：用 VS Code 打开 bsp 目录，借助 env 的编译环境执行 scons，再通过 Cortex-Debug 等插件连接qemu-dbg.bat开放的 gdbstub 端口进行编译、下载与调试一体化开发。

4.4 Linux 下运行：安装 QEMU 与启动

安装 qemu-system-arm

Linux 下与 Windows 稍有区别：Windows 的 env 工具自带qemu-system-arm，而 Linux 默认没有该工具，直接执行./qemu.sh会报错：

bsp/qemu-vexpress-a9$ ./qemu-nographic.sh ./qemu-nographic.sh: line 5: /usr/bin/qemu-system-arm: No such file or directory

此时需要在 Linux 平台安装qemu-system-arm工具包，以 Ubuntu 为例：

bsp/qemu-vexpress-a9$ sudo apt-get install qemu-system-arm

安装成功后，输入以下命令应能看到版本信息，证明其可正常使用：

bsp/qemu-vexpress-a9$ qemu-system-arm --version QEMU emulator version 4.2.1 (Debian 1:4.2-3ubuntu6.17) Copyright (c) 2003-2019 Fabrice Bellard and the QEMU Project developers

启动 QEMU

Linux 平台一般是不带界面的服务器，所以推荐用qemu-nographic.sh启动，运行示例输出如下：

bsp/qemu-vexpress-a9$ ./qemu-nographic.sh WARNING: Image format was not specified for 'sd.bin' and probing guessed raw. Automatically detecting the format is dangerous for raw images, write operations on block 0 will be restricted. Specify the 'raw' format explicitly to remove the restrictions. ALSA lib confmisc.c:767:(parse_card) cannot find card '0' ... audio: Failed to create voice `lm4549.out' \ | / - RT - Thread Operating System / | \ 4.1.0 build Nov 24 2021 19:49:17 2006 - 2021 Copyright by rt-thread team lwIP-2.1.2 initialized! [I/sal.skt] Socket Abstraction Layer initialize success. [I/SDIO] SD card capacity 65536 KB. [I/SDIO] switching card to high speed failed! [W/POSIX.delay] Please consider implementing rt_hw_us_delay() in another file. hello rt-thread msh /> msh /> msh />

注意：前面的错误信息可以忽略——包括 sd.bin 未声明 raw 格式的告警、ALSA 声卡初始化失败（服务器无音频设备所致）等。只要能看到 RT-Thread 的启动 logo 输出，且 msh 能正常输入输出，即可进行代码调试。同时从日志可见网络栈（lwIP-2.1.2 + SAL Socket Abstraction Layer）与 SDIO 子系统均已随系统初始化，印证了该 BSP 对外设的完整模拟能力。

退出 QEMU

Linux 下退出方式与 Windows 不同：在 msh 提示输入的状态下，按下CTRL+A，再按下X，即可退出 QEMU：

hello rt-thread msh /> msh /> msh />QEMU: Terminated

5 支持的外设驱动一览

该 BSP 的驱动支持情况如下：

对照drivers/目录的源码，可以逐项找到实现对应：

• UART：drv_uart.c /drv_uart_v2.c，rtconfig.h 中BSP_USING_UART0已默认使能，且RT_CONSOLE_DEVICE_NAME指定为"uart0"，即控制台走 UART0；
• SD/MMC：drv_sdio.c，配合RT_USING_SDIO与文件系统栈RT_USING_DFS_ELMFAT（elm-FAT）实现 SD 卡块设备与 FAT 文件系统；
• CLCD：drv_clcd.c，配套rt_lcd.h与applications/lcd_init.c，QEMU 中以图形窗口呈现；
• Key / Mouse：drv_keyboard.c、drv_mouse.c，模拟开发板键盘与鼠标输入；
• EMAC：drv_smc911x.c，对应 VExpress 板载 SMSC LAN911x 以太网控制器，配合上文提到的自动生成 MAC 地址的automac.h使用；
• 定时器：drv_timer.c；多核辅助：secondary_cpu.c。

6 运行常见现象与注意事项

• 首次启动 SD 卡挂载失败属正常：空sd.bin上没有 FAT 文件系统，mnt.c会自动执行mkfs格式化后再次挂载；格式化后文件系统即可正常读写（见第 4.2 节）。
• switching card to high speed failed!与POSIX.delay警告可忽略：前者是模拟器对 SD 高速模式的限制，后者提示rt_hw_us_delay()未实现，均不影响 msh 与文件系统的正常使用。
• 图形界面可选：qemu-nographic系列以纯文本方式运行，适合服务器/SSH 环境；qemu.bat/qemu.sh会同时打开 VExpress 的图形显示窗口（若未初始化显示，窗口内会提示 “Guest has not initialized the display (yet)”）。
• 调试端口：qemu-dbg系列通过-S -s在 tcp:1234 提供 gdbstub，可用arm-none-eabi-gdb连接后设置断点、查看寄存器与内存，配合 debug 模式编译（-O0 -gdwarf-2）体验最佳。

7 联系人信息

本 BSP 的维护人为 bernard 与 recan-li，相关驱动与脚本问题可在 RT-Thread 社区按此信息查找维护人沟通。

综上，bsp/qemu-vexpress-a9是一份开箱即用的“模拟开发板”BSP：一条scons -j4命令完成编译，一个qemu.bat/qemu-nographic.sh命令完成启动，msh 控制台、SD 卡 FAT 文件系统、网络栈与 CLCD 图形界面全部可用。无论你手上有没有真实硬件，都可以借助它快速验证 RT-Thread 内核机制、设备驱动框架乃至 GUI 应用。

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