xtos_ bci_ read_ samples
读取驱动 int32 纳伏样本并数值转换为 float 微伏(v1.0.2)。
本页目录
声明
#include <xtos/bci.h>
ssize_t xtos_bci_read_samples(xtos_bci_session_t *session,
float *buffer,
size_t num_samples);参数
| 参数 | 类型 | 说明 |
|---|---|---|
| session | xtos_bci_session_t * | 非 NULL 会话句柄;不能并发读取或销毁。 |
| buffer | float * | 非 NULL,调用方拥有,至少可容纳 num_samples 个 float;成功输出单位 µV。 |
| num_samples | size_t | 请求的标量数量,必须大于 0 且不超过 SIZE_MAX/sizeof(int32_t);不是帧数。 |
返回值
累积读取至请求数量或 EOF。成功返回非负标量数(EOF 可短读或为 0);失败返回 -1,本次已消费的部分数据不交付且无法通过本函数重取。
错误
| errno | 条件 |
|---|---|
| EINVAL | session/buffer 为 NULL,或 num_samples 为 0。 |
| EBUSY | frame snapshot 持有 token 或待清理时由 SDK 拒绝;legacy snapshot 持有时由内核 read 拒绝。 |
| EOVERFLOW | num_samples×sizeof(int32_t) 超出 SIZE_MAX,分配前拒绝。 |
| ENOMEM | 原始整数临时缓冲 malloc 失败时通常由分配器设置。 |
| EIO | EOF 后的字节数不是 sizeof(int32_t) 的整数倍;整次调用失败。 |
| EAGAIN/EWOULDBLOCK | 调用方另设非阻塞时可能出现;即使已读到部分数据也返回 -1,不返回部分计数。 |
| system errno | frame snapshot token 持有期间(包括失败后待清理)SDK 返回 EBUSY;legacy snapshot 由内核 read 返回 EBUSY。EINTR 内部重试;其他 read 错误保留底层 errno。 |
注意事项
- 先 malloc 原始 int32 缓冲,循环 read,再以 (float)raw / 1000.0f 转换。每次 malloc/free 及可能阻塞的填满请求行为不适合严格无分配实时线程;poll 就绪不保证整个请求不会等待。
- 转换仅在无读取错误且整数对齐后写入输出。任何非 EINTR 错误(包括 EAGAIN)或 EIO 都丢弃本次临时数据;设备偏移可能已前进。
- 调用方拥有输出;本接口不提供设备时间戳、序号、质量标志或可靠多通道帧边界。需要主机接收元数据时使用 frame API;旧 get_mmap_buffer 已拒绝,新快照输出整数 nV,不能解释为 float。
- 同一会话的所有 API 必须由调用方串行化;SDK 无内部锁。调用可阻塞或分配,不能据此保证实时 deadline。
- make -C sdk/libxtos-bci test 的固定目标包括 test_samples、test_snapshot、test_snapshot_uapi、test_config、test_frame;软件 FIFO/系统调用包装测试不证明物理设备、串口实测或最坏时延。
示例
源码
本文按 OpenXTOS v1.0.2(c24e923717670c4724cdaf24c7c105caee8dc2fb)的头文件和实现编写。