(915ba13)

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"

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 struct dif_uart_config	dif_uart_config_t
	Runtime configuration for UART. More...

typedef enum dif_uart_config_result	dif_uart_config_result_t
	The result of a UART operation.

typedef enum dif_uart_watermark	dif_uart_watermark_t
	A UART FIFO watermark depth configuration.

typedef enum dif_uart_fifo_reset	dif_uart_fifo_reset_t
	A UART FIFO reset selection.

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_config_result { kDifUartConfigOk = kDifOk, kDifUartConfigError = kDifError, kDifUartConfigBadArg = kDifBadArg, kDifUartConfigBadConfig, kDifUartConfigBadNco }
	The result of a UART operation. More...

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

enum	dif_uart_fifo_reset { kDifUartFifoResetRx = 0, kDifUartFifoResetTx, kDifUartFifoResetAll }
	A UART FIFO reset selection. 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_init (mmio_region_t base_addr, dif_uart_t *uart)
	Creates a new handle for UART. More...

OT_WARN_UNUSED_RESULT dif_uart_config_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_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_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...

dif_result_t	dif_uart_fifo_reset (const dif_uart_t *uart, dif_uart_fifo_reset_t reset)
	UART TX reset RX/TX FIFO. More...

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 43 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.

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_config_result

enum dif_uart_config_result

The result of a UART operation.

Enumerator
kDifUartConfigOk	Indicates that the operation succeeded.
kDifUartConfigError	Indicates some unspecified failure.
kDifUartConfigBadArg	Indicates that some parameter passed into a function failed a precondition. When this value is returned, no hardware operations occurred.
kDifUartConfigBadConfig	Indicates that the given configuration parameters are not valid.
kDifUartConfigBadNco	Indicates that the calculated NCO value was not valid.

Definition at line 65 of file dif_uart.h.

◆ dif_uart_fifo_reset

enum dif_uart_fifo_reset

A UART FIFO reset selection.

Enumerator
kDifUartFifoResetRx	Indicates that the RX FIFO should be reset.
kDifUartFifoResetTx	Indicates that the TX FIFO should be reset.
kDifUartFifoResetAll	Indicates that both FIFOs should be reset.

Definition at line 120 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 138 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 26 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.
kDifUartWatermarkByte4	Indicates a four-byte watermark.
kDifUartWatermarkByte8	Indicates an eight-byte watermark.
kDifUartWatermarkByte16	Indicates a sixteen-byte watermark.
kDifUartWatermarkByte30	Indicates a thirty-byte watermark.

Definition at line 94 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 276 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 257 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 241 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 225 of file dif_uart.c.

◆ dif_uart_configure()

OT_WARN_UNUSED_RESULT dif_uart_config_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 98 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 371 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 357 of file dif_uart.c.

◆ dif_uart_fifo_reset()

dif_result_t dif_uart_fifo_reset	(	const dif_uart_t *	uart,
		dif_uart_fifo_reset_t	reset
	)

UART TX reset RX/TX FIFO.

Resets one or both FIFOs. If the byte is in transit, this function will not abort the operation.

Parameters

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

Returns: The result of the operation.

Definition at line 321 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 383 of file dif_uart.c.

◆ dif_uart_init()

OT_WARN_UNUSED_RESULT dif_result_t dif_uart_init	(	mmio_region_t	base_addr,
		dif_uart_t *	uart
	)

Creates a new handle for UART.

This function does not actuate the hardware.

Parameters

	base_addr	Base address of the UART peripheral.
[out]	uart	Out param for the initialized handle.

Returns: The result of the operation.

Definition at line 89 of file dif_uart.c.

◆ dif_uart_loopback_set()

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 342 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 291 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 305 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 153 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 190 of file dif_uart.c.

(915ba13)

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_config_result

◆ dif_uart_fifo_reset

◆ 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_init()

◆ dif_uart_loopback_set()

◆ dif_uart_rx_bytes_available()

◆ dif_uart_tx_bytes_available()

◆ dif_uart_watermark_rx_set()

◆ dif_uart_watermark_tx_set()