libxtos-bcixtos_bci_frame_read

xtos_bci_frame_read

读取并消费完整整数 nV 帧批次,保留对应配置、流代次、序号和主机接收元数据。

本页目录

声明

c
#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);

参数

参数类型说明
sessionxtos_bci_session_t *非 NULL,调用方持有且负责生命周期;必须串行使用。
capacity_framesuint32_t完整帧容量,范围 1..292;不是标量数或字节数。
flagsuint32_t0 表示可阻塞;XTOS_BCI_FRAME_NONBLOCK=1 表示非阻塞;拒绝其他位。
outstruct xtos_bci_frame_batch *非 NULL、调用方拥有的描述符;records 借用会话内存。失败保持描述符和上次成功读取的可达字节。

输出字段

字段类型含义
recordsconst struct xtos_bci_frame_v1 *会话拥有的只读记录数组指针,至少 frame_count 条;不能 free 或修改;成功空批次时不得解引用。
frame_countuint32_t本次完整帧数量,0..capacity_frames;快照成功必须大于 0。
cursoruint64_t该批次起始逻辑游标,单位帧;从 0 开始,第一条 sequence=cursor+1。
next_cursoruint64_t批次后逻辑游标,单位帧;等于 cursor+frame_count。
overwritten_framesuint64_t累计覆盖未读帧数量;与线计数缺失和 RESET_STATS 独立,不计显式消费或 reopen 丢弃。
stream_generationuint64_t流代次,无单位;非空批次非零,所有记录相同;停止且干净的空读时为 0。
configstruct xtos_bci_config_v1批次实际保留的 384 字节已验证配置副本;按 config.* 展开;停止且干净的空读时全零。
config.versionuint32_tABI 版本,无单位;必须为 1。
config.flagsuint32_t标志,无单位;本版本为 0。
config.channelsuint32_t通道数量;验证配置为 8。
config.sample_rate_hzuint32_t采样率,单位 Hz;验证配置为 250。
config.enabled_maskuint32_t通道使能标志,无单位;bit 0..7 对应通道 0..7,与 CHnSET 掉电位一致。
config.capabilitiesuint32_t能力标志,无单位:CONFIG_READBACK=1、FIRMWARE_READBACK=2、GAIN_CONTROL=4、IMPEDANCE=8、SELF_TEST=16;前两位必需,未知位拒绝;固定 Cyton 路径不声明阻抗/自检支持。
config.reserved0uint32_t[2]保留字段,无单位;两项均为 0。
config.generationuint64_t配置代次,无单位;设备寿命内成功验证提交时递增且非零,即使读回内容未变也递增,不是板卡唯一标识。
config.gainuint32_t[8]每通道无量纲增益;各项为 1、2、4、6、8、12 或 24,与寄存器回读一致。
config.registersuint8_t[24]24 个 ADS 寄存器的实际回读字节,无单位;CONFIG1 低三位为 6,CHnSET 验证增益和使能状态。
config.firmwarechar[256]固件 banner,无单位;非空、NUL 结尾,NUL 前为可打印 ASCII 或 CR/LF;不是唯一设备身份。
config.reserveduint32_t[8]保留字段,无单位;八项均为 0。
records[].versionuint32_t记录 ABI 版本,无单位;值为 1。
records[].record_bytesuint32_t单条记录长度,单位字节;值为 224。
records[].channelsuint32_t有效通道数量;当前为 8,与批次 config.channels 一致。
records[].sample_rate_hzuint32_t采样率,单位 Hz;当前为 250,与批次配置一致。
records[].unituint32_t样本单位标识;XTOS_BCI_UNIT_NANOVOLT=1 表示整数 nV。
records[].host_clockuint32_t主机时钟标识;XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 表示 Linux CLOCK_MONOTONIC。
records[].quality_flagsuint32_t质量标志,无单位:CONFIG_VERIFIED=1 必需、COUNTER_GAP=2、RESYNC=4、ADC_RAIL=8、CONTINUITY_UNKNOWN=16;ADC 端点观察不等于生理质量诊断。
records[].source_flagsuint32_t来源标志,无单位;只能为 SERDEV=1 或 SYNTHETIC=2 之一;SERDEV 不证明实机验收。
records[].host_rx_nsxtos_bci_frame_u64主机接收回调时间,单位 ns;取得 state_lock 后、处理本回调字节前采样 CLOCK_MONOTONIC;同回调帧可相等,不是设备采样时间或物理延迟。
records[].sequencextos_bci_frame_u64生命周期序号,无单位;第 i 条为 batch.cursor+i+1,START/reopen 不重置。
records[].stream_generationxtos_bci_frame_u64流代次,无单位;非零且与批次相同;新 START admission 保留新代次,幂等重复启动不重复分配。
records[].config_generationxtos_bci_frame_u64配置代次,无单位;等于批次保留配置的 generation,后续配置不能重标记旧帧。
records[].device_counteruint32_t线协议计数值,无单位;范围 0..255;不是时间戳。
records[].counter_bitsuint32_t线计数器宽度,单位 bit;值为 8。
records[].missing_beforeuint32_t此帧前推断缺失的线帧数量,0..126;由接受的模 256 delta 2..127 推断,非零当且仅当 COUNTER_GAP;255→0 的 delta 1 正常。
records[].enabled_maskuint32_t通道使能位掩码,无单位;等于批次配置 enabled_mask。
records[].reservedxtos_bci_frame_u64[2]保留字段,无单位;两项为 0;xtos_bci_frame_u64 是 8 字节对齐的 uint64_t。
records[].samples_nvint32_t[32]原生字节序有符号样本数组,单位 nV;通道 0..7 有效,位置 8..31 为零;保留 32 个位置不代表支持 32 通道。

返回值

成功返回 0,通过 frame_count 返回帧数,不把帧数作为返回值;停止且无故障的空流成功返回 frame_count=0;失败 -1/errno。

错误

errno条件
EINVALsession/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。

示例

c
#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)的头文件和实现编写。