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

xtos_bci_snapshot_acquire

Acquires an immutable integer-nV snapshot of the legacy ring without advancing its byte cursor.

On this page

Declaration

c
#include <xtos/bci.h>

int xtos_bci_snapshot_acquire(xtos_bci_session_t *session,
                              size_t requested_bytes,
                              struct xtos_bci_snapshot *result);

Parameters

ParameterTypeDescription
sessionxtos_bci_session_t *Non-NULL, caller-managed lifetime; externally serialize access.
requested_bytessize_tRequested 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.
resultstruct xtos_bci_snapshot *Non-NULL caller-owned output descriptor; zeroed at call entry, so every failure leaves a zero descriptor.

Output fields

FieldTypeMeaning
mappingconst void *Start of the session-owned read-only immutable mapping; expires on release/destroy. Do not modify or munmap it.
mapping_bytessize_tTotal mapping length in bytes, rounded up to the system page size; includes header, payload and zero tail.
headerconst struct xtos_bci_snapshot_header *Borrowed read-only pointer to the validated header at the mapping start; expanded as header.*.
payloadconst int32_t *Session-owned contiguous native-endian signed32 samples in nV; complete channel frames with no timestamp.
payload_bytessize_tValid sample length in bytes; divide by sizeof(int32_t) for scalar count, then by channels for frame count. Excludes the page tail.
header.magicuint32_tFormat identifier, dimensionless; XTOS_BCI_SNAPSHOT_MAGIC=0x58424349.
header.versionuint32_tSnapshot ABI version, dimensionless; equals 1.
header.header_sizeuint32_tHeader length in bytes; sizeof(struct xtos_bci_snapshot_header)=64.
header.unituint32_tSample-unit identifier; XTOS_BCI_UNIT_NANOVOLT=1 denotes integer nV.
header.payload_bytesuint64_tValid payload length in bytes; nonzero, at most the request and 65536, and a multiple of channels×4.
header.cursoruint64_tOriginal legacy-ring read cursor in bytes at acquisition; consume must still match it.
header.tokenuint64_tNonzero FD-local snapshot identifier, dimensionless; both families share a non-reused token sequence, retained by the SDK for consume/release.
header.channelsuint32_tPositive channel count per frame.
header.sample_rate_hzuint32_tPositive sampling rate in Hz.
header.sample_sizeuint32_tScalar length in bytes; sizeof(int32_t)=4.
header.reserved0uint32_tReserved, dimensionless; zero.
header.reserved1uint64_tReserved, dimensionless; zero.

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.
  • 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

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