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

xtos_bci_read_samples

Reads driver int32 nanovolt samples and numerically converts to float microvolts (v1.0.2).

On this page

Declaration

c
#include <xtos/bci.h>

ssize_t xtos_bci_read_samples(xtos_bci_session_t *session,
                             float *buffer,
                             size_t num_samples);

Parameters

ParameterTypeDescription
sessionxtos_bci_session_t *Non-NULL session handle; do not race reads or destruction.
bufferfloat *Non-NULL caller-owned buffer for at least num_samples floats; successful values are in µV.
num_samplessize_tRequested scalar count, positive and at most SIZE_MAX/sizeof(int32_t); not a frame count.

Return value

Accumulates reads until the request or EOF. Returns a nonnegative scalar count on success (short or zero at EOF); returns -1 on failure, without delivering or allowing this function to recover data already consumed by the call.

Errors

errnoCondition
EINVALsession/buffer is NULL or num_samples is zero.
EBUSYThe SDK refuses while a frame snapshot token is owned or pending cleanup; kernel read refuses while a legacy snapshot is held.
EOVERFLOWnum_samples×sizeof(int32_t) exceeds SIZE_MAX; rejected before allocation.
ENOMEMNormally set by the allocator if malloc of the raw integer temporary buffer fails.
EIOBytes at EOF are not a multiple of sizeof(int32_t); the entire call fails.
EAGAIN/EWOULDBLOCKPossible after caller-enabled nonblocking mode; returns -1 even after partial progress, not a partial count.
system errnoWhile a frame snapshot token is owned, including pending cleanup, the SDK returns EBUSY; legacy snapshots cause kernel read to return EBUSY. EINTR is retried internally; other read errors preserve underlying errno.

Notes

  • mallocs an int32 buffer, loops over read, then converts with (float)raw / 1000.0f. Per-call malloc/free and potentially blocking request filling are not suitable for a strictly allocation-free real-time thread; poll readiness does not guarantee the full request will not wait.
  • Output is written only after error-free, integer-aligned reading. Any non-EINTR error, including EAGAIN, or EIO discards the temporary data from this call; device position may already have advanced.
  • The caller owns output; no device timestamp, sequence, quality flags, or reliable multichannel framing is provided. Use the frame API for host receive metadata. Legacy get_mmap_buffer is refused; versioned snapshots expose integer nV, never float.
  • 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 pinned make -C sdk/libxtos-bci test target runs test_samples, test_snapshot, test_snapshot_uapi, test_config and test_frame. These are software FIFO/syscall-wrapper checks, not physical hardware, measured serial behavior, or worst-case latency evidence.

Example

Source

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