![]() |
S32 SDK
|
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 | S32K142 | S32K144 | S32K148 | S32V234 | MPC5748G | MPC5746C |
---|---|---|---|---|---|---|
LPUART | YES | YES | YES | NO | NO | NO |
FLEXIO_UART | YES | YES | YES | NO | NO | NO |
LINFlexD_UART | NO | NO | NO | 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 |
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... | |
Defines the number of bits in a character.
Definition at line 40 of file uart_pal.h.
enum uart_parity_mode_t |
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.
enum uart_transfer_type_t |
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.
status_t UART_AbortReceivingData | ( | uart_instance_t | instance | ) |
Terminates a non-blocking receive early.
instance | Instance number |
Definition at line 758 of file uart_pal.c.
status_t UART_AbortSendingData | ( | uart_instance_t | instance | ) |
Terminates a non-blocking transmission early.
instance | Instance number |
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.
[in] | instance | Instance number |
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.
instance | Instance number. | |
[out] | configuredBaudRate | configured baud rate. |
This function returns the UART configured baud rate.
instance | instance number. | |
[out] | configuredBaudRate | configured 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.
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 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.
instance | Instance number |
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 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.
[in] | instance | Instance number |
[in] | config | The configuration structure |
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).
[in] | instance | Instance number |
[in] | rxBuff | pointer to the data to be transferred |
[in] | rxSize | length in bytes of the data to be transferred |
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.
[in] | instance | Instance number |
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 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).
[in] | instance | Instance number |
[in] | txBuffer | pointer to the data to be transferred |
[in] | txSize | length in bytes of the data to be transferred |
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.
[in] | instance | Instance number |
[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 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.
instance | Instance number. |
desiredBaudRate | desired baud rate. |
Definition at line 450 of file uart_pal.c.