xtos_ bci_ frame_ snapshot_ acquire
获取完整帧及其保留配置的只读不可变快照;不推进帧游标。
本页目录
声明
#include <xtos/bci.h>
int xtos_bci_frame_snapshot_acquire(xtos_bci_session_t *session,
uint32_t capacity_frames,
struct xtos_bci_frame_snapshot *out);参数
| 参数 | 类型 | 说明 |
|---|---|---|
| session | xtos_bci_session_t * | 非 NULL,调用方持有且负责生命周期;必须串行使用。 |
| capacity_frames | uint32_t | 完整帧容量,1..292;无 flags 参数,获取始终非阻塞。 |
| out | struct xtos_bci_frame_snapshot * | 非 NULL、调用方拥有的输出描述符;失败保持原值,不交付新指针。 |
输出字段
| 字段 | 类型 | 含义 |
|---|---|---|
| mapping | const void * | 会话拥有的只读不可变映射起始指针;release/destroy 后失效,不得自行解除映射。 |
| mapping_bytes | size_t | 映射总长度,单位字节;PAGE_ALIGN(512+frame_count×224),包括零填充页尾。 |
| header | const struct xtos_bci_frame_snapshot_header * | 映射偏移 0 处的已验证头借用指针,字段按 header.* 展开。 |
| batch | struct xtos_bci_frame_batch | 帧批次描述符,按 batch.* 展开;records 指向映射偏移 512,配置位于偏移 128 并与 batch.config 相同。 |
| header.magic | uint32_t | 格式标识,无单位;XTOS_BCI_FRAME_SNAPSHOT_MAGIC=0x58424631。 |
| header.version | uint32_t | 帧 ABI 版本,无单位;为 1。 |
| header.header_bytes | uint32_t | 映射头长度,单位字节;为 128。 |
| header.record_bytes | uint32_t | 单条帧记录长度,单位字节;为 224。 |
| header.frame_count | uint32_t | 完整帧数量,1..capacity_frames;等于 batch.frame_count。 |
| header.flags | uint32_t | 标志,无单位;为 0。 |
| header.unit | uint32_t | 样本单位标识;NANOVOLT=1。 |
| header.host_clock | uint32_t | 主机时钟标识;MONOTONIC=1。 |
| header.payload_bytes | xtos_bci_frame_u64 | 记录区域长度,单位字节;frame_count×224,不包括头、配置和页尾。 |
| header.cursor | xtos_bci_frame_u64 | 原始起始逻辑游标,单位帧;与 batch.cursor 相同。 |
| header.next_cursor | xtos_bci_frame_u64 | 批次后逻辑游标,单位帧;cursor+frame_count。 |
| header.token | xtos_bci_frame_u64 | 本 fd 的非零快照标识,无单位;SDK 保存用于 consume/release,不由调用方改写。 |
| header.stream_generation | xtos_bci_frame_u64 | 流代次,无单位;等于 batch 和每条记录的 stream_generation。 |
| header.config_generation | xtos_bci_frame_u64 | 配置代次,无单位;等于 batch.config.generation 和每条记录的 config_generation。 |
| header.overwritten_frames | xtos_bci_frame_u64 | 累计覆盖未读帧数量,与 batch.overwritten_frames 相同,不是 wire counter 缺失数。 |
| header.mapping_bytes | xtos_bci_frame_u64 | 映射总长度,单位字节;与外层 mapping_bytes 相同。 |
| header.config_bytes | uint32_t | 已验证配置长度,单位字节;为 384。 |
| header.records_offset | uint32_t | 记录区起始偏移,单位字节;为 512,配置位于 128。 |
| header.reserved | uint32_t[6] | 保留字段,无单位;六项均为 0。 |
| batch.records | const struct xtos_bci_frame_v1 * | 会话拥有的只读记录数组指针,至少 frame_count 条;不能 free 或修改;成功空批次时不得解引用。 |
| batch.frame_count | uint32_t | 本次完整帧数量,0..capacity_frames;快照成功必须大于 0。 |
| batch.cursor | uint64_t | 该批次起始逻辑游标,单位帧;从 0 开始,第一条 sequence=cursor+1。 |
| batch.next_cursor | uint64_t | 批次后逻辑游标,单位帧;等于 cursor+frame_count。 |
| batch.overwritten_frames | uint64_t | 累计覆盖未读帧数量;与线计数缺失和 RESET_STATS 独立,不计显式消费或 reopen 丢弃。 |
| batch.stream_generation | uint64_t | 流代次,无单位;非空批次非零,所有记录相同;停止且干净的空读时为 0。 |
| batch.config | struct xtos_bci_config_v1 | 批次实际保留的 384 字节已验证配置副本;按 config.* 展开;停止且干净的空读时全零。 |
| batch.config.version | uint32_t | ABI 版本,无单位;必须为 1。 |
| batch.config.flags | uint32_t | 标志,无单位;本版本为 0。 |
| batch.config.channels | uint32_t | 通道数量;验证配置为 8。 |
| batch.config.sample_rate_hz | uint32_t | 采样率,单位 Hz;验证配置为 250。 |
| batch.config.enabled_mask | uint32_t | 通道使能标志,无单位;bit 0..7 对应通道 0..7,与 CHnSET 掉电位一致。 |
| batch.config.capabilities | uint32_t | 能力标志,无单位:CONFIG_READBACK=1、FIRMWARE_READBACK=2、GAIN_CONTROL=4、IMPEDANCE=8、SELF_TEST=16;前两位必需,未知位拒绝;固定 Cyton 路径不声明阻抗/自检支持。 |
| batch.config.reserved0 | uint32_t[2] | 保留字段,无单位;两项均为 0。 |
| batch.config.generation | uint64_t | 配置代次,无单位;设备寿命内成功验证提交时递增且非零,即使读回内容未变也递增,不是板卡唯一标识。 |
| batch.config.gain | uint32_t[8] | 每通道无量纲增益;各项为 1、2、4、6、8、12 或 24,与寄存器回读一致。 |
| batch.config.registers | uint8_t[24] | 24 个 ADS 寄存器的实际回读字节,无单位;CONFIG1 低三位为 6,CHnSET 验证增益和使能状态。 |
| batch.config.firmware | char[256] | 固件 banner,无单位;非空、NUL 结尾,NUL 前为可打印 ASCII 或 CR/LF;不是唯一设备身份。 |
| batch.config.reserved | uint32_t[8] | 保留字段,无单位;八项均为 0。 |
| batch.records[].version | uint32_t | 记录 ABI 版本,无单位;值为 1。 |
| batch.records[].record_bytes | uint32_t | 单条记录长度,单位字节;值为 224。 |
| batch.records[].channels | uint32_t | 有效通道数量;当前为 8,与批次 config.channels 一致。 |
| batch.records[].sample_rate_hz | uint32_t | 采样率,单位 Hz;当前为 250,与批次配置一致。 |
| batch.records[].unit | uint32_t | 样本单位标识;XTOS_BCI_UNIT_NANOVOLT=1 表示整数 nV。 |
| batch.records[].host_clock | uint32_t | 主机时钟标识;XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 表示 Linux CLOCK_MONOTONIC。 |
| batch.records[].quality_flags | uint32_t | 质量标志,无单位:CONFIG_VERIFIED=1 必需、COUNTER_GAP=2、RESYNC=4、ADC_RAIL=8、CONTINUITY_UNKNOWN=16;ADC 端点观察不等于生理质量诊断。 |
| batch.records[].source_flags | uint32_t | 来源标志,无单位;只能为 SERDEV=1 或 SYNTHETIC=2 之一;SERDEV 不证明实机验收。 |
| batch.records[].host_rx_ns | xtos_bci_frame_u64 | 主机接收回调时间,单位 ns;取得 state_lock 后、处理本回调字节前采样 CLOCK_MONOTONIC;同回调帧可相等,不是设备采样时间或物理延迟。 |
| batch.records[].sequence | xtos_bci_frame_u64 | 生命周期序号,无单位;第 i 条为 batch.cursor+i+1,START/reopen 不重置。 |
| batch.records[].stream_generation | xtos_bci_frame_u64 | 流代次,无单位;非零且与批次相同;新 START admission 保留新代次,幂等重复启动不重复分配。 |
| batch.records[].config_generation | xtos_bci_frame_u64 | 配置代次,无单位;等于批次保留配置的 generation,后续配置不能重标记旧帧。 |
| batch.records[].device_counter | uint32_t | 线协议计数值,无单位;范围 0..255;不是时间戳。 |
| batch.records[].counter_bits | uint32_t | 线计数器宽度,单位 bit;值为 8。 |
| batch.records[].missing_before | uint32_t | 此帧前推断缺失的线帧数量,0..126;由接受的模 256 delta 2..127 推断,非零当且仅当 COUNTER_GAP;255→0 的 delta 1 正常。 |
| batch.records[].enabled_mask | uint32_t | 通道使能位掩码,无单位;等于批次配置 enabled_mask。 |
| batch.records[].reserved | xtos_bci_frame_u64[2] | 保留字段,无单位;两项为 0;xtos_bci_frame_u64 是 8 字节对齐的 uint64_t。 |
| batch.records[].samples_nv | int32_t[32] | 原生字节序有符号样本数组,单位 nV;通道 0..7 有效,位置 8..31 为零;保留 32 个位置不代表支持 32 通道。 |
返回值
成功返回 0;失败返回 -1/errno。获取不消费数据,必须显式 consume 和 release。
错误
| errno | 条件 |
|---|---|
| EINVAL | session/output 为 NULL 或容量/flags 无效。 |
| EBUSY | 任一快照家族持有 token,包括失败后待清理的 token。 |
| EPROTO | 内核描述符、配置、记录或映射头不一致。 |
| EOVERFLOW | 地址/长度不可表示、token/游标耗尽或消费前发生覆盖。 |
| ENOTTY/EOPNOTSUPP | 内核或设备不支持该家族;不回退旧接口。 |
| EAGAIN/ENODEV/system errno | 空数据、断连或 ioctl/mmap 的其他错误原样传播。 |
注意事项
- 同一会话的所有 API 必须由调用方串行化;SDK 无内部锁。调用可阻塞或分配,不能据此保证实时 deadline。
- 映射为只读、原生字节序、会话拥有的不可变副本;不是真正实时零复制 ring。不得修改、free、munmap 或通过借用 fd 自行发快照 ioctl。consume 不释放映射,release/destroy 后所有借用指针失效;保留数据需先复制。
- 映射布局为头 128 字节、配置 384 字节、记录偏移 512、每条 224 字节及零填充页尾;单批只包含同一流/配置代次。SDK 校验所有元数据和记录后才发布 out。
- 两类快照互斥,token 持有期间 frame_read/普通读取被拒绝 EBUSY;失败获取可能留下待清理 token,必须调用本家族 release 重试后再获取。
- 获取失败会尝试清理并保留原始失败 errno;mmap 返回地址 0 不是 MAP_FAILED,但 SDK 以 EPROTO 拒绝并按已记录长度清理。不支持的内核不会回退旧 mmap。
- 获取始终非阻塞;空活动流和停止的干净空流均 EAGAIN,空故障流返回保存的故障;host_rx_ns 仅为主机接收回调时间。
示例
#include <xtos/bci.h>
#include <errno.h>
/* Exclusive session; no previously held snapshot. */
int frame_snapshot_once(xtos_bci_session_t *s) {
struct xtos_bci_frame_snapshot view;
int rc = xtos_bci_frame_snapshot_acquire(s, 32, &view);
if (rc == 0) {
/* Inspect/copy view here, before consume/release. */
rc = xtos_bci_frame_snapshot_consume(s);
}
int operation_errno = errno;
for (int attempt = 0; attempt < 3; ++attempt) {
if (xtos_bci_frame_snapshot_release(s) == 0) {
if (rc < 0) errno = operation_errno;
return rc;
}
}
/* Cleanup failed: s retains remaining ownership for later retry. */
return -1;
}源码
本文按 OpenXTOS v1.0.2(c24e923717670c4724cdaf24c7c105caee8dc2fb)的头文件和实现编写。