Universal Asynchronous Receiver/Transmitter - Peripheral Abstraction Layer (UART PAL)

Detailed Description

The S32 SDK provides a Peripheral Abstraction Layer for Universal Asynchronous Receiver-Transmitter (UART) modules of S32 SDK devices.

The UART PAL driver allows communication over a serial port. It was designed to be portable across all platforms and IPs which support UART communication.

How to integrate UART PAL in your application

Unlike the other drivers, UART PAL modules need to include a configuration file named uart_pal_cfg.h, which allows the user to specify which IPSs are used and how many resources are allocated for each of them (state structures). The following code example shows how to configure one instance for each available UART IPs.

#ifndef uart_pal_cfg_H
#define uart_pal_cfg_H
/* Define which IP instance will be used in current project */
#define UART_OVER_LPUART
#define UART_OVER_FLEXIO
#define UART_OVER_LINFLEXD
/* Define the resources necessary for current project */
#define NO_OF_LPUART_INSTS_FOR_UART 1U
#define NO_OF_FLEXIO_INSTS_FOR_UART 1U
#define NO_OF_LINFLEXD_INSTS_FOR_UART 1U
#endif /* uart_pal_cfg_H */

The following table contains the matching between platforms and available IPs

IP/MCU S32K116S32K118S32K142S32K144S32K146S32K148S32V234MPC5748GMPC5746CMPC5744P
LPUART YES YES YES YES YES YES NO NO NO NO
FLEXIO_UART YES YES YES YES YES YES NO NO NO NO
LINFlexD_UART NO NO NO NO NO NO YES YES YES YES

Features

The following table contains the matching between IPs and available features

IP/FEATURE Bits per char Parity Stop Bits
LPUART 8, 9, 10 Disabled, Even, Odd 1, 2
FLEXIO_UART 7, 8, 9, 10, 15, 16 Disabled 1
LINFlexD_UART 7, 8, 15, 16 Disabled, Even, Odd 1, 2

Functionality

Initialization

In order to use the UART PAL driver it must be first initialized, using UART_Init() function. Once initialized, it cannot be initialized again for the same UART module instance until it is de-initialized, using UART_Deinit(). The initialization function does the following operations:

Interrupt-based communication

After initialization, a serial communication can be triggered by calling UART_SendData function. The driver interrupt handler takes care of transmitting all bytes in the TX buffer. Similarly, data reception is triggered by calling UART_ReceiveData function, passing the RX buffer as parameter. The driver interrupt handler reads the received byte and saves them in the RX buffer. Non-blocking operations will initiate the transfer and return STATUS_SUCCESS, but the module is still busy with the transfer and another transfer can't be initiated until the current transfer is complete. The application can check the status of the current transfer by calling UART_GetTransmitStatus() / UART_GetReceiveStatus().

The workflow applies to send/receive operations using blocking method (triggered by UART_SendDataBlocking() and UART_ReceiveDataBlocking()), with the single difference that the send/receive function will not return until the send/receive operation is complete (all bytes are successfully transferred or a timeout occured). The timeout for the blocking method is passed as parameter by the user.

When configured to use the LPUART or LINFlexD peripherals, if a user callback is installed for RX/TX, the callback has to take care of data handling and aborting the transfer when complete; the driver interrupt handler does not manipulate the buffers in this case. When using the UART PAL over FLEXIO, when the driver completes the transmission or reception of the current buffer, it will invoke the user callback (if installed) with an appropriate event.

DMA-based communication

In DMA operation, both blocking and non-blocking transmission methods confiure a DMA channel to copy data to/from the buffer. The driver assumes the DMA channel is already allocated. In case of LPUART and LINFlexD, the application also assumes that the proper requests are routed to it via DMAMUX. The FLEXIO driver will set the DMA request source. After configuring the DMA channel, the driver enables DMA requests for RX/TX, then the DMA engine takes care of moving data to/from the data buffer. In this scenario, the callback is only called when the full transmission is done, that is when the DMA channel finishes the number of loops configured in the transfer descriptor.

Important Notes

Example code

uint32_t bytesRemaining;
/* Instance information structure */
uart_instance_t uart_pal1_instance = {
.instIdx = 0U
};
/* Configure UART */
uart_user_config_t uart_pal1_Config0 = {
.baudRate = 600U,
.bitCount = UART_7_BITS_PER_CHAR,
.parityMode = UART_PARITY_DISABLED,
.stopBitCount = UART_ONE_STOP_BIT,
.transferType = UART_USING_INTERRUPTS,
.rxDMAChannel = 0U,
.txDMAChannel = 0U,
.rxCallback = NULL,
.rxCallbackParam = NULL,
.txCallback = NULL,
.txCallbackParam = NULL,
.extension = NULL
};
/* Configure FLEXIO pins routing */
extension_flexio_for_uart_t extension = {
.dataPinTx = 0U,
.dataPinRx = 1U,
};
uart_pal1_Config0.extension = &extension;
/* Buffers */
uint8_t tx[8] = {0, 1, 2, 3, 4, 5, 6, 7};
uint8_t rx[8];
/* Initialize UART */
UART_Init(&uart_pal1_instance, &uart_pal1_Config0);
/* Send 8 frames */
UART_SendData(&uart_pal1_instance, tx, 8U);
while(UART_GetTransmitStatus(&uart_pal1_instance, &bytesRemaining) != STATUS_SUCCESS);
/* Receive 8 frames */
UART_ReceiveData(&uart_pal1_instance, rx, 8UL);
/* Wait for transfer to be completed */
while(UART_GetReceiveStatus(&uart_pal1_instance, &bytesRemaining) != STATUS_SUCCESS);
/* De-initialize UART */
UART_Deinit(&uart_pal1_instance);

Data Structures

struct  uart_user_config_t
 Defines the UART configuration structure. More...
 

Enumerations

enum  uart_bit_count_per_char_t {
  UART_7_BITS_PER_CHAR = 0x0U, UART_8_BITS_PER_CHAR = 0x1U, UART_9_BITS_PER_CHAR = 0x2U, UART_10_BITS_PER_CHAR = 0x3U,
  UART_15_BITS_PER_CHAR = 0x4U, UART_16_BITS_PER_CHAR = 0x5U
}
 Defines the number of bits in a character. More...
 
enum  uart_transfer_type_t { UART_USING_DMA = 0U, UART_USING_INTERRUPTS = 1U }
 Defines the transfer type. More...
 
enum  uart_parity_mode_t { UART_PARITY_DISABLED = 0x0U, UART_PARITY_EVEN = 0x2U, UART_PARITY_ODD = 0x3U }
 Defines the parity mode. More...
 
enum  uart_stop_bit_count_t { UART_ONE_STOP_BIT = 0x0U, UART_TWO_STOP_BIT = 0x1U }
 Defines the number of stop bits. More...
 

Functions

status_t UART_Init (const uart_instance_t *const instance, const uart_user_config_t *config)
 Initializes the UART module. More...
 
status_t UART_Deinit (const uart_instance_t *const instance)
 De-initializes the UART module. More...
 
status_t UART_SetBaudRate (const uart_instance_t *const instance, uint32_t desiredBaudRate)
 Configures the UART baud rate. More...
 
status_t UART_GetBaudRate (const uart_instance_t *const instance, uint32_t *configuredBaudRate)
 Returns the UART baud rate. More...
 
status_t UART_SendDataBlocking (const uart_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
 Perform a blocking UART transmission. More...
 
status_t UART_SendData (const uart_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize)
 Perform a non-blocking UART transmission. More...
 
status_t UART_AbortSendingData (const uart_instance_t *const instance)
 Terminates a non-blocking transmission early. More...
 
status_t UART_GetTransmitStatus (const uart_instance_t *const instance, uint32_t *bytesRemaining)
 Get the status of the current non-blocking UART transmission. More...
 
status_t UART_ReceiveDataBlocking (const uart_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
 Perform a blocking UART reception. More...
 
status_t UART_ReceiveData (const uart_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize)
 Perform a non-blocking UART reception. More...
 
status_t UART_AbortReceivingData (const uart_instance_t *const instance)
 Terminates a non-blocking receive early. More...
 
status_t UART_GetReceiveStatus (const uart_instance_t *const instance, uint32_t *bytesRemaining)
 Get the status of the current non-blocking UART reception. More...
 
status_t UART_SetRxBuffer (const uart_instance_t *const instance, uint8_t *rxBuff, uint32_t rxSize)
 Provide a buffer for receiving data. More...
 
status_t UART_SetTxBuffer (const uart_instance_t *const instance, const uint8_t *txBuff, uint32_t txSize)
 Provide a buffer for transmitting data. More...
 

Enumeration Type Documentation

Defines the number of bits in a character.

Implements : uart_bit_count_per_char_t_Class

Enumerator
UART_7_BITS_PER_CHAR 

7-bit data characters

UART_8_BITS_PER_CHAR 

8-bit data characters

UART_9_BITS_PER_CHAR 

9-bit data characters

UART_10_BITS_PER_CHAR 

10-bit data characters

UART_15_BITS_PER_CHAR 

15-bit data characters

UART_16_BITS_PER_CHAR 

16-bit data characters

Definition at line 42 of file uart_pal.h.

Defines the parity mode.

Implements : uart_parity_mode_t_Class

Enumerator
UART_PARITY_DISABLED 

parity disabled

UART_PARITY_EVEN 

parity enabled, type even

UART_PARITY_ODD 

parity enabled, type odd

Definition at line 68 of file uart_pal.h.

Defines the number of stop bits.

Implements : uart_stop_bit_count_t_Class

Enumerator
UART_ONE_STOP_BIT 

one stop bit

UART_TWO_STOP_BIT 

two stop bits

Definition at line 80 of file uart_pal.h.

Defines the transfer type.

Implements : uart_transfer_type_t_Class

Enumerator
UART_USING_DMA 

Driver uses DMA for data transfers

UART_USING_INTERRUPTS 

Driver uses interrupts for data transfers

Definition at line 57 of file uart_pal.h.

Function Documentation

status_t UART_AbortReceivingData ( const uart_instance_t *const  instance)

Terminates a non-blocking receive early.

Parameters
instanceInstance number
Returns
Whether the receiving was successful or not.

Definition at line 924 of file uart_pal.c.

status_t UART_AbortSendingData ( const uart_instance_t *const  instance)

Terminates a non-blocking transmission early.

Parameters
instanceThe instance structure
Returns
Whether the aborting is successful or not.

Definition at line 738 of file uart_pal.c.

status_t UART_Deinit ( const uart_instance_t *const  instance)

De-initializes the UART module.

This function de-initializes the UART module.

Parameters
[in]instanceThe instance structure
Returns
Error or success status returned by API

Definition at line 463 of file uart_pal.c.

status_t UART_GetBaudRate ( const uart_instance_t *const  instance,
uint32_t *  configuredBaudRate 
)

Returns the UART baud rate.

This function returns the UART configured baud rate.

Parameters
instanceInstance number.
[out]configuredBaudRateconfigured baud rate.
Returns
STATUS_SUCCESS

Definition at line 593 of file uart_pal.c.

status_t UART_GetReceiveStatus ( const uart_instance_t *const  instance,
uint32_t *  bytesRemaining 
)

Get the status of the current non-blocking UART reception.

Parameters
instanceInstance number
bytesRemainingPointer to value that is filled with the number of bytes that still need to be received in the active transfer
Note
In DMA mode, this parameter may not be accurate, in case the transfer completes right after calling this function; in this edge-case, the parameter will reflect the initial transfer size, due to automatic reloading of the major loop count in the DMA transfer descriptor.
Returns
The transmit status.
Return values
STATUS_SUCCESSThe transmit has completed successfully.
STATUS_BUSYThe transmit is still in progress. bytesTransmitted will be filled with the number of bytes that have been transmitted so far.
STATUS_UART_ABORTEDThe transmit was aborted.
STATUS_TIMEOUTA timeout was reached.
STATUS_ERRORAn error occurred.

Definition at line 968 of file uart_pal.c.

status_t UART_GetTransmitStatus ( const uart_instance_t *const  instance,
uint32_t *  bytesRemaining 
)

Get the status of the current non-blocking UART transmission.

Parameters
instanceThe instance structure
bytesRemainingPointer to value that is populated with the number of bytes that have been sent in the active transfer
Note
In DMA mode, this parameter may not be accurate, in case the transfer completes right after calling this function; in this edge-case, the parameter will reflect the initial transfer size, due to automatic reloading of the major loop count in the DMA transfer descriptor.
Returns
The transmit status.
Return values
STATUS_SUCCESSThe transmit has completed successfully.
STATUS_BUSYThe transmit is still in progress. bytesTransmitted will be filled with the number of bytes that have been transmitted so far.
STATUS_UART_ABORTEDThe transmit was aborted.
STATUS_TIMEOUTA timeout was reached.
STATUS_ERRORAn error occurred.

Definition at line 782 of file uart_pal.c.

status_t UART_Init ( const uart_instance_t *const  instance,
const uart_user_config_t config 
)

Initializes the UART module.

This function initializes and enables the requested UART module, configuring the bus parameters.

Parameters
[in]instanceThe instance structure
[in]configThe configuration structure
Returns
Error or success status returned by API

Definition at line 208 of file uart_pal.c.

status_t UART_ReceiveData ( const uart_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Perform a non-blocking UART reception.

This function receives a block of data and returns immediately. The rest of the transmission is handled by the interrupt service routine (if the driver is initialized in interrupt mode).

Parameters
[in]instanceThe instance structure
[in]rxBuffpointer to the data to be transferred
[in]rxSizelength in bytes of the data to be transferred
Returns
Error or success status returned by API

Definition at line 878 of file uart_pal.c.

status_t UART_ReceiveDataBlocking ( const uart_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize,
uint32_t  timeout 
)

Perform a blocking UART reception.

This function receives a block of data and only returns when the transmission is complete.

Parameters
[in]instanceThe instance structure
rxBuffpointer to the receive buffer
rxSizelength in bytes of the data to be received
timeouttimeout for the transfer in milliseconds
Returns
Error or success status returned by API

Definition at line 827 of file uart_pal.c.

status_t UART_SendData ( const uart_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Perform a non-blocking UART transmission.

This function sends a block of data and returns immediately. The rest of the transmission is handled by the interrupt service routine (if the driver is initialized in interrupt mode).

Parameters
[in]instanceThe instance structure
[in]txBufferpointer to the data to be transferred
[in]txSizelength in bytes of the data to be transferred
Returns
Error or success status returned by API

Definition at line 691 of file uart_pal.c.

status_t UART_SendDataBlocking ( const uart_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize,
uint32_t  timeout 
)

Perform a blocking UART transmission.

This function sends a block of data and only returns when the transmission is complete.

Parameters
[in]instanceThe instance structure
[in]txBufferpointer to the data to be transferred
[in]txSizelength in bytes of the data to be transferred
[in]timeouttimeout value in milliseconds
Returns
Error or success status returned by API

Definition at line 638 of file uart_pal.c.

status_t UART_SetBaudRate ( const uart_instance_t *const  instance,
uint32_t  desiredBaudRate 
)

Configures the UART baud rate.

This function configures the UART baud rate. Note that due to module limitation not any baud rate can be achieved. The driver will set a baud rate as close as possible to the requested baud rate, but there may still be substantial differences. The application should call UART_GetBaudRate() after UART_SetBaudRate() to check what baud rate was actually set.

Parameters
instanceThe instance structure
desiredBaudRatedesired baud rate.
Returns
STATUS_SUCCESS

Definition at line 540 of file uart_pal.c.

status_t UART_SetRxBuffer ( const uart_instance_t *const  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Provide a buffer for receiving data.

The function can be used to provide a new buffer for receiving data to the driver. Beside, It can be called from rx callback to provide a new buffer for continuous reception.

Parameters
instanceThe instance structure.
rxBuffPointer to buffer containing received data.
rxSizeThe number of bytes to receive.
Returns
Executed status. STATUS_ERROR Wrong instance STATUS_SUCCESS Provide completed.

Definition at line 1013 of file uart_pal.c.

status_t UART_SetTxBuffer ( const uart_instance_t *const  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Provide a buffer for transmitting data.

The function can be used to provide a new buffer for transmitting data to the driver. Beside, It can be called from tx callback to provide a new buffer for continuous transmission.

Parameters
instanceThe instance structure.
txBuffPointer to buffer containing transmitted data.
txSizeThe number of bytes to transmit.
Returns
Executed status. STATUS_ERROR Wrong instance STATUS_SUCCESS Provide completed.

Definition at line 1057 of file uart_pal.c.