S32 SDK
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 S32K142S32K144S32K148S32V234MPC5748GMPC5746C
LPUART YES YES YES NO NO NO
FLEXIO_UART YES YES YES NO NO NO
LINFlexD_UART NO NO NO 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;
/* 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(INST_UART_PAL1, &uart_pal1_Config0);
/* Send 8 frames */
UART_SendData(INST_UART_PAL1, tx, 8U);
while(UART_GetTransmitStatus(INST_UART_PAL1, &bytesRemaining) != STATUS_SUCCESS);
/* Receive 8 frames */
UART_ReceiveData(INST_UART_PAL1, rx, 8UL);
/* Wait for transfer to be completed */
while(UART_GetReceiveStatus(INST_UART_PAL1, &bytesRemaining) != STATUS_SUCCESS);
/* De-initialize UART */
UART_Deinit(INST_UART_PAL1);

Data Structures

struct  uart_user_config_t
 

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 (uart_instance_t instance, uart_user_config_t *config)
 Initializes the UART module. More...
 
status_t UART_Deinit (uart_instance_t instance)
 De-initializes the UART module. More...
 
status_t UART_SetBaudRate (uart_instance_t instance, uint32_t desiredBaudRate)
 Configures the UART baud rate. More...
 
status_t UART_GetBaudRate (uart_instance_t instance, uint32_t *configuredBaudRate)
 Returns the UART baud rate. More...
 
status_t UART_SendDataBlocking (uart_instance_t instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
 Perform a blocking UART transmission. More...
 
status_t UART_SendData (uart_instance_t instance, const uint8_t *txBuff, uint32_t txSize)
 Perform a non-blocking UART transmission. More...
 
status_t UART_AbortSendingData (uart_instance_t instance)
 Terminates a non-blocking transmission early. More...
 
status_t UART_GetTransmitStatus (uart_instance_t instance, uint32_t *bytesRemaining)
 Get the status of the current non-blocking UART transmission. More...
 
status_t UART_ReceiveDataBlocking (uart_instance_t instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
 Perform a blocking UART reception. More...
 
status_t UART_ReceiveData (uart_instance_t instance, uint8_t *rxBuff, uint32_t rxSize)
 Perform a non-blocking UART reception. More...
 
status_t UART_AbortReceivingData (uart_instance_t instance)
 Terminates a non-blocking receive early. More...
 
status_t UART_GetReceiveStatus (uart_instance_t instance, uint32_t *bytesRemaining)
 Get the status of the current non-blocking UART reception. More...
 

Enumeration Type Documentation

Defines the number of bits in a character.

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 40 of file uart_pal.h.

Defines the parity mode.

Enumerator
UART_PARITY_DISABLED 

parity disabled

UART_PARITY_EVEN 

parity enabled, type even

UART_PARITY_ODD 

parity enabled, type odd

Definition at line 62 of file uart_pal.h.

Defines the number of stop bits.

Enumerator
UART_ONE_STOP_BIT 

one stop bit

UART_TWO_STOP_BIT 

two stop bits

Definition at line 72 of file uart_pal.h.

Defines the transfer type.

Enumerator
UART_USING_DMA 

Driver uses DMA for data transfers

UART_USING_INTERRUPTS 

Driver uses interrupts for data transfers

Definition at line 53 of file uart_pal.h.

Function Documentation

status_t UART_AbortReceivingData ( uart_instance_t  instance)

Terminates a non-blocking receive early.

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

Definition at line 758 of file uart_pal.c.

status_t UART_AbortSendingData ( uart_instance_t  instance)

Terminates a non-blocking transmission early.

Parameters
instanceInstance number
Returns
Whether the aborting is successful or not.

Definition at line 608 of file uart_pal.c.

status_t UART_Deinit ( uart_instance_t  instance)

De-initializes the UART module.

This function de-initializes the UART module.

Parameters
[in]instanceInstance number
Returns
Error or success status returned by API

Definition at line 386 of file uart_pal.c.

status_t UART_GetBaudRate ( uart_instance_t  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

This function returns the UART configured baud rate.

Parameters
instanceinstance number.
[out]configuredBaudRateconfigured baud rate.

Definition at line 492 of file uart_pal.c.

status_t UART_GetReceiveStatus ( uart_instance_t  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
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 793 of file uart_pal.c.

status_t UART_GetTransmitStatus ( uart_instance_t  instance,
uint32_t *  bytesRemaining 
)

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

Parameters
instanceInstance number
bytesRemainingPointer to value that is populated with the number of bytes that have been sent in the active transfer
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 643 of file uart_pal.c.

status_t UART_Init ( uart_instance_t  instance,
uart_user_config_t config 
)

Initializes the UART module.

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

Parameters
[in]instanceInstance number
[in]configThe configuration structure
Returns
Error or success status returned by API

Definition at line 144 of file uart_pal.c.

status_t UART_ReceiveData ( uart_instance_t  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]instanceInstance number
[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 721 of file uart_pal.c.

status_t UART_ReceiveDataBlocking ( uart_instance_t  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]instanceInstance number
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 679 of file uart_pal.c.

status_t UART_SendData ( uart_instance_t  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]instanceInstance number
[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 570 of file uart_pal.c.

status_t UART_SendDataBlocking ( uart_instance_t  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]instanceInstance number
[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 528 of file uart_pal.c.

status_t UART_SetBaudRate ( uart_instance_t  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
instanceInstance number.
desiredBaudRatedesired baud rate.
Returns
STATUS_SUCCESS

Definition at line 450 of file uart_pal.c.