UART Interface

Detailed Description

Interface for UART communications.

Summary

The UART interface provides common APIs for UART HAL drivers. The UART interface supports the following features:

• Full-duplex UART communication
• Interrupt driven transmit/receive processing
• Callback function with returned event code
• Runtime baud-rate change
• Hardware resource locking during a transaction
• CTS/RTS hardware flow control support (with an associated IOPORT pin)

Data Structures
struct	uart_info_t
struct	uart_callback_args_t
struct	uart_cfg_t
struct	uart_api_t
struct	uart_instance_t

Typedefs
typedef void	uart_ctrl_t

Enumerations
enum	uart_event_t
enum	uart_data_bits_t
enum	uart_parity_t
enum	uart_stop_bits_t
enum	uart_dir_t

---

Data Structure Documentation

uart_info_t

struct uart_info_t

UART driver specific information

Data Fields
uint32_t	write_bytes_max	Maximum bytes that can be written at this time. Only applies if uart_cfg_t::p_transfer_tx is not NULL.
uint32_t	read_bytes_max	Maximum bytes that are available to read at one time. Only applies if uart_cfg_t::p_transfer_rx is not NULL.

uart_callback_args_t

struct uart_callback_args_t

UART Callback parameter definition

Data Fields
uint32_t	channel	Device channel number.
uart_event_t	event	Event code.
uint32_t	data	Contains the next character received for the events UART_EVENT_RX_CHAR, UART_EVENT_ERR_PARITY, UART_EVENT_ERR_FRAMING, or UART_EVENT_ERR_OVERFLOW. Otherwise unused.
void const *	p_context	Context provided to user during callback.

uart_cfg_t

struct uart_cfg_t

UART Configuration

Data Fields
uint8_t	channel
	Select a channel corresponding to the channel number of the hardware.
uart_data_bits_t	data_bits
	Data bit length (8 or 7 or 9)
uart_parity_t	parity
	Parity type (none or odd or even)
uart_stop_bits_t	stop_bits
	Stop bit length (1 or 2)
uint8_t	rxi_ipl
	Receive interrupt priority.
IRQn_Type	rxi_irq
	Receive interrupt IRQ number.
uint8_t	txi_ipl
	Transmit interrupt priority.
IRQn_Type	txi_irq
	Transmit interrupt IRQ number.
uint8_t	tei_ipl
	Transmit end interrupt priority.
IRQn_Type	tei_irq
	Transmit end interrupt IRQ number.
uint8_t	eri_ipl
	Error interrupt priority.
IRQn_Type	eri_irq
	Error interrupt IRQ number.
transfer_instance_t const *	p_transfer_rx
transfer_instance_t const *	p_transfer_tx
void(*	p_callback )(uart_callback_args_t *p_args)
	Pointer to callback function.
void const *	p_context
	User defined context passed into callback function.
void const *	p_extend
	UART hardware dependent configuration.

Field Documentation

p_transfer_rx

transfer_instance_t const* uart_cfg_t::p_transfer_rx

Optional transfer instance used to receive multiple bytes without interrupts. Set to NULL if unused. If NULL, the number of bytes allowed in the read API is limited to one byte at a time.

p_transfer_tx

transfer_instance_t const* uart_cfg_t::p_transfer_tx

Optional transfer instance used to send multiple bytes without interrupts. Set to NULL if unused. If NULL, the number of bytes allowed in the write APIs is limited to one byte at a time.

uart_api_t

struct uart_api_t

Shared Interface definition for UART

Data Fields
fsp_err_t(*	open )(uart_ctrl_t *const p_ctrl, uart_cfg_t const *const p_cfg)
fsp_err_t(*	read )(uart_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const bytes)
fsp_err_t(*	write )(uart_ctrl_t *const p_ctrl, uint8_t const *const p_src, uint32_t const bytes)
fsp_err_t(*	baudSet )(uart_ctrl_t *const p_ctrl, void const *const p_baudrate_info)
fsp_err_t(*	infoGet )(uart_ctrl_t *const p_ctrl, uart_info_t *const p_info)
fsp_err_t(*	communicationAbort )(uart_ctrl_t *const p_ctrl, uart_dir_t communication_to_abort)
fsp_err_t(*	callbackSet )(uart_ctrl_t *const p_ctrl, void(*p_callback)(uart_callback_args_t *), void const *const p_context, uart_callback_args_t *const p_callback_memory)
fsp_err_t(*	close )(uart_ctrl_t *const p_ctrl)
fsp_err_t(*	readStop )(uart_ctrl_t *const p_ctrl, uint32_t *remaining_bytes)

Field Documentation

open

fsp_err_t(* uart_api_t::open) (uart_ctrl_t *const p_ctrl, uart_cfg_t const *const p_cfg)

Open UART device.

Parameters

[in,out]	p_ctrl	Pointer to the UART control block. Must be declared by user. Value set here.
[in]	uart_cfg_t	Pointer to UART configuration structure. All elements of this structure must be set by user.

read

fsp_err_t(* uart_api_t::read) (uart_ctrl_t *const p_ctrl, uint8_t *const p_dest, uint32_t const bytes)

Read from UART device. The read buffer is used until the read is complete. When a transfer is complete, the callback is called with event UART_EVENT_RX_COMPLETE. Bytes received outside an active transfer are received in the callback function with event UART_EVENT_RX_CHAR. The maximum transfer size is reported by infoGet().

Parameters

[in]	p_ctrl	Pointer to the UART control block for the channel.
[in]	p_dest	Destination address to read data from.
[in]	bytes	Read data length.

write

fsp_err_t(* uart_api_t::write) (uart_ctrl_t *const p_ctrl, uint8_t const *const p_src, uint32_t const bytes)

Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), the callback called with event UART_EVENT_TX_COMPLETE. The maximum transfer size is reported by infoGet().

Parameters

[in]	p_ctrl	Pointer to the UART control block.
[in]	p_src	Source address to write data to.
[in]	bytes	Write data length.

baudSet

fsp_err_t(* uart_api_t::baudSet) (uart_ctrl_t *const p_ctrl, void const *const p_baudrate_info)

Change baud rate.

Warning

Calling this API aborts any in-progress transmission and disables reception until the new baud settings have been applied.

Parameters

[in]	p_ctrl	Pointer to the UART control block.
[in]	p_baudrate_info	Pointer to module specific information for configuring baud rate.

infoGet

fsp_err_t(* uart_api_t::infoGet) (uart_ctrl_t *const p_ctrl, uart_info_t *const p_info)

Get the driver specific information.

Parameters

[in]	p_ctrl	Pointer to the UART control block.
[out]	p_info	Pointer to UART information structure.

communicationAbort

fsp_err_t(* uart_api_t::communicationAbort) (uart_ctrl_t *const p_ctrl, uart_dir_t communication_to_abort)

Abort ongoing transfer.

Parameters

[in]	p_ctrl	Pointer to the UART control block.
[in]	communication_to_abort	Type of abort request.

callbackSet

fsp_err_t(* uart_api_t::callbackSet) (uart_ctrl_t *const p_ctrl, void(*p_callback)(uart_callback_args_t *), void const *const p_context, uart_callback_args_t *const p_callback_memory)

Specify callback function and optional context pointer and working memory pointer.

Parameters

[in]	p_ctrl	Pointer to the UART control block.
[in]	p_callback	Callback function
[in]	p_context	Pointer to send to callback function
[in]	p_working_memory	Pointer to volatile memory where callback structure can be allocated. Callback arguments allocated here are only valid during the callback.

close

fsp_err_t(* uart_api_t::close) (uart_ctrl_t *const p_ctrl)

Close UART device.

Parameters

[in]

p_ctrl

Pointer to the UART control block.

readStop

fsp_err_t(* uart_api_t::readStop) (uart_ctrl_t *const p_ctrl, uint32_t *remaining_bytes)

Stop ongoing read and return the number of bytes remaining in the read.

Parameters

[in]	p_ctrl	Pointer to the UART control block.
[in,out]	remaining_bytes	Pointer to location to store remaining bytes for read.

uart_instance_t

struct uart_instance_t

This structure encompasses everything that is needed to use an instance of this interface.

Data Fields
uart_ctrl_t *	p_ctrl	Pointer to the control structure for this instance.
uart_cfg_t const *	p_cfg	Pointer to the configuration structure for this instance.
uart_api_t const *	p_api	Pointer to the API structure for this instance.

Typedef Documentation

uart_ctrl_t

typedef void uart_ctrl_t

UART control block. Allocate an instance specific control block to pass into the UART API calls.

Enumeration Type Documentation

uart_event_t

enum uart_event_t

UART Event codes

Enumerator
UART_EVENT_RX_COMPLETE	Receive complete event.
UART_EVENT_TX_COMPLETE	Transmit complete event.
UART_EVENT_RX_CHAR	Character received.
UART_EVENT_ERR_PARITY	Parity error event.
UART_EVENT_ERR_FRAMING	Mode fault error event.
UART_EVENT_ERR_OVERFLOW	FIFO Overflow error event.
UART_EVENT_BREAK_DETECT	Break detect error event.
UART_EVENT_TX_DATA_EMPTY	Last byte is transmitting, ready for more data.

uart_data_bits_t

enum uart_data_bits_t

UART Data bit length definition

Enumerator
UART_DATA_BITS_9	Data bits 9-bit.
UART_DATA_BITS_8	Data bits 8-bit.
UART_DATA_BITS_7	Data bits 7-bit.

uart_parity_t

enum uart_parity_t

UART Parity definition

Enumerator
UART_PARITY_OFF	No parity.
UART_PARITY_ZERO	Zero parity.
UART_PARITY_EVEN	Even parity.
UART_PARITY_ODD	Odd parity.

uart_stop_bits_t

enum uart_stop_bits_t

UART Stop bits definition

Enumerator
UART_STOP_BITS_1	Stop bit 1-bit.
UART_STOP_BITS_2	Stop bits 2-bit.

uart_dir_t

enum uart_dir_t

UART transaction definition

Enumerator
UART_DIR_RX_TX	Both RX and TX.
UART_DIR_RX	Only RX.
UART_DIR_TX	Only TX.