排错
按现象、检查结果和修复路径处理构建、客体与 BCI 问题。
本页目录
错误记录
先区分构建脚本、主机验证器和客体测试。主机 uname 不能证明 QEMU 客体是 PREEMPT_RT。BUILD_ROOT 未设置时才是 .build;不要先删除 .build。
git rev-parse HEAD
git status --short
uname -a
gcc --version
make --version
BUILD_ROOT="${BUILD_ROOT:-$PWD/.build}"
printf 'build_root=%s\n' "$BUILD_ROOT"
if QEMU_TIMEOUT=300 ./scripts/verify_system.sh; then
verify_status=0
else
verify_status=$?
fi
printf 'verify_exit=%s\n' "$verify_status"| 现象 | 检查结果 | 修复 |
|---|---|---|
| verify_system.sh 返回 1 | 读取 system_qemu=fail exit=… 和 system-qemu.log;1 是验证器状态,不一定是 QEMU 原始状态。 | 按日志中的启动、标记或 panic 修复。 |
| timeout 返回 124 | 预算耗尽;检查日志进度和最终标记。 | 先定位停顿,不用增加预算掩盖错误。 |
| guest 返回 1 | 读取缺失标记和 Failed 数量;脚本忽略 QEMU 管线状态。 | 修复第一项缺失或失败检查。 |
| 基础跨架构返回 0 | 基础脚本允许最多两项 FAIL。 | 继续运行 verify_guest_*,要求 Failed: 0。 |
依赖与资源
command not found、头文件缺失和链接失败先查 PATH 与开发包。build_system.sh 只检查部分工具。cc1 被终止通常查内存,No space left on device 查磁盘,源码语法错误查编译器输出。
for tool in gcc make flex bison bc cpio gzip rsync python3 depmod; do
command -v "$tool" || printf 'missing=%s\n' "$tool"
done
df -h .
free -h
command -v qemu-system-x86_64
command -v aarch64-linux-gnu-gcc
command -v riscv64-linux-gnu-gcc
test -r /usr/share/qemu/opensbi-riscv64-generic-fw_dynamic.bin| 缺失项 | Debian/Ubuntu 包 | 结果与修复 |
|---|---|---|
| 编译和生成工具 | build-essential flex bison bc | 安装后重跑失败阶段;内存不足时 JOBS=2。 |
| OpenSSL、ELF、libc 开发文件 | libssl-dev libelf-dev libc6-dev | 保留完整编译诊断,不把头文件错误归因于 QEMU。 |
| 打包和模块工具 | cpio gzip kmod rsync python3 file | x86 使用 cpio --reproducible,先确认选项存在。 |
| x86_64 QEMU | qemu-system-x86 | 需要 qemu-system-x86_64。 |
| ARM64 | crossbuild-essential-arm64 libc6-dev-arm64-cross qemu-system-arm | 需要 aarch64-linux-gnu-gcc 和 qemu-system-aarch64。 |
| RISC-V64 | gcc-riscv64-linux-gnu binutils-riscv64-linux-gnu libc6-dev-riscv64-cross qemu-system-misc opensbi | 检查 qemu-system-riscv64 和固定 OpenSBI 路径。 |
cpio --help | grep -- --reproducible
JOBS=2 ./scripts/build_system.sh镜像与超时
镜像缺失时完成对应构建,或把验证器指向实际 BUILD_ROOT。超时时看日志是否到达内核、init、测试或关机。普通跨架构镜像进入 BusyBox shell;只有 guestcheck 镜像自动检查并关机。
BUILD_ROOT="${BUILD_ROOT:-$PWD/.build}"
for image in xtos-bzImage xtos-rootfs.cpio.gz kernel.config; do
test -s "$BUILD_ROOT/images/$image" || printf 'missing_or_empty=%s\n' "$image"
done
grep -nE 'Linux version|Run /init|realtime=|xtos_modules=|guest_|XTOS_|Kernel panic|Power down|power down|error:' "$BUILD_ROOT/system-qemu.log"| 现象 | 检查 | 修复 |
|---|---|---|
| 没有 Linux version | QEMU、镜像、架构;RISC-V64 还查 OpenSBI。 | 修文件或命令后重跑同架构。 |
| 有内核,没有 START | 是否使用 guestcheck initramfs;ARM64 为 ttyAMA0,RISC-V64 为 ttyS0。 | 运行 verify_guest_*,不要把普通 shell 当作客体检查。 |
| 有 START,没有测试 PASS | 看 test_*、模块错误和 QEMU 进度。 | 恢复 rootfs 测试或修断言;确认只是慢时才加预算。 |
| 只有 DONE | 查 realtime、配置、模块、每个测试和 FAIL。 | DONE 不是通过;保留日志并修具体项。 |
QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh
QEMU_TIMEOUT=360 ./scripts/verify_guest_riscv64.sh实时配置
客体运行 xtos-rt-status:1/退出 0 为检测通过,0/退出 1 为已有节点未确认 RT,unknown/退出 2 为无法确认。/sys/kernel/realtime 缺失时,工具同时要求运行内核 /proc/config.gz 的 CONFIG_PREEMPT_RT=y 与 uname -v 的 PREEMPT_RT 标记;构建配置不能替代运行配置。
uname -r
cat /proc/mounts
/usr/bin/xtos-rt-status
zcat /proc/config.gz | grep -E '^CONFIG_(PREEMPT_RT|XTOS_SCHED|XTOS_BCI|XTOS_BCI_OPENBCI|IKCONFIG|IKCONFIG_PROC)='BUILD_ROOT="${BUILD_ROOT:-$PWD/.build}"
grep -E '^CONFIG_(PREEMPT_RT|XTOS_SCHED|XTOS_BCI|XTOS_BCI_OPENBCI|IKCONFIG|IKCONFIG_PROC)=' "$BUILD_ROOT/kernel-build-arm64/.config"
grep -E '^CONFIG_(PREEMPT_RT|XTOS_SCHED|XTOS_BCI|XTOS_BCI_OPENBCI)=' "$BUILD_ROOT/kernel-build-arm64/include/config/auto.conf"预期是 PREEMPT_RT=y、XTOS_SCHED=y、XTOS_BCI=m、XTOS_BCI_OPENBCI=m、IKCONFIG=y 和 IKCONFIG_PROC=y。交叉构建器只在 .config 不存在时初始化配置;旧 BUILD_ROOT 可能保留错误配置。
repair_build=$(mktemp -d "$HOME/xtos-repair-arm64.XXXXXX")
BUILD_ROOT="$repair_build" JOBS=2 ./scripts/build_system_arm64.sh
BUILD_ROOT="$repair_build" QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh模块版本
modprobe 名称是 xtos_bci_core、xtos_bci_buffer、openbci_cyton,不是 CONFIG_XTOS_BCI。编译目录有 .ko 不代表客体 /lib/modules 有匹配模块。模块检查必须在目标客体执行。
uname -r
find /lib/modules -maxdepth 2 -type f -name modules.dep -print
find /lib/modules -type f -name '*xtos*' -print
find /lib/modules -type f -name '*openbci*' -print
modprobe xtos_bci_core
modprobe xtos_bci_buffer
modprobe openbci_cyton
dmesg | tail -80
ls -d /sys/module/xtos_bci_core /sys/module/xtos_bci_buffer /sys/module/openbci_cyton| 错误 | 检查与修复 |
|---|---|
| module not found | 比较 uname -r 与 /lib/modules;确认 modules_install 和 depmod,重建匹配的 kernel/rootfs。 |
| invalid module format | 主机 modinfo 查 vermagic,与客体版本比较;不要强制加载。 |
| Unknown symbol | 保留 dmesg 符号名,查依赖、索引和混用的 .ko。 |
| Operation not permitted | 客体查 id;主机 root 不会给客体进程权限。 |
BUILD_ROOT="${BUILD_ROOT:-$PWD/.build}"
find "$BUILD_ROOT/rootfs-arm64/lib/modules" -type f -name 'xtos_bci_core.ko*' -exec modinfo -F vermagic {} \;
cat "$BUILD_ROOT/kernel-build-arm64/include/config/kernel.release"用系统构建脚本重新安装模块、生成 depmod 索引和 initramfs。不要把单个 .ko 复制到另一个版本目录;应在新 BUILD_ROOT 生成匹配内核和 rootfs。
库架构
file 对 .a 通常只显示 current ar archive。遇到 file in wrong format 时,读取实际归档成员,并用目标 objdump 检查 rootfs/usr/lib 下三个库的架构。
BUILD_ROOT="${BUILD_ROOT:-$PWD/.build}"
aarch64-linux-gnu-objdump -f "$BUILD_ROOT/rootfs-arm64/usr/lib/libxtos-rt.a"
aarch64-linux-gnu-objdump -f "$BUILD_ROOT/rootfs-arm64/usr/lib/libxtos-signal.a"
aarch64-linux-gnu-objdump -f "$BUILD_ROOT/rootfs-arm64/usr/lib/libxtos-bci.a"
riscv64-linux-gnu-objdump -f "$BUILD_ROOT/rootfs-riscv64/usr/lib/libxtos-rt.a"| 目标 | objdump 预期 | 编译器 |
|---|---|---|
| ARM64 | architecture: aarch64 | aarch64-linux-gnu-gcc |
| RISC-V64 | architecture: riscv:rv64 | riscv64-linux-gnu-gcc |
repair_source=$(mktemp -d "$HOME/xtos-archive-repair.XXXXXX")
git archive HEAD | tar -x -C "$repair_source"
cd "$repair_source"
JOBS=2 ./scripts/build_system_arm64.sh
QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.shARM64/RISC-V64 构建器会在源码目录重建 SDK 库,新的 BUILD_ROOT 不能隔离这些生成物。
需要同时保留两种架构时使用不同源码副本并串行构建。
若库架构正确但测试缺失,检查 Stage 4 警告;交叉脚本可能继续打包,严格 guest 会报告 guest_test_*=missing。
BCI 节点
分开检查模块加载、驱动绑定、设备注册和会话控制。examples/bci_test.c 默认使用 /dev/xtos0,也接受第一个参数指定路径。默认字符串不证明设备存在;普通串口或手工空节点不能替代已注册 XTOS BCI 设备。
id
ls -l /dev/xtos* /dev/ttyUSB* /dev/ttyACM* 2>/dev/null
find /sys/class -maxdepth 2 -iname '*bci*' -print
ls -d /sys/module/xtos_bci_core /sys/module/xtos_bci_buffer /sys/module/openbci_cyton
dmesg | tail -100| 错误 | 原因 | 修复 |
|---|---|---|
| ENOENT | 路径不存在;普通 QEMU 不接入真实 BCI。 | 查注册节点和绑定;无设备时记录未验证接通。 |
| EACCES / EPERM | session_create 使用 O_RDWR,需要读写权限。 | 按属主、组和进程身份授予访问;不要把 chmod 777 当通用修复。 |
| ENOTTY | 文件或驱动不支持 BCI ioctl,或请求编码不匹配;串口不实现 XTOS ioctl。 | 核对设备类型和内核/SDK UAPI;sudo 不能增加 ioctl。 |
| 有模块,无节点 | 模块存在不证明 serdev 绑定或设备注册。 | 查板卡串口、设备树和驱动日志;需要真实设备 bring-up。 |
#define XTOS_BCI_GET_INFO _IOR(XTOS_BCI_IOC_MAGIC, 1, struct xtos_bci_info)
#define XTOS_BCI_START_STREAM _IO(XTOS_BCI_IOC_MAGIC, 2)
#define XTOS_BCI_CHECK_IMP _IOR(XTOS_BCI_IOC_MAGIC, 8, uint32_t[32])v1.0.2 read_samples 将驱动 int32 纳伏数值转为 float 微伏,累积读取至请求字节数或 EOF,并自动重试 EINTR。分配大小溢出为 EOVERFLOW,malloc 失败通常 ENOMEM,EOF 留下非完整整数为 EIO;其他读取错误(含 EAGAIN)返回 -1,已消费的本次部分数据不交付。
read_samples 每次 malloc/free,不是无分配实时接口;frame snapshot 持有或待清理时返回 EBUSY。校准与阻抗均为 EOPNOTSUPP。Cyton 只支持 250 Hz,通道 gain 配置有寄存器回读;不支持的高采样率也为 EOPNOTSUPP。
旧 get_mmap_buffer 返回 NULL、size=0;有效会话为 EOPNOTSUPP。改用版本化 snapshot/config/frame 接口,按 token/cursor 消费并重试失败的释放;同一会话由应用串行化。frame 的 host_rx_ns 不是设备采样时间,新增元数据不等于实板验收。
测试与报告
三个 SDK 都有公开 test 目标。BCI 运行 test_samples、test_snapshot、test_snapshot_uapi、test_config、test_frame:覆盖软件转换、快照生命周期、UAPI 布局、配置验证与帧视图。它们使用 FIFO 或 syscall fixture,不验证真实设备或穷尽所有异常路径。
make -C sdk/libxtos-rt all test
make -C sdk/libxtos-signal all test
make -C sdk/libxtos-bci all test
./scripts/check_abi.shXTOS_ABI_SDK_ROOT="${BUILD_ROOT:-$PWD/.build}/userspace-source/sdk" ./scripts/check_abi.shcheck_abi.sh 默认读取源码 sdk/ 的共享库,可用 XTOS_ABI_SDK_ROOT 指定 SDK 根目录。x86 build_system.sh 将库暂存至 BUILD_ROOT/userspace-source/sdk/,无需在源码目录重复构建即可检查。
no built shared object found 表示选定 SDK 根目录没有共享库;先完成对应构建或修正路径,不要混用目标架构。
脚本检查 SONAME 与文件名的 major/minor,不检查完整结构和符号兼容性。
- 报告主机 OS、源码提交、工作区修改和目标架构。
- 报告编译器、QEMU、精确命令、环境变量和脚本退出码。
- 附完整错误输出和串口日志,指出第一项缺失或失败标记。
- 说明新构建目录、真实设备是否存在以及是否完成绑定。
源码:公开构建/验证脚本、sdk/libxtos-bci/Makefile 与 src/session.c、examples/bci_test.c、内核和 SDK BCI UAPI、scripts/check_abi.sh 及公开 Makefile。