Dawn IO

Dawn IO - an object type that can be read or written to system resources or DAWN resources. IO objects can be accessed by Programs and Protocols.

Overview

IO objects represent data sources/sinks in Dawn.
Most IO classes are backed by OS resources (GPIO, ADC, file, timerfd, CAN, etc.).
Some IO classes are framework-facing control points (for example ConfigIO, ControlIO, TriggerIO).
Programs and protocols access IO through dawn::CIOHandler.

Binding Model

IO configuration is descriptor-driven:

IO objects are created from descriptor entries.
configure() parses IO-specific configuration items.
init() allocates runtime resources.
CIOHandler::bindObjects() resolves target bindings for special IOs (Config/Control/Trigger) after all handlers are initialized.

Lifecycle

IO lifecycle is managed by dawn::CIOHandler:

init(): create IO objects from descriptor and attach factories.
initAll(): run configure() and init() for each IO.
startAll() / stopAll(): activate or stop IO runtime behavior. When CONFIG_DAWN_IO_NOTIFY is enabled, notifier thread lifecycle is handled here.
deinitAll(): release IO-owned resources.

Data Access Model

Dawn provides two interfaces to access IO data: fetch (pull) and notification (push).

Fetch reads on request via dawn::CIOCommon::getData() in the caller thread. It is the right fit for synchronous protocols and periodic polling.

Notification delivers data when the IO becomes readable, using dawn::IIONotifier callbacks registered through dawn::CIOCommon::bindNotifier() and dawn::CIOCommon::setNotifier(). Notification support is controlled by CONFIG_DAWN_IO_NOTIFY; when enabled it is preferred for event-driven or latency-sensitive flows.

Dawn supports multiple notification strategies:

Poll notifier (CIONotifier): Multiplexes multiple IOs per thread using poll(). IOs with the same priority share a thread. Default strategy.
Stream notifier (CStreamNotifier): Dedicated thread per IO. Enabled by CONFIG_DAWN_IO_NOTIFY_STREAM. Suited for high-frequency data paths requiring independent priority scheduling.

The CIONotifierManager routes each IO to the correct notifier based on its IO_CFG_NOTIFY descriptor configuration (type, priority, batch count). Both strategies use dawn::CIOCommon::getData() internally, so the IO abstraction is preserved throughout.

See IO Notifier for notifier details and YAML configuration.

See IO Data for IO data container details.

Seekable IO

Seekable (offset-based) IO access is controlled by CONFIG_DAWN_IO_SEEKABLE.

When enabled, seekable IO classes can use partial reads/writes via getData()/setData() with non-zero offset.

When disabled, offset-based access is not available and returns -ENOTSUP.

Timestamp

Timestamp support requires CONFIG_DAWN_IO_TIMESTAMP.

Timestamps are controlled per IO instance via the IO_FLAGS_TS flag in the object descriptor. When an IO has timestamps enabled:

The IO produces timestamp values (typically microseconds since boot).
Data buffers created with TS=true (io_sdata_t) or ts=true (io_ddata_t) store a per-batch timestamp alongside the data.
ddata_alloc() automatically matches the IO’s timestamp setting.

When timestamps are disabled for an IO (the default):

Data buffers omit per-batch timestamp storage, saving 8 bytes per batch.
Memory layout is contiguous data, suitable for zero-copy and burst reads.

For inputs, timestamp is the time associated with a given input sample.

For outputs, timestamp is the time when the output was last set.

See IO Data for data buffer layout details.

IO Limits

IO limits are common IO configuration items defined in dawn::CIOCommon:

IO_CFG_LIMIT_MIN
IO_CFG_LIMIT_MAX
IO_CFG_LIMIT_STEP

This feature is controlled by CONFIG_DAWN_IO_LIMITS.

Each limit item stores a word array (uint32_t words) with DTYPE metadata. The three items must use the same DTYPE and size.

If limits are disabled or not configured, no range/step limit enforcement is applied.

Limit checks are applied on write paths (setData/setDataImpl), not on reads.

For scalar values, one element is checked. For multi-dimensional payloads, limits are checked element-by-element.

step == 0 means “any value between min and max”.

Limits are descriptor-defined runtime constraints. They complement, but do not replace, hardware/static limits enforced by specific IO implementations.