Detailed Description

This module covers the functionality of the Low Power Universal Asynchronous Receiver-Transmitter (LPUART) peripheral driver.

The LPUART driver implements serial communication using the LPUART module in the S32K1xx platforms.

Features

Functionality

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

Interrupt-based communication

After initialization, a serial communication can be triggered by calling LPUART_DRV_SendData() function; this will save the reference of the data buffer received as parameter in the internal tx buffer pointer, then copy the first byte to the data register. The transmitter then automatically shifts the data and triggers a 'Transmit buffer empty' interrupt when all bits are shifted. The drivers interrupt handler takes care of transmitting the next byte in the buffer, by increasing the data pointer and decreasing the data size. The same sequence of operations is executed until all bytes in the tx buffer have been transmitted.

Similarly, data reception is triggered by calling LPUART_DRV_ReceiveData() function, passing the rx buffer as parameter. When the receiver copies the received bits in the data register, the 'Receive buffer full' interrupt is triggered; the driver irq handler clears the flag by reading the received byte, saves it in the rx buffer, then increments the data pointer and decrements the data size. This is repeated until all bytes are received.

The workflow applies to send/receive operations using blocking method (triggered by LPUART_DRV_SendDataBlocking() and LPUART_DRV_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 occurred). The timeout for the blocking method is passed as parameter by the user.

DMA-based communication

In DMA operation, both blocking and non-blocking transmission methods configure a DMA channel to copy data from the buffer to the data register (for tx), or viceversa (for rx). The driver assumes the DMA channel is already allocated and the proper requests are routed to it via DMAMUX. 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.

Polling mode

The driver also provides polling methods for send and receive (LPUART_DRV_SendDataPolling() and LPUART_DRV_ReceiveDataPolling()). These functions are blocking (return only when the transfer is complete) and do not use interrupt or DMA services. The tx buffer empty and rx buffer full flags are polled by software in order to copy data to/from the data register.

Error handling

The driver treats the following errors on reception:

Callbacks

The driver provides callback notifications for asynchronous transfers. LPUART_DRV_InstallTxCallback() function can be used for installing a callback routine to be called when the transmission is finished. The tx callback is called twice: first when the tx buffer becomes empty (no more data to be transmitted) - at this point the application can call LPUART_DRV_SetTxBuffer() inside the callback in order to provide more data, resulting in a continuous transmission; if there is no more data to be transmitted, the callback is called again when the transmission is complete (all the bytes have been shifted out on the line). The event parameter in the callback signature differentiates these two calls - the values are UART_EVENT_TX_EMPTY and UART_EVENT_END_TRANSFER, respectively.
Similarly, LPUART_DRV_InstallRxCallback() installs a callback routine for reception. This callback is called twice (UART_EVENT_RX_FULL and UART_EVENT_END_TRANSFER); if a new buffer is provided within the first callback call (LPUART_DRV_SetRxBuffer()), the reception will continue without interruption. In case of an error detected during an ongoing reception, the transfer is aborted and the callback is called with UART_EVENT_ERROR parameter. The driver treats rx overrun, parity, framing and noise errors.

Important Notes

Data Structures

struct  lpuart_state_t
 Runtime state of the LPUART driver. More...
 
struct  lpuart_user_config_t
 LPUART configuration structure. More...
 

Enumerations

enum  lpuart_transfer_type_t { LPUART_USING_DMA = 0, LPUART_USING_INTERRUPTS }
 Type of LPUART transfer (based on interrupts or DMA). More...
 
enum  lpuart_bit_count_per_char_t { LPUART_8_BITS_PER_CHAR = 0x0U, LPUART_9_BITS_PER_CHAR = 0x1U, LPUART_10_BITS_PER_CHAR = 0x2U }
 LPUART number of bits in a character. More...
 
enum  lpuart_parity_mode_t { LPUART_PARITY_DISABLED = 0x0U, LPUART_PARITY_EVEN = 0x2U, LPUART_PARITY_ODD = 0x3U }
 LPUART parity mode. More...
 
enum  lpuart_stop_bit_count_t { LPUART_ONE_STOP_BIT = 0x0U, LPUART_TWO_STOP_BIT = 0x1U }
 LPUART number of stop bits. More...
 

LPUART Driver

status_t LPUART_DRV_Init (uint32_t instance, lpuart_state_t *lpuartStatePtr, const lpuart_user_config_t *lpuartUserConfig)
 Initializes an LPUART operation instance. More...
 
status_t LPUART_DRV_Deinit (uint32_t instance)
 Shuts down the LPUART by disabling interrupts and transmitter/receiver. More...
 
uart_callback_t LPUART_DRV_InstallRxCallback (uint32_t instance, uart_callback_t function, void *callbackParam)
 Installs callback function for the LPUART receive. More...
 
uart_callback_t LPUART_DRV_InstallTxCallback (uint32_t instance, uart_callback_t function, void *callbackParam)
 Installs callback function for the LPUART transmit. More...
 
status_t LPUART_DRV_SendDataBlocking (uint32_t instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout)
 Sends data out through the LPUART module using a blocking method. More...
 
void LPUART_DRV_SendDataPolling (uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
 Send out multiple bytes of data using polling method. More...
 
status_t LPUART_DRV_SendData (uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
 Sends data out through the LPUART module using a non-blocking method. This enables an a-sync method for transmitting data. When used with a non-blocking receive, the LPUART can perform a full duplex operation. Non-blocking means that the function returns immediately. The application has to get the transmit status to know when the transmit is complete. More...
 
status_t LPUART_DRV_GetTransmitStatus (uint32_t instance, uint32_t *bytesRemaining)
 Returns whether the previous transmit is complete. More...
 
status_t LPUART_DRV_AbortSendingData (uint32_t instance)
 Terminates a non-blocking transmission early. More...
 
status_t LPUART_DRV_ReceiveDataBlocking (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout)
 Gets data from the LPUART module by using a blocking method. Blocking means that the function does not return until the receive is complete. More...
 
status_t LPUART_DRV_ReceiveDataPolling (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
 Receive multiple bytes of data using polling method. More...
 
status_t LPUART_DRV_ReceiveData (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
 Gets data from the LPUART module by using a non-blocking method. This enables an a-sync method for receiving data. When used with a non-blocking transmission, the LPUART can perform a full duplex operation. Non-blocking means that the function returns immediately. The application has to get the receive status to know when the receive is complete. More...
 
status_t LPUART_DRV_GetReceiveStatus (uint32_t instance, uint32_t *bytesRemaining)
 Returns whether the previous receive is complete. More...
 
status_t LPUART_DRV_AbortReceivingData (uint32_t instance)
 Terminates a non-blocking receive early. More...
 
status_t LPUART_DRV_SetBaudRate (uint32_t instance, uint32_t desiredBaudRate)
 Configures the LPUART baud rate. More...
 
void LPUART_DRV_GetBaudRate (uint32_t instance, uint32_t *configuredBaudRate)
 Returns the LPUART baud rate. More...
 
status_t LPUART_DRV_SetTxBuffer (uint32_t instance, const uint8_t *txBuff, uint32_t txSize)
 Sets the internal driver reference to the tx buffer. More...
 
status_t LPUART_DRV_SetRxBuffer (uint32_t instance, uint8_t *rxBuff, uint32_t rxSize)
 Sets the internal driver reference to the rx buffer. More...
 

Enumeration Type Documentation

LPUART number of bits in a character.

Implements : lpuart_bit_count_per_char_t_Class

Enumerator
LPUART_8_BITS_PER_CHAR 

8-bit data characters

LPUART_9_BITS_PER_CHAR 

9-bit data characters

LPUART_10_BITS_PER_CHAR 

10-bit data characters

Definition at line 56 of file lpuart_driver.h.

LPUART parity mode.

Implements : lpuart_parity_mode_t_Class

Enumerator
LPUART_PARITY_DISABLED 

parity disabled

LPUART_PARITY_EVEN 

parity enabled, type even, bit setting: PE|PT = 10

LPUART_PARITY_ODD 

parity enabled, type odd, bit setting: PE|PT = 11

Definition at line 67 of file lpuart_driver.h.

LPUART number of stop bits.

Implements : lpuart_stop_bit_count_t_Class

Enumerator
LPUART_ONE_STOP_BIT 

one stop bit

LPUART_TWO_STOP_BIT 

two stop bits

Definition at line 78 of file lpuart_driver.h.

Type of LPUART transfer (based on interrupts or DMA).

Implements : lpuart_transfer_type_t_Class

Enumerator
LPUART_USING_DMA 

The driver will use DMA to perform UART transfer

LPUART_USING_INTERRUPTS 

The driver will use interrupts to perform UART transfer

Definition at line 46 of file lpuart_driver.h.

Function Documentation

status_t LPUART_DRV_AbortReceivingData ( uint32_t  instance)

Terminates a non-blocking receive early.

Parameters
instanceLPUART instance number
Returns
Whether the receiving was successful or not.

Definition at line 828 of file lpuart_driver.c.

status_t LPUART_DRV_AbortSendingData ( uint32_t  instance)

Terminates a non-blocking transmission early.

Parameters
instanceLPUART instance number
Returns
Whether the aborting is successful or not.

Definition at line 544 of file lpuart_driver.c.

status_t LPUART_DRV_Deinit ( uint32_t  instance)

Shuts down the LPUART by disabling interrupts and transmitter/receiver.

Parameters
instanceLPUART instance number
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if an error occurred

Definition at line 248 of file lpuart_driver.c.

void LPUART_DRV_GetBaudRate ( uint32_t  instance,
uint32_t *  configuredBaudRate 
)

Returns the LPUART baud rate.

This function returns the LPUART configured baud rate.

Parameters
instanceLPUART instance number.
[out]configuredBaudRateLPUART configured baud rate.

Definition at line 967 of file lpuart_driver.c.

status_t LPUART_DRV_GetReceiveStatus ( uint32_t  instance,
uint32_t *  bytesRemaining 
)

Returns whether the previous receive is complete.

Parameters
instanceLPUART instance 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 receive status.
Return values
STATUS_SUCCESSthe receive has completed successfully.
STATUS_BUSYthe receive is still in progress. bytesReceived will be filled with the number of bytes that have been received so far.
STATUS_UART_ABORTEDThe receive was aborted.
STATUS_TIMEOUTA timeout was reached.
STATUS_UART_RX_OVERRUN,STATUS_UART_FRAMING_ERROR,STATUS_UART_PARITY_ERROR,orSTATUS_UART_NOISE_ERROR An error occurred during reception.

Definition at line 783 of file lpuart_driver.c.

status_t LPUART_DRV_GetTransmitStatus ( uint32_t  instance,
uint32_t *  bytesRemaining 
)

Returns whether the previous transmit is complete.

Parameters
instanceLPUART instance number
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 498 of file lpuart_driver.c.

status_t LPUART_DRV_Init ( uint32_t  instance,
lpuart_state_t lpuartStatePtr,
const lpuart_user_config_t lpuartUserConfig 
)

Initializes an LPUART operation instance.

The caller provides memory for the driver state structures during initialization. The user must select the LPUART clock source in the application to initialize the LPUART.

Parameters
instanceLPUART instance number
lpuartUserConfiguser configuration structure of type lpuart_user_config_t
lpuartStatePtrpointer to the LPUART driver state structure
Returns
STATUS_SUCCESS if successful; STATUS_ERROR if an error occurred

Definition at line 158 of file lpuart_driver.c.

uart_callback_t LPUART_DRV_InstallRxCallback ( uint32_t  instance,
uart_callback_t  function,
void *  callbackParam 
)

Installs callback function for the LPUART receive.

Note
After a callback is installed, it bypasses part of the LPUART IRQHandler logic. Therefore, the callback needs to handle the indexes of txBuff and txSize.
Parameters
instanceThe LPUART instance number.
functionThe LPUART receive callback function.
rxBuffThe receive buffer used inside IRQHandler. This buffer must be kept as long as the callback is alive.
callbackParamThe LPUART receive callback parameter pointer.
Returns
Former LPUART receive callback function pointer.

Definition at line 289 of file lpuart_driver.c.

uart_callback_t LPUART_DRV_InstallTxCallback ( uint32_t  instance,
uart_callback_t  function,
void *  callbackParam 
)

Installs callback function for the LPUART transmit.

Note
After a callback is installed, it bypasses part of the LPUART IRQHandler logic. Therefore, the callback needs to handle the indexes of txBuff and txSize.
Parameters
instanceThe LPUART instance number.
functionThe LPUART transmit callback function.
txBuffThe transmit buffer used inside IRQHandler. This buffer must be kept as long as the callback is alive.
callbackParamThe LPUART transmit callback parameter pointer.
Returns
Former LPUART transmit callback function pointer.

Definition at line 312 of file lpuart_driver.c.

status_t LPUART_DRV_ReceiveData ( uint32_t  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Gets data from the LPUART module by using a non-blocking method. This enables an a-sync method for receiving data. When used with a non-blocking transmission, the LPUART can perform a full duplex operation. Non-blocking means that the function returns immediately. The application has to get the receive status to know when the receive is complete.

Parameters
instanceLPUART instance number
rxBuffbuffer containing 8-bit read data chars received
rxSizethe number of bytes to receive
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if a resource is busy; STATUS_ERROR if an error occurred

Definition at line 740 of file lpuart_driver.c.

status_t LPUART_DRV_ReceiveDataBlocking ( uint32_t  instance,
uint8_t *  rxBuff,
uint32_t  rxSize,
uint32_t  timeout 
)

Gets data from the LPUART module by using a blocking method. Blocking means that the function does not return until the receive is complete.

Parameters
instanceLPUART instance number
rxBuffbuffer containing 8-bit read data chars received
rxSizethe number of bytes to receive
timeouttimeout value in milliseconds
Returns
STATUS_SUCCESS if successful; STATUS_TIMEOUT if the timeout was reached; STATUS_BUSY if a resource is busy; STATUS_ERROR if an error occurred

Definition at line 582 of file lpuart_driver.c.

status_t LPUART_DRV_ReceiveDataPolling ( uint32_t  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Receive multiple bytes of data using polling method.

Parameters
instanceLPUART instance number.
rxBuffThe buffer pointer which saves the data to be received.
rxSizeSize of data need to be received in unit of byte.
Returns
STATUS_SUCCESS if the transaction is success or STATUS_UART_RX_OVERRUN if rx overrun.

Definition at line 648 of file lpuart_driver.c.

status_t LPUART_DRV_SendData ( uint32_t  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Sends data out through the LPUART module using a non-blocking method. This enables an a-sync method for transmitting data. When used with a non-blocking receive, the LPUART can perform a full duplex operation. Non-blocking means that the function returns immediately. The application has to get the transmit status to know when the transmit is complete.

Parameters
instanceLPUART instance number
txBuffsource buffer containing 8-bit data chars to send
txSizethe number of bytes to send
Returns
STATUS_SUCCESS if successful; STATUS_BUSY if a resource is busy; STATUS_ERROR if an error occurred

Definition at line 454 of file lpuart_driver.c.

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

Sends data out through the LPUART module using a blocking method.

Blocking means that the function does not return until the transmission is complete.

Parameters
instanceLPUART instance number
txBuffsource buffer containing 8-bit data chars to send
txSizethe number of bytes to send
timeouttimeout value in milliseconds
Returns
STATUS_SUCCESS if successful; STATUS_TIMEOUT if the timeout was reached; STATUS_BUSY if a resource is busy; STATUS_ERROR if an error occurred

Definition at line 335 of file lpuart_driver.c.

void LPUART_DRV_SendDataPolling ( uint32_t  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Send out multiple bytes of data using polling method.

Parameters
instanceLPUART instance number.
txBuffThe buffer pointer which saves the data to be sent.
txSizeSize of data to be sent in unit of byte.

Definition at line 402 of file lpuart_driver.c.

status_t LPUART_DRV_SetBaudRate ( uint32_t  instance,
uint32_t  desiredBaudRate 
)

Configures the LPUART baud rate.

This function configures the LPUART baud rate. In some LPUART instances the user must disable the transmitter/receiver before calling this function. Generally, this may be applied to all LPUARTs to ensure safe operation.

Parameters
instanceLPUART instance number.
desiredBaudRateLPUART desired baud rate.
Returns
STATUS_BUSY if called during an on-going transfer, STATUS_SUCCESS otherwise

Definition at line 868 of file lpuart_driver.c.

status_t LPUART_DRV_SetRxBuffer ( uint32_t  instance,
uint8_t *  rxBuff,
uint32_t  rxSize 
)

Sets the internal driver reference to the rx buffer.

This function can be called from the rx callback to provide the driver with a new buffer, for continuous reception.

Parameters
instanceLPUART instance number
rxBuffdestination buffer containing 8-bit data chars to receive
rxSizethe number of bytes to receive
Returns
STATUS_SUCCESS

Definition at line 1020 of file lpuart_driver.c.

status_t LPUART_DRV_SetTxBuffer ( uint32_t  instance,
const uint8_t *  txBuff,
uint32_t  txSize 
)

Sets the internal driver reference to the tx buffer.

This function can be called from the tx callback to provide the driver with a new buffer, for continuous transmission.

Parameters
instanceLPUART instance number
txBuffsource buffer containing 8-bit data chars to send
txSizethe number of bytes to send
Returns
STATUS_SUCCESS

Definition at line 996 of file lpuart_driver.c.