xtos_ bci_ frame_ read
读取并消费完整整数 nV 帧批次,保留对应配置、流代次、序号和主机接收元数据。
本页目录
声明
#include <xtos/bci.h>
int xtos_bci_frame_read(xtos_bci_session_t *session, uint32_t capacity_frames,
uint32_t flags, struct xtos_bci_frame_batch *out);参数
| 参数 | 类型 | 说明 |
|---|---|---|
| session | xtos_bci_session_t * | 非 NULL,调用方持有且负责生命周期;必须串行使用。 |
| capacity_frames | uint32_t | 完整帧容量,范围 1..292;不是标量数或字节数。 |
| flags | uint32_t | 0 表示可阻塞;XTOS_BCI_FRAME_NONBLOCK=1 表示非阻塞;拒绝其他位。 |
| out | struct xtos_bci_frame_batch * | 非 NULL、调用方拥有的描述符;records 借用会话内存。失败保持描述符和上次成功读取的可达字节。 |
输出字段
| 字段 | 类型 | 含义 |
|---|---|---|
| records | const struct xtos_bci_frame_v1 * | 会话拥有的只读记录数组指针,至少 frame_count 条;不能 free 或修改;成功空批次时不得解引用。 |
| frame_count | uint32_t | 本次完整帧数量,0..capacity_frames;快照成功必须大于 0。 |
| cursor | uint64_t | 该批次起始逻辑游标,单位帧;从 0 开始,第一条 sequence=cursor+1。 |
| next_cursor | uint64_t | 批次后逻辑游标,单位帧;等于 cursor+frame_count。 |
| overwritten_frames | uint64_t | 累计覆盖未读帧数量;与线计数缺失和 RESET_STATS 独立,不计显式消费或 reopen 丢弃。 |
| stream_generation | uint64_t | 流代次,无单位;非空批次非零,所有记录相同;停止且干净的空读时为 0。 |
| config | struct xtos_bci_config_v1 | 批次实际保留的 384 字节已验证配置副本;按 config.* 展开;停止且干净的空读时全零。 |
| config.version | uint32_t | ABI 版本,无单位;必须为 1。 |
| config.flags | uint32_t | 标志,无单位;本版本为 0。 |
| config.channels | uint32_t | 通道数量;验证配置为 8。 |
| config.sample_rate_hz | uint32_t | 采样率,单位 Hz;验证配置为 250。 |
| config.enabled_mask | uint32_t | 通道使能标志,无单位;bit 0..7 对应通道 0..7,与 CHnSET 掉电位一致。 |
| config.capabilities | uint32_t | 能力标志,无单位:CONFIG_READBACK=1、FIRMWARE_READBACK=2、GAIN_CONTROL=4、IMPEDANCE=8、SELF_TEST=16;前两位必需,未知位拒绝;固定 Cyton 路径不声明阻抗/自检支持。 |
| config.reserved0 | uint32_t[2] | 保留字段,无单位;两项均为 0。 |
| config.generation | uint64_t | 配置代次,无单位;设备寿命内成功验证提交时递增且非零,即使读回内容未变也递增,不是板卡唯一标识。 |
| config.gain | uint32_t[8] | 每通道无量纲增益;各项为 1、2、4、6、8、12 或 24,与寄存器回读一致。 |
| config.registers | uint8_t[24] | 24 个 ADS 寄存器的实际回读字节,无单位;CONFIG1 低三位为 6,CHnSET 验证增益和使能状态。 |
| config.firmware | char[256] | 固件 banner,无单位;非空、NUL 结尾,NUL 前为可打印 ASCII 或 CR/LF;不是唯一设备身份。 |
| config.reserved | uint32_t[8] | 保留字段,无单位;八项均为 0。 |
| records[].version | uint32_t | 记录 ABI 版本,无单位;值为 1。 |
| records[].record_bytes | uint32_t | 单条记录长度,单位字节;值为 224。 |
| records[].channels | uint32_t | 有效通道数量;当前为 8,与批次 config.channels 一致。 |
| records[].sample_rate_hz | uint32_t | 采样率,单位 Hz;当前为 250,与批次配置一致。 |
| records[].unit | uint32_t | 样本单位标识;XTOS_BCI_UNIT_NANOVOLT=1 表示整数 nV。 |
| records[].host_clock | uint32_t | 主机时钟标识;XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 表示 Linux CLOCK_MONOTONIC。 |
| records[].quality_flags | uint32_t | 质量标志,无单位:CONFIG_VERIFIED=1 必需、COUNTER_GAP=2、RESYNC=4、ADC_RAIL=8、CONTINUITY_UNKNOWN=16;ADC 端点观察不等于生理质量诊断。 |
| records[].source_flags | uint32_t | 来源标志,无单位;只能为 SERDEV=1 或 SYNTHETIC=2 之一;SERDEV 不证明实机验收。 |
| records[].host_rx_ns | xtos_bci_frame_u64 | 主机接收回调时间,单位 ns;取得 state_lock 后、处理本回调字节前采样 CLOCK_MONOTONIC;同回调帧可相等,不是设备采样时间或物理延迟。 |
| records[].sequence | xtos_bci_frame_u64 | 生命周期序号,无单位;第 i 条为 batch.cursor+i+1,START/reopen 不重置。 |
| records[].stream_generation | xtos_bci_frame_u64 | 流代次,无单位;非零且与批次相同;新 START admission 保留新代次,幂等重复启动不重复分配。 |
| records[].config_generation | xtos_bci_frame_u64 | 配置代次,无单位;等于批次保留配置的 generation,后续配置不能重标记旧帧。 |
| records[].device_counter | uint32_t | 线协议计数值,无单位;范围 0..255;不是时间戳。 |
| records[].counter_bits | uint32_t | 线计数器宽度,单位 bit;值为 8。 |
| records[].missing_before | uint32_t | 此帧前推断缺失的线帧数量,0..126;由接受的模 256 delta 2..127 推断,非零当且仅当 COUNTER_GAP;255→0 的 delta 1 正常。 |
| records[].enabled_mask | uint32_t | 通道使能位掩码,无单位;等于批次配置 enabled_mask。 |
| records[].reserved | xtos_bci_frame_u64[2] | 保留字段,无单位;两项为 0;xtos_bci_frame_u64 是 8 字节对齐的 uint64_t。 |
| records[].samples_nv | int32_t[32] | 原生字节序有符号样本数组,单位 nV;通道 0..7 有效,位置 8..31 为零;保留 32 个位置不代表支持 32 通道。 |
返回值
成功返回 0,通过 frame_count 返回帧数,不把帧数作为返回值;停止且无故障的空流成功返回 frame_count=0;失败 -1/errno。
错误
| errno | 条件 |
|---|---|
| EINVAL | session/output 为 NULL 或容量/flags 无效。 |
| EBUSY | 任一快照家族持有 token,包括失败后待清理的 token。 |
| EPROTO | 内核描述符、配置、记录或映射头不一致。 |
| EOVERFLOW | 地址/长度不可表示、token/游标耗尽或消费前发生覆盖。 |
| ENOTTY/EOPNOTSUPP | 内核或设备不支持该家族;不回退旧接口。 |
| EAGAIN/ENODEV/system errno | 空数据、断连或 ioctl/mmap 的其他错误原样传播。 |
注意事项
- 同一会话的所有 API 必须由调用方串行化;SDK 无内部锁。调用可阻塞或分配,不能据此保证实时 deadline。
- SDK 创建会话时预分配两个最多 292 条记录的 staging/published 缓冲(各 65408 字节、合计 130816);读取阶段不作 SDK 堆分配,但内核 FRAME_READ 可分配并等待。
- 成功读取推进帧 ring cursor;SDK 验证失败时 out 和旧视图不变,但成功 ioctl 可能已经消费内核数据。两套 legacy/frame ring 独立,消费一套不消费另一套。
- records 只读且归会话所有;视图在下一次成功帧读取、release 或 destroy 时到期。失败读取不改变上次有效视图;保留数据须复制。
- host_rx_ns 是主机接收回调取得 state_lock 后的 CLOCK_MONOTONIC 时间,单位 ns;不是硬件采样时间、UART 中断或端到端延迟,同回调多帧可相等。xtos_bci_frame_u64 是 8 字节对齐的 uint64_t。
- 无数据且采集活动时非阻塞返回 EAGAIN,阻塞等待;停止且干净为空时返回 0 帧。先排空已缓存帧再返回采集故障;断连 ENODEV。SDK 不重试 ioctl 的 EINTR。
示例
#include <xtos/bci.h>
int read_frames(xtos_bci_session_t *s) {
struct xtos_bci_frame_batch batch;
if (xtos_bci_frame_read(s, 32, XTOS_BCI_FRAME_NONBLOCK, &batch) < 0) return -1;
return (int)batch.frame_count;
}源码
本文按 OpenXTOS v1.0.2(c24e923717670c4724cdaf24c7c105caee8dc2fb)的头文件和实现编写。