Hardware Abstraction Layer (HAL)
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:

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

Flow control can be configured by providing cts / rts pins to cyhal_uart_init() and this will activate the feature in driver. In case flow control enablement status needs to be changed, cyhal_uart_enable_flow_control() function can be used.

The data frame size, STOP bits and parity can be configured via cyhal_uart_cfg_t. The UART contains dedicated hardware buffers for transmit and receive. Optionally, either of these can be augmented with a software buffer. This is done in scope of cyhal_uart_init (if appropriate configuration was selected) and cyhal_uart_config_software_buffer functions.

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

Features

Interrupts and callbacks

Interrupts are handled by callbacks based on events cyhal_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 CYHAL_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

cyhal_uart_init is used for UART initialization

Code Snippets

Snippet 1: Initialization and Configuration

The following snippet initializes the UART block and assigns the tx, rx pins and sets the baudrate.

The snippet also shows how to use cyhal_uart_write, cyhal_uart_putc, cyhal_uart_read API.

#define DATA_BITS_8 8
#define STOP_BITS_1 1
#define BAUD_RATE 115200
#define UART_DELAY 10u
#define RX_BUF_SIZE 4
#define TX_BUF_SIZE 4
// Variable Declarations
cy_rslt_t rslt;
cyhal_uart_t uart_obj;
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 configuration structure
const cyhal_uart_cfg_t uart_config =
{
.data_bits = DATA_BITS_8,
.stop_bits = STOP_BITS_1,
.rx_buffer = rx_buf,
.rx_buffer_size = RX_BUF_SIZE
};
// Initialize the UART Block
rslt = cyhal_uart_init(&uart_obj, CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, NC, NC, NULL,
&uart_config);
// Set the baud rate
rslt = cyhal_uart_set_baud(&uart_obj, BAUD_RATE, &actualbaud);
// Begin Tx Transfer
cyhal_uart_write(&uart_obj, (void*)tx_buf, &tx_length);
cyhal_system_delay_ms(UART_DELAY);
// Send a Character
cyhal_uart_putc(&uart_obj, value);
cyhal_system_delay_ms(UART_DELAY);
// Begin Rx Transfer
cyhal_uart_read(&uart_obj, (void*)rx_buf, &rx_length);
cyhal_system_delay_ms(UART_DELAY);
UART object.
Definition: cyhal_hw_types.h:1513
@ NC
No Connect/Invalid Pin.
Definition: cyhal_psoc6_01_104_m_csp_ble.h:53
cy_rslt_t cyhal_system_delay_ms(uint32_t milliseconds)
Requests that the current operation delays for at least the specified length of time.
uint32_t data_bits
The number of data bits (generally 8 or 9)
Definition: cyhal_uart.h:197
cy_rslt_t cyhal_uart_set_baud(cyhal_uart_t *obj, uint32_t baudrate, uint32_t *actualbaud)
Configure the baud rate.
cy_rslt_t cyhal_uart_putc(cyhal_uart_t *obj, uint32_t value)
Send a character.
cy_rslt_t cyhal_uart_write(cyhal_uart_t *obj, void *tx, size_t *tx_length)
Begin synchronous TX transfer.
cy_rslt_t cyhal_uart_init(cyhal_uart_t *obj, cyhal_gpio_t tx, cyhal_gpio_t rx, cyhal_gpio_t cts, cyhal_gpio_t rts, const cyhal_clock_t *clk, const cyhal_uart_cfg_t *cfg)
Initialize the UART peripheral.
cy_rslt_t cyhal_uart_read(cyhal_uart_t *obj, void *rx, size_t *rx_length)
Begin synchronous RX transfer (enable interrupt for data collecting)
@ CYHAL_UART_PARITY_NONE
UART has no parity check
Definition: cyhal_uart.h:154
Initial UART configuration.
Definition: cyhal_uart.h:196
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426

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.

// Event handler callback function
void uart_event_handler(void* handler_arg, cyhal_uart_event_t event)
{
(void)handler_arg;
{
// An error occurred in Tx
// Insert application code to handle Tx error
}
{
// All Tx data has been transmitted
// Insert application code to handle Tx done
}
{
// All Rx data has been received
// Insert application code to handle Rx done
}
}
cy_rslt_t snippet_cyhal_uart_event()
{
// Macro Definitions
#define BAUD_RATE 115200
#define UART_DELAY 10u
#define TX_BUF_SIZE 4
#define INT_PRIORITY 3
#define DATA_BITS_8 8
#define STOP_BITS_1 1
// Variable Declarations
cy_rslt_t rslt;
cyhal_uart_t uart_obj;
uint8_t tx_buf[TX_BUF_SIZE] = { '1', '2', '3', '4' };
size_t tx_length = TX_BUF_SIZE;
// Initialize the UART configuration structure
const cyhal_uart_cfg_t uart_config =
{
.data_bits = DATA_BITS_8,
.stop_bits = STOP_BITS_1,
.rx_buffer = NULL,
.rx_buffer_size = 0
};
// Initialize the UART Block
rslt = cyhal_uart_init(&uart_obj, CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, NC, NC, NULL,
&uart_config);
// The UART callback handler registration
if (CY_RSLT_SUCCESS == rslt)
{
cyhal_uart_register_callback(&uart_obj, uart_event_handler, NULL);
// Enable required UART events
INT_PRIORITY, true);
// Begin asynchronous TX transfer
rslt = cyhal_uart_write_async(&uart_obj, (void*)tx_buf, tx_length);
}
return rslt;
}
#endif /* !defined (SUT_WOUNDING_TEST) */
void cyhal_uart_enable_event(cyhal_uart_t *obj, cyhal_uart_event_t event, uint8_t intr_priority, bool enable)
Enable or disable specified UART events.
cy_rslt_t cyhal_uart_write_async(cyhal_uart_t *obj, void *tx, size_t length)
Begin asynchronous TX transfer.
void cyhal_uart_register_callback(cyhal_uart_t *obj, cyhal_uart_event_callback_t callback, void *callback_arg)
Register a uart callback handler.
cyhal_uart_event_t
Enum to enable/disable/report interrupt cause flags.
Definition: cyhal_uart.h:161
@ CYHAL_UART_IRQ_TX_DONE
All TX data has been transmitted (applicable only for cyhal_uart_write_async)
Definition: cyhal_uart.h:164
@ CYHAL_UART_IRQ_TX_ERROR
An error occurred during TX.
Definition: cyhal_uart.h:165
@ CYHAL_UART_IRQ_RX_DONE
All RX data has been received (applicable only for cyhal_uart_read_async)
Definition: cyhal_uart.h:167
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:453

API Reference

 UART HAL Results
 UART specific return codes.
 

Data Structures

struct  cyhal_uart_cfg_t
 Initial UART configuration. More...
 

Macros

#define CYHAL_UART_DEFAULT_BAUD   115200
 The baud rate to set to if no clock is specified in the init function.
 
#define CYHAL_UART_MAX_BAUD_PERCENT_DIFFERENCE   10
 The maximum allowable difference between baud requested and actual baud.
 

Typedefs

typedef void(* cyhal_uart_event_callback_t) (void *callback_arg, cyhal_uart_event_t event)
 UART callback function type.
 

Enumerations

enum  cyhal_uart_parity_t {
  CYHAL_UART_PARITY_NONE ,
  CYHAL_UART_PARITY_EVEN ,
  CYHAL_UART_PARITY_ODD
}
 UART Parity. More...
 
enum  cyhal_uart_event_t {
  CYHAL_UART_IRQ_NONE = 0 ,
  CYHAL_UART_IRQ_TX_TRANSMIT_IN_FIFO = 1 << 1 ,
  CYHAL_UART_IRQ_TX_DONE = 1 << 2 ,
  CYHAL_UART_IRQ_TX_ERROR = 1 << 3 ,
  CYHAL_UART_IRQ_RX_FULL = 1 << 4 ,
  CYHAL_UART_IRQ_RX_DONE = 1 << 5 ,
  CYHAL_UART_IRQ_RX_ERROR = 1 << 6 ,
  CYHAL_UART_IRQ_RX_NOT_EMPTY = 1 << 7 ,
  CYHAL_UART_IRQ_TX_EMPTY = 1 << 8 ,
  CYHAL_UART_IRQ_TX_FIFO = 1 << 9 ,
  CYHAL_UART_IRQ_RX_FIFO = 1 << 10
}
 Enum to enable/disable/report interrupt cause flags. More...
 
enum  cyhal_uart_fifo_type_t {
  CYHAL_UART_FIFO_RX ,
  CYHAL_UART_FIFO_TX
}
 UART FIFO type. More...
 
enum  cyhal_uart_output_t {
  CYHAL_UART_OUTPUT_TRIGGER_RX_FIFO_LEVEL_REACHED ,
  CYHAL_UART_OUTPUT_TRIGGER_TX_FIFO_LEVEL_REACHED
}
 Enum of possible output signals from a UART. More...
 

Functions

cy_rslt_t cyhal_uart_init (cyhal_uart_t *obj, cyhal_gpio_t tx, cyhal_gpio_t rx, cyhal_gpio_t cts, cyhal_gpio_t rts, const cyhal_clock_t *clk, const cyhal_uart_cfg_t *cfg)
 Initialize the UART peripheral. More...
 
void cyhal_uart_free (cyhal_uart_t *obj)
 Release the UART peripheral. More...
 
cy_rslt_t cyhal_uart_set_baud (cyhal_uart_t *obj, uint32_t baudrate, uint32_t *actualbaud)
 Configure the baud rate. More...
 
cy_rslt_t cyhal_uart_configure (cyhal_uart_t *obj, const cyhal_uart_cfg_t *cfg)
 Configure the data bits, stop bits, and parity. More...
 
cy_rslt_t cyhal_uart_getc (cyhal_uart_t *obj, uint8_t *value, uint32_t timeout)
 Get a character. More...
 
cy_rslt_t cyhal_uart_putc (cyhal_uart_t *obj, uint32_t value)
 Send a character. More...
 
uint32_t cyhal_uart_readable (cyhal_uart_t *obj)
 Check the number of bytes available to read from the receive buffers. More...
 
uint32_t cyhal_uart_writable (cyhal_uart_t *obj)
 Check the number of bytes than can be written to the transmit buffer. More...
 
cy_rslt_t cyhal_uart_clear (cyhal_uart_t *obj)
 Clear the UART buffers. More...
 
cy_rslt_t cyhal_uart_enable_flow_control (cyhal_uart_t *obj, bool enable_cts, bool enable_rts)
 Configure the UART for flow control. More...
 
cy_rslt_t cyhal_uart_write (cyhal_uart_t *obj, void *tx, size_t *tx_length)
 Begin synchronous TX transfer. More...
 
cy_rslt_t cyhal_uart_read (cyhal_uart_t *obj, void *rx, size_t *rx_length)
 Begin synchronous RX transfer (enable interrupt for data collecting) More...
 
cy_rslt_t cyhal_uart_set_async_mode (cyhal_uart_t *obj, cyhal_async_mode_t mode, uint8_t dma_priority)
 Set the mechanism that is used to perform UART asynchronous transfers. More...
 
cy_rslt_t cyhal_uart_write_async (cyhal_uart_t *obj, void *tx, size_t length)
 Begin asynchronous TX transfer. More...
 
cy_rslt_t cyhal_uart_read_async (cyhal_uart_t *obj, void *rx, size_t length)
 Begin asynchronous RX transfer. More...
 
bool cyhal_uart_is_tx_active (cyhal_uart_t *obj)
 Determines if the UART peripheral is currently in use for TX. More...
 
bool cyhal_uart_is_rx_active (cyhal_uart_t *obj)
 Determines if the UART peripheral is currently in use for RX. More...
 
cy_rslt_t cyhal_uart_write_abort (cyhal_uart_t *obj)
 Abort the ongoing TX transaction. More...
 
cy_rslt_t cyhal_uart_read_abort (cyhal_uart_t *obj)
 Abort the ongoing read transaction. More...
 
void cyhal_uart_register_callback (cyhal_uart_t *obj, cyhal_uart_event_callback_t callback, void *callback_arg)
 Register a uart callback handler. More...
 
void cyhal_uart_enable_event (cyhal_uart_t *obj, cyhal_uart_event_t event, uint8_t intr_priority, bool enable)
 Enable or disable specified UART events. More...
 
cy_rslt_t cyhal_uart_set_fifo_level (cyhal_uart_t *obj, cyhal_uart_fifo_type_t type, uint16_t level)
 Sets a threshold level for a FIFO that will generate an interrupt and a trigger output. More...
 
cy_rslt_t cyhal_uart_enable_output (cyhal_uart_t *obj, cyhal_uart_output_t output, cyhal_source_t *source)
 Enables the specified output signal from a UART. More...
 
cy_rslt_t cyhal_uart_disable_output (cyhal_uart_t *obj, cyhal_uart_output_t output)
 Disables the specified output signal from a UART. More...
 
cy_rslt_t cyhal_uart_init_cfg (cyhal_uart_t *obj, const cyhal_uart_configurator_t *cfg)
 Initialize the UART peripheral using a configurator generated configuration struct. More...
 
cy_rslt_t cyhal_uart_config_software_buffer (cyhal_uart_t *obj, uint8_t *rx_buffer, uint32_t rx_buffer_size)
 Configure UART RX software buffer, which will extend the hardware RX FIFO buffer only for SW async mode. More...
 

Data Structure Documentation

◆ cyhal_uart_cfg_t

struct cyhal_uart_cfg_t
Data Fields
uint32_t data_bits The number of data bits (generally 8 or 9)
uint32_t stop_bits The number of stop bits (generally 0 or 1)
cyhal_uart_parity_t parity The parity.
uint8_t * rx_buffer The rx software buffer pointer, if NULL, no rx software buffer will be used.
uint32_t rx_buffer_size The number of bytes in the rx software buffer.

Enumeration Type Documentation

◆ cyhal_uart_parity_t

UART Parity.

Enumerator
CYHAL_UART_PARITY_NONE 

UART has no parity check

CYHAL_UART_PARITY_EVEN 

UART has even parity check.

CYHAL_UART_PARITY_ODD 

UART has odd parity check

◆ cyhal_uart_event_t

Enum to enable/disable/report interrupt cause flags.

Enumerator
CYHAL_UART_IRQ_NONE 

No interrupt.

CYHAL_UART_IRQ_TX_TRANSMIT_IN_FIFO 

All TX data from transmit has been moved to the HW TX FIFO buffer.

CYHAL_UART_IRQ_TX_DONE 

All TX data has been transmitted (applicable only for cyhal_uart_write_async)

CYHAL_UART_IRQ_TX_ERROR 

An error occurred during TX.

CYHAL_UART_IRQ_RX_FULL 

The SW RX buffer (if used) is full. Additional data will be stored in the HW RX FIFO buffer.

CYHAL_UART_IRQ_RX_DONE 

All RX data has been received (applicable only for cyhal_uart_read_async)

CYHAL_UART_IRQ_RX_ERROR 

An error occurred during RX.

CYHAL_UART_IRQ_RX_NOT_EMPTY 

The HW RX FIFO buffer is not empty.

CYHAL_UART_IRQ_TX_EMPTY 

The HW TX FIFO buffer is empty.

CYHAL_UART_IRQ_TX_FIFO 

Number of entries in the HW TX FIFO is less than the TX FIFO trigger level.

CYHAL_UART_IRQ_RX_FIFO 

Number of entries in the HW RX FIFO is more than the RX FIFO trigger level.

◆ cyhal_uart_fifo_type_t

UART FIFO type.

Enumerator
CYHAL_UART_FIFO_RX 

Set RX FIFO level.

CYHAL_UART_FIFO_TX 

Set TX FIFO level.

◆ cyhal_uart_output_t

Enum of possible output signals from a UART.

Enumerator
CYHAL_UART_OUTPUT_TRIGGER_RX_FIFO_LEVEL_REACHED 

Output the RX FIFO signal which is triggered when the receive FIFO has more entries than the configured level.

CYHAL_UART_OUTPUT_TRIGGER_TX_FIFO_LEVEL_REACHED 

Output the TX FIFO signal which is triggered when the transmit FIFO has less entries than the configured level.

Function Documentation

◆ cyhal_uart_init()

cy_rslt_t cyhal_uart_init ( cyhal_uart_t obj,
cyhal_gpio_t  tx,
cyhal_gpio_t  rx,
cyhal_gpio_t  cts,
cyhal_gpio_t  rts,
const cyhal_clock_t clk,
const cyhal_uart_cfg_t cfg 
)

Initialize the UART peripheral.

Note
This will set the baud rate to a default of CYHAL_UART_DEFAULT_BAUD. This can be changed by calling cyhal_uart_set_baud.
Function activates the flow control feature if CTS / RTS pins are provided.
Parameters
[out]objPointer to a UART object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]txThe TX pin name, if no TX pin use NC
[in]rxThe RX pin name, if no RX pin use NC
[in]ctsThe CTS pin name, if no CTS pin use NC
[in]rtsThe RTS pin name, if no RTS pin use NC
[in]clkThe clock to use can be shared. If not provided, a new clock will be allocated and the default baud rate will be set
[in]cfgThe UART configuration data for data bits, stop bits and parity. If not provided, default values of (8, 1, none) will be used
Returns
The status of the init request

◆ cyhal_uart_free()

void cyhal_uart_free ( cyhal_uart_t obj)

Release the UART peripheral.

Parameters
[in,out]objThe UART object

◆ cyhal_uart_set_baud()

cy_rslt_t cyhal_uart_set_baud ( cyhal_uart_t obj,
uint32_t  baudrate,
uint32_t *  actualbaud 
)

Configure the baud rate.

Note
This function should only be called if a shared clock divider is not used i.e. the clock parameter is set to NULL when calling cyhal_uart_init.
Parameters
[in,out]objThe UART object
[in]baudrateThe baud rate to be configured
[out]actualbaudThe actual baud rate achieved by the HAL Specify NULL if you do not want this information.
Returns
The status of the set_baud request

◆ cyhal_uart_configure()

cy_rslt_t cyhal_uart_configure ( cyhal_uart_t obj,
const cyhal_uart_cfg_t cfg 
)

Configure the data bits, stop bits, and parity.

Parameters
[in,out]objThe UART object
[in]cfgThe UART configuration data for data bits, stop bits and parity. rx_buffer and rx_buffer_size are ignored.
Returns
The status of the configure request

◆ cyhal_uart_getc()

cy_rslt_t cyhal_uart_getc ( cyhal_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]objThe UART object
[out]valueThe value read from the serial port
[in]timeoutThe time in ms to spend attempting to receive from serial port. Zero is wait forever
Returns
The status of the getc request

◆ cyhal_uart_putc()

cy_rslt_t cyhal_uart_putc ( cyhal_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]objThe UART object
[in]valueThe character to be sent
Returns
The status of the putc request

◆ cyhal_uart_readable()

uint32_t cyhal_uart_readable ( cyhal_uart_t obj)

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

Parameters
[in]objThe UART object
Returns
The number of readable bytes

◆ cyhal_uart_writable()

uint32_t cyhal_uart_writable ( cyhal_uart_t obj)

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

Parameters
[in]objThe UART object
Returns
The number of bytes that can be written

◆ cyhal_uart_clear()

cy_rslt_t cyhal_uart_clear ( cyhal_uart_t obj)

Clear the UART buffers.

Parameters
[in]objThe UART object
Returns
The status of the clear request

◆ cyhal_uart_enable_flow_control()

cy_rslt_t cyhal_uart_enable_flow_control ( cyhal_uart_t obj,
bool  enable_cts,
bool  enable_rts 
)

Configure the UART for flow control.

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

Parameters
[in,out]objThe UART object
[in]enable_ctsEnable or disable CTS functionality
[in]enable_rtsEnable or disable RTS functionality
Returns
The status of the enable_flow_control request

◆ cyhal_uart_write()

cy_rslt_t cyhal_uart_write ( cyhal_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]objThe UART object
[in]txThe transmit buffer
[in,out]tx_length[in] The number of bytes to transmit, [out] number actually transmitted
Returns
The status of the tx request

◆ cyhal_uart_read()

cy_rslt_t cyhal_uart_read ( cyhal_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]objThe UART object
[in]rxThe receive buffer
[in,out]rx_length[in] The number of bytes to receive, [out] number actually received
Returns
The status of the rx request

◆ cyhal_uart_set_async_mode()

cy_rslt_t cyhal_uart_set_async_mode ( cyhal_uart_t obj,
cyhal_async_mode_t  mode,
uint8_t  dma_priority 
)

Set the mechanism that is used to perform UART asynchronous transfers.

The default is SW.

Warning
The effect of calling this function while an async transfer is pending is undefined.
Parameters
[in]objThe UART object
[in]modeThe transfer mode
[in]dma_priorityThe priority, if DMA is used. Valid values are the same as for cyhal_dma_init. If DMA is not selected, the only valid value is CYHAL_DMA_PRIORITY_DEFAULT, and no guarantees are made about prioritization.
Returns
The status of the set mode request

◆ cyhal_uart_write_async()

cy_rslt_t cyhal_uart_write_async ( cyhal_uart_t obj,
void *  tx,
size_t  length 
)

Begin asynchronous TX transfer.

This will transfer length bytes into the buffer pointed to by tx in the background. When the requested quantity of data has been transferred, the CYHAL_UART_IRQ_TX_TRANSMIT_IN_FIFO event will be raised. The transmit buffer is a user defined buffer that will be sent on the UART. The user must register a callback with cyhal_uart_register_callback. If desired, TX callback events can be enabled using cyhal_uart_enable_event with the appropriate events.

Parameters
[in]objThe UART object
[in]txThe transmit buffer
[in]lengthThe number of bytes to transmit
Returns
The status of the tx_async request

◆ cyhal_uart_read_async()

cy_rslt_t cyhal_uart_read_async ( cyhal_uart_t obj,
void *  rx,
size_t  length 
)

Begin asynchronous RX transfer.

This will transfer length bytes into the buffer pointed to by rx in the background. When the requested quantity of data has been transferred, the CYHAL_UART_IRQ_RX_DONE event will be raised. Received data is placed in the user specified buffer. The user must register a callback with cyhal_uart_register_callback. RX callback events can be enabled using cyhal_uart_enable_event with the appropriate events.

Parameters
[in]objThe UART object
[out]rxThe user specified receive buffer
[in]lengthThe number of bytes to receive
Returns
The status of the rx_async request

◆ cyhal_uart_is_tx_active()

bool cyhal_uart_is_tx_active ( cyhal_uart_t obj)

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

Parameters
[in]objThe UART object
Returns
TX channel active status (active=true)

◆ cyhal_uart_is_rx_active()

bool cyhal_uart_is_rx_active ( cyhal_uart_t obj)

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

Parameters
[in]objThe UART object
Returns
RX channel active status (active=true)

◆ cyhal_uart_write_abort()

cy_rslt_t cyhal_uart_write_abort ( cyhal_uart_t obj)

Abort the ongoing TX transaction.

Disables the TX interrupt and flushes the TX hardware buffer if TX FIFO is used.

Parameters
[in]objThe UART object
Returns
The status of the tx_abort request

◆ cyhal_uart_read_abort()

cy_rslt_t cyhal_uart_read_abort ( cyhal_uart_t obj)

Abort the ongoing read transaction.

Disables the RX interrupt and flushes the RX hardware buffer if RX FIFO is used.

Parameters
[in]objThe UART object
Returns
The status of the read_abort request

◆ cyhal_uart_register_callback()

void cyhal_uart_register_callback ( cyhal_uart_t obj,
cyhal_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 cyhal_uart_enable_event occurs.

Parameters
[in]objThe UART object
[in]callbackThe callback handler which will be invoked when the interrupt fires
[in]callback_argGeneric argument that will be provided to the callback when called

◆ cyhal_uart_enable_event()

void cyhal_uart_enable_event ( cyhal_uart_t obj,
cyhal_uart_event_t  event,
uint8_t  intr_priority,
bool  enable 
)

Enable or disable specified UART events.

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

Parameters
[in]objThe UART object
[in]eventThe uart event type, this argument supports the bitwise-or of multiple enum flag values
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue to turn on interrupts, False to turn off

◆ cyhal_uart_set_fifo_level()

cy_rslt_t cyhal_uart_set_fifo_level ( cyhal_uart_t obj,
cyhal_uart_fifo_type_t  type,
uint16_t  level 
)

Sets a threshold level for a FIFO that will generate an interrupt and a trigger output.

The RX FIFO interrupt and trigger will be activated when the receive FIFO has more entries than the threshold. The TX FIFO interrupt and trigger will be activated when the transmit FIFO has less entries than the threshold.

Parameters
[in]objThe UART object
[in]typeFIFO type to set level for
[in]levelLevel threshold to set
Returns
The status of the level set

◆ cyhal_uart_enable_output()

cy_rslt_t cyhal_uart_enable_output ( cyhal_uart_t obj,
cyhal_uart_output_t  output,
cyhal_source_t source 
)

Enables the specified output signal from a UART.

Parameters
[in]objThe UART object
[in]outputWhich output signal to enable
[out]sourcePointer to user-allocated source signal object which will be initialized by enable_output. source should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.
Returns
The status of the output enable

◆ cyhal_uart_disable_output()

cy_rslt_t cyhal_uart_disable_output ( cyhal_uart_t obj,
cyhal_uart_output_t  output 
)

Disables the specified output signal from a UART.

Parameters
[in]objThe UART object
[in]outputWhich output signal to disable
Returns
The status of the output disable

◆ cyhal_uart_init_cfg()

cy_rslt_t cyhal_uart_init_cfg ( cyhal_uart_t obj,
const cyhal_uart_configurator_t cfg 
)

Initialize the UART peripheral using a configurator generated configuration struct.

Parameters
[in]objThe UART peripheral to configure
[in]cfgConfiguration structure generated by a configurator.
Returns
The status of the operation

◆ cyhal_uart_config_software_buffer()

cy_rslt_t cyhal_uart_config_software_buffer ( cyhal_uart_t obj,
uint8_t *  rx_buffer,
uint32_t  rx_buffer_size 
)

Configure UART RX software buffer, which will extend the hardware RX FIFO buffer only for SW async mode.

cyhal_uart_init function does not require this function call if a non-null value was provided for rx_buffer.

Parameters
[in]objThe UART peripheral to configure
[in]rx_bufferThe RX software buffer pointer
[in]rx_buffer_sizeThe number of bytes in the RX software buffer
Returns
The status of the operation