PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Macros | Typedefs | Enumerations | Functions
UART (Universal Asynchronous Receiver-Transmitter)
HAL API Reference » HAL Drivers

## 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);
rslt = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, NULL);
rslt = mtb_hal_uart_enable(&uart_obj, true);
// 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);
mtb_hal_uart_enable
cy_rslt_t mtb_hal_uart_enable(mtb_hal_uart_t *obj, bool enable)
Enable/disable the UART.
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.
Definition: mtb_hal_uart.c:731
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.
Definition: mtb_hal_uart.c:577
mtb_hal_uart_put
cy_rslt_t mtb_hal_uart_put(mtb_hal_uart_t *obj, uint32_t value)
Send a character.
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)
Definition: mtb_hal_uart.c:756
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
cy_stc_scb_uart_context_t
UART context structure.
Definition: cy_scb_uart.h:555
Cy_SCB_UART_Init
cy_en_scb_uart_status_t Cy_SCB_UART_Init(CySCB_Type *base, cy_stc_scb_uart_config_t const *config, cy_stc_scb_uart_context_t *context)
Initializes the SCB for UART operation.
Definition: cy_scb_uart.c:267
Cy_SysLib_Delay
void Cy_SysLib_Delay(uint32_t milliseconds)
The function delays by the specified number of milliseconds.
Definition: cy_syslib.c:104
mtb_hal_uart_t
UART object.
Definition: mtb_hal_hw_types_uart_scb.h:77

## 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);
rslt = mtb_hal_uart_setup(&uart_obj, &UART_hal_config, &uart_context, NULL);
rslt = mtb_hal_uart_enable(&uart_obj, true);
// 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) */
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.
Definition: mtb_hal_uart.c:831
mtb_hal_uart_event_t
mtb_hal_uart_event_t
UART enum to enable/disable/report interrupt cause flags.
Definition: mtb_hal_uart.h:167
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.
Definition: mtb_hal_uart.c:816
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.
Definition: mtb_hal_uart.c:946
MTB_HAL_UART_IRQ_TX_ERROR
@ MTB_HAL_UART_IRQ_TX_ERROR
An error occurred during RX.
Definition: mtb_hal_uart.h:182
MTB_HAL_UART_IRQ_TX_DONE
@ MTB_HAL_UART_IRQ_TX_DONE
All TX data has been transmitted (applicable only for mtb_hal_uart_write_async)
Definition: mtb_hal_uart.h:173
MTB_HAL_UART_IRQ_RX_DONE
@ MTB_HAL_UART_IRQ_RX_DONE
An error occurred during TX.
Definition: mtb_hal_uart.h:175
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486
cy_stc_sysint_t::intrSrc
IRQn_Type intrSrc
Interrupt source.
Definition: cy_sysint.h:229
cy_stc_sysint_t
Initialization configuration structure for a single interrupt channel.
Definition: cy_sysint.h:227
Cy_SysInt_Init
cy_en_sysint_status_t Cy_SysInt_Init(const cy_stc_sysint_t *config, cy_israddress userIsr)
Initializes the referenced interrupt by setting the priority and the interrupt vector.
Definition: cy_sysint_v2.c:80

## 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_enable (mtb_hal_uart_t *obj, bool enable)
| Enable/disable the UART. More...
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...
bool | mtb_hal_uart_is_rx_active (mtb_hal_uart_t *obj)
| Determines if the UART peripheral is currently in use for RX. 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...
cy_rslt_t | mtb_hal_uart_write_string (mtb_hal_uart_t *obj, const char *tx)
| Begin synchronous TX transfer of string. 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_enable()

cy_rslt_t mtb_hal_uart_enable | ( | mtb_hal_uart_t * | obj,
|  | bool | enable
| ) |  |

Enable/disable the UART.

The function returns without waiting for the enable to complete.

Parameters

  [in] | obj | The UART object
  [in] | enable | Enable/disable

Returns
  The status of the enable request

## ◆ 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_is_rx_active()

bool mtb_hal_uart_is_rx_active | ( | mtb_hal_uart_t * | obj | ) |

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

This checks if all the data in the UART RX FIFO is received

Parameters

  [in] | obj | The UART object

Returns
  RX 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

## ◆ mtb_hal_uart_write_string()

cy_rslt_t mtb_hal_uart_write_string | ( | mtb_hal_uart_t * | obj,
|  | const char * | tx
| ) |  |

Begin synchronous TX transfer of string.

Parameters

  [in] | obj | The UART object
  [in] | tx | The null-terminated string to transfer

Returns
  The status of the tx request