文档libxtos-bci

libxtos-bci

BCI 会话、设备能力、缓冲区所有权和公开数据格式限制。

本页目录

设备前提

会话访问 XTOS 字符设备(如 /dev/xtos0),不直接访问任意 /dev/ttyUSB0。

需要 xtos_bci_core、xtos_bci_buffer 和匹配设备驱动,并完成设备注册。

公开 OpenBCI Cyton 实现是 serdev 驱动,设备树 compatible 为 openbci,cyton;加载模块不等于串口绑定或设备注册。

create 使用 open(path, O_RDWR),调用者需要读写权限。节点缺失通常 ENOENT,权限不足 EACCES。内核 core 当前只允许一个打开者,第二个为 EBUSY。QEMU 可验证模块加载,不能在没有串口板卡时证明硬件采集。

会话顺序

c
xtos_bci_session_t *xtos_bci_session_create(const char *device_path);
int xtos_bci_get_info(xtos_bci_session_t *session,
                      struct xtos_bci_device_info *info);
int xtos_bci_start(xtos_bci_session_t *session);
int xtos_bci_stop(xtos_bci_session_t *session);
void xtos_bci_session_destroy(xtos_bci_session_t *session);
  1. create:path 非 NULL 且为 NUL 结尾字符串;NULL 为 EINVAL,分配或 open 失败返回 NULL 并保留失败 errno。
  2. get_info:session/info 非 NULL;返回 create 时缓存,不重新请求 GET_INFO。检查 num_channels、sampling_rate、resolution_bits。
  3. 配置:采集前设置支持的速率和通道;Cyton 核对寄存器回读,另用 get_config 查询配置与代次。
  4. start→采集或 poll→stop:start/stop 执行 ioctl,成功 0、失败 -1;仅 ioctl 成功后更新 streaming 标志。
  5. destroy:先停工作线程并显式释放快照以检查清理错误。函数即使 STOP 失败也尝试清理映射/token,再 close/free;destroy(NULL) 是空操作。

GET_INFO 失败时 create 仍返回会话,缓存保持 calloc 的零值;后续 get_info 可能返回 0。因此创建成功不等于节点实现 XTOS UAPI。info.name 是固定 32 字节,未保证 NUL 结尾,输出要限长。session.c 无并发锁;不要并发读、配置或销毁同一会话。

采集配置

接口约束与返回公开 Cyton 行为
set_sampling_raterate 为整数 Hz,成功 0、失败 -1/errno;成功后更新缓存。仅支持 250 Hz,并核对配置回读;500/1000/2000 Hz 为 EOPNOTSUPP,其他非法值为 EINVAL;采集期间为 EBUSY。
set_channelchannel 从 0 开始,enabled 为 bool,gain 为 uint32;成功 0,失败 -1/errno。Cyton 通道 0–7,增益 1, 2, 4, 6, 8, 12, 24;gain=0 保留当前增益。core 传递 enabled/gain,驱动检查应答与寄存器回读;采集中为 EBUSY。
calibrateNULL session 为 -1/EINVAL;有效会话由驱动处理。返回 -1/EOPNOTSUPP,不执行校准,不报告伪成功。
check_impedanceoutput 非 NULL,1≤channels≤32;数组至少 channels 个 uint32,单位整数 kΩ。返回 -1/EOPNOTSUPP,不填测量值。
xtos_bci_get_configsession/out 非 NULL,成功 0、失败 -1/errno;失败不改 out。查询并验证 v1 配置、寄存器、firmware、gain 和 generation;格式不符为 EPROTO,不将 get_info 缓存当作实时配置。

这些接口配置采集设备,不是执行器命令接口。ioctl 可能返回 EINVAL、EOPNOTSUPP、EFAULT 或未知命令的 ENOTTY,串口错误也可能上传。区分参数非法、能力不支持和链路失败;同时记录期望配置和核验配置。

样本格式

c
ssize_t xtos_bci_read_samples(xtos_bci_session_t *session,
                             float *buffer, size_t num_samples);

要求 session/buffer 非 NULL、num_samples>0,否则 -1/EINVAL。

内部先检查 num_samples≤SIZE_MAX/sizeof(int32_t),再 malloc 原始整数缓冲并累积 read,直到请求字节数或 EOF。成功时每个值按 (float)raw / 1000.0f 转为微伏;调用方 buffer 至少容纳 num_samples 个 float。

参数是标量通道值数量,不自动表示多通道帧数。

EOVERFLOW 表示分配大小乘法溢出;malloc 失败通常 ENOMEM。EINTR 自动重试;其他读取错误(包括 EAGAIN)返回 -1,已从设备消费的本次部分数据被释放,不写入输出。EOF 时只有完整整数才返回短计数(可为 0),残余非完整 int32 返回 EIO。

read_samples 不返回设备时间戳、packet 序号、质量标志或可靠多通道帧边界;读完成时间不是采样时间。版本化 frame 接口提供序号、质量与配置元数据及主机接收时间,仍不提供设备采样时间。直接借用 fd 读取时自行处理字节、单位和边界。

fd 与版本化视图

c
void *xtos_bci_get_mmap_buffer(xtos_bci_session_t *session, size_t *size);
int xtos_bci_get_fd(xtos_bci_session_t *session);

get_fd 返回会话拥有的借用 fd;NULL 为 -1/EINVAL。可用于 poll/select,但不能 close,也不能在 destroy 后使用。open 默认不是 O_NONBLOCK;poll 后 read 仍可能受竞态、信号和短读影响。应用可用 fcntl 设置非阻塞,此时无数据可为 EAGAIN。

旧 xtos_bci_get_mmap_buffer 始终返回 NULL;可选 size 始终置 0。有效 session 为 EOPNOTSUPP,NULL session 为 EINVAL。它不再映射原始缓冲区。

同一会话必须外部串行化;不要并发读、配置、消费、释放或销毁,也不要通过借用 fd 自行发 snapshot ioctl。snapshot 两家族互斥;持有 token 或待清理时再次 acquire 与 frame_read 返回 EBUSY。有效视图属于会话,禁止修改、free 或 munmap;需长期保存时先复制。

接口使用约束
xtos_bci_snapshot_acquirerequested_bytes 非零且为 4 的倍数;UAPI 上限 64 KiB,内核向下取整到完整通道帧。成功 0,返回 native-endian int32 纳伏只读映射;失败 -1,result 清零。
xtos_bci_snapshot_consume使用原 token/cursor 消费完整 payload;成功 0,失败 -1/errno,无有效快照为 ENOENT。consume 不释放映射,重放、覆盖或解绑错误原样上传。
xtos_bci_snapshot_release先解除映射再释放 token;无快照返回 0。munmap 失败保留映射/token 以重试;ioctl 失败时映射已失效,除 ENODEV/ENOENT 终止所有权外保留 token。失败返回 -1/errno。
xtos_bci_frame_readcapacity_frames 为 1–292,flags 为 0 或 XTOS_BCI_FRAME_NONBLOCK;成功 0、失败 -1/errno。创建会话时预留两份最大批次缓冲,read 不分配;失败保持 out 与上一有效视图字节不变,旧读视图在下一次成功读、release 或 destroy 后失效。
xtos_bci_frame_snapshot_acquirecapacity_frames 为 1–292,成功返回只读 frame 批次、配置与映射;失败 -1,out 不变。元数据与记录校验后才公开指针。
xtos_bci_frame_snapshot_consume按原 token/cursor/stream_generation 消费整批;成功 0、失败 -1/errno,无有效视图为 ENOENT。consume 后映射仍可读,重放错误上传。
xtos_bci_frame_snapshot_release先解除映射再释放 token;成功 0,无快照也为 0。任一步失败均保留剩余所有权供重试,断开后仍可调用;解除映射后不能 consume。

参数错误为 EINVAL,元数据不符为 EPROTO,地址/长度不可表示为 EOVERFLOW;内核不支持时原样返回 ioctl 错误,不回退到旧 mmap。获取失败会尝试清理并保留原错误;若清理失败,先重试对应 release,再获取新视图。release/destroy 结束快照生命周期;destroy 即使 STOP 失败也尝试清理,但 void 返回不能报告清理失败。

frame 的 samples_nv 是整数纳伏,配置含 gain 与代次;host_rx_ns 是回调取得锁后记录的 CLOCK_MONOTONIC 主机接收时间,不是设备采样时间或物理延迟证明。序号、计数器缺口与质量标志辅助诊断,不证明硬件时间同步或全部丢包可检测。

统计与限制

c
int xtos_bci_get_stats(xtos_bci_session_t *session,
                      struct xtos_bci_statistics *stats);
int xtos_bci_reset_stats(xtos_bci_session_t *session);

get_stats 要求 session/stats 非 NULL,返回 0/-1;reset_stats 要求 session 非 NULL。字段为 samples_read、samples_dropped、errors、overruns。Cyton 在通道值写入缓冲后增加 samples_read,不是应用读出的帧数;空间不足时 ring buffer 丢弃最旧字节并增加 overruns,samples_dropped 不是所有丢失的完整计数。源码:sdk/libxtos-bci/include/xtos/bci.h、bci_uapi.h、src/session.c;内核为 xtos_bci_core.c、xtos_bci_buffer.c、devices/openbci_cyton.c。

分别记录会话控制、读取转换、分配与错误丢数、配置回读、snapshot/frame 生命周期,以及校准和阻抗的 EOPNOTSUPP。源码与软件测试不能合并为硬件 BCI 全链路验收。