1.26.4.22 DBGU_Read Function

C

/* Blocking and non-blocking mode */

bool DBGU_Read( void *buffer, const size_t size )

/* Ring buffer mode */

size_t DBGU_Read(uint8_t* buffer, const size_t size)

Summary

Blocking and non-blocking mode

Submits a read buffer to the given DBGU 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 DBGU_ErrorGet() API to check the error. The DBGU_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 DBGU 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 DBGU_ReadIsBusy function. The success of the operation can be obtained by calling the DBGU_ErrorGet function. If the DBGU_ErrorGet function returns no error, then this means that the requested number of bytes have been processed. If the function returns some error, the DBGU_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

DBGU_Initialize must have been called for the associated DBGU 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 DBGU_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 DBGU_ReadThresholdSet API).

Example

Blocking mode

uint8_t rxBuffer[100];

//The below call blocks until the requested bytes have been read
DBGU_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 DBGU_ReadIsBusy API or by registering a callback and getting notified.
DBGU_Read(rxBuffer, 100);

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

Ring buffer mode

uint8_t rxBuffer[100];
uint32_t nBytesRead = 0;

nBytesRead = DBGU_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