xtos_ bci_ frame_ read
Reads and consumes a whole integer-nV frame batch with its retained configuration, stream generation, sequence and host receive metadata.
On this page
Declaration
#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);Parameters
| Parameter | Type | Description |
|---|---|---|
| session | xtos_bci_session_t * | Non-NULL, caller-managed lifetime; externally serialize access. |
| capacity_frames | uint32_t | Whole-frame capacity, 1..292; not a scalar count or byte count. |
| flags | uint32_t | 0 permits blocking; XTOS_BCI_FRAME_NONBLOCK=1 is nonblocking. Other bits are rejected. |
| out | struct xtos_bci_frame_batch * | Non-NULL caller-owned descriptor; records borrow session storage. Failure preserves the descriptor and bytes reachable from the previous successful read. |
Output fields
| Field | Type | Meaning |
|---|---|---|
| records | const struct xtos_bci_frame_v1 * | Session-owned read-only records pointer for frame_count records; do not free or modify it. Do not dereference an empty batch. |
| frame_count | uint32_t | Complete frame count, 0..capacity_frames; a successful snapshot is nonempty. |
| cursor | uint64_t | Starting logical cursor in frames, starting at zero; first sequence=cursor+1. |
| next_cursor | uint64_t | Logical cursor after the batch, in frames; equals cursor+frame_count. |
| overwritten_frames | uint64_t | Cumulative unread frames displaced by overwrite; independent of wire-counter loss and RESET_STATS, excluding explicit consumption and reopen discard. |
| stream_generation | uint64_t | Dimensionless stream generation; nonzero and homogeneous in a nonempty batch, zero for a stopped clean empty read. |
| config | struct xtos_bci_config_v1 | The batch's retained verified 384-byte configuration copy, expanded as config.*; all zero for a stopped clean empty read. |
| config.version | uint32_t | ABI version, dimensionless; must be 1. |
| config.flags | uint32_t | Flags, dimensionless; zero in v1. |
| config.channels | uint32_t | Channel count; the validated profile requires 8. |
| config.sample_rate_hz | uint32_t | Sampling rate in Hz; the validated profile requires 250. |
| config.enabled_mask | uint32_t | Dimensionless enabled-channel mask; bits 0..7 represent channels 0..7 and agree with CHnSET power-down bits. |
| config.capabilities | uint32_t | Dimensionless capability bits: CONFIG_READBACK=1, FIRMWARE_READBACK=2, GAIN_CONTROL=4, IMPEDANCE=8, SELF_TEST=16; the first two are required, unknown bits rejected. The pinned Cyton path does not advertise impedance/self-test. |
| config.reserved0 | uint32_t[2] | Reserved, dimensionless; both elements are zero. |
| config.generation | uint64_t | Dimensionless nonzero configuration generation; increases on successful verified commits during the device lifetime, even for unchanged readbacks. It is not a unique board ID. |
| config.gain | uint32_t[8] | Per-channel dimensionless gain; each is 1, 2, 4, 6, 8, 12, or 24 and agrees with register readback. |
| config.registers | uint8_t[24] | 24 actual ADS register bytes, dimensionless; CONFIG1 low three bits equal 6 and CHnSET validates gains and enable state. |
| config.firmware | char[256] | Firmware banner, no unit; nonempty and NUL-terminated, with printable ASCII or CR/LF before NUL. It is not unique device identity. |
| config.reserved | uint32_t[8] | Reserved, dimensionless; all eight elements are zero. |
| records[].version | uint32_t | Record ABI version, dimensionless; equals 1. |
| records[].record_bytes | uint32_t | Record size in bytes; equals 224. |
| records[].channels | uint32_t | Valid channel count, currently 8; agrees with batch config.channels. |
| records[].sample_rate_hz | uint32_t | Sampling rate in Hz, currently 250; agrees with batch configuration. |
| records[].unit | uint32_t | Sample-unit enum; XTOS_BCI_UNIT_NANOVOLT=1 denotes integer nV. |
| records[].host_clock | uint32_t | Host-clock enum; XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 denotes Linux CLOCK_MONOTONIC. |
| records[].quality_flags | uint32_t | Dimensionless quality bits: CONFIG_VERIFIED=1 required, COUNTER_GAP=2, RESYNC=4, ADC_RAIL=8, CONTINUITY_UNKNOWN=16. An observed ADC endpoint is not a physiological quality diagnosis. |
| records[].source_flags | uint32_t | Dimensionless source flag; exactly SERDEV=1 or SYNTHETIC=2. SERDEV does not prove hardware acceptance. |
| records[].host_rx_ns | xtos_bci_frame_u64 | Host receive callback time in ns: CLOCK_MONOTONIC sampled after state_lock acquisition and before processing callback bytes. Frames in one callback may share it; it is not device acquisition time or physical latency. |
| records[].sequence | xtos_bci_frame_u64 | Dimensionless lifetime sequence; record i equals batch.cursor+i+1 and START/reopen do not reset it. |
| records[].stream_generation | xtos_bci_frame_u64 | Dimensionless nonzero stream generation, equal to the batch value; new START admission reserves a new generation, idempotent START does not. |
| records[].config_generation | xtos_bci_frame_u64 | Dimensionless configuration generation, equal to retained batch config.generation; later configuration cannot relabel old frames. |
| records[].device_counter | uint32_t | Dimensionless wire counter, 0..255; not a timestamp. |
| records[].counter_bits | uint32_t | Wire-counter width in bits; equals 8. |
| records[].missing_before | uint32_t | Inferred missing wire-frame count before this frame, 0..126, from accepted modulo-256 deltas 2..127; nonzero exactly when COUNTER_GAP is set. Delta 1 across 255→0 is normal. |
| records[].enabled_mask | uint32_t | Dimensionless enabled-channel bitmask; equals batch config.enabled_mask. |
| records[].reserved | xtos_bci_frame_u64[2] | Reserved, dimensionless; both are zero. xtos_bci_frame_u64 is uint64_t with 8-byte alignment. |
| records[].samples_nv | int32_t[32] | Native-endian signed samples in nV; channels 0..7 are valid and positions 8..31 are zero. Reserving 32 positions does not claim 32-channel support. |
Return value
Returns 0 with count in frame_count, not as the return value. A stopped clean empty stream succeeds with frame_count=0; failure returns -1/errno.
Errors
| errno | Condition |
|---|---|
| EINVAL | session/output is NULL or capacity/flags are invalid. |
| EBUSY | Either snapshot family owns a token, including pending cleanup after failure. |
| EPROTO | Kernel descriptor, configuration, records, or mapped header are inconsistent. |
| EOVERFLOW | Address/length is unrepresentable, token/cursor exhausted, or overwrite occurred before consumption. |
| ENOTTY/EOPNOTSUPP | The kernel or device lacks this family; there is no legacy fallback. |
| EAGAIN/ENODEV/system errno | Empty data, disconnect, or other ioctl/mmap errors propagate unchanged. |
Notes
- Externally serialize every API on one session; the SDK has no internal lock. Calls may block or allocate and establish no real-time deadline guarantee.
- Session creation preallocates separate staging/published buffers of at most 292 records (65408 bytes each, 130816 total). The SDK read phase allocates no heap memory, but kernel FRAME_READ may allocate and wait.
- A successful read advances the frame-ring cursor. SDK validation failure preserves out and the old view, but a successful ioctl may already have consumed kernel data. Legacy and frame rings are independent; consuming one does not consume the other.
- records are read-only and session-owned. Views expire on the next successful frame read, release, or destroy. A failed read preserves the previous valid view; copy data to retain it.
- host_rx_ns is host receive callback CLOCK_MONOTONIC time in ns, sampled after state_lock acquisition. It is not hardware acquisition time, UART interrupt time, or end-to-end latency; multiple frames in one callback may share it. xtos_bci_frame_u64 is uint64_t aligned to 8 bytes.
- When empty and active, nonblocking returns EAGAIN and blocking waits. Stopped clean empty returns zero frames. Buffered frames drain before acquisition errors; disconnect returns ENODEV. The SDK does not retry ioctl EINTR.
Example
#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;
}Source
This reference describes headers and implementation in OpenXTOS v1.0.2 (c24e923717670c4724cdaf24c7c105caee8dc2fb).