XTOS / OPEN SOURCE REAL-TIME SYSTEMOPEN SOURCE · 1.0.2 · PRERELEASE · IMAGES & SOURCE
libxtos-bcixtos_bci_frame_read

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

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

ParameterTypeDescription
sessionxtos_bci_session_t *Non-NULL, caller-managed lifetime; externally serialize access.
capacity_framesuint32_tWhole-frame capacity, 1..292; not a scalar count or byte count.
flagsuint32_t0 permits blocking; XTOS_BCI_FRAME_NONBLOCK=1 is nonblocking. Other bits are rejected.
outstruct 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

FieldTypeMeaning
recordsconst 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_countuint32_tComplete frame count, 0..capacity_frames; a successful snapshot is nonempty.
cursoruint64_tStarting logical cursor in frames, starting at zero; first sequence=cursor+1.
next_cursoruint64_tLogical cursor after the batch, in frames; equals cursor+frame_count.
overwritten_framesuint64_tCumulative unread frames displaced by overwrite; independent of wire-counter loss and RESET_STATS, excluding explicit consumption and reopen discard.
stream_generationuint64_tDimensionless stream generation; nonzero and homogeneous in a nonempty batch, zero for a stopped clean empty read.
configstruct xtos_bci_config_v1The batch's retained verified 384-byte configuration copy, expanded as config.*; all zero for a stopped clean empty read.
config.versionuint32_tABI version, dimensionless; must be 1.
config.flagsuint32_tFlags, dimensionless; zero in v1.
config.channelsuint32_tChannel count; the validated profile requires 8.
config.sample_rate_hzuint32_tSampling rate in Hz; the validated profile requires 250.
config.enabled_maskuint32_tDimensionless enabled-channel mask; bits 0..7 represent channels 0..7 and agree with CHnSET power-down bits.
config.capabilitiesuint32_tDimensionless 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.reserved0uint32_t[2]Reserved, dimensionless; both elements are zero.
config.generationuint64_tDimensionless nonzero configuration generation; increases on successful verified commits during the device lifetime, even for unchanged readbacks. It is not a unique board ID.
config.gainuint32_t[8]Per-channel dimensionless gain; each is 1, 2, 4, 6, 8, 12, or 24 and agrees with register readback.
config.registersuint8_t[24]24 actual ADS register bytes, dimensionless; CONFIG1 low three bits equal 6 and CHnSET validates gains and enable state.
config.firmwarechar[256]Firmware banner, no unit; nonempty and NUL-terminated, with printable ASCII or CR/LF before NUL. It is not unique device identity.
config.reserveduint32_t[8]Reserved, dimensionless; all eight elements are zero.
records[].versionuint32_tRecord ABI version, dimensionless; equals 1.
records[].record_bytesuint32_tRecord size in bytes; equals 224.
records[].channelsuint32_tValid channel count, currently 8; agrees with batch config.channels.
records[].sample_rate_hzuint32_tSampling rate in Hz, currently 250; agrees with batch configuration.
records[].unituint32_tSample-unit enum; XTOS_BCI_UNIT_NANOVOLT=1 denotes integer nV.
records[].host_clockuint32_tHost-clock enum; XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 denotes Linux CLOCK_MONOTONIC.
records[].quality_flagsuint32_tDimensionless 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_flagsuint32_tDimensionless source flag; exactly SERDEV=1 or SYNTHETIC=2. SERDEV does not prove hardware acceptance.
records[].host_rx_nsxtos_bci_frame_u64Host 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[].sequencextos_bci_frame_u64Dimensionless lifetime sequence; record i equals batch.cursor+i+1 and START/reopen do not reset it.
records[].stream_generationxtos_bci_frame_u64Dimensionless nonzero stream generation, equal to the batch value; new START admission reserves a new generation, idempotent START does not.
records[].config_generationxtos_bci_frame_u64Dimensionless configuration generation, equal to retained batch config.generation; later configuration cannot relabel old frames.
records[].device_counteruint32_tDimensionless wire counter, 0..255; not a timestamp.
records[].counter_bitsuint32_tWire-counter width in bits; equals 8.
records[].missing_beforeuint32_tInferred 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_maskuint32_tDimensionless enabled-channel bitmask; equals batch config.enabled_mask.
records[].reservedxtos_bci_frame_u64[2]Reserved, dimensionless; both are zero. xtos_bci_frame_u64 is uint64_t with 8-byte alignment.
records[].samples_nvint32_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

errnoCondition
EINVALsession/output is NULL or capacity/flags are invalid.
EBUSYEither snapshot family owns a token, including pending cleanup after failure.
EPROTOKernel descriptor, configuration, records, or mapped header are inconsistent.
EOVERFLOWAddress/length is unrepresentable, token/cursor exhausted, or overwrite occurred before consumption.
ENOTTY/EOPNOTSUPPThe kernel or device lacks this family; there is no legacy fallback.
EAGAIN/ENODEV/system errnoEmpty 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

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