运行

使用 QEMU 启动系统、运行自检并查看日志。

本页目录

检查范围

层级	入口	能够说明	不能说明
构建	build_system*.sh	镜像、模块与用户态产物生成。	内核一定能启动、测试已运行。
交互启动	run_system.sh 或本页 QEMU 命令。	选定镜像可进入开发 shell。	完整模块与 SDK 自检已通过。
自动系统检查	x86 verify_system.sh；ARM/RISC-V verify_system_*。	x86 包含自检；跨架构基本脚本主要检查启动文本。	跨架构的启动 PASSED 等于 guest 测试全通过。
跨架构客体检查	verify_guest_arm64.sh、verify_guest_riscv64.sh	运行标志、配置、模块及 rt/spsc/signal 测试的标记。	真实设备采集、硬件端到端时延或模型准确率。

run_system.sh 实际 exec qemu-system-x86_64，不是硬件直启脚本，也不安装引导器或刷写磁盘。所有命令要求先完成对应架构构建；自定义 BUILD_ROOT 必须继续传给运行与验证命令。

x86_64 启动

bash

./scripts/run_system.sh

脚本固定 -machine pc、-cpu max、-m 512、-smp 2，加载 images/xtos-bzImage 与 images/xtos-rootfs.cpio.gz，使用 console=ttyS0 rdinit=/init loglevel=4、-nographic、-no-reboot。附加参数可通过脚本尾部 "$@" 交给 QEMU，但脚本没有 QEMU_MEM/QEMU_SMP 环境参数；需要调整时理解 QEMU 参数，不能把交叉验证脚本的变量当成全局选项。

客体 shell：手动自检不会由外层 /init 自动打印 XTOS_SYSTEM_TEST=PASS。

uname -r
cat /sys/kernel/realtime
cat /proc/cmdline
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
cat /proc/modules
/usr/bin/xtos-selftest

手动 xtos-selftest 使用 set -eu，失败即非零退出。

它检查实时标志与配置、加载三个模块、运行三个 SDK 测试、CSV 管线与信号基准；成功时打印 xtos_modules=pass 和 guest_userspace=pass。

XTOS_SYSTEM_TEST=PASS 是 /init 在自动自检分支打印的最终标记，不是所有手工调用都会输出的文本。

退出可在客体 poweroff -f，或 Ctrl+a 再按 x 退出 QEMU。x86 的 /init 会重启退出的 shell，所以单纯 exit 不代表虚拟机关机。开发控制台是本地、无默认网络服务的 root shell，不应当作经过加固的多用户生产系统。

x86_64 自检

bash

QEMU_TIMEOUT=180 ./scripts/verify_system.sh

verify_system.sh 要求内核镜像、initramfs 和 kernel.config 都非空，使用 timeout --foreground 启动 QEMU，在命令行增加 panic=1 xtos.selftest=1，并将串口保存到 system-qemu.log。客体自检结束由 /init 输出 PASS 或 FAIL，再 sync/poweroff。这个流程不留下可继续输入命令的 shell。

QEMU 退出状态为 0；超时、异常退出或主机启动失败均不能通过。
去掉串口 CR 后存在完整行 XTOS_SYSTEM_TEST=PASS。
日志没有 XTOS_SYSTEM_TEST=FAIL 或 Kernel panic；最终主机命令退出 0。

自检的 CSV JSON 在 /run/pipeline.json，基准在 /run/signal-benchmark.json；前者内容被打印进串口日志，后者自检只要求文件存在且非空，并不把所有数值自动带回主机。需要保存基准内容时，使用交互 shell 显示并另行记录。这些 fixture 结果和基准计时不是硬件采集报告。

跨架构自检

bash

QEMU_TIMEOUT=180 ./scripts/verify_system_arm64.sh
QEMU_TIMEOUT=300 QEMU_MEM=2G QEMU_SMP=2 ./scripts/verify_guest_arm64.sh

QEMU_TIMEOUT=300 ./scripts/verify_system_riscv64.sh
QEMU_TIMEOUT=360 QEMU_MEM=2G QEMU_SMP=2 ./scripts/verify_guest_riscv64.sh

verify_guest_* 复制正常 rootfs，在验证专用 initramfs 中把 /init 替换成 system/rootfs/xtos-guest-check，再启动对应 QEMU。

ARM64 使用 virt/cortex-a57、ttyAMA0；RISC-V 使用 virt/rv64、ttyS0 与固定 OpenSBI 固件路径。

QEMU_TIMEOUT 默认分别为 300/360 秒，QEMU_MEM 默认 2G，QEMU_SMP 默认 2。

默认启动镜像不受替换 /init 的影响。

应出现的关键标记；RISC-V 另需 OpenSBI，且不能出现 Kernel panic。

XTOS_GUEST_CHECK=START
realtime=1
preempt_rt=y
xtos_sched=y
module_xtos_bci_core=ok
module_xtos_bci_buffer=ok
module_openbci_cyton=ok
xtos_modules=pass
guest_test_rt=pass
guest_test_spsc=pass
guest_test_signal=pass
guest_userspace=pass
XTOS_GUEST_CHECK=DONE

严格解析器包含 ARM64 的 14 项检查、RISC-V64 的 15 项检查（后者增加 OpenSBI）；看每项标记而不是只数 DONE。

test_rt 同时测试调度和锁内存的权限失败边界，允许指定 errno，因此 guest_test_rt=pass 不是“所有线程都成功切为 SCHED_FIFO”的证明。

跨架构检查没有 x86 的 EEG 管线和基准覆盖。

跨架构 shell

公开基线只有 x86_64 的 run_system.sh。ARM64/RISC-V64 交互模式可直接复用正常镜像启动 QEMU；不要使用 guestcheck initramfs，因为它会执行测试后关机。下面设置默认构建目录；如果使用自定义 BUILD_ROOT，先把 B 改成同一绝对路径。

主机：ARM64 正常启动镜像。

B="$PWD/.build"
qemu-system-aarch64 -machine virt -cpu cortex-a57 -m 2G -smp 2 \
  -kernel "$B/kernel-install-arm64/Image" \
  -initrd "$B/initramfs-arm64.cpio.gz" \
  -append 'console=ttyAMA0 panic=1 init=/sbin/init' \
  -nographic -no-reboot

主机：RISC-V64 正常启动镜像。

B="$PWD/.build"
qemu-system-riscv64 -machine virt -cpu rv64 -m 2G -smp 2 \
  -bios /usr/share/qemu/opensbi-riscv64-generic-fw_dynamic.bin \
  -kernel "$B/kernel-install-riscv64/Image" \
  -initrd "$B/initramfs-riscv64.cpio.gz" \
  -append 'console=ttyS0 panic=1 init=/sbin/init' \
  -nographic -no-reboot

客体：跨架构测试位置是 /bin，不是 /usr/libexec/xtos。

uname -m
uname -r
cat /sys/kernel/realtime
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
cat /proc/modules
/bin/test_rt
/bin/test_spsc
/bin/test_signal
poweroff -f

串口提示 can’t access tty 或 job control 警告可能来自 BusyBox 控制台设置，基本验证脚本将其作为可选 shell 文本。是否真的启动成功仍需确认可执行命令、运行标志与完整 guest 检查；不要仅因看到警告就改写内核配置或宣称系统失败。

日志与排查

检查	相对 BUILD_ROOT 的日志
x86_64 系统自检	system-qemu.log
ARM64 基本启动	qemu-arm64-output.txt
ARM64 客体检查	qemu-arm64-guestcheck-output.txt
RISC-V64 基本启动	qemu-riscv64-output.txt
RISC-V64 客体检查	qemu-riscv64-guestcheck-output.txt

镜像缺失：确认 BUILD_ROOT 与架构正确，按“构建系统”检查 Image/bzImage 和 initramfs 路径，而不是复制另一个架构的镜像。
OpenSBI 缺失：确认指定固件文件存在并安装 opensbi/QEMU 的发行包；脚本没有 OPENSBI 环境路径覆盖参数。
模块 fail：使用 xtos_bci_core、xtos_bci_buffer、openbci_cyton 真正模块名，检查 /lib/modules/<uname -r> 与当前内核匹配，查看 dmesg。
guest_test_*=missing：回看交叉构建的测试编译警告与静态 libc 依赖；不要通过跳过该检查来宣称完成。
realtime 不为 1：检查最终 .config、/proc/config.gz 与实际加载的镜像，不只搜索启动横幅里的 PREEMPT_RT 文本；6.6-rt 的横幅可能只显示 PREEMPT。

硬件边界

QEMU 启动、模块装载、用户态测试和 fixture 管线不是实际硬件端到端验证。OpenBCI 需要另外确认设备树、串口、包布局、数值单位、SDK raw 转换、时间戳、丢样与溢出；公开基线的 float 读取断点尚不支持直接宣称正确硬件到 DSP 通路。真实硬件性能、板卡 bring-up、模型结果和反馈安全性都需要独立的测试与证据。

源码依据：提交 dd313955ad57542bcd2af8827157d1bbd0cf5e83 的 scripts/run_system.sh、scripts/verify_system.sh、scripts/verify_system_arm64.sh、scripts/verify_system_riscv64.sh、scripts/verify_guest_arm64.sh、scripts/verify_guest_riscv64.sh、system/rootfs/init、system/rootfs/usr/bin/xtos-selftest、system/rootfs/xtos-guest-check、sdk/libxtos-rt/tests/test_rt.c、examples/bci_test.c 与 sdk/libxtos-bci/src/session.c。