1.10.23.24 UARTx_Read Function

C

/* x = UART instance number */

/* Blocking and non-blocking mode */

bool UARTx_Read( void *buffer, const size_t size )

/* Ring buffer mode */

size_t UARTx_Read(uint8_t* buffer, const size_t size)

Summary

Blocking and non-blocking mode

Submits a read buffer to the given UART peripheral to process

Ring buffer mode

Read the requested data from the receive buffer into the application buffer

Description

Blocking mode

In blocking mode, the API blocks until the requested number of bytes have been received. The return value is true if the requested number of bytes have been read successfully. If not, call the UARTx_ErrorGet() API to check the error. The UARTx_ReadCountGet function can be called to know the number of bytes that were received till the error occurred.

Non-blocking mode

This function submits a read buffer to the UART peripheral to process. A call to this function submits the buffer and the size to the peripheral library and returns immediately. The transfer completion status can either be checked through the callback mechanism or by calling the UARTx_ReadIsBusy function. The success of the operation can be obtained by calling the UARTx_ErrorGet function. If the UARTx_ErrorGet function returns no error, then this means that the requested number of bytes have been processed. If the function returns some error, the UARTx_ReadCountGet function can be called to know the number of bytes that were received till the error occurred.

Ring buffer mode

The API copies the number of bytes available in the receive buffer and returns the number of bytes actually copied. If the number of bytes copied is less than the requested size, the application must try reading after some time. If notifications are enabled and a callback is registered, a callback is given when the receive threshold condition is met. This lets the application to get notified when the data is available in the receive buffer.

Precondition

UARTx_Initialize must have been called for the associated UART instance.

Parameters

Returns

Blocking and non-blocking mode

true - if the Read transaction is successful or if the requested size is 0.

false - if the arguments are not valid or if the device is busy or if an error occurred while receiving data.

Ring buffer mode

The API returns the number of bytes actually read into the user buffer. Application must retry by calling this API again if the return value is less than the number of bytes requested. Application can use the UARTx_ReadCountGet API to determine the number of unread bytes available in the receive buffer. Application can also choose to register for event notification to get notified when data is available in the receive buffer (set by the UARTx_ReadThresholdSet API). If 9-bit mode is enabled, then the return value indicates the number of 9-bit data copied to the application buffer.

Example

Blocking mode

uint8_t rxBuffer[100];

//The below call blocks until the requested bytes have been read
UART1_Read(rxBuffer, 100);
    

Non-blocking mode

uint8_t rxBuffer[100];

//The below call submits the request and returns immediately. Transfer status can be checked either by calling the UARTx_ReadIsBusy API or by registering a callback and getting notified.
UART1_Read(rxBuffer, 100);

if (UART1_ReadIsBusy() == false)
{
	// Transfer has completed.
}
    

Ring buffer mode

uint8_t rxBuffer[100];
uint32_t nBytesRead = 0;

nBytesRead = UART1_Read((uint8_t*)rxBuffer, 100);
if (nBytesRead < 100)
{
    // Receive buffer does not have more data, try after some time
    // Application can even enable notification to get notified when the
    // data becomes available in the receive buffer
}

Remarks

None