API Reference

Normative

The UART driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Function and type signatures are extracted from the driver headers with Doxygen/Breathe; only the interrupt handler is hand-framed, because its name is vendor-specific. Keywords per Requirement Keywords; behavioral rules in Uart — Requirements; error codes in Errors.

Data types at a glance

Type	Kind	Purpose
Uart_ConfigType	struct	Root configuration structure (build-time; `Uart_Init` takes `NULL_PTR`).
Uart_ChannelTxStateType	enum	TX channel state (UNINIT / IDLE / READY / BUSY).
Uart_ChannelRxStateType	enum	RX channel state (UNINIT / IDLE / BUSY).

API at a glance

Function	Group	Purpose
Uart_Init	Initialization and shutdown	Initialize the driver and every channel.
Uart_DeInit	Initialization and shutdown	Abort transfers and de-initialize the driver.
Uart_StartTxTransaction	Transmission	Start transmitting a buffer.
Uart_StartRxTransaction	Reception	Arm reception into a buffer, with an optional trigger.
Uart_CancelRxTransaction	Reception	Stop hardware reception.
Uart_SetAdditionalRxLenTrg	Reception	Re-arm the mid-transfer trigger (from the callout).
Uart_GetChannelTxState	Status and scheduling	Read a channel’s TX state.
Uart_GetChannelRxState	Status and scheduling	Read a channel’s RX state.
Uart_PollFunction	Status and scheduling	Service events for polled channels.
Uart_Interrupt	Status and scheduling	Driver interrupt service routine.

Callouts and expected interfaces at a glance

The functions the integrator MUST provide (CHI-UART-MUST-21); see the Callouts group below. UartDrv has no upper-layer interface stack, so it reports its events through callouts that the integrator implements in the generated Uart_Callout_Stubs.c (see The Callout Stub File).

Function	Kind	Purpose
Uart_Callout_OnReception	Callout	Reception reached the trigger length or filled the buffer.
Uart_Callout_OnTransmission	Callout	A transmission completed on the bus (HwCompletion).
Uart_Callout_OnStreamingDataRequest	Callout	The software TX buffer emptied (Streaming).
LogM_Report	Common	Reports development / runtime errors with a log level.
`<Mip>_EnterCriticalSection` / `<Mip>_ExitCriticalSection`	Common	Bracket sections requiring exclusive access — see critical sections.

Reception

Uart_StartRxTransaction

Std_ReturnType Uart_StartRxTransaction(uint8 channelId, uint8 *rxDataPtr, uint16 rxDataLength, uint16 additionalRxLenTrg)

Sets up the RX buffer to store the received data. If reception has not been started, this interface will start reception. This interface can be called only when reception is IDLE or during Uart_Callout_OnReception (i.e. reception is stopped or previous reception has been completed).

Sync/Async:

Asynchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelId)

Service ID [hex]:

0x03

Development error(s):

UART_DEVERR_PARAM_CHANNELID channelId is out of range from configured channels.
UART_DEVERR_PARAM_POINTER rxDataPtr is NULL_PTR
UART_DEVERR_PARAM_DATA_LENGTH rxDataLength == 0
UART_DEVERR_PARAM_DATA_LENGTH additionalRxLenTrg > rxDataLength
UART_DEVERR_UNINIT Called when the internal state is UART_CH_RX_STATE_UNINIT
UART_DEVERR_INVALID_CH_STATE Called when the internal state is NOT UART_CH_RX_STATE_IDLE

Parameters:

channelId – [in] ID of the UART channel to be addressed
rxDataPtr – [in] Buffer pointer to store the received data.
rxDataLength – [in] Specifies the buffer length. Must be > 0.
additionalRxLenTrg – [in] Specifies the receive data length for additional indication at the middle of reception. If additionalRxLenTrg > 0, Uart_Callout_OnReception will be called when the received data length reaches additionalRxLenTrg, in addition to when the receive buffer is full. If additionalRxLenTrg is 0, the additional indication won’t be notified. Must be <= rxDataLength.

Return values:

E_OK – Request has been accepted
E_NOT_OK – Development error detected

When to call: on an IDLE RX channel, or from within Uart_Callout_OnReception to hand over the next buffer (streaming). additionalRxLenTrg (≤ rxDataLength) requests a mid-transfer Uart_Callout_OnReception; 0 disables it. The caller MUST keep rxDataPtr valid until the callout. Errors: see Errors. Available via: Uart.h

Uart_CancelRxTransaction

Std_ReturnType Uart_CancelRxTransaction(uint8 channelId)

Cancel RX transaction. This interface is intended to be used for:

.

Stop HW RX operation The UartDrv does not stop HW RX operation once it’s started by Uart_StartRxTransaction for streaming usage. The UartDrv continues HW reception when the given RX buffer fulfilled and expects buffer switching by Uart_StartRxTransaction. To stop HW RX operation, need to call this interface.
Cancel RX transaction after interpreting 1st RX data RX transaction is separated into multiple chunks by additionalRxLenTrg and 1st chunk means command. Command reception is indicated by Uart_Callout_OnReception. Then upper layer interprets the command. If no more RX needs in the transaction, then call this interface to cancel the transaction.

Sync/Async:

Synchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelId)

Service ID [hex]:

0x04

Development error(s):

UART_DEVERR_PARAM_CHANNELID channelId is out of range from configured channelIds.
UART_DEVERR_UNINIT Called when the internal state is UART_CH_RX_STATE_UNINIT

Parameters:

channelId – [in] ID of the UART channel to be addressed

Return values:

E_OK – Request has been accepted. If no RX transaction is on-going to be canceled return E_OK.
E_NOT_OK – Development error detected

Effect: stops hardware reception and returns the RX channel to IDLE. Returns E_OK even when no reception is ongoing. Errors: see Errors. Available via: Uart.h

Uart_SetAdditionalRxLenTrg

void Uart_SetAdditionalRxLenTrg(uint8 channelId, uint16 additionalRxLenTrg)

Sets a trigger for additional calls of Uart_Callout_OnReception. This interface can be called only in Uart_Callout_OnReception.

Sync/Async:

Synchronous

Reentrancy:

Conditionally reentrant (reentrant when called with different channelId)

Service ID [hex]:

0x05

Development error(s):

UART_DEVERR_PARAM_CHANNELID channelId is out of range from configured channelIds.
UART_DEVERR_UNINIT Called when the internal state is UART_CH_RX_STATE_UNINIT

Parameters:

channelId – [in] ID of the UART channel to be addressed
additionalRxLenTrg – [in] Specifies the receive data length for additional indication at the middle of reception. If additionalRxLenTrg > 0, Uart_Callout_OnReception will be called when the received data length reaches additionalRxLenTrg, in addition to when the receive buffer is full. If additionalRxLenTrg is 0, the additional indication won’t be notified. Note that Uart_Callout_OnReception on RX buffer full will be called even if additionalRxLenTrg parameter is 0.

Returns:

None.

When to call: only from within Uart_Callout_OnReception, to re-arm the mid-transfer trigger. Errors: see Errors. Available via: Uart.h

Callouts the integrator provides

The driver calls these callouts; the integrator MUST provide them (CHI-UART-MUST-21) by filling in the matching user code block in Uart_Callout_Stubs.c (see The Callout Stub File). The prototypes are declared in Uart.h. LogM_Report and the critical-section services are documented in the general reference.

Uart_Callout_OnReception

void Uart_Callout_OnReception(uint8 channelId, uint16 length)

Notifies data length reaches additionalRxLenTrg or RX buffer fulfilled.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelId)

Parameters:

channelId – [in] ID of the UART channel which informs the event
length – [in] Total RX length in the current transaction

Returns:

None.

Reception reached additionalRxLenTrg or filled the buffer; length is the total received in the current transaction. Available via: Uart.h; implement it in Uart_Callout_Stubs.c

Uart_Callout_OnTransmission

void Uart_Callout_OnTransmission(uint8 channelId, uint16 length)

Notifies that the data transmission requested by Uart_StartTxTransaction has been completed. This interface is called when the UART HW has sent the whole data on the UART bus (i.e. HW FIFO and the shift register do not hold any data to be sent). This API can be used if the upper layer requires a confirmation once all data has been successfully transmitted on the bus.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelId)

Parameters:

channelId – [in] ID of the UART channel which informs the event
length – [in] Total TX length in the current transaction

Returns:

None.

HwCompletion channels: the whole buffer has been sent on the bus (FIFO and shift register empty). Available via: Uart.h; implement it in Uart_Callout_Stubs.c

Uart_Callout_OnStreamingDataRequest

void Uart_Callout_OnStreamingDataRequest(uint8 channelId, uint16 length)

Notifies that the SW TX buffer is empty and a new transaction can be initiated (The HW FIFO or the shift register can still hold data from the previous transaction request that is about to be sent). This API can be used to optimize the use of the UART controller in transmission mode for streaming purposes.

Sync/Async:: Synchronous
Reentrancy:: Conditionally reentrant (reentrant when called with different channelId)

Parameters:

channelId – [in] ID of the UART channel which informs the event
length – [in] Total TX length in the current transaction

Returns:

None.

Streaming channels: the software TX buffer is empty and a new transaction can be staged (the HW may still be draining). A channel uses this or Uart_Callout_OnTransmission, never both. Available via: Uart.h; implement it in Uart_Callout_Stubs.c