Design Decisions

Informative

The rationale behind the UART driver contract. This helps implementers get the behavior right; it is not itself a requirement. Each entry points to the requirement it explains.

Why does UartDrv have no UartIf interface layer?

Relates to CHI-GEN-MUST-15, CHI-GEN-MUST-16.

There is no standardized interface stack above a UART driver the way CanIf sits above a CAN driver, so a UartIf layer would have had no implementation and no owner. UartDrv therefore declares its completion, streaming and reception notifications as callouts in Uart.h, which the integrator implements in the generated Uart_Callout_Stubs.c. The full reasoning, and why Can / Lin / Mem / Wdg keep their interface layer, is in Design Decisions.

Implication for implementers: publish the specification’s types in Uart_DriverTypes.h and the callout prototypes in Uart.h; do not ship a UartIf.h.

Why two transmission-notification styles (HwCompletion vs Streaming)?

Governs CHI-UART-MUST-10, CHI-UART-MUST-11.

Two use cases pull in opposite directions. Some components need a true “the bytes are on the wire” confirmation (e.g. before switching a transceiver direction) — that is Uart_Callout_OnTransmission, fired when the hardware is fully drained. Others stream continuously and want to refill the moment the software buffer is free, without waiting for the FIFO to empty — that is Uart_Callout_OnStreamingDataRequest, fired earlier so the next buffer can be queued and the bus stays saturated. Supporting both, but fixing one per channel by configuration, keeps each notification’s meaning unambiguous and the driver’s TX path simple.

Implication for implementers: pick the callout from transmission_callback_type and never fire both for one channel; make Uart_Callout_OnTransmission mean bus-idle and Uart_Callout_OnStreamingDataRequest mean SW-buffer-empty.

Why doesn’t reception stop when the buffer fills?

Governs CHI-UART-MUST-13, CHI-UART-MUST-14.

If the driver stopped the hardware the instant a buffer filled, bytes arriving during Uart_Callout_OnReception would be lost — fatal for back-to-back streaming. Instead the hardware keeps receiving in the background, and the integration code hands over the next buffer from within the callout. Only if it does not is reception stopped (after the callout returns). This makes gap-free reception the default and an explicit stop (Uart_CancelRxTransaction) the deliberate exception.

Implication for implementers: keep the hardware receiving across Uart_Callout_OnReception; stop only if no Uart_StartRxTransaction was issued in the callout, or on Uart_CancelRxTransaction.

Why a mid-transfer trigger (additionalRxLenTrg)?

Relates to CHI-UART-MUST-13, CHI-UART-MUST-15.

Message protocols often begin with a fixed-size header that announces the payload length. Notifying at a caller-chosen length (not only on buffer-full) lets the integration code read the header, learn the remaining size, and re-arm the trigger — all within one reception, without over-sizing the buffer or polling. Allowing Uart_SetAdditionalRxLenTrg inside the callout makes that header-then-body flow natural.

Implication for implementers: count from the previous trigger point; when trigger and buffer-full coincide, notify once; honour a re-armed trigger for the remainder.

Why no LIN / multi-processor / sub-modes?

Relates to CHI-UART-MUST-01.

These modes carry substantial, device-specific state machines that most small-MCU UART usage never needs, and LIN in particular is a separate driver in this HAL. Restricting the UART driver to the basic asynchronous protocol keeps it small and portable; a system that needs more layers a dedicated driver or protocol handler on top.

Implication for implementers: implement basic UART only; leave higher protocols to the upper layer.

Why does Uart_Init take only NULL_PTR?

Relates to CHI-UART-MUST-06.

Configuration variants are selected at build time, not passed at runtime. Requiring configPtr == NULL_PTR keeps the interface stable and avoids implying a runtime variant-selection mechanism the driver does not provide.

Implication for implementers: bind the active configuration at build time; reject a non-null configPtr as a development error.