UART Device Interface Functions More...

#include <stdbool.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Data Structures
struct	dif_uart_config
	UART configuration data. More...

struct	dif_uart
	UART instance state. More...

Typedefs
typedef enum dif_uart_interrupt	dif_uart_interrupt_t
	UART interrupt configuration. More...

typedef enum dif_uart_watermark	dif_uart_watermark_t
	TX and RX FIFO depth configuration. More...

typedef enum dif_uart_fifo_reset	dif_uart_fifo_reset_t
	UART TX/RX FIFO reset enumeration.

typedef enum dif_uart_loopback	dif_uart_loopback_t
	UART System/Line loopback enumeration.

typedef enum dif_uart_enable	dif_uart_enable_t
	Generic enable/disable enumeration. More...

typedef enum dif_uart_parity	dif_uart_parity_t
	UART parity enumeration. More...

typedef struct dif_uart_config	dif_uart_config_t
	UART configuration data. More...

typedef struct dif_uart	dif_uart_t
	UART instance state. More...

typedef enum dif_uart_result	dif_uart_result_t
	Uart generic status codes. More...

typedef enum dif_uart_config_result	dif_uart_config_result_t
	Uart initialisation routine status codes.

Enumerations
enum	dif_uart_interrupt { kDifUartInterruptTxWatermark = 0, kDifUartInterruptRxWatermark, kDifUartInterruptTxEmpty, kDifUartInterruptRxOverflow, kDifUartInterruptRxFrameErr, kDifUartInterruptRxBreakErr, kDifUartInterruptRxTimeout, kDifUartInterruptRxParityErr, kDifUartInterruptLast }
	UART interrupt configuration. More...

enum	dif_uart_watermark { kDifUartWatermarkByte1 = 0, kDifUartWatermarkByte4, kDifUartWatermarkByte8, kDifUartWatermarkByte16, kDifUartWatermarkByte30, kDifUartWatermarkLast }
	TX and RX FIFO depth configuration. More...

enum	dif_uart_fifo_reset { kDifUartFifoResetRx = 0, kDifUartFifoResetTx, kDifUartFifoResetAll }
	UART TX/RX FIFO reset enumeration. More...

enum	dif_uart_loopback { kDifUartLoopbackSystem = 0, kDifUartLoopbackLine }
	UART System/Line loopback enumeration. More...

enum	dif_uart_enable { kDifUartDisable = 0, kDifUartEnable }
	Generic enable/disable enumeration. More...

enum	dif_uart_parity { kDifUartParityOdd = 0, kDifUartParityEven }
	UART parity enumeration. More...

enum	dif_uart_result { kDifUartOk = 0, kDifUartError, kDifUartBadArg }
	Uart generic status codes. More...

enum	dif_uart_config_result { kDifUartConfigOk = 0, kDifUartConfigError, kDifUartConfigBadArg, kDifUartConfigBadConfig, kDifUartConfigBadNco }
	Uart initialisation routine status codes. More...

Functions
DIF_WARN_UNUSED_RESULT dif_uart_config_result_t	dif_uart_init (mmio_region_t base_addr, const dif_uart_config_t config, dif_uart_t uart)
	Initialise an instance of UART. More...

DIF_WARN_UNUSED_RESULT dif_uart_config_result_t	dif_uart_configure (const dif_uart_t uart, const dif_uart_config_t config)
	Configure an instance of UART. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_watermark_rx_set (const dif_uart_t *uart, dif_uart_watermark_t watermark)
	Set the RX FIFO watermark. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_watermark_tx_set (const dif_uart_t *uart, dif_uart_watermark_t watermark)
	Set the TX FIFO watermark. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_bytes_send (const dif_uart_t uart, const uint8_t data, size_t bytes_requested, size_t *bytes_written)
	UART send bytes. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_bytes_receive (const dif_uart_t uart, size_t bytes_requested, uint8_t data, size_t *bytes_read)
	UART receive bytes. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_byte_send_polled (const dif_uart_t *uart, uint8_t byte)
	Transmit a single UART byte (polled). More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_byte_receive_polled (const dif_uart_t uart, uint8_t byte)
	Receive a single UART byte (polled). More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_irq_state_get (const dif_uart_t uart, dif_uart_interrupt_t irq_type, dif_uart_enable_t state)
	UART get requested IRQ state. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_irq_state_clear (const dif_uart_t *uart, dif_uart_interrupt_t irq_type)
	UART clear requested IRQ state. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_irqs_disable (const dif_uart_t uart, uint32_t state)
	UART disable interrupts. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_irqs_restore (const dif_uart_t *uart, uint32_t state)
	UART restore IRQ state. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_irq_enable (const dif_uart_t *uart, dif_uart_interrupt_t irq_type, dif_uart_enable_t enable)
	UART interrupt control. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_irq_force (const dif_uart_t *uart, dif_uart_interrupt_t irq_type)
	UART interrupt force. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_rx_bytes_available (const dif_uart_t uart, size_t num_bytes)
	UART RX bytes available. More...

DIF_WARN_UNUSED_RESULT dif_uart_result_t	dif_uart_tx_bytes_available (const dif_uart_t uart, size_t num_bytes)
	UART TX bytes available. More...

dif_uart_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_uart_result_t	dif_uart_loopback_set (const dif_uart_t *uart, dif_uart_loopback_t loopback, dif_uart_enable_t enable)
	UART enable/disable transmit/receive loopback. More...

Variables
const uint32_t	kDifUartFifoSizeBytes

Detailed Description

UART Device Interface Functions

Definition in file dif_uart.h.

Data Structure Documentation

◆ dif_uart_config

struct dif_uart_config

UART configuration data.

The fundamental data used to configure an UART instance.

Definition at line 104 of file dif_uart.h.

Data Fields
uint32_t	baudrate	Requested baudrate.
uint32_t	clk_freq_hz	Input clock frequency.
dif_uart_parity_t	parity	Set parity (even by default).
dif_uart_enable_t	parity_enable	Enable parity check.

◆ dif_uart

struct dif_uart

UART instance state.

UART persistent data that is required by all UART API. base_address must be initialised by the caller, before passing into the UART DIF init routine.

Definition at line 117 of file dif_uart.h.

Data Fields
mmio_region_t	base_addr	UART base address.

Typedef Documentation

◆ dif_uart_config_t

typedef struct dif_uart_config dif_uart_config_t

UART configuration data.

The fundamental data used to configure an UART instance.

◆ dif_uart_enable_t

typedef enum dif_uart_enable dif_uart_enable_t

Generic enable/disable enumeration.

Enumeration used to enable/disable bits, flags, ...

◆ dif_uart_interrupt_t

typedef enum dif_uart_interrupt dif_uart_interrupt_t

UART interrupt configuration.

Enumeration used to enable, disable, test and query the UART interrupts. Please see the comportability specification for more information: https://docs.opentitan.org/doc/rm/comportability_specification/

◆ dif_uart_parity_t

typedef enum dif_uart_parity dif_uart_parity_t

UART parity enumeration.

Enumeration used to convey parity information

◆ dif_uart_result_t

typedef enum dif_uart_result dif_uart_result_t

Uart generic status codes.

These error codes can be used by any function. However if a function requires additional status codes, it must define a set of status codes to be used exclusicvely by such function.

◆ dif_uart_t

typedef struct dif_uart dif_uart_t

UART instance state.

UART persistent data that is required by all UART API. base_address must be initialised by the caller, before passing into the UART DIF init routine.

◆ dif_uart_watermark_t

typedef enum dif_uart_watermark dif_uart_watermark_t

TX and RX FIFO depth configuration.

Enumeration used to set the upper limit of bytes to queue.

Enumeration Type Documentation

◆ dif_uart_config_result

enum dif_uart_config_result

Uart initialisation routine status codes.

Enumerator
kDifUartConfigOk	Success.
kDifUartConfigError	General error.
kDifUartConfigBadArg	Input parameter is not valid.
kDifUartConfigBadConfig	Configuration is not valid.
kDifUartConfigBadNco	Calculated NCO is not valid.

Definition at line 137 of file dif_uart.h.

◆ dif_uart_enable

enum dif_uart_enable

Generic enable/disable enumeration.

Enumeration used to enable/disable bits, flags, ...

Enumerator
kDifUartDisable	disable.
kDifUartEnable	enable.

Definition at line 84 of file dif_uart.h.

◆ dif_uart_fifo_reset

enum dif_uart_fifo_reset

UART TX/RX FIFO reset enumeration.

Enumerator
kDifUartFifoResetRx	Reset RX FIFO.
kDifUartFifoResetTx	Reset TX FIFO.
kDifUartFifoResetAll	All above.

Definition at line 65 of file dif_uart.h.

◆ dif_uart_interrupt

enum dif_uart_interrupt

UART interrupt configuration.

Enumeration used to enable, disable, test and query the UART interrupts. Please see the comportability specification for more information: https://docs.opentitan.org/doc/rm/comportability_specification/

Enumerator
kDifUartInterruptTxWatermark	TX FIFO dipped below watermark.
kDifUartInterruptRxWatermark	RX FIFO reached high watermark.
kDifUartInterruptTxEmpty	TX FIFO empty.
kDifUartInterruptRxOverflow	RX FIFO overflow.
kDifUartInterruptRxFrameErr	RX framing error.
kDifUartInterruptRxBreakErr	RX break condition.
kDifUartInterruptRxTimeout	RX FIFO timeout (not empty in a set time)
kDifUartInterruptRxParityErr	RX parity error detection.

Definition at line 34 of file dif_uart.h.

◆ dif_uart_loopback

enum dif_uart_loopback

UART System/Line loopback enumeration.

Enumerator
kDifUartLoopbackSystem	Outgoing TX bits received through RX.
kDifUartLoopbackLine	Incoming RX bits are forwarded to TX.

Definition at line 74 of file dif_uart.h.

◆ dif_uart_parity

enum dif_uart_parity

UART parity enumeration.

Enumeration used to convey parity information

Enumerator
kDifUartParityOdd	odd.
kDifUartParityEven	even.

Definition at line 94 of file dif_uart.h.

◆ dif_uart_result

enum dif_uart_result

Uart generic status codes.

These error codes can be used by any function. However if a function requires additional status codes, it must define a set of status codes to be used exclusicvely by such function.

Enumerator
kDifUartOk	Success.
kDifUartError	General error.
kDifUartBadArg	Input parameter is not valid.

Definition at line 128 of file dif_uart.h.

◆ dif_uart_watermark

enum dif_uart_watermark

TX and RX FIFO depth configuration.

Enumeration used to set the upper limit of bytes to queue.

Enumerator
kDifUartWatermarkByte1	1 byte.
kDifUartWatermarkByte4	4 bytes.
kDifUartWatermarkByte8	8 bytes.
kDifUartWatermarkByte16	16 bytes.
kDifUartWatermarkByte30	30 bytes.

Definition at line 52 of file dif_uart.h.

Function Documentation

◆ dif_uart_byte_receive_polled()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_byte_receive_polled	(	const dif_uart_t *	uart,
		uint8_t *	byte
	)

Receive a single UART byte (polled).

Receive a single UART byte and store it in byte. This operation is polled, and will busy wait until a byte has been read. Must not be used inside an ISR.

Parameters

uart	UART state data.
byte	Received byte.

Returns: dif_uart_result_t.

Definition at line 321 of file dif_uart.c.

◆ dif_uart_byte_send_polled()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_byte_send_polled	(	const dif_uart_t *	uart,
		uint8_t	byte
	)

Transmit a single UART byte (polled).

Transmit a single UART byte byte. This operation is polled, and will busy wait until a byte has been sent. Must not be used inside an ISR.

Parameters

uart	UART state data.
byte	Byte to be transmitted.

Returns: dif_uart_result_t.

Definition at line 301 of file dif_uart.c.

◆ dif_uart_bytes_receive()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_bytes_receive	(	const dif_uart_t *	uart,
		size_t	bytes_requested,
		uint8_t *	data,
		size_t *	bytes_read
	)

UART receive bytes.

Non-blocking UART receive bytes routine. 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	UART state data.
bytes_requested	Number of bytes requested to be read by the caller.
data	Data to be read.
bytes_read	Number of bytes read (optional).

Returns: dif_uart_result_t

Definition at line 285 of file dif_uart.c.

◆ dif_uart_bytes_send()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_bytes_send	(	const dif_uart_t *	uart,
		const uint8_t *	data,
		size_t	bytes_requested,
		size_t *	bytes_written
	)

UART send bytes.

Non-blocking UART send bytes routine. 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	UART state data.
data	Data to be written.
bytes_requested	Number of bytes requested to be written by the caller.
bytes_written	Number of bytes written (optional).

Returns: dif_uart_result_t.

Definition at line 268 of file dif_uart.c.

◆ dif_uart_configure()

DIF_WARN_UNUSED_RESULT dif_uart_config_result_t dif_uart_configure	(	const dif_uart_t *	uart,
		const dif_uart_config_t *	config
	)

Configure an instance of UART.

Configure UART using the configuration data in config. This operation performs fundamental configuration.

Parameters

uart	UART state data.
config	UART configuration data.

Returns: dif_uart_config_result_t.

Definition at line 183 of file dif_uart.c.

◆ dif_uart_fifo_reset()

dif_uart_result_t dif_uart_fifo_reset	(	const dif_uart_t *	uart,
		dif_uart_fifo_reset_t	reset
	)

UART TX reset RX/TX FIFO.

Reset both FIFOs, or the requested one.

Parameters

uart	UART state data.
reset	FIFO to reset (RX or TX).

Returns: dif_uart_result_t.

Definition at line 479 of file dif_uart.c.

◆ dif_uart_init()

DIF_WARN_UNUSED_RESULT dif_uart_config_result_t dif_uart_init	(	mmio_region_t	base_addr,
		const dif_uart_config_t *	config,
		dif_uart_t *	uart
	)

Initialise an instance of UART.

Initialise UART instance using the configuration data in config. Information that must be retained, and is required to program UART must be stored in uart.

Parameters

base_addr	Base address of an instance of UART IP block.
config	UART configuration data.
uart	UART state data.

Returns: dif_uart_config_result_t.

Definition at line 171 of file dif_uart.c.

◆ dif_uart_irq_enable()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_enable	(	const dif_uart_t *	uart,
		dif_uart_interrupt_t	irq_type,
		dif_uart_enable_t	enable
	)

UART interrupt control.

Enable/disable an UART interrupt specified in enable.

Parameters

uart	UART state data.
irq_type	UART interrupt type.
enable	enable or disable the interrupt.

Returns: dif_uart_result_t.

Definition at line 407 of file dif_uart.c.

◆ dif_uart_irq_force()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_force	(	const dif_uart_t *	uart,
		dif_uart_interrupt_t	irq_type
	)

UART interrupt force.

Force interrupt specified in irq_type.

Parameters

uart	UART state data.
irq_type	UART interrupt type to be forced.

Returns: dif_uart_result_t.

Definition at line 431 of file dif_uart.c.

◆ dif_uart_irq_state_clear()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_state_clear	(	const dif_uart_t *	uart,
		dif_uart_interrupt_t	irq_type
	)

UART clear requested IRQ state.

Clear the state of the requested IRQ in irq_type. Primary use of this function is to de-assert the interrupt after it has been serviced.

Parameters

uart	UART state data.
irq_type	IRQ to be de-asserted.

Returns: dif_uart_result_t.

Definition at line 360 of file dif_uart.c.

◆ dif_uart_irq_state_get()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_state_get	(	const dif_uart_t *	uart,
		dif_uart_interrupt_t	irq_type,
		dif_uart_enable_t *	state
	)

UART get requested IRQ state.

Get the state of the requested IRQ in irq_type.

Parameters

uart	UART state data.
irq_type	IRQ to get the state of.
state	IRQ state passed back to the caller.

Returns: dif_uart_result_t.

Definition at line 336 of file dif_uart.c.

◆ dif_uart_irqs_disable()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irqs_disable	(	const dif_uart_t *	uart,
		uint32_t *	state
	)

UART disable interrupts.

Disable generation of all UART interrupts, and pass previous interrupt state in state back to the caller. Parameter state is ignored if NULL.

Parameters

uart	UART state data.
state	IRQ state passed back to the caller.

Returns: 'dif_uart_result_t'.

Definition at line 378 of file dif_uart.c.

◆ dif_uart_irqs_restore()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irqs_restore	(	const dif_uart_t *	uart,
		uint32_t	state
	)

UART restore IRQ state.

Restore previous UART IRQ state. This function is used to restore the UART interrupt state prior to dif_uart_irqs_disable function call.

Parameters

uart	UART state data.
state	IRQ state to restore.

Returns: 'dif_uart_result_t'.

Definition at line 395 of file dif_uart.c.

◆ dif_uart_loopback_set()

dif_uart_result_t dif_uart_loopback_set	(	const dif_uart_t *	uart,
		dif_uart_loopback_t	loopback,
		dif_uart_enable_t	enable
	)

UART enable/disable transmit/receive loopback.

This API can be used for testing purpose. For example, 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	UART state data.
loopback	Loopback type (transmit/receive).
enable	Enable/disable control flag.

Returns: dif_uart_result_t.

Definition at line 508 of file dif_uart.c.

◆ dif_uart_rx_bytes_available()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_rx_bytes_available	(	const dif_uart_t *	uart,
		size_t *	num_bytes
	)

UART RX bytes available.

Get 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	UART state data.
num_bytes	Number of bytes available to be read.

Returns: dif_uart_result_t.

Definition at line 449 of file dif_uart.c.

◆ dif_uart_tx_bytes_available()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_tx_bytes_available	(	const dif_uart_t *	uart,
		size_t *	num_bytes
	)

UART TX bytes available.

Get the number of bytes available to be written to the UART TX FIFO. This function can be used to check FIFO full and empty conditions.

Parameters

uart	UART state data.
num_bytes	Number of bytes available to be written.

Returns: dif_uart_result_t.

Definition at line 463 of file dif_uart.c.

◆ dif_uart_watermark_rx_set()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_watermark_rx_set	(	const dif_uart_t *	uart,
		dif_uart_watermark_t	watermark
	)

Set the RX FIFO watermark.

Set the RX FIFO watermark, 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	UART state data.
watermark	RX FIFO watermark.

Returns: dif_uart_result_t.

Definition at line 192 of file dif_uart.c.

◆ dif_uart_watermark_tx_set()

DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_watermark_tx_set	(	const dif_uart_t *	uart,
		dif_uart_watermark_t	watermark
	)

Set the TX FIFO watermark.

Set the TX FIFO watermark, is only useful when the corresponding interrupt is enabled. When the queued TX FIFO number of bytes falls to or below this level, the TX watermark interrupt is raised.

Parameters

uart	UART state data.
watermark	TX FIFO watermark.

Returns: dif_uart_result_t.

Definition at line 231 of file dif_uart.c.

Data Structures

Typedefs

Enumerations

Functions

Variables

Detailed Description

Data Structure Documentation

◆ dif_uart_config

◆ dif_uart

Typedef Documentation

◆ dif_uart_config_t

◆ dif_uart_enable_t

◆ dif_uart_interrupt_t

◆ dif_uart_parity_t

◆ dif_uart_result_t

◆ dif_uart_t

◆ dif_uart_watermark_t

Enumeration Type Documentation

◆ dif_uart_config_result

◆ dif_uart_enable

◆ dif_uart_fifo_reset

◆ dif_uart_interrupt

◆ dif_uart_loopback

◆ dif_uart_parity

◆ dif_uart_result

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

◆ dif_uart_init()

◆ dif_uart_irq_enable()

◆ dif_uart_irq_force()

◆ dif_uart_irq_state_clear()

◆ dif_uart_irq_state_get()

◆ dif_uart_irqs_disable()

◆ dif_uart_irqs_restore()

◆ dif_uart_loopback_set()

◆ dif_uart_rx_bytes_available()

◆ dif_uart_tx_bytes_available()

◆ dif_uart_watermark_rx_set()

◆ dif_uart_watermark_tx_set()