排错

按现象、检查结果和修复路径处理构建、客体与 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 路径。

主机：补依赖后以低并发重试 x86；README 建议约 10 GB 可用磁盘。

cpio --help | grep -- --reproducible
JOBS=2 ./scripts/build_system.sh

镜像与超时

镜像缺失时完成对应构建，或把验证器指向实际 BUILD_ROOT。超时时看日志是否到达内核、init、测试或关机。普通跨架构镜像进入 BusyBox shell；只有 guestcheck 镜像自动检查并关机。

主机：检查 x86 产物和日志；grep 只用于阅读。

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_MEM 默认 2G，QEMU_SMP 默认 2。

QEMU_TIMEOUT=300 ./scripts/verify_guest_arm64.sh
QEMU_TIMEOUT=360 ./scripts/verify_guest_riscv64.sh

实时配置

运行时查客体 /sys/kernel/realtime，配置查当前内核 /proc/config.gz。-rt15 或 PREEMPT 启动字样不够。sysfs 未挂载时检查器可能输出 0；/proc/config.gz 缺失时不会有 preempt_rt=y 和 xtos_sched=y。

客体：检查实际运行内核和挂载。

uname -r
cat /proc/mounts
cat /sys/kernel/realtime
zcat /proc/config.gz | grep -E '^CONFIG_(PREEMPT_RT|XTOS_SCHED|XTOS_BCI|XTOS_BCI_OPENBCI|IKCONFIG|IKCONFIG_PROC)='

主机 ARM64：x86 使用 kernel-build，RISC-V64 使用 kernel-build-riscv64。

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 可能保留错误配置。

主机：用新目录重建 ARM64，不删除旧产物。

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 有匹配模块。模块检查必须在目标客体执行。

客体：保留 modprobe 的 stderr 和 dmesg。

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 不会给客体进程权限。

主机 ARM64：比较安装模块和同次构建的 kernel.release。

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 下三个库的架构。

主机：预期 ARM64 为 architecture: aarch64，RISC-V64 为 architecture: riscv:rv64。

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

主机：从当前提交导出独立 ARM64 副本；RISC-V64 使用对应脚本。

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.sh

ARM64/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。

UAPI：核对 magic、命令号和类型大小。

#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])

公开 read_samples 直接把 read 字节写入 float 缓冲区，没有数值单位转换。示例中的 µV 文本不证明样本单位、布局或采集链路正确；mmap 也不改变这个边界。

驱动输出 int32 纳伏；session.c 没有 nV→µV 转换。calibrate（校准）当前只是占位返回，阻抗检查不支持；set_channel 的 gain 字段当前未传入驱动。mmap 只映射原始存储，消费协议仍不足，不能当作已转换的 float 样本。

测试与报告

公开基线中 libxtos-rt 和 libxtos-signal 有 test 目标；libxtos-bci 的 Makefile 没有 test 目标。部分 tools Makefile 的 test 目标引用公开树中不存在的 Python 文件，不能当作完整公开测试套件。

主机：原生架构构建 SDK；BCI 检查构建和 ABI 元数据。

make -C sdk/libxtos-rt all test
make -C sdk/libxtos-signal all test
make -C sdk/libxtos-bci all
./scripts/check_abi.sh

check_abi.sh 从源码 sdk/ 目录读取共享库；x86 系统构建把库暂存到 BUILD_ROOT/userspace-source/sdk/。

出现 no built shared object found 时，先在源码 SDK 目录运行 all。

脚本检查 SONAME 与文件名的 major/minor，不检查完整结构和符号兼容性。

报告主机 OS、源码提交、工作区修改和目标架构。
报告编译器、QEMU、精确命令、环境变量和脚本退出码。
附完整错误输出和串口日志，指出第一项缺失或失败标记。
说明新构建目录、真实设备是否存在以及是否完成绑定。

源码：公开构建/验证脚本、sdk/libxtos-bci/Makefile 与 src/session.c、examples/bci_test.c、内核和 SDK BCI UAPI、scripts/check_abi.sh 及公开 Makefile。