UART (Universal Asynchronous Receiver-Transmitter)

General Description

High level interface for interacting with the Universal Asynchronous Receiver-Transmitter (UART).

The Universal Asynchronous Receiver/Transmitter (UART) protocol is an asynchronous serial interface protocol. UART communication is typically point-to-point. The UART interface consists of two signals:

• TX: Transmitter output
• RX: Receiver input

Additionally, two side-band signals are used to implement flow control in UART. Note that the flow control applies only to TX functionality.

• Clear to Send (CTS): This is an input signal to the transmitter. When active, it indicates that the slave is ready for the master to transmit data.
• Ready to Send (RTS): This is an output signal from the receiver. When active, it indicates that the receiver is ready to receive data

Flow control can be configured by providing cts / rts pins in the device configurator or through manually generated structures.In case CTS flow control enablement status needs to be changed, mtb_hal_uart_enable_cts_flow_control function can be used.

Note

RTS flow control line is deasserted by the receiver when the number of bytes in the receiver RX FIFO reaches configured RTS RX FIFO level. RX FIFO on the receiver side could end up having an extra byte depending on if the transmitter has begun the transmission of the next byte when the RTS flow control line is deasserted by the receiver.

The UART contains dedicated hardware buffers for transmit and receive. Optionally, either of these can be augmented with a software buffer. This can be done using the PDL functions

Note

For applications that require printing messages on a UART terminal using printf(), the retarget-io utility library can be used directly.

Features

• Configurable UART baud rate - mtb_hal_uart_set_baud*
• Configurable interrupts and callback on UART events - mtb_hal_uart_event_t

Interrupts and callbacks

Interrupts are handled by callbacks based on events mtb_hal_uart_event_t If an event is disabled, the underlying interrupt is still enabled. Enabling or disabling an event only enables or disables the callback.

Note

Care must be exercised when using the MTB_HAL_UART_IRQ_RX_NOT_EMPTY event. The callback must read all available received data or the interrupt will not be cleared leading to the callback being immediately retriggered.

Quick Start

1. Initialize the UART Hardware
2. Enable the UART Hardware
3. Allocate the memory for the HAL UART object
4. Set up the HAL UART using mtb_hal_uart_setup by passing the HAL UART object and the pre-initialized UART Structures.
5. Set up the interrupt handler and arrange for mtb_hal_uart_process_interrupt to be invoked from the interrupt handler if UART events need to be handled
6. Config the UART for async transfers using mtb_hal_uart_config_async if async transfers are needed. This needs to be done before invoking any async transfer functions

Code Snippets

Snippet 1: Initialization

The following snippet sets up the UART block.

The snippet also shows how to use mtb_hal_uart_write, mtb_hal_uart_put, mtb_hal_uart_read API.

    #define BAUD_RATE       115200
    #define UART_DELAY      10u
    #define RX_BUF_SIZE     4
    #define TX_BUF_SIZE     4
 
    // Variable Declarations
    cy_rslt_t                         rslt;
    mtb_hal_uart_t                    uart_obj;
    cy_stc_scb_uart_context_t         uart_context;
    uint32_t                          actualbaud;
    uint8_t                           tx_buf[TX_BUF_SIZE] = { '1', '2', '3', '4' };
    uint8_t                           rx_buf[RX_BUF_SIZE];
    size_t                            tx_length = TX_BUF_SIZE;
    size_t                            rx_length = RX_BUF_SIZE;
    uint32_t                          value     = 'A';
 
    // Initialize the UART Block
    rslt = (cy_rslt_t)Cy_SCB_UART_Init(UART_HW, &UART_config, &uart_context);
    Cy_SCB_UART_Enable(UART_HW);
    rslt = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, NULL);
 
    // Set the baud rate
    rslt = mtb_hal_uart_set_baud(&uart_obj, BAUD_RATE, &actualbaud);
 
    // Begin Tx Transfer
    mtb_hal_uart_write(&uart_obj, (void*)tx_buf, &tx_length);
    Cy_SysLib_Delay(UART_DELAY); // todo once Next System is complete, replace w/ HAL delay calls
 
    // Send a Character
    mtb_hal_uart_put(&uart_obj, value);
    Cy_SysLib_Delay(UART_DELAY);
 
    // Begin Rx Transfer
    mtb_hal_uart_read(&uart_obj, (void*)rx_buf, &rx_length);
    Cy_SysLib_Delay(UART_DELAY);
 

Snippet 2: Interrupts on UART events

In the following snippet, UART events are handled in a callback function. The callback function has to be registered and then the events have to be enabled.

mtb_hal_uart_t uart_obj;
 
// UART interrupt handler
void uart_interrupt_handler(void)
{
    mtb_hal_uart_process_interrupt(&uart_obj);
}
 
 
// UART event handler
void uart_event_handler(void* handler_arg, mtb_hal_uart_event_t event)
{
    (void)handler_arg;
    (void)event;
}
 
 
cy_rslt_t snippet_mtb_hal_uart_event(void)
{
    // Macro Definitions
    #define TX_BUF_SIZE     4
    #define INT_PRIORITY    3
 
    // Variable Declarations
    cy_rslt_t                       rslt;
    uint8_t                         tx_buf[TX_BUF_SIZE] = { '1', '2', '3', '4' };
    size_t                          tx_length           = TX_BUF_SIZE;
    cy_stc_scb_uart_context_t       uart_context;
    mtb_async_transfer_context_t    uart_async_tran_context;
 
    // Initialize the UART Block
    rslt = (cy_rslt_t)Cy_SCB_UART_Init(UART_HW, &UART_config, &uart_context);
    Cy_SCB_UART_Enable(UART_HW);
    rslt = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, NULL);
 
    // The UART interrupt handler registration
    // UART_IRQ generated by configurator, named <alias>_IRQ
    cy_stc_sysint_t intr_cfg = { .intrSrc = UART_IRQ, .intrPriority = INT_PRIORITY };
    Cy_SysInt_Init(&intr_cfg, uart_interrupt_handler);
    NVIC_EnableIRQ(UART_IRQ);
 
    if (CY_RSLT_SUCCESS == rslt)
    {
        // Register for UART event callback
        mtb_hal_uart_register_callback(&uart_obj, uart_event_handler, NULL);
        // Enable required UART events
        mtb_hal_uart_enable_event(&uart_obj,
                                  (mtb_hal_uart_event_t)(MTB_HAL_UART_IRQ_TX_DONE |
                                                         MTB_HAL_UART_IRQ_TX_ERROR |
                                                         MTB_HAL_UART_IRQ_RX_DONE),
                                  true);
 
        //Configure the UART for async transfer
        rslt = mtb_hal_uart_config_async(&uart_obj, &uart_async_tran_context);
 
        // Begin asynchronous TX transfer
        rslt = mtb_hal_uart_write_async(&uart_obj, (void*)tx_buf, tx_length);
    }
 
    return rslt;
}
 
 
#endif /* !defined (SUT_WOUNDING_TEST) */
 

API Reference
	UART HAL Results
	UART specific return codes.

Macros
#define	MTB_HAL_UART_MAX_BAUD_PERCENT_DIFFERENCE   10
	The maximum allowable difference between baud requested and actual baud.
#define	MTB_HAL_UART_CLOCK_FREQ_MAX_TOLERANCE_PPM   (20000UL)
	The maximum allowable tolerance in PPM on the UART clock frequency.

Typedefs
typedef void(*	mtb_hal_uart_event_callback_t) (void *callback_arg, mtb_hal_uart_event_t event)
	UART callback function type.

Enumerations
enum	mtb_hal_uart_event_t {   MTB_HAL_UART_IRQ_NONE = 0 ,   MTB_HAL_UART_IRQ_TX_TRANSMIT_IN_FIFO = (MTB_HAL_MAP_UART_IRQ_TX_TRANSMIT_IN_FIFO) ,   MTB_HAL_UART_IRQ_TX_DONE = (MTB_HAL_MAP_UART_IRQ_TX_DONE) ,   MTB_HAL_UART_IRQ_RX_DONE = (MTB_HAL_MAP_UART_IRQ_RX_DONE) ,   MTB_HAL_UART_IRQ_RX_FULL = (MTB_HAL_MAP_UART_IRQ_RX_FULL) ,   MTB_HAL_UART_IRQ_RX_ERROR = (MTB_HAL_MAP_UART_IRQ_RX_ERROR) ,   MTB_HAL_UART_IRQ_TX_ERROR = (MTB_HAL_MAP_UART_IRQ_TX_ERROR) ,   MTB_HAL_UART_IRQ_RX_NOT_EMPTY = (MTB_HAL_MAP_UART_IRQ_RX_NOT_EMPTY) ,   MTB_HAL_UART_IRQ_TX_EMPTY = (MTB_HAL_MAP_UART_IRQ_TX_EMPTY) ,   MTB_HAL_UART_IRQ_TX_FIFO = (MTB_HAL_MAP_UART_IRQ_TX_FIFO) ,   MTB_HAL_UART_IRQ_RX_FIFO = (MTB_HAL_MAP_UART_IRQ_RX_FIFO) }
	UART enum to enable/disable/report interrupt cause flags. More...

Functions
cy_rslt_t	mtb_hal_uart_set_baud (mtb_hal_uart_t *obj, uint32_t baudrate, uint32_t *actualbaud)
	Configure the baud rate. More...
cy_rslt_t	mtb_hal_uart_get (mtb_hal_uart_t *obj, uint8_t *value, uint32_t timeout)
	Get a character. More...
cy_rslt_t	mtb_hal_uart_put (mtb_hal_uart_t *obj, uint32_t value)
	Send a character. More...
uint32_t	mtb_hal_uart_readable (mtb_hal_uart_t *obj)
	Check the number of bytes available to read from the receive buffers. More...
uint32_t	mtb_hal_uart_writable (mtb_hal_uart_t *obj)
	Check the number of bytes than can be written to the transmit buffer. More...
cy_rslt_t	mtb_hal_uart_clear (mtb_hal_uart_t *obj)
	Clear the UART buffers. More...
cy_rslt_t	mtb_hal_uart_enable_cts_flow_control (mtb_hal_uart_t *obj, bool enable)
	Configure the UART CTS for flow control. More...
cy_rslt_t	mtb_hal_uart_write (mtb_hal_uart_t *obj, void *tx, size_t *tx_length)
	Begin synchronous TX transfer. More...
cy_rslt_t	mtb_hal_uart_read (mtb_hal_uart_t *obj, void *rx, size_t *rx_length)
	Begin synchronous RX transfer (enable interrupt for data collecting) More...
bool	mtb_hal_uart_is_tx_active (mtb_hal_uart_t *obj)
	Determines if the UART peripheral is currently in use for TX. More...
void	mtb_hal_uart_register_callback (mtb_hal_uart_t *obj, mtb_hal_uart_event_callback_t callback, void *callback_arg)
	Register a uart callback handler. More...
void	mtb_hal_uart_enable_event (mtb_hal_uart_t *obj, mtb_hal_uart_event_t event, bool enable)
	Enable or disable specified UART events. More...
cy_rslt_t	mtb_hal_uart_process_interrupt (mtb_hal_uart_t *obj)
	Process interrupts related related to a UART instance. More...

Enumeration Type Documentation

mtb_hal_uart_event_t

enum mtb_hal_uart_event_t

UART enum to enable/disable/report interrupt cause flags.

Enumerator
MTB_HAL_UART_IRQ_NONE	No interrupt.
MTB_HAL_UART_IRQ_TX_TRANSMIT_IN_FIFO	All TX data from transmit has been moved to the HW TX FIFO buffer.
MTB_HAL_UART_IRQ_TX_DONE	All TX data has been transmitted (applicable only for mtb_hal_uart_write_async)
MTB_HAL_UART_IRQ_RX_DONE	An error occurred during TX.
MTB_HAL_UART_IRQ_RX_FULL	The SW RX buffer (if used) is full. Additional data will be stored in the HW RX FIFO buffer.
MTB_HAL_UART_IRQ_RX_ERROR	All RX data has been received (applicable only for mtb_hal_uart_read_async)
MTB_HAL_UART_IRQ_TX_ERROR	An error occurred during RX.
MTB_HAL_UART_IRQ_RX_NOT_EMPTY	The HW RX FIFO buffer is not empty.
MTB_HAL_UART_IRQ_TX_EMPTY	The HW TX FIFO buffer is empty.
MTB_HAL_UART_IRQ_TX_FIFO	Number of entries in the HW TX FIFO is less than the TX FIFO trigger level.
MTB_HAL_UART_IRQ_RX_FIFO	Number of entries in the HW RX FIFO is more than the RX FIFO trigger level.

Function Documentation

mtb_hal_uart_set_baud()

cy_rslt_t mtb_hal_uart_set_baud	(	mtb_hal_uart_t *	obj,
		uint32_t	baudrate,
		uint32_t *	actualbaud
	)

Configure the baud rate.

Parameters

[in,out]	obj	The UART object
[in]	baudrate	The baud rate to be configured
[out]	actualbaud	The actual baud rate achieved by the HAL Specify NULL if you do not want this information.

Returns

The status of the set_baud request

mtb_hal_uart_get()

cy_rslt_t mtb_hal_uart_get	(	mtb_hal_uart_t *	obj,
		uint8_t *	value,
		uint32_t	timeout
	)

Get a character.

This is a blocking call which waits till a character is received.

Parameters

[in]	obj	The UART object
[out]	value	The value read from the serial port
[in]	timeout	The time in ms to spend attempting to receive from serial port. Zero is wait forever

Returns

The status of the getc request

mtb_hal_uart_put()

cy_rslt_t mtb_hal_uart_put	(	mtb_hal_uart_t *	obj,
		uint32_t	value
	)

Send a character.

This is a blocking call which waits till the character is sent out from the UART completely.

Parameters

[in]	obj	The UART object
[in]	value	The character to be sent

Returns

The status of the putc request

mtb_hal_uart_readable()

uint32_t mtb_hal_uart_readable

(

mtb_hal_uart_t *

obj

)

Check the number of bytes available to read from the receive buffers.

Parameters

[in]

obj

The UART object

Returns

The number of readable bytes

mtb_hal_uart_writable()

uint32_t mtb_hal_uart_writable

(

mtb_hal_uart_t *

obj

)

Check the number of bytes than can be written to the transmit buffer.

Parameters

[in]

obj

The UART object

Returns

The number of bytes that can be written

mtb_hal_uart_clear()

cy_rslt_t mtb_hal_uart_clear

(

mtb_hal_uart_t *

obj

)

Clear the UART buffers.

Parameters

[in]

obj

The UART object

Returns

The status of the clear request

mtb_hal_uart_enable_cts_flow_control()

cy_rslt_t mtb_hal_uart_enable_cts_flow_control	(	mtb_hal_uart_t *	obj,
		bool	enable
	)

Configure the UART CTS for flow control.

It sets flow control in the hardware if a UART peripheral supports it, otherwise software emulation is used.

Parameters

[in,out]	obj	The UART object
[in]	enable	Enable or disable the CTS flow control

Returns

The status of the enable_flow_control request

mtb_hal_uart_write()

cy_rslt_t mtb_hal_uart_write	(	mtb_hal_uart_t *	obj,
		void *	tx,
		size_t *	tx_length
	)

Begin synchronous TX transfer.

This will write either length bytes or until the write buffer is full, whichever is less, then return. The value pointed to by length will be updated to reflect the number of bytes that was actually written.

Parameters

[in]	obj	The UART object
[in]	tx	The transmit buffer
[in,out]	tx_length	[in] The number of bytes to transmit, [out] number actually transmitted

Returns

The status of the tx request

mtb_hal_uart_read()

cy_rslt_t mtb_hal_uart_read	(	mtb_hal_uart_t *	obj,
		void *	rx,
		size_t *	rx_length
	)

Begin synchronous RX transfer (enable interrupt for data collecting)

This will read either length bytes or the number of bytes that are currently available in the receive buffer, whichever is less, then return. The value pointed to by length will be updated to reflect the number of bytes that was actually read.

Parameters

[in]	obj	The UART object
[in]	rx	The receive buffer
[in,out]	rx_length	[in] The number of bytes to receive, [out] number actually received

Returns

The status of the rx request

Begin synchronous RX transfer (enable interrupt for data collecting)

mtb_hal_uart_is_tx_active()

bool mtb_hal_uart_is_tx_active

(

mtb_hal_uart_t *

obj

)

Determines if the UART peripheral is currently in use for TX.

This checks if all the data in the UART TX FIFO is transmitted

Parameters

[in]

obj

The UART object

Returns

TX channel active status (active=true)

mtb_hal_uart_register_callback()

void mtb_hal_uart_register_callback	(	mtb_hal_uart_t *	obj,
		mtb_hal_uart_event_callback_t	callback,
		void *	callback_arg
	)

Register a uart callback handler.

This function will be called when one of the events enabled by mtb_hal_uart_enable_event occurs.

Parameters

[in]	obj	The UART object
[in]	callback	The callback handler which will be invoked when the interrupt fires
[in]	callback_arg	Generic argument that will be provided to the callback when called

mtb_hal_uart_enable_event()

void mtb_hal_uart_enable_event	(	mtb_hal_uart_t *	obj,
		mtb_hal_uart_event_t	event,
		bool	enable
	)

Enable or disable specified UART events.

When an enabled event occurs, the function specified by mtb_hal_uart_register_callback will be called.

Parameters

[in]	obj	The UART object
[in]	event	The uart event type, this argument supports the bitwise-or of multiple enum flag values
[in]	enable	True to turn on interrupts, False to turn off

mtb_hal_uart_process_interrupt()

cy_rslt_t mtb_hal_uart_process_interrupt

(

mtb_hal_uart_t *

obj

)

Process interrupts related related to a UART instance.

Parameters

obj	HAL object for which the interrupt should be processed

Returns

CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error