proposal: rework timeouts, StreamDevices and DatagramDevices

[RecursiveError]

Summary:

• Change the default timeout behavior in protocols that behave like streams

• Analyze ambiguity between the current Datagram and StreamDevices interfaces

• Extra case: Analyze the use case of drivers exposing generic interfaces

How a timeout can turn a stream into a datagram

A stream represents a communication channel with no predefined size.
Because of this, a timeout should not be treated as an error by default — it’s expected that a device might not send an entire buffer at once, or that a receiver might not always have enough incoming data to fill its read buffer.

However, the way we currently handle timeouts in most UART HALs treats a timeout as a failed transmission of a fixed-size buffer in single transaction, effectively turning the stream into a datagram-like operation.

This raises an interesting question:

Is UART really a StreamDevice?

Streams often use UART as their canonical example, since UART is a very common way to perform raw communication between two controllers.
But thinking more deeply — what prevents a fixed-size protocol from using UART?
Nothing. It’s perfectly valid (even if less common in some designs) to implement length-defined packet protocols over UART.

That means StreamDevice has an edge case where it behaves like a datagram.
But then, what are the edge cases for Datagram?

---

Is a datagram also a kind of stream?

By analogy, datagram interfaces are typically represented by I2C or SPI, which are usually used for fixed-size packet transfers.
And that’s true — to some extent.

These buses are very common in simple modules where communication rules are rigidly defined, and a write timeout or failed full transfer is indeed an error.

But both I2C and SPI can also be used in a stream-like context, especially SPI, which is often used for raw controller-to-controller communication (similar to USART).

I2C as a special case:

In a host → device transaction, the device can send a NACK to indicate it no longer wants to receive data — this is valid behavior.

In a device → host transaction, the specification requires the device to send 0xFF if it has no more data to transmit; This means that a reader with an arbitrary buffer length does not generate an error, which is problematic for streams: here, 0xFF is ambiguous, as it could be either valid data or a placeholder.

Despite this, REPEATED START, makes it much closer to stream-like behavior over a datagram, And there are also cases of
some I2C modules — especially those that also support SPI — to typically provide a burst read/write function, allowing the host to read or write N bytes sequentially (as long as a certain limit is not exceeded), edge-case of stream-like behavior on I2C.

So, even protocols usually treated as datagram-based have situations where they behave like streams.

In other words:

Anything that can be a stream can also behave like a datagram —
but not everything that’s a datagram can behave like a stream.

---

Why separate them, then?

If the distinction between stream and datagram depends mostly on how timeouts and buffer sizes are handled, we might not need two separate interfaces at all.

By defining methods like read_all and write_all, we can express both behaviors cleanly:

• write/read — Timeout, NACK or any EOF is not an error → behaves like a stream
• write_all/read_all — Timeout, NACK or any early EOF is an error → behaves like a datagram

[Grazfather]

Is this a proposal? Please put that in the title and near the top of your post.

Great explanation, though. Thanks for going in detail and with clarity.

[RecursiveError]

Extra Case – Drivers Exposing Generic Interfaces

Up to this point, we’ve been dealing exclusively with Datagram and Stream Devices in the context of providing a generic interface for drivers to use.
However, there’s another interesting possibility: drivers that expose these interfaces for communication.

Let’s take the HD44780 display as an example. It’s very common to use an I²C I/O expander with this display to reduce the number of required pins.
If we analyze this setup closely, we realize that we actually have a driver that receives a generic interface, acts as a bridge between two protocols, and then returns another generic interface for the display to use.

The interesting part of this use case is that it applies to any kind of bridge driver—drivers that can expose another interface.
In this scenario, the distinction between Stream and Datagram becomes even thinner, because it’s now the driver itself that defines what constitutes a “transaction,” rather than the underlying protocol topology.

Returning to the HD44780 example: even though the I/O expander operates as a well-defined Datagram device, the bridge to the display behaves differently.
If communication fails midway, there’s no need to restart—the display has already received N bytes, and the next transaction can simply continue from where it left off.
This kind of setup can be thought of as a Virtual Interface.

[RecursiveError]

Another Edge Case – Non-Standard External Flow Control

Some modules (yes, I’m talking about SPI and its odd relatives) use additional mechanisms to work around protocol limitations.
In many of these cases, an extra “busy” state is introduced — something the base protocol wouldn’t normally have.

This isn’t necessarily an error by itself, but the added waiting period can lead to a timeout.
And then we’re back to the original question: “Is it really an error, or not?”

(There’s also a similar situation with DMA or internal FIFOs on microcontrollers.
In those cases, you’re reading from or writing to an arbitrary-length buffer rather than directly accessing the bus.
However, that already falls under the category of a non-blocking API, which is honestly outside the current scope.)