Jump to main content

##

# 2.27.3 DBGU_Write Function

## C

    /* Blocking and non-blocking mode */

    bool DBGU_Write( void* buffer, const size_t size )

    /* Ring buffer mode */

    size_t DBGU_Write(uint8_t* buffer, const size_t size )

## Summary

Submits a write buffer to the given DBGU peripheral to transfer

## Description

Blocking mode

This function submits a write buffer to be transmitted by the DBGU 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 DBGU 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 DBGU_WriteIsBusy() function.

Ring buffer mode

This function submits a write buffer to the DBGU peripheral to transfer. The data to be transmitted is deep copied into the DBGU peripheral's transmit ring buffer. The size of this buffer is configurable in MCC. 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

DBGU_Initialize must have been called for the associated DBGU instance.

## Parameters

Param | Description
--- | ---
buffer | Pointer to the user buffer. This contains the data to betransferred.
size | Number of bytes to be transferred. If 9-bit mode is enabled, thenthe size is specified in terms of number of 9 bit data. For example, if 5 9-bit data are being transmitted, then the size must be specified as 5.

## 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 DBGU_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 DBGU_WriteThresholdSet API) in the transmit buffer.

## Example

Blocking mode

    char myData[] = {"hello"};

    // This API blocks until the requested bytes are transmitted out
    DBGU_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 DBGU_WriteIsBusy API or can get notified by registering a callback.
    DBGU_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 (DBGU_WriteFreeBufferCountGet() > 0)
    {
        nBytesCopied = DBGU_Write((uint8_t*)txBuffer, nBytes);

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

## Remarks

None