1.34.27.9 1.35.21.9 USARTx_Write Function

C

/* x = USART instance number */

/* Blocking and non-blocking mode */

bool USARTx_Write( void* buffer, const size_t size )

/* Ring buffer mode */

size_t USARTx_Write(uint8_t* buffer, const size_t size )

Summary

Submits a write buffer to the given USART peripheral to transfer

Description

Blocking mode

This function submits a write buffer to be transmitted by the USART peripheral. The API blocks until the requested bytes are transmitted out.

Non-blocking mode

This function submits a write buffer to be transmitted by the USART peripheral. A call to this function submits the buffer and the size to the peripheral library, initiates the transfer and returns immediately. The transfer then takes place from the peripheral interrupt. The transfer completion status can either be checked through the callback mechanism or by calling the USARTx_WriteIsBusy() function.

Ring buffer mode

This function submits a write buffer to the USART peripheral to transfer. The data to be transmitted is deep copied into the USART peripheral's transmit ring buffer. The size of this buffer is configurable in MHC. Since, the data is deep copied into the transmit buffer, it allows the use of local variables/buffers. This function call is always non-blocking. If notifications are enabled and a callback is registered, a callback is given when the threshold condition is met.

Precondition

USARTx_Initialize must have been called for the associated USART instance.

Parameters

Returns

Blocking mode

true -Specified number of bytes were transferred successfully or if the size requested is 0

false - Arguments are not valid

Non-blocking mode

true - Request was placed successfully (in interrupt mode) or if the specified number of bytes were transferred or if the size requested is 0

false - Arguments are not valid or if the peripheral is busy with another request.

Ring buffer mode

The API returns the number of bytes actually copied. Depending on the space available in the transmit buffer, the number of bytes copied may be less than or equal to the requested size. Application must retry by calling this API again if the return value is less than the number of bytes requested. Application can also use the USARTx_WriteFreeBufferCountGet API to determine the free space available in the transmit buffer before calling this API. Application can also choose to register for event notification to get notified when there is sufficient free space (using the USARTx_WriteThresholdSet API) in the transmit buffer.

Example

Blocking mode

char myData[] = {"hello"};

// This API blocks until the requested bytes are transmitted out
USART1_Write(&myData, sizeof(myData));
    

Non-blocking mode

char myData[] = {"hello"};

// The below API submits the request and returns immediately. Application can poll the status of the transfer either by calling the USARTx_WriteIsBusy API or can get notified by registering a callback.
USART1_Write(&myData, sizeof(myData));
    

Ring buffer mode

size_t nBytesCopied;
uint8_t txBuffer[50];
uint32_t nBytes;

// Check if there is any free space is available in the transmit buffer
if (USART1_WriteFreeBufferCountGet() > 0)
{
    nBytesCopied = USART1_Write((uint8_t*)txBuffer, nBytes);

    if (nBytesCopied != nBytes)
    {
        //The transmit buffer is full. Try after some time.
    }
}

Remarks

None