xtos_ bci_ snapshot_ acquire
Acquires an immutable integer-nV snapshot of the legacy ring without advancing its byte cursor.
On this page
Declaration
#include <xtos/bci.h>
int xtos_bci_snapshot_acquire(xtos_bci_session_t *session,
size_t requested_bytes,
struct xtos_bci_snapshot *result);Parameters
| Parameter | Type | Description |
|---|---|---|
| session | xtos_bci_session_t * | Non-NULL, caller-managed lifetime; externally serialize access. |
| requested_bytes | size_t | Requested bytes: positive and divisible by 4. The pinned kernel requires at most 65536; rounds down to whole channels×4 frames and returns EAGAIN if less than one frame is available. |
| result | struct xtos_bci_snapshot * | Non-NULL caller-owned output descriptor; zeroed at call entry, so every failure leaves a zero descriptor. |
Output fields
| Field | Type | Meaning |
|---|---|---|
| mapping | const void * | Start of the session-owned read-only immutable mapping; expires on release/destroy. Do not modify or munmap it. |
| mapping_bytes | size_t | Total mapping length in bytes, rounded up to the system page size; includes header, payload and zero tail. |
| header | const struct xtos_bci_snapshot_header * | Borrowed read-only pointer to the validated header at the mapping start; expanded as header.*. |
| payload | const int32_t * | Session-owned contiguous native-endian signed32 samples in nV; complete channel frames with no timestamp. |
| payload_bytes | size_t | Valid sample length in bytes; divide by sizeof(int32_t) for scalar count, then by channels for frame count. Excludes the page tail. |
| header.magic | uint32_t | Format identifier, dimensionless; XTOS_BCI_SNAPSHOT_MAGIC=0x58424349. |
| header.version | uint32_t | Snapshot ABI version, dimensionless; equals 1. |
| header.header_size | uint32_t | Header length in bytes; sizeof(struct xtos_bci_snapshot_header)=64. |
| header.unit | uint32_t | Sample-unit identifier; XTOS_BCI_UNIT_NANOVOLT=1 denotes integer nV. |
| header.payload_bytes | uint64_t | Valid payload length in bytes; nonzero, at most the request and 65536, and a multiple of channels×4. |
| header.cursor | uint64_t | Original legacy-ring read cursor in bytes at acquisition; consume must still match it. |
| header.token | uint64_t | Nonzero FD-local snapshot identifier, dimensionless; both families share a non-reused token sequence, retained by the SDK for consume/release. |
| header.channels | uint32_t | Positive channel count per frame. |
| header.sample_rate_hz | uint32_t | Positive sampling rate in Hz. |
| header.sample_size | uint32_t | Scalar length in bytes; sizeof(int32_t)=4. |
| header.reserved0 | uint32_t | Reserved, dimensionless; zero. |
| header.reserved1 | uint64_t | Reserved, dimensionless; zero. |
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.
- The mapping contains a 64-byte header, contiguous signed32-nV payload and page tail, with at most 64 KiB of payload. The SDK validates request/lengths and mapped header before exposing pointers; it supplies no frame timestamps or sequence.
- 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.
Example
#include <xtos/bci.h>
#include <errno.h>
/* Exclusive session; no previously held snapshot. */
int snapshot_once(xtos_bci_session_t *s) {
struct xtos_bci_snapshot view;
int rc = xtos_bci_snapshot_acquire(s, 4096, &view);
if (rc == 0) {
/* Inspect/copy view here, before consume/release. */
rc = xtos_bci_snapshot_consume(s);
}
int operation_errno = errno;
for (int attempt = 0; attempt < 3; ++attempt) {
if (xtos_bci_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).