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.
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.
The following table contains the matching between platforms and available IPs
IP/MCU | S32K116 | S32K118 | S32K142 | S32K144 | S32K146 | S32K148 | S32V234 | MPC5748G | MPC5746C | MPC5744P |
---|---|---|---|---|---|---|---|---|---|---|
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 |
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 |
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:
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.
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.
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... | |
Defines the number of bits in a character.
Implements : uart_bit_count_per_char_t_Class
Definition at line 42 of file uart_pal.h.
enum uart_parity_mode_t |
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.
enum uart_transfer_type_t |
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.
status_t UART_AbortReceivingData | ( | const uart_instance_t *const | instance | ) |
Terminates a non-blocking receive early.
instance | Instance number |
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.
instance | The instance structure |
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.
[in] | instance | The instance structure |
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.
instance | Instance number. | |
[out] | configuredBaudRate | configured baud rate. |
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.
instance | Instance number |
bytesRemaining | Pointer to value that is filled with the number of bytes that still need to be received in the active transfer |
STATUS_SUCCESS | The transmit has completed successfully. |
STATUS_BUSY | The transmit is still in progress. bytesTransmitted will be filled with the number of bytes that have been transmitted so far. |
STATUS_UART_ABORTED | The transmit was aborted. |
STATUS_TIMEOUT | A timeout was reached. |
STATUS_ERROR | An 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.
instance | The instance structure |
bytesRemaining | Pointer to value that is populated with the number of bytes that have been sent in the active transfer |
STATUS_SUCCESS | The transmit has completed successfully. |
STATUS_BUSY | The transmit is still in progress. bytesTransmitted will be filled with the number of bytes that have been transmitted so far. |
STATUS_UART_ABORTED | The transmit was aborted. |
STATUS_TIMEOUT | A timeout was reached. |
STATUS_ERROR | An 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.
[in] | instance | The instance structure |
[in] | config | The configuration structure |
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).
[in] | instance | The instance structure |
[in] | rxBuff | pointer to the data to be transferred |
[in] | rxSize | length in bytes of the data to be transferred |
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.
[in] | instance | The instance structure |
rxBuff | pointer to the receive buffer | |
rxSize | length in bytes of the data to be received | |
timeout | timeout for the transfer in milliseconds |
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).
[in] | instance | The instance structure |
[in] | txBuffer | pointer to the data to be transferred |
[in] | txSize | length in bytes of the data to be transferred |
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.
[in] | instance | The instance structure |
[in] | txBuffer | pointer to the data to be transferred |
[in] | txSize | length in bytes of the data to be transferred |
[in] | timeout | timeout value in milliseconds |
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.
instance | The instance structure |
desiredBaudRate | desired baud rate. |
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.
instance | The instance structure. |
rxBuff | Pointer to buffer containing received data. |
rxSize | The number of bytes to receive. |
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.
instance | The instance structure. |
txBuff | Pointer to buffer containing transmitted data. |
txSize | The number of bytes to transmit. |
Definition at line 1057 of file uart_pal.c.