Concepts

Informative

The model behind the UART driver: its driver- and per-channel TX/RX state machines, the two transmission-notification styles, the streaming reception model with a mid-transfer trigger, and how events are handled. Non-binding; the normative rules live in Uart — Requirements.

State machine

The driver has a driver-wide state and, within the initialized state, independent TX and RX states per channel.

Driver state

        stateDiagram-v2
   [*] --> UART_DRV_STATE_UNINIT : Reset
   UART_DRV_STATE_UNINIT --> UART_DRV_STATE_INIT : Uart_Init()
   UART_DRV_STATE_INIT --> UART_DRV_STATE_UNINIT : Uart_DeInit()

Driver state	Meaning	API calls accepted
`UART_DRV_STATE_UNINIT`	Not initialized (state after reset/startup)	Only `Uart_Init()`
`UART_DRV_STATE_INIT`	Initialized; service APIs are accepted	All

TX channel state

Each channel has a transmit state (Uart_ChannelTxStateType). The BUSY → READY → IDLE path applies to streaming channels (the software buffer empties before the hardware finishes); HW-completion channels go straight BUSY → IDLE when the bus is idle.

        stateDiagram-v2
   direction LR
   [*] --> UART_CH_TX_STATE_UNINIT : Reset
   UART_CH_TX_STATE_UNINIT --> UART_CH_TX_STATE_IDLE : Uart_Init()
   UART_CH_TX_STATE_IDLE --> UART_CH_TX_STATE_BUSY : Uart_StartTxTransaction()
   UART_CH_TX_STATE_BUSY --> UART_CH_TX_STATE_READY : SW buffer empty (Streaming)
   UART_CH_TX_STATE_READY --> UART_CH_TX_STATE_IDLE : HW finished sending
   UART_CH_TX_STATE_READY --> UART_CH_TX_STATE_BUSY : Uart_StartTxTransaction()
   UART_CH_TX_STATE_BUSY --> UART_CH_TX_STATE_IDLE : HW finished (HwCompletion) or TX error

TX state	Meaning
`UART_CH_TX_STATE_UNINIT`	Not initialized.
`UART_CH_TX_STATE_IDLE`	No transmission ongoing.
`UART_CH_TX_STATE_READY`	Streaming only: the software buffer has been fully handed to the hardware, but a transmission is still ongoing — a new buffer may be staged.
`UART_CH_TX_STATE_BUSY`	A transmission is ongoing.

RX channel state

        stateDiagram-v2
   direction LR
   [*] --> UART_CH_RX_STATE_UNINIT : Reset
   UART_CH_RX_STATE_UNINIT --> UART_CH_RX_STATE_IDLE : Uart_Init()
   UART_CH_RX_STATE_IDLE --> UART_CH_RX_STATE_BUSY : Uart_StartRxTransaction()
   UART_CH_RX_STATE_BUSY --> UART_CH_RX_STATE_IDLE : buffer full / Uart_CancelRxTransaction() / RX error

RX state	Meaning
`UART_CH_RX_STATE_UNINIT`	Not initialized.
`UART_CH_RX_STATE_IDLE`	Not receiving; the hardware holds no pending data.
`UART_CH_RX_STATE_BUSY`	Receiving, or the hardware holds data not yet stored to the buffer.

See Uart — Requirements (CHI-UART-MUST-03…CHI-UART-MUST-05).

Transmission: completion vs streaming

A channel is configured for one of two transmission-notification styles (transmission_callback_type) — the driver does not use both for the same channel:

HwCompletion (Uart_Callout_OnTransmission) — fired when the whole buffer has left the UART hardware onto the bus (FIFO and shift register empty). Use it when the integration code needs a true “sent” confirmation.
Streaming (Uart_Callout_OnStreamingDataRequest) — fired as soon as the software buffer has been handed to the hardware (the FIFO/shift register may still be draining). The channel enters READY and the integration code can immediately stage the next buffer with Uart_StartTxTransaction — keeping the bus continuously fed.

Reception: buffer, trigger, and streaming

Uart_StartRxTransaction(channelId, rxDataPtr, rxDataLength, additionalRxLenTrg) arms reception into a buffer. The integration code is notified through Uart_Callout_OnReception(channelId, length) at two points:

when the received length reaches additionalRxLenTrg (if it is > 0) — a mid-transfer indication, useful to inspect a command header before the rest arrives; and
when the buffer becomes full.

If the buffer length is a multiple of the trigger and both fire together, Uart_Callout_OnReception is called once. The trigger can be re-armed from within the callout with Uart_SetAdditionalRxLenTrg.

Crucially, reception is streaming-friendly: the driver does not stop the hardware when the buffer fills. Inside Uart_Callout_OnReception the integration code calls Uart_StartRxTransaction again to hand over the next buffer without losing bytes; if it does not, the driver stops reception after the callout returns. Uart_CancelRxTransaction explicitly stops the hardware (e.g. after interpreting a command chunk and deciding no more data is needed).

Event handling: interrupt or polling

Per channel, event handling is interrupt or polling: Uart_Interrupt services interrupt channels, Uart_PollFunction services polled ones — both do the same work and drive the same callouts. Optional hardware flow control is enabled per channel where the hardware supports it.

TX sequence (streaming)

The informative view of a streaming transmission (CHI-UART-MUST-08, CHI-UART-MUST-11):

        sequenceDiagram
   participant INTEG as Integration code
   participant DRV as UartDrv
   participant HW as UART HW

   INTEG->>DRV: Uart_StartTxTransaction(ch, txData, len)
   activate DRV
   DRV->>HW: fill HW FIFO (channel BUSY)
   DRV-->>INTEG: E_OK
   deactivate DRV

   HW->>DRV: Uart_Interrupt (SW buffer empty)
   activate DRV
   DRV->>INTEG: Uart_Callout_OnStreamingDataRequest(ch, length) (channel READY)
   opt more to send
      INTEG->>DRV: Uart_StartTxTransaction(ch, next, len)
   end
   Note over DRV,HW: HW keeps draining the FIFO to the bus asynchronously
   deactivate DRV

RX sequence (chunked)

The informative view of a chunked reception with a mid-transfer trigger (CHI-UART-MUST-12, CHI-UART-MUST-13, CHI-UART-MUST-14):

        sequenceDiagram
   participant INTEG as Integration code
   participant DRV as UartDrv
   participant HW as UART HW

   INTEG->>DRV: Uart_StartRxTransaction(ch, buf, len, trg)
   activate DRV
   DRV->>HW: start reception (channel BUSY)
   DRV-->>INTEG: E_OK
   deactivate DRV

   HW->>DRV: Uart_Interrupt (data)
   activate DRV
   alt RX error
      DRV->>HW: stop reception (channel IDLE)
      DRV->>INTEG: LogM_Report(UART_RTERR_RX_*)
   else reached trigger or buffer full
      DRV->>INTEG: Uart_Callout_OnReception(ch, length)
      opt keep receiving
         INTEG->>DRV: Uart_StartRxTransaction(ch, nextBuf, len, trg)
      end
   end
   Note over DRV,HW: if no restart in the callout, the driver stops reception after it returns
   deactivate DRV

Key terms

For UART terms — streaming vs HW-completion, additional RX length trigger, hardware flow control — see the glossary in the appendix and the shared foundation in General.