Uart — Requirements

Normative

Defines what a conformant UART driver MUST do. Keywords per Requirement Keywords; conformance per Conformance. Requirements do not carry individual status — the set-level status applies to all of them. Signatures, error codes, and configuration properties are in the API Reference, Errors, and Configuration Reference pages. Cross-module rules (types, error model, naming, memory mapping) are in General.

Mandatory (MUST) - 23 Requirements

The conformance contract — an implementation MUST satisfy every requirement here.

Scope and event handling

CHI-UART-MUST-01 — Basic UART protocol

The driver MUST support the basic UART protocol (asynchronous byte framing). LIN, multi-processor, and sub-modes such as Smart Card / IrDA are out of scope.

CHI-UART-MUST-02 — Event handling mode

For each channel, event handling MUST be statically configurable as interrupt or polling. In interrupt mode Uart_Interrupt MUST service events; in polling mode Uart_PollFunction MUST service them.

State machine

CHI-UART-MUST-03 — Driver state machine

After reset the driver MUST be in UART_DRV_STATE_UNINIT. Uart_Init MUST move it to UART_DRV_STATE_INIT; Uart_DeInit MUST return it to UART_DRV_STATE_UNINIT.

CHI-UART-MUST-04 — TX channel state machine

Each channel’s TX state MUST follow the TX state machine in Concepts: UNINIT → IDLE at init; IDLE → BUSY on Uart_StartTxTransaction; for a streaming channel BUSY → READY when the software buffer empties and READY → IDLE when the hardware finishes; for an HW-completion channel BUSY → IDLE when the hardware finishes; and BUSY → IDLE on a TX error.

CHI-UART-MUST-05 — RX channel state machine

Each channel’s RX state MUST follow the RX state machine: UNINIT → IDLE at init; IDLE → BUSY on Uart_StartRxTransaction; BUSY → IDLE on buffer-full, Uart_CancelRxTransaction, or an RX error.

Initialization and shutdown

CHI-UART-MUST-06 — Initialization

Uart_Init MUST initialize driver state and the hardware per the configuration, leaving every channel’s TX and RX state IDLE. configPtr MUST be NULL_PTR. The driver MUST NOT receive any frame before Uart_StartRxTransaction is called.

CHI-UART-MUST-07 — De-initialization

Uart_DeInit MUST immediately stop ongoing transmission and reception and de-initialize the hardware.

Transmission

CHI-UART-MUST-08 — Start a transmission

Uart_StartTxTransaction MUST start transmitting txDataLength bytes from txDataPtr on the channel, moving it to BUSY. It is non-blocking and MUST be accepted only when the channel is IDLE or (streaming) READY. The caller’s buffer MUST remain valid until the matching completion / streaming callout.

CHI-UART-MUST-09 — Transmit data transfer

While TX data remains, Uart_Interrupt / Uart_PollFunction MUST feed the remaining data to the hardware.

CHI-UART-MUST-10 — Transmission completion notification

For an HW-completion channel, when the whole buffer has been sent on the bus (FIFO and shift register empty) the driver MUST move the channel to IDLE and call Uart_Callout_OnTransmission with the transferred length.

CHI-UART-MUST-11 — Streaming data request notification

For a streaming channel, when the software TX buffer empties the driver MUST move the channel to READY and call Uart_Callout_OnStreamingDataRequest with the transferred length, allowing a new buffer to be staged while the hardware drains. A channel MUST use either Uart_Callout_OnTransmission or Uart_Callout_OnStreamingDataRequest, never both.

Reception

CHI-UART-MUST-12 — Start a reception

Uart_StartRxTransaction MUST arm reception into rxDataPtr (length rxDataLength), move the channel to BUSY, and retain additionalRxLenTrg. The caller’s buffer MUST remain valid until the matching Uart_Callout_OnReception.

CHI-UART-MUST-13 — Reception data transfer and notification

On RX events the driver MUST store received data into the buffer and call Uart_Callout_OnReception with the total received length when the length reaches additionalRxLenTrg (if > 0) and when the buffer becomes full. If both coincide (buffer length a multiple of the trigger) it MUST call Uart_Callout_OnReception only once.

CHI-UART-MUST-14 — Streaming reception continuation

The driver MUST NOT stop hardware reception merely because the buffer filled: it MUST allow Uart_StartRxTransaction to be called within Uart_Callout_OnReception to continue without losing bytes, and MUST stop hardware reception after the callout returns if no new reception was started.

CHI-UART-MUST-15 — Additional RX length trigger

Uart_SetAdditionalRxLenTrg MUST update the retained additionalRxLenTrg for the channel. It is intended to be called from within Uart_Callout_OnReception.

CHI-UART-MUST-16 — Cancel a reception

Uart_CancelRxTransaction MUST stop hardware reception and return the RX channel to IDLE, returning E_OK even when no reception is ongoing.

Errors, status, and scheduling

CHI-UART-MUST-17 — RX error handling

On an RX error the driver MUST stop reception, return the channel to IDLE, and report it via LogM_Report at runtime-error level with UART_RTERR_RX / UART_RTERR_RX_<VENDOR_SPECIFIC> (a HW buffer overflow as UART_RTERR_RX_OVERFLOW) (CHI-GEN-MUST-10).

CHI-UART-MUST-18 — Poll function

Uart_PollFunction MUST provide the same event handling as Uart_Interrupt by polling the hardware, for channels configured for polling.

CHI-UART-MUST-19 — Channel state query

Uart_GetChannelTxState and Uart_GetChannelRxState MUST return the current TX and RX state of the requested channel.

CHI-UART-MUST-20 — Development error detection

When development error reporting is enabled, each API MUST detect the conditions listed in Errors and report them via LogM_Report (CHI-GEN-MUST-10).

Types, callouts, and configuration

CHI-UART-MUST-21 — Callout notifications

The driver MUST call Uart_Callout_OnReception, Uart_Callout_OnTransmission, and Uart_Callout_OnStreamingDataRequest with the parameters and at the points defined in API Reference.

CHI-UART-MUST-22 — Public types and error identifiers

The driver MUST provide Uart_ConfigType, Uart_ChannelTxStateType, Uart_ChannelRxStateType, and the development and runtime error identifiers as defined in API Reference and Errors, and MUST use the shared type system from General (CHI-GEN-MUST-09).

CHI-UART-MUST-23 — Configuration model

The driver MUST support the configuration model in Configuration Reference — a General section and a ConfigSet with a channel list (frame format, bitrate, event-handling mode, and transmission_callback_type) — following the common model in General (CHI-GEN-MUST-12).