libxtos-bcixtos_bci_snapshot_acquire

xtos_bci_snapshot_acquire

获取 legacy ring 的整数 nV 不可变快照;不推进字节游标。

本页目录

声明

c
#include <xtos/bci.h>

int xtos_bci_snapshot_acquire(xtos_bci_session_t *session,
                              size_t requested_bytes,
                              struct xtos_bci_snapshot *result);

参数

参数类型说明
sessionxtos_bci_session_t *非 NULL,调用方持有且负责生命周期;必须串行使用。
requested_bytessize_t请求字节数,正数、4 的整数倍;固定内核要求不超过 65536,按 channels×4 向下截为完整帧,不足一帧 EAGAIN。
resultstruct xtos_bci_snapshot *非 NULL、调用方拥有的输出描述符;调用开始即清零,任何失败均为零描述符。

输出字段

字段类型含义
mappingconst void *会话拥有的只读不可变映射起始地址;release/destroy 后失效,不得修改或自行 munmap。
mapping_bytessize_t映射总长度,单位字节,按系统页大小向上取整;包括头、payload 和页尾零填充。
headerconst struct xtos_bci_snapshot_header *映射开头已验证头的借用只读指针;字段按 header.* 展开。
payloadconst int32_t *会话拥有的连续原生字节序 signed32 样本数组,单位 nV;包含完整通道帧,不含时间戳。
payload_bytessize_t有效样本长度,单位字节;除以 sizeof(int32_t) 得标量数,再除 channels 得帧数;不含页尾。
header.magicuint32_t格式标识,无单位;XTOS_BCI_SNAPSHOT_MAGIC=0x58424349。
header.versionuint32_t快照 ABI 版本,无单位;值为 1。
header.header_sizeuint32_t头长度,单位字节;等于 sizeof(struct xtos_bci_snapshot_header)=64。
header.unituint32_t样本单位标识;XTOS_BCI_UNIT_NANOVOLT=1 表示整数 nV。
header.payload_bytesuint64_t有效 payload 长度,单位字节;非零、不超过请求和 65536,且是 channels×4 的整数倍。
header.cursoruint64_t获取时 legacy ring 的原始读游标,单位字节;consume 必须仍匹配该游标。
header.tokenuint64_t本 fd 的非零快照标识,无单位;两类快照共用不重用的 token 序列,由 SDK 保存用于 consume/release。
header.channelsuint32_t每帧通道数量,正整数。
header.sample_rate_hzuint32_t采样率,单位 Hz,正整数。
header.sample_sizeuint32_t单个标量长度,单位字节;sizeof(int32_t)=4。
header.reserved0uint32_t保留字段,无单位;为 0。
header.reserved1uint64_t保留字段,无单位;为 0。

返回值

成功返回 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 后所有借用指针失效;保留数据需先复制。
  • 映射为 64 字节头加连续 signed32 nV payload 和页尾;最多 64 KiB payload。SDK 校验请求/长度和映射头后才交付指针;不提供帧时间戳或序号。
  • 两类快照互斥,token 持有期间 frame_read/普通读取被拒绝 EBUSY;失败获取可能留下待清理 token,必须调用本家族 release 重试后再获取。
  • 获取失败会尝试清理并保留原始失败 errno;mmap 返回地址 0 不是 MAP_FAILED,但 SDK 以 EPROTO 拒绝并按已记录长度清理。不支持的内核不会回退旧 mmap。

示例

c
#include <xtos/bci.h>
#include <errno.h>
/* Exclusive session; no previously held snapshot. */
int snapshot_once(xtos_bci_session_t *s) {
    struct xtos_bci_snapshot view;
    int rc = xtos_bci_snapshot_acquire(s, 4096, &view);
    if (rc == 0) {
        /* Inspect/copy view here, before consume/release. */
        rc = xtos_bci_snapshot_consume(s);
    }
    int operation_errno = errno;
    for (int attempt = 0; attempt < 3; ++attempt) {
        if (xtos_bci_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)的头文件和实现编写。