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

xtos_bci_frame_snapshot_acquire

Acquires a read-only immutable snapshot of whole frames and their retained configuration without advancing the frame cursor.

On this page

Declaration

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

Parameters

ParameterTypeDescription
sessionxtos_bci_session_t *Non-NULL, caller-managed lifetime; externally serialize access.
capacity_framesuint32_tWhole-frame capacity, 1..292; there is no flags parameter and acquisition is always nonblocking.
outstruct xtos_bci_frame_snapshot *Non-NULL caller-owned output descriptor; failure leaves it unchanged and publishes no new pointers.

Output fields

FieldTypeMeaning
mappingconst void *Start pointer of the session-owned read-only immutable mapping; expires on release/destroy. Do not unmap it yourself.
mapping_bytessize_tTotal mapping length in bytes: PAGE_ALIGN(512+frame_count×224), including the zero-filled tail.
headerconst struct xtos_bci_frame_snapshot_header *Borrowed pointer to the validated header at mapping offset 0; expanded as header.*.
batchstruct xtos_bci_frame_batchFrame-batch descriptor, expanded as batch.*; records point at mapping offset 512. Configuration at offset 128 equals batch.config.
header.magicuint32_tFormat identifier, dimensionless; XTOS_BCI_FRAME_SNAPSHOT_MAGIC=0x58424631.
header.versionuint32_tFrame ABI version, dimensionless; equals 1.
header.header_bytesuint32_tMapping-header length in bytes; equals 128.
header.record_bytesuint32_tFrame-record length in bytes; equals 224.
header.frame_countuint32_tComplete frame count, 1..capacity_frames; equals batch.frame_count.
header.flagsuint32_tFlags, dimensionless; zero.
header.unituint32_tSample-unit identifier; NANOVOLT=1.
header.host_clockuint32_tHost-clock identifier; MONOTONIC=1.
header.payload_bytesxtos_bci_frame_u64Record-area length in bytes: frame_count×224, excluding header, configuration and tail.
header.cursorxtos_bci_frame_u64Original starting logical cursor in frames; equals batch.cursor.
header.next_cursorxtos_bci_frame_u64Logical cursor after the batch, in frames; cursor+frame_count.
header.tokenxtos_bci_frame_u64Nonzero FD-local snapshot identifier, dimensionless; retained by the SDK for consume/release, never caller-modified.
header.stream_generationxtos_bci_frame_u64Dimensionless stream generation; equals the batch and every record's stream_generation.
header.config_generationxtos_bci_frame_u64Dimensionless configuration generation; equals batch.config.generation and every record's config_generation.
header.overwritten_framesxtos_bci_frame_u64Cumulative overwritten unread-frame count, equal to batch.overwritten_frames; not wire-counter loss.
header.mapping_bytesxtos_bci_frame_u64Total mapping length in bytes; equals outer mapping_bytes.
header.config_bytesuint32_tVerified configuration length in bytes; equals 384.
header.records_offsetuint32_tRecord-area offset in bytes; equals 512, with configuration at 128.
header.reserveduint32_t[6]Reserved, dimensionless; all six elements are zero.
batch.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.
batch.frame_countuint32_tComplete frame count, 0..capacity_frames; a successful snapshot is nonempty.
batch.cursoruint64_tStarting logical cursor in frames, starting at zero; first sequence=cursor+1.
batch.next_cursoruint64_tLogical cursor after the batch, in frames; equals cursor+frame_count.
batch.overwritten_framesuint64_tCumulative unread frames displaced by overwrite; independent of wire-counter loss and RESET_STATS, excluding explicit consumption and reopen discard.
batch.stream_generationuint64_tDimensionless stream generation; nonzero and homogeneous in a nonempty batch, zero for a stopped clean empty read.
batch.configstruct xtos_bci_config_v1The batch's retained verified 384-byte configuration copy, expanded as config.*; all zero for a stopped clean empty read.
batch.config.versionuint32_tABI version, dimensionless; must be 1.
batch.config.flagsuint32_tFlags, dimensionless; zero in v1.
batch.config.channelsuint32_tChannel count; the validated profile requires 8.
batch.config.sample_rate_hzuint32_tSampling rate in Hz; the validated profile requires 250.
batch.config.enabled_maskuint32_tDimensionless enabled-channel mask; bits 0..7 represent channels 0..7 and agree with CHnSET power-down bits.
batch.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.
batch.config.reserved0uint32_t[2]Reserved, dimensionless; both elements are zero.
batch.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.
batch.config.gainuint32_t[8]Per-channel dimensionless gain; each is 1, 2, 4, 6, 8, 12, or 24 and agrees with register readback.
batch.config.registersuint8_t[24]24 actual ADS register bytes, dimensionless; CONFIG1 low three bits equal 6 and CHnSET validates gains and enable state.
batch.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.
batch.config.reserveduint32_t[8]Reserved, dimensionless; all eight elements are zero.
batch.records[].versionuint32_tRecord ABI version, dimensionless; equals 1.
batch.records[].record_bytesuint32_tRecord size in bytes; equals 224.
batch.records[].channelsuint32_tValid channel count, currently 8; agrees with batch config.channels.
batch.records[].sample_rate_hzuint32_tSampling rate in Hz, currently 250; agrees with batch configuration.
batch.records[].unituint32_tSample-unit enum; XTOS_BCI_UNIT_NANOVOLT=1 denotes integer nV.
batch.records[].host_clockuint32_tHost-clock enum; XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 denotes Linux CLOCK_MONOTONIC.
batch.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.
batch.records[].source_flagsuint32_tDimensionless source flag; exactly SERDEV=1 or SYNTHETIC=2. SERDEV does not prove hardware acceptance.
batch.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.
batch.records[].sequencextos_bci_frame_u64Dimensionless lifetime sequence; record i equals batch.cursor+i+1 and START/reopen do not reset it.
batch.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.
batch.records[].config_generationxtos_bci_frame_u64Dimensionless configuration generation, equal to retained batch config.generation; later configuration cannot relabel old frames.
batch.records[].device_counteruint32_tDimensionless wire counter, 0..255; not a timestamp.
batch.records[].counter_bitsuint32_tWire-counter width in bits; equals 8.
batch.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.
batch.records[].enabled_maskuint32_tDimensionless enabled-channel bitmask; equals batch config.enabled_mask.
batch.records[].reservedxtos_bci_frame_u64[2]Reserved, dimensionless; both are zero. xtos_bci_frame_u64 is uint64_t with 8-byte alignment.
batch.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 on success or -1/errno on failure. Acquisition does not consume data; consume and release are explicit.

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.
  • The read-only native-endian mapping is an immutable session-owned copy, not a live zero-copy ring. Do not modify, free, munmap, or issue snapshot ioctls through the borrowed fd. Consume leaves the mapping readable; release/destroy expire borrowed pointers. Copy data before retaining it.
  • Layout: 128-byte header, 384-byte configuration, records at offset 512, 224 bytes per record, and a zero tail. A batch is homogeneous in stream/configuration generation. The SDK validates all metadata and records before publishing out.
  • The two snapshot families exclude each other. While a token is held, frame_read/ordinary reads are refused with EBUSY. A failed acquisition can retain a pending-cleanup token; retry this family’s release before acquiring again.
  • Failed acquisition attempts cleanup while preserving the original errno. A successful address-zero mmap is distinct from MAP_FAILED, but the SDK rejects it with EPROTO and cleans up by its recorded length. Unsupported kernels never fall back to legacy mmap.
  • Acquisition is always nonblocking: empty active and stopped-clean streams return EAGAIN, while empty faulted streams return the saved error. host_rx_ns is only host receive callback time.

Example

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;
}

Source

This reference describes headers and implementation in OpenXTOS v1.0.2 (c24e923717670c4724cdaf24c7c105caee8dc2fb).