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.
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.
cyhal_uart_init is used for UART initialization
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.
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.
API Reference | |
UART HAL Results | |
UART specific return codes. | |
Data Structures | |
struct | cyhal_uart_cfg_t |
Initial UART configuration. More... | |
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... | |
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. |
enum cyhal_uart_parity_t |
enum cyhal_uart_event_t |
Enum to enable/disable/report interrupt cause flags.
enum cyhal_uart_output_t |
Enum of possible output signals from a UART.
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.
[out] | obj | Pointer to a UART object. The caller must allocate the memory for this object but the init function will initialize its contents. |
[in] | tx | The TX pin name, if no TX pin use NC |
[in] | rx | The RX pin name, if no RX pin use NC |
[in] | cts | The CTS pin name, if no CTS pin use NC |
[in] | rts | The RTS pin name, if no RTS pin use NC |
[in] | clk | The clock to use can be shared. If not provided, a new clock will be allocated and the default baud rate will be set |
[in] | cfg | The UART configuration data for data bits, stop bits and parity. If not provided, default values of (8, 1, none) will be used |
void cyhal_uart_free | ( | cyhal_uart_t * | obj | ) |
Release the UART peripheral.
[in,out] | obj | The UART object |
cy_rslt_t cyhal_uart_set_baud | ( | cyhal_uart_t * | obj, |
uint32_t | baudrate, | ||
uint32_t * | actualbaud | ||
) |
Configure the baud rate.
[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. |
cy_rslt_t cyhal_uart_configure | ( | cyhal_uart_t * | obj, |
const cyhal_uart_cfg_t * | cfg | ||
) |
Configure the data bits, stop bits, and parity.
[in,out] | obj | The UART object |
[in] | cfg | The UART configuration data for data bits, stop bits and parity. rx_buffer and rx_buffer_size are ignored. |
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.
[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 |
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.
[in] | obj | The UART object |
[in] | value | The character to be sent |
uint32_t cyhal_uart_readable | ( | cyhal_uart_t * | obj | ) |
Check the number of bytes available to read from the receive buffers.
[in] | obj | The UART object |
uint32_t cyhal_uart_writable | ( | cyhal_uart_t * | obj | ) |
Check the number of bytes than can be written to the transmit buffer.
[in] | obj | The UART object |
cy_rslt_t cyhal_uart_clear | ( | cyhal_uart_t * | obj | ) |
Clear the UART buffers.
[in] | obj | The UART object |
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.
[in,out] | obj | The UART object |
[in] | enable_cts | Enable or disable CTS functionality |
[in] | enable_rts | Enable or disable RTS functionality |
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.
[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 |
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.
[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 |
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.
[in] | obj | The UART object |
[in] | mode | The transfer mode |
[in] | dma_priority | The 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. |
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.
[in] | obj | The UART object |
[in] | tx | The transmit buffer |
[in] | length | The number of bytes to transmit |
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.
[in] | obj | The UART object |
[out] | rx | The user specified receive buffer |
[in] | length | The number of bytes to receive |
bool cyhal_uart_is_tx_active | ( | cyhal_uart_t * | obj | ) |
Determines if the UART peripheral is currently in use for TX.
[in] | obj | The UART object |
bool cyhal_uart_is_rx_active | ( | cyhal_uart_t * | obj | ) |
Determines if the UART peripheral is currently in use for RX.
[in] | obj | The UART object |
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.
[in] | obj | The UART object |
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.
[in] | obj | The UART object |
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.
[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 |
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.
[in] | obj | The UART object |
[in] | event | The uart event type, this argument supports the bitwise-or of multiple enum flag values |
[in] | intr_priority | The priority for NVIC interrupt events |
[in] | enable | True to turn on interrupts, False to turn off |
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.
[in] | obj | The UART object |
[in] | type | FIFO type to set level for |
[in] | level | Level threshold to set |
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.
[in] | obj | The UART object |
[in] | output | Which output signal to enable |
[out] | source | Pointer 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. |
cy_rslt_t cyhal_uart_disable_output | ( | cyhal_uart_t * | obj, |
cyhal_uart_output_t | output | ||
) |
Disables the specified output signal from a UART.
[in] | obj | The UART object |
[in] | output | Which output signal to disable |
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.
[in] | obj | The UART peripheral to configure |
[in] | cfg | Configuration structure generated by a configurator. |
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
.
[in] | obj | The UART peripheral to configure |
[in] | rx_buffer | The RX software buffer pointer |
[in] | rx_buffer_size | The number of bytes in the RX software buffer |