libxtos-bcixtos_bci_frame_snapshot_acquire

xtos_bci_frame_snapshot_acquire

获取完整帧及其保留配置的只读不可变快照;不推进帧游标。

本页目录

声明

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

参数

参数类型说明
sessionxtos_bci_session_t *非 NULL,调用方持有且负责生命周期;必须串行使用。
capacity_framesuint32_t完整帧容量,1..292;无 flags 参数,获取始终非阻塞。
outstruct xtos_bci_frame_snapshot *非 NULL、调用方拥有的输出描述符;失败保持原值,不交付新指针。

输出字段

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

返回值

成功返回 0;失败返回 -1/errno。获取不消费数据,必须显式 consume 和 release。

错误

errno条件
EINVALsession/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 仅为主机接收回调时间。

示例

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