libxtos-bci
BCI sessions, device capability, buffer ownership, and released data-format limits.
On this page
Device prerequisites
A session accesses an XTOS character device such as /dev/xtos0, not an arbitrary /dev/ttyUSB0.
Enable xtos_bci_core, xtos_bci_buffer, and the matching device driver, then register the device.
The public OpenBCI Cyton implementation is a serdev driver with device-tree compatible openbci,cyton; loading modules does not establish binding or registration.
create calls open(path, O_RDWR), so the caller needs read/write permission. A missing node usually gives ENOENT; insufficient permission gives EACCES. The current core permits one opener; a second gets EBUSY. QEMU can check module loading, not hardware acquisition without the board.
Session order
xtos_bci_session_t *xtos_bci_session_create(const char *device_path);
int xtos_bci_get_info(xtos_bci_session_t *session,
struct xtos_bci_device_info *info);
int xtos_bci_start(xtos_bci_session_t *session);
int xtos_bci_stop(xtos_bci_session_t *session);
void xtos_bci_session_destroy(xtos_bci_session_t *session);- create: path is non-NULL and NUL-terminated; NULL gives EINVAL, allocation/open failure returns NULL with the failing errno.
- get_info: session/info are non-NULL; returns the cache from create and does not issue GET_INFO again. Check num_channels, sampling_rate, and resolution_bits.
- Configure: set supported rate and channels before acquisition; Cyton checks register readback. Query configuration and generation with get_config.
- start→acquire or poll→stop: start/stop issue ioctl and return 0/-1; streaming changes only after ioctl success.
- destroy: stop workers and explicitly release snapshots to observe cleanup errors. Even if STOP fails it attempts mapping/token cleanup, then close/free; destroy(NULL) is a no-op.
If GET_INFO fails, create still returns a session with a calloc-zeroed cache; later get_info can return 0. Successful creation does not prove XTOS UAPI. info.name is a fixed 32-byte array and may lack NUL termination; print it with a bound. session.c has no concurrency lock; do not race reads, configuration, or destruction.
Acquisition controls
| Interface | Constraints and return | Public Cyton behavior |
|---|---|---|
| set_sampling_rate | rate is integer Hz; returns 0 or -1/errno and updates the cache on success. | Only 250 Hz is supported, with configuration readback. 500/1000/2000 Hz give EOPNOTSUPP; other invalid values give EINVAL. Control during acquisition gives EBUSY. |
| set_channel | channel is zero-based, enabled is bool, gain is uint32; returns 0 or -1/errno. | Cyton channels are 0–7, with gains 1, 2, 4, 6, 8, 12, 24; gain=0 preserves the current gain. The core forwards enabled/gain; the driver checks acknowledgement and register readback. Acquisition gives EBUSY. |
| calibrate | NULL session gives -1/EINVAL; a valid session is handled by the driver. | Returns -1/EOPNOTSUPP without calibration or false success. |
| check_impedance | Non-NULL output, 1≤channels≤32; array holds at least channels uint32 values in integer kΩ. | Returns -1/EOPNOTSUPP without measurement values. |
| xtos_bci_get_config | session/out are non-NULL; returns 0 or -1/errno, leaving out unchanged on failure. | Queries and validates v1 configuration, registers, firmware, gain, and generation; malformed data gives EPROTO. The get_info cache is not live configuration. |
These functions configure acquisition devices; they are not generic actuator commands. ioctl can return EINVAL, EOPNOTSUPP, EFAULT, or ENOTTY for an unknown command, and serial errors can propagate. Distinguish invalid parameters, unsupported capability, and link failure; record requested and verified configuration.
Sample format
ssize_t xtos_bci_read_samples(xtos_bci_session_t *session,
float *buffer, size_t num_samples);Requires non-NULL session/buffer and num_samples>0, otherwise -1/EINVAL.
The function checks num_samples≤SIZE_MAX/sizeof(int32_t), mallocs a raw integer buffer, and accumulates reads until the requested bytes or EOF. On success each value becomes microvolts via (float)raw / 1000.0f; caller buffer holds at least num_samples floats.
The parameter counts scalar channel values, not automatically multichannel frames.
EOVERFLOW means allocation-size multiplication overflow; malloc failure normally gives ENOMEM. EINTR is retried. Other read errors, including EAGAIN, return -1 and discard data already consumed by this call without writing output. At EOF, complete integers return a short count, possibly 0; a trailing partial int32 returns EIO.
read_samples returns no device timestamp, packet sequence, quality flags, or reliable multichannel frame boundary; read completion is not sample time. Versioned frame interfaces provide sequence, quality, configuration metadata, and host receive time, but no device acquisition time. Direct borrowed-fd reads still require byte, unit, and boundary handling.
fd and versioned views
void *xtos_bci_get_mmap_buffer(xtos_bci_session_t *session, size_t *size);
int xtos_bci_get_fd(xtos_bci_session_t *session);get_fd returns the session-owned borrowed fd; NULL gives -1/EINVAL. It can be used with poll/select, but do not close it or use it after destroy. open does not set O_NONBLOCK; read after poll still needs race, signal, and short-read handling. fcntl can enable nonblocking mode, where no data can give EAGAIN.
Legacy xtos_bci_get_mmap_buffer always returns NULL and sets optional size to 0. A valid session gives EOPNOTSUPP; a NULL session gives EINVAL. It no longer maps the raw buffer.
A session must be externally serialized: do not race reads, configuration, consume, release, or destruction, or issue snapshot ioctls through the borrowed fd. The two snapshot families exclude each other; an owned token or pending cleanup gives EBUSY on another acquire or frame_read. Views belong to the session: do not modify, free, or munmap them; copy data for retention.
| Interface | Usage contract |
|---|---|
| xtos_bci_snapshot_acquire | requested_bytes is nonzero and a multiple of 4; UAPI limit 64 KiB, rounded down by the kernel to whole channel frames. Success is 0 with a read-only native-endian int32 nanovolt mapping; failure is -1 and zeroes result. |
| xtos_bci_snapshot_consume | Consumes the full payload with its original token/cursor; returns 0 or -1/errno, with ENOENT for no valid snapshot. Consume does not release the mapping; replay, overwrite, and unbind errors propagate. |
| xtos_bci_snapshot_release | Unmaps before releasing the token; no snapshot returns 0. A munmap failure retains mapping/token for retry. After ioctl failure the mapping is invalid and the token remains, except ENODEV/ENOENT terminate ownership. Failure returns -1/errno. |
| xtos_bci_frame_read | capacity_frames is 1–292; flags is 0 or XTOS_BCI_FRAME_NONBLOCK. Returns 0 or -1/errno. Two maximum-batch buffers are reserved at creation, so read does not allocate. Failure preserves out and previous valid view bytes; the old read view expires on the next successful read, release, or destroy. |
| xtos_bci_frame_snapshot_acquire | capacity_frames is 1–292. Success returns a read-only frame batch, configuration, and mapping; failure returns -1 with out unchanged. Pointers are published only after metadata and record validation. |
| xtos_bci_frame_snapshot_consume | Consumes the whole batch with its original token/cursor/stream_generation; returns 0 or -1/errno, with ENOENT for no valid view. The mapping remains readable after consume; replay errors propagate. |
| xtos_bci_frame_snapshot_release | Unmaps before token release; success or no snapshot returns 0. Any failure retains remaining ownership for retry; release remains callable after disconnect. Consume is unavailable after unmapping. |
Invalid arguments give EINVAL, malformed metadata EPROTO, and unrepresentable addresses/lengths EOVERFLOW. Unsupported kernels propagate ioctl errors without legacy mmap fallback. Failed acquisition attempts cleanup while preserving the original error; retry the matching release after cleanup failure before acquiring again. Release/destroy ends snapshot lifetime. Destroy attempts cleanup even after STOP fails, but its void return cannot report cleanup failure.
Frame samples_nv contains integer nanovolts, and configuration includes gain and generation. host_rx_ns is CLOCK_MONOTONIC host receive time recorded after the callback acquires its lock, not device acquisition time or proof of physical latency. Sequence, counter gaps, and quality flags aid diagnosis; they do not establish hardware clock synchronization or detection of every lost packet.
Statistics and limits
int xtos_bci_get_stats(xtos_bci_session_t *session,
struct xtos_bci_statistics *stats);
int xtos_bci_reset_stats(xtos_bci_session_t *session);get_stats requires non-NULL session/stats and returns 0/-1; reset_stats requires non-NULL session. Fields are samples_read, samples_dropped, errors, and overruns. Cyton increments samples_read when channel values enter the buffer, not when an application consumes a frame. When space is short, the ring buffer drops oldest bytes and increments overruns; samples_dropped is not a complete loss count. Sources: sdk/libxtos-bci/include/xtos/bci.h, bci_uapi.h, src/session.c, and kernel xtos_bci_core.c, xtos_bci_buffer.c, devices/openbci_cyton.c.
Record session control, read conversion, allocation and error-related loss, configuration readback, snapshot/frame lifetimes, and EOPNOTSUPP for calibration and impedance separately. Source and software tests do not establish end-to-end hardware BCI acceptance.