(d1073c972c)

UART Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/autogen/dif_uart_autogen.h"
#include "uart_regs.h"

Go to the source code of this file.

Data Structures
struct	dif_uart_config
	Runtime configuration for UART. More...

Typedefs
typedef enum dif_uart_parity	dif_uart_parity_t
	A parity state: odd, or even.

typedef enum dif_uart_rx_break_level	dif_uart_rx_break_level_t
	Number of characters that the UART RX line should be held low for to trigger a line break error.

typedef struct dif_uart_config	dif_uart_config_t
	Runtime configuration for UART. More...

typedef enum dif_uart_watermark	dif_uart_watermark_t
	A UART FIFO watermark depth configuration.

typedef enum dif_uart_datapath	dif_uart_datapath_t
	A UART datapath to select various enables / FIFO resets.

typedef enum dif_uart_loopback	dif_uart_loopback_t
	A UART system/line loopback configuration.

Enumerations
enum	dif_uart_parity { kDifUartParityOdd = 0 , kDifUartParityEven }
	A parity state: odd, or even. More...

enum	dif_uart_rx_break_level { kDifUartRxBreakLevel2 = UART_CTRL_RXBLVL_VALUE_BREAK2 , kDifUartRxBreakLevel4 = UART_CTRL_RXBLVL_VALUE_BREAK4 , kDifUartRxBreakLevel8 = UART_CTRL_RXBLVL_VALUE_BREAK8 , kDifUartRxBreakLevel16 = UART_CTRL_RXBLVL_VALUE_BREAK16 }
	Number of characters that the UART RX line should be held low for to trigger a line break error.

enum	dif_uart_watermark { kDifUartWatermarkByte1 = 0 , kDifUartWatermarkByte2 , kDifUartWatermarkByte4 , kDifUartWatermarkByte8 , kDifUartWatermarkByte16 , kDifUartWatermarkByte32 , kDifUartWatermarkByte62 }
	A UART FIFO watermark depth configuration. More...

enum	dif_uart_datapath { kDifUartDatapathRx = 0 , kDifUartDatapathTx , kDifUartDatapathAll }
	A UART datapath to select various enables / FIFO resets. More...

enum	dif_uart_loopback { kDifUartLoopbackSystem = 0 , kDifUartLoopbackLine }
	A UART system/line loopback configuration. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_configure (const dif_uart_t *uart, dif_uart_config_t config)
	Configures UART with runtime information. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_rx_break_level_set (const dif_uart_t *uart, dif_uart_rx_break_level_t rx_break_level)
	Set the RX break level. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_watermark_rx_set (const dif_uart_t *uart, dif_uart_watermark_t watermark)
	Sets the RX FIFO watermark. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_watermark_tx_set (const dif_uart_t *uart, dif_uart_watermark_t watermark)
	Sets the TX FIFO watermark. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_set_enable (const dif_uart_t *uart, dif_uart_datapath_t datapath, dif_toggle_t enabled)
	Sets the enablement state of one or both (TX/RX) datapaths. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_bytes_send (const dif_uart_t uart, const uint8_t data, size_t bytes_requested, size_t *bytes_written)
	Sends bytes over UART. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_bytes_receive (const dif_uart_t uart, size_t bytes_requested, uint8_t data, size_t *bytes_read)
	Recieves bytes over UART. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_byte_send_polled (const dif_uart_t *uart, uint8_t byte)
	Transmits a single UART byte (polled). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_byte_receive_polled (const dif_uart_t uart, uint8_t byte)
	Receives a single UART byte (polled). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_rx_bytes_available (const dif_uart_t uart, size_t num_bytes)
	Gets the number of bytes available to be read from the UART RX FIFO. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_tx_bytes_available (const dif_uart_t uart, size_t num_bytes)
	Gets the number of bytes available to be written from the UART TX FIFO. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_fifo_reset (const dif_uart_t *uart, dif_uart_datapath_t fifo)
	Resets one or both datapath FIFOs. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_loopback_set (const dif_uart_t *uart, dif_uart_loopback_t loopback, dif_toggle_t enable)
	Enables or disables a transmit/receive loopback. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_enable_rx_timeout (const dif_uart_t *uart, uint32_t duration_ticks)
	Enables the RX timeout with the given duration. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_disable_rx_timeout (const dif_uart_t *uart)
	Disables the RX timeout. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_uart_get_rx_timeout (const dif_uart_t uart, dif_toggle_t status, uint32_t *duration_ticks)
	Gets the current status of the RX timeout control. More...

Variables
const uint32_t	kDifUartFifoSizeBytes
	The size of the UART TX and RX FIFOs, in bytes.

Detailed Description

UART Device Interface Functions

Definition in file dif_uart.h.

Data Structure Documentation

◆ dif_uart_config

struct dif_uart_config

Runtime configuration for UART.

This struct describes runtime information for one-time configuration of the hardware.

Definition at line 55 of file dif_uart.h.

Data Fields
uint32_t	baudrate	The UART baudrate.
uint32_t	clk_freq_hz	The frequency of the clock driving the UART.
dif_uart_parity_t	parity	The parity to set.
dif_toggle_t	parity_enable	Whether to enable parity checking.
dif_uart_rx_break_level_t	rx_break_level	Number of characters at which the RX line break error is triggered.
dif_toggle_t	rx_enable	Whether to enable RX datapath.
dif_toggle_t	tx_enable	Whether to enable TX datapath.

Typedef Documentation

◆ dif_uart_config_t

typedef struct dif_uart_config dif_uart_config_t

Runtime configuration for UART.

This struct describes runtime information for one-time configuration of the hardware.

Enumeration Type Documentation

◆ dif_uart_datapath

enum dif_uart_datapath

A UART datapath to select various enables / FIFO resets.

Enumerator
kDifUartDatapathRx	Selects the RX datapath for enablement / reset.
kDifUartDatapathTx	Selects the TX datapath for enablement / reset.
kDifUartDatapathAll	Selects both the RX and TX datapaths for enablement / reset.

Definition at line 123 of file dif_uart.h.

◆ dif_uart_loopback

enum dif_uart_loopback

A UART system/line loopback configuration.

Enumerator
kDifUartLoopbackSystem	Indicates that outgoing TX bits should be recieved through RX.
kDifUartLoopbackLine	Indicates that incoming RX bits should be forwarded to TX.

Definition at line 141 of file dif_uart.h.

◆ dif_uart_parity

enum dif_uart_parity

A parity state: odd, or even.

Enumerator
kDifUartParityOdd	Indicates the "odd" parity.
kDifUartParityEven	Indicates the "even" parity.

Definition at line 27 of file dif_uart.h.

◆ dif_uart_watermark

enum dif_uart_watermark

A UART FIFO watermark depth configuration.

Enumerator
kDifUartWatermarkByte1	Indicates a one-byte watermark.
kDifUartWatermarkByte2	Indicates a two-byte watermark.
kDifUartWatermarkByte4	Indicates a four-byte watermark.
kDifUartWatermarkByte8	Indicates an eight-byte watermark.
kDifUartWatermarkByte16	Indicates a sixteen-byte watermark.
kDifUartWatermarkByte32	Indicates a thirty-two-byte watermark.
kDifUartWatermarkByte62	Indicates a sixty-four-byte watermark.

Definition at line 89 of file dif_uart.h.

Function Documentation

◆ dif_uart_byte_receive_polled()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_byte_receive_polled	(	const dif_uart_t *	uart,
		uint8_t *	byte
	)

Receives a single UART byte (polled).

This operation is polled, and will busy wait until a byte has been read.

Must not be used inside an ISR.

Parameters

	uart	A UART handle.
[out]	byte	Received byte.

Returns: The result of the operation.

Definition at line 339 of file dif_uart.c.

◆ dif_uart_byte_send_polled()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_byte_send_polled	(	const dif_uart_t *	uart,
		uint8_t	byte
	)

Transmits a single UART byte (polled).

This operation is polled, and will busy wait until a byte has been sent.

Must not be used inside an ISR.

Parameters

uart	A UART handle.
byte	Byte to be transmitted.

Returns: The result of the operation.

Definition at line 320 of file dif_uart.c.

◆ dif_uart_bytes_receive()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_bytes_receive	(	const dif_uart_t *	uart,
		size_t	bytes_requested,
		uint8_t *	data,
		size_t *	bytes_read
	)

Recieves bytes over UART.

Can be used from inside an UART ISR.

This function attempts to read bytes_requested number of bytes from the UART RX FIFO into data, and passes bytes_read back to the caller. bytes_read is optional, NULL should be passed in if the value is not needed.

Parameters

	uart	A UART handle.
	bytes_requested	Number of bytes requested to be read by the caller.
[out]	data	Buffer for up to `bytes_requested` bytes of read data.
[out]	bytes_read	Number of bytes read (optional).

Returns: The result of the operation.

Definition at line 304 of file dif_uart.c.

◆ dif_uart_bytes_send()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_bytes_send	(	const dif_uart_t *	uart,
		const uint8_t *	data,
		size_t	bytes_requested,
		size_t *	bytes_written
	)

Sends bytes over UART.

Can be used from inside an UART ISR.

This function attempts to write bytes_requested number of bytes to the UART TX FIFO from bytes_requested, and passes bytes_written back to the caller. bytes_written is optional, NULL should be passed in if the value is not needed.

Parameters

	uart	A UART handle.
	data	Data to be written.
	bytes_requested	Number of bytes requested to be written by the caller.
[out]	bytes_written	Number of bytes written (optional).

Returns: The result of the operation.

Definition at line 288 of file dif_uart.c.

◆ dif_uart_configure()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_configure	(	const dif_uart_t *	uart,
		dif_uart_config_t	config
	)

Configures UART with runtime information.

This function should need to be called once for the lifetime of handle.

Parameters

uart	A UART handle.
config	Runtime configuration parameters.

Returns: The result of the operation.

Definition at line 91 of file dif_uart.c.

◆ dif_uart_disable_rx_timeout()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_disable_rx_timeout ( const dif_uart_t * uart )

Disables the RX timeout.

In addition to disabling the RX timeout the timeout duration is reset to 0 ticks.

Parameters

uart	A UART handle.

Returns: The result of the operation.

Definition at line 442 of file dif_uart.c.

◆ dif_uart_enable_rx_timeout()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_enable_rx_timeout	(	const dif_uart_t *	uart,
		uint32_t	duration_ticks
	)

Enables the RX timeout with the given duration.

Parameters

uart	A UART handle.
duration_ticks	RX timeout value in UART bit times (using the baud rate clock as reference) in the range [0,0xffffff].

Returns: The result of the operation.

Definition at line 427 of file dif_uart.c.

◆ dif_uart_fifo_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_fifo_reset	(	const dif_uart_t *	uart,
		dif_uart_datapath_t	fifo
	)

Resets one or both datapath FIFOs.

If the byte is in transit, this function will not abort the operation.

Parameters

uart	A UART handle.
fifo	The FIFO to reset (RX, TX or both).

Returns: The result of the operation.

Definition at line 384 of file dif_uart.c.

◆ dif_uart_get_rx_timeout()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_get_rx_timeout	(	const dif_uart_t *	uart,
		dif_toggle_t *	status,
		uint32_t *	duration_ticks
	)

Gets the current status of the RX timeout control.

Parameters

	uart	A UART handle.
[out]	status	The status of the RX timeout control (enabled or disabled).
[out]	duration_ticks	RX timeout value in UART bit times (using the baud rate clock as reference) in the range [0,0xffffff] (optional).

Returns: The result of the operation.

Definition at line 454 of file dif_uart.c.

◆ dif_uart_loopback_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_loopback_set	(	const dif_uart_t *	uart,
		dif_uart_loopback_t	loopback,
		dif_toggle_t	enable
	)

Enables or disables a transmit/receive loopback.

This API can be used for testing, such as to validate transmit and receive routines.

Loopback should only be enabled when device is in the IDLE state to prevent data loss/coruption. Behaviour depends on the loopback parameter:

kDifUartLoopbackSystem: Receives the data that is being transmitted. No external data can be received (from the RX line). When enabled the TX line goes high.
kDifUartLoopbackLine: Transmits the data that is being received. No internal data can be sent out (from the TX FIFO). When enabled the RX line goes high.

Parameters

uart	A UART handle.
loopback	Loopback type (transmit/receive).
enable	Enable/disable control flag.

Returns: The result of the operation.

Definition at line 412 of file dif_uart.c.

◆ dif_uart_rx_break_level_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_rx_break_level_set	(	const dif_uart_t *	uart,
		dif_uart_rx_break_level_t	rx_break_level
	)

Set the RX break level.

This is the number of characters that the RX line must be held low for to trigger the RX break error.

Parameters

uart	A UART handle.
rx_break_level	The level to configure.

Returns: The result of the operation.

Definition at line 161 of file dif_uart.c.

◆ dif_uart_rx_bytes_available()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_rx_bytes_available	(	const dif_uart_t *	uart,
		size_t *	num_bytes
	)

Gets the number of bytes available to be read from the UART RX FIFO.

This function can be used to check FIFO full and empty conditions.

Parameters

	uart	A UART handle.
[out]	num_bytes	Number of bytes available to be read.

Returns: The result of the operation.

Definition at line 354 of file dif_uart.c.

◆ dif_uart_set_enable()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_set_enable	(	const dif_uart_t *	uart,
		dif_uart_datapath_t	datapath,
		dif_toggle_t	enabled
	)

Sets the enablement state of one or both (TX/RX) datapaths.

Parameters

uart	A UART handle.
datapath	The datapath to set the enablement state of (RX, TX or both).
enabled	The enablement state to set.

Returns: The result of the operation.

Definition at line 255 of file dif_uart.c.

◆ dif_uart_tx_bytes_available()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_tx_bytes_available	(	const dif_uart_t *	uart,
		size_t *	num_bytes
	)

Gets the number of bytes available to be written from the UART TX FIFO.

This function can be used to check FIFO full and empty conditions.

Parameters

	uart	A UART handle.
[out]	num_bytes	Number of bytes available to be written.

Returns: The result of the operation.

Definition at line 368 of file dif_uart.c.

◆ dif_uart_watermark_rx_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_watermark_rx_set	(	const dif_uart_t *	uart,
		dif_uart_watermark_t	watermark
	)

Sets the RX FIFO watermark.

This function is only useful when the corresponding interrupt is enabled. When the queued RX FIFO number of bytes rises to or above this level, the RX watermark interrupt is raised.

Parameters

uart	A UART handle.
watermark	RX FIFO watermark.

Returns: The result of the operation.

Definition at line 174 of file dif_uart.c.

◆ dif_uart_watermark_tx_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_watermark_tx_set	(	const dif_uart_t *	uart,
		dif_uart_watermark_t	watermark
	)

Sets the TX FIFO watermark.

This function is only useful when the corresponding interrupt is enabled. When the queued RX FIFO number of bytes rises to or above this level, the RX watermark interrupt is raised.

Parameters

uart	A UART handle.
watermark	TX FIFO watermark.

Returns: The result of the operation.

Definition at line 217 of file dif_uart.c.

(d1073c972c)

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dif_uart_config

Typedef Documentation

◆ dif_uart_config_t

Enumeration Type Documentation

◆ dif_uart_datapath

◆ dif_uart_loopback

◆ dif_uart_parity

◆ dif_uart_watermark

Function Documentation

◆ dif_uart_byte_receive_polled()

◆ dif_uart_byte_send_polled()

◆ dif_uart_bytes_receive()

◆ dif_uart_bytes_send()

◆ dif_uart_configure()

◆ dif_uart_disable_rx_timeout()

◆ dif_uart_enable_rx_timeout()

◆ dif_uart_fifo_reset()

◆ dif_uart_get_rx_timeout()

◆ dif_uart_loopback_set()

◆ dif_uart_rx_break_level_set()

◆ dif_uart_rx_bytes_available()

◆ dif_uart_set_enable()

◆ dif_uart_tx_bytes_available()

◆ dif_uart_watermark_rx_set()

◆ dif_uart_watermark_tx_set()