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
#include <xtos/bci.h>
int xtos_bci_frame_snapshot_consume(xtos_bci_session_t *session);Parameters
| Parameter | Type | Description |
|---|---|---|
| session | xtos_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
| errno | Condition |
|---|---|
| EINVAL | session is NULL or the kernel rejects request metadata. |
| ENOENT | No valid mapped snapshot of this family exists, or it was already unmapped. |
| ESTALE | The snapshot was consumed or the kernel rejects a stale/replayed token. |
| EOVERFLOW | Overwrite moved the ring read cursor; replacement data is not consumed. |
| ENODEV/system errno | Disconnect 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
#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).