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
#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
| 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; there is no flags parameter and acquisition is always nonblocking. |
| out | struct xtos_bci_frame_snapshot * | Non-NULL caller-owned output descriptor; failure leaves it unchanged and publishes no new pointers. |
Output fields
| Field | Type | Meaning |
|---|---|---|
| mapping | const void * | Start pointer of the session-owned read-only immutable mapping; expires on release/destroy. Do not unmap it yourself. |
| mapping_bytes | size_t | Total mapping length in bytes: PAGE_ALIGN(512+frame_count×224), including the zero-filled tail. |
| header | const struct xtos_bci_frame_snapshot_header * | Borrowed pointer to the validated header at mapping offset 0; expanded as header.*. |
| batch | struct xtos_bci_frame_batch | Frame-batch descriptor, expanded as batch.*; records point at mapping offset 512. Configuration at offset 128 equals batch.config. |
| header.magic | uint32_t | Format identifier, dimensionless; XTOS_BCI_FRAME_SNAPSHOT_MAGIC=0x58424631. |
| header.version | uint32_t | Frame ABI version, dimensionless; equals 1. |
| header.header_bytes | uint32_t | Mapping-header length in bytes; equals 128. |
| header.record_bytes | uint32_t | Frame-record length in bytes; equals 224. |
| header.frame_count | uint32_t | Complete frame count, 1..capacity_frames; equals batch.frame_count. |
| header.flags | uint32_t | Flags, dimensionless; zero. |
| header.unit | uint32_t | Sample-unit identifier; NANOVOLT=1. |
| header.host_clock | uint32_t | Host-clock identifier; MONOTONIC=1. |
| header.payload_bytes | xtos_bci_frame_u64 | Record-area length in bytes: frame_count×224, excluding header, configuration and tail. |
| header.cursor | xtos_bci_frame_u64 | Original starting logical cursor in frames; equals batch.cursor. |
| header.next_cursor | xtos_bci_frame_u64 | Logical cursor after the batch, in frames; cursor+frame_count. |
| header.token | xtos_bci_frame_u64 | Nonzero FD-local snapshot identifier, dimensionless; retained by the SDK for consume/release, never caller-modified. |
| header.stream_generation | xtos_bci_frame_u64 | Dimensionless stream generation; equals the batch and every record's stream_generation. |
| header.config_generation | xtos_bci_frame_u64 | Dimensionless configuration generation; equals batch.config.generation and every record's config_generation. |
| header.overwritten_frames | xtos_bci_frame_u64 | Cumulative overwritten unread-frame count, equal to batch.overwritten_frames; not wire-counter loss. |
| header.mapping_bytes | xtos_bci_frame_u64 | Total mapping length in bytes; equals outer mapping_bytes. |
| header.config_bytes | uint32_t | Verified configuration length in bytes; equals 384. |
| header.records_offset | uint32_t | Record-area offset in bytes; equals 512, with configuration at 128. |
| header.reserved | uint32_t[6] | Reserved, dimensionless; all six elements are zero. |
| batch.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. |
| batch.frame_count | uint32_t | Complete frame count, 0..capacity_frames; a successful snapshot is nonempty. |
| batch.cursor | uint64_t | Starting logical cursor in frames, starting at zero; first sequence=cursor+1. |
| batch.next_cursor | uint64_t | Logical cursor after the batch, in frames; equals cursor+frame_count. |
| batch.overwritten_frames | uint64_t | Cumulative unread frames displaced by overwrite; independent of wire-counter loss and RESET_STATS, excluding explicit consumption and reopen discard. |
| batch.stream_generation | uint64_t | Dimensionless stream generation; nonzero and homogeneous in a nonempty batch, zero for a stopped clean empty read. |
| batch.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. |
| batch.config.version | uint32_t | ABI version, dimensionless; must be 1. |
| batch.config.flags | uint32_t | Flags, dimensionless; zero in v1. |
| batch.config.channels | uint32_t | Channel count; the validated profile requires 8. |
| batch.config.sample_rate_hz | uint32_t | Sampling rate in Hz; the validated profile requires 250. |
| batch.config.enabled_mask | uint32_t | Dimensionless enabled-channel mask; bits 0..7 represent channels 0..7 and agree with CHnSET power-down bits. |
| batch.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. |
| batch.config.reserved0 | uint32_t[2] | Reserved, dimensionless; both elements are zero. |
| batch.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. |
| batch.config.gain | uint32_t[8] | Per-channel dimensionless gain; each is 1, 2, 4, 6, 8, 12, or 24 and agrees with register readback. |
| batch.config.registers | uint8_t[24] | 24 actual ADS register bytes, dimensionless; CONFIG1 low three bits equal 6 and CHnSET validates gains and enable state. |
| batch.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. |
| batch.config.reserved | uint32_t[8] | Reserved, dimensionless; all eight elements are zero. |
| batch.records[].version | uint32_t | Record ABI version, dimensionless; equals 1. |
| batch.records[].record_bytes | uint32_t | Record size in bytes; equals 224. |
| batch.records[].channels | uint32_t | Valid channel count, currently 8; agrees with batch config.channels. |
| batch.records[].sample_rate_hz | uint32_t | Sampling rate in Hz, currently 250; agrees with batch configuration. |
| batch.records[].unit | uint32_t | Sample-unit enum; XTOS_BCI_UNIT_NANOVOLT=1 denotes integer nV. |
| batch.records[].host_clock | uint32_t | Host-clock enum; XTOS_BCI_FRAME_CLOCK_MONOTONIC=1 denotes Linux CLOCK_MONOTONIC. |
| batch.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. |
| batch.records[].source_flags | uint32_t | Dimensionless source flag; exactly SERDEV=1 or SYNTHETIC=2. SERDEV does not prove hardware acceptance. |
| batch.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. |
| batch.records[].sequence | xtos_bci_frame_u64 | Dimensionless lifetime sequence; record i equals batch.cursor+i+1 and START/reopen do not reset it. |
| batch.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. |
| batch.records[].config_generation | xtos_bci_frame_u64 | Dimensionless configuration generation, equal to retained batch config.generation; later configuration cannot relabel old frames. |
| batch.records[].device_counter | uint32_t | Dimensionless wire counter, 0..255; not a timestamp. |
| batch.records[].counter_bits | uint32_t | Wire-counter width in bits; equals 8. |
| batch.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. |
| batch.records[].enabled_mask | uint32_t | Dimensionless enabled-channel bitmask; equals batch config.enabled_mask. |
| batch.records[].reserved | xtos_bci_frame_u64[2] | Reserved, dimensionless; both are zero. xtos_bci_frame_u64 is uint64_t with 8-byte alignment. |
| batch.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 on success or -1/errno on failure. Acquisition does not consume data; consume and release are explicit.
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.
- 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
#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).