xtos_ bci_ read_ samples
Reads driver int32 nanovolt samples and numerically converts to float microvolts (v1.0.2).
On this page
Declaration
#include <xtos/bci.h>
ssize_t xtos_bci_read_samples(xtos_bci_session_t *session,
float *buffer,
size_t num_samples);Parameters
| Parameter | Type | Description |
|---|---|---|
| session | xtos_bci_session_t * | Non-NULL session handle; do not race reads or destruction. |
| buffer | float * | Non-NULL caller-owned buffer for at least num_samples floats; successful values are in µV. |
| num_samples | size_t | Requested 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
| errno | Condition |
|---|---|
| EINVAL | session/buffer is NULL or num_samples is zero. |
| EBUSY | The SDK refuses while a frame snapshot token is owned or pending cleanup; kernel read refuses while a legacy snapshot is held. |
| EOVERFLOW | num_samples×sizeof(int32_t) exceeds SIZE_MAX; rejected before allocation. |
| ENOMEM | Normally set by the allocator if malloc of the raw integer temporary buffer fails. |
| EIO | Bytes at EOF are not a multiple of sizeof(int32_t); the entire call fails. |
| EAGAIN/EWOULDBLOCK | Possible after caller-enabled nonblocking mode; returns -1 even after partial progress, not a partial count. |
| system errno | While 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).