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

xtos_bci_frame_snapshot_consume

Uses the original SDK-retained token and cursor to consume the entire acquired snapshot once without releasing its mapping.

On this page

Declaration

c
#include <xtos/bci.h>

int xtos_bci_frame_snapshot_consume(xtos_bci_session_t *session);

Parameters

ParameterTypeDescription
sessionxtos_bci_session_t *Non-NULL, caller-managed lifetime; externally serialize access.

Return value

Returns 0 on success or -1/errno on failure. It never auto-releases; failure is not successful consumption.

Errors

errnoCondition
EINVALsession is NULL or the kernel rejects request metadata.
ENOENTNo valid mapped snapshot of this family exists, or it was already unmapped.
ESTALEThe snapshot was consumed or the kernel rejects a stale/replayed token.
EOVERFLOWOverwrite moved the ring read cursor; replacement data is not consumed.
ENODEV/system errnoDisconnect or other ioctl 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 frame family sends token, original cursor, entire frame_count and stream_generation; the legacy family sends token, original byte cursor and entire payload_bytes. Partial consumption is unavailable, and editing the output cannot change the SDK-retained request.
  • Success only advances the corresponding ring consumer position; it does not update the output descriptor or invalidate pointers. A repeated call resends the request and propagates ESTALE.

Example

c
#include <xtos/bci.h>
int consume_view(xtos_bci_session_t *s) {
    return xtos_bci_frame_snapshot_consume(s);
}

Source

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