IO Data

IOData is the common container used by IO read/write paths (dawn::CIOCommon::getData(), dawn::CIOCommon::setData()) and notifier callbacks.

Overview

  • Common base interface: dawn::IODataCmn provides item count, data size, per-batch pointers, and timestamp access.

  • Timestamps are per-instance: each buffer is created with or without per-batch timestamp storage. When timestamps are disabled, batches contain only data elements, enabling contiguous memory layout.

  • Static variant: dawn::io_sdata_t (template io_sdata_t<T, N, M, TS>) keeps storage in the object itself (compile-time size, no heap allocation). The TS parameter (default false) controls whether per-batch timestamps are included.

  • Dynamic variant: dawn::io_ddata_t allocates storage on heap (runtime-configurable type size, items, batch count, and timestamp flag).

  • View variant: dawn::io_data_view_t wraps caller-owned storage without allocating or copying. It is useful for temporary protocol buffers and other synchronous adapters into the IO API.

  • Timestamp type: dawn::io_ts_t (uint64_t).

Timestamp Control

Timestamp storage is controlled per-instance, not globally. Each data buffer is created with or without per-batch timestamps:

  • ``io_sdata_t<T, N, M, TS>``: the TS template parameter (default false) selects between two memory layouts at compile time.

  • ``io_ddata_t(t, n, m, dt, ts)``: the ts constructor parameter (default false) selects the layout at runtime.

When TS/ts is false:

  • Batch layout: [data[0] .. data[N-1]] (no timestamp overhead).

  • getPtr() and getDataPtr() return the same address.

  • getTs() returns a shared dummy reference (writes are discarded).

  • hasTimestamp() returns false.

  • For multi-batch buffers (M > 1), all batches are stored contiguously in memory. This layout enables efficient burst reads where a single read(fd, buffer, M * batch_size) call fills the entire buffer without per-sample overhead.

When TS/ts is true:

  • Batch layout: [timestamp | data[0] .. data[N-1]].

  • getPtr() returns the start of the batch (timestamp + data).

  • getDataPtr() skips the timestamp and returns the data start.

  • getTs() returns the per-batch timestamp reference.

  • hasTimestamp() returns true.

IO drivers that interact with kernel structs (e.g., NuttX sensor drivers) always receive [timestamp | data] from the kernel. The driver reads into a temporary buffer and copies only the data portion into the user buffer via getDataPtr(). If isTimestamp() is enabled for the IO instance, the kernel timestamp is also extracted into getTs().

Typical use

  • Use dawn::io_sdata_t when shape is fixed and known at compile time.

  • Use dawn::io_ddata_t when shape comes from descriptor-provided runtime configuration.

  • Use dawn::io_data_view_t when an existing buffer should be passed to getData() or setData() without transferring ownership.

  • Access payload bytes via getDataPtr() and batch timestamp via getTs().

  • Use hasTimestamp() to check whether per-batch timestamps are stored.

Non-Owning Views

io_data_view_t implements IODataCmn over a caller-provided buffer. The view object and the backing buffer may live on the stack, heap, or in static storage; io_data_view_t does not own or free that memory.

getPtr() and getDataPtr() both return the viewed buffer. hasTimestamp() is always false and getTs() returns a dummy timestamp reference.

The caller must ensure that the backing buffer remains valid for the whole getData() or setData() call. IO implementations must not retain the view object or its returned pointer after the call returns.

Doxygen