Software APIs
Data Structures | Typedefs | Enumerations | Functions | Variables
dif_uart.h File Reference

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"

Go to the source code of this file.

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

UART configuration data.

The fundamental data used to configure an UART instance.

◆ dif_uart_enable_t

Generic enable/disable enumeration.

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

◆ 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

UART parity enumeration.

Enumeration used to convey parity information

◆ 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

TX and RX FIFO depth configuration.

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

Enumeration Type Documentation

◆ 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

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

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

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

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

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

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

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
uartUART state data.
byteReceived 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
uartUART state data.
byteByte 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
uartUART state data.
bytes_requestedNumber of bytes requested to be read by the caller.
dataData to be read.
bytes_readNumber 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
uartUART state data.
dataData to be written.
bytes_requestedNumber of bytes requested to be written by the caller.
bytes_writtenNumber 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
uartUART state data.
configUART configuration data.
Returns
dif_uart_config_result_t.

Definition at line 183 of file dif_uart.c.

◆ dif_uart_fifo_reset()

UART TX reset RX/TX FIFO.

Reset both FIFOs, or the requested one.

Parameters
uartUART state data.
resetFIFO 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_addrBase address of an instance of UART IP block.
configUART configuration data.
uartUART 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
uartUART state data.
irq_typeUART interrupt type.
enableenable 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
uartUART state data.
irq_typeUART 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
uartUART state data.
irq_typeIRQ 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
uartUART state data.
irq_typeIRQ to get the state of.
stateIRQ 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
uartUART state data.
stateIRQ 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
uartUART state data.
stateIRQ 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
uartUART state data.
loopbackLoopback type (transmit/receive).
enableEnable/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
uartUART state data.
num_bytesNumber 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
uartUART state data.
num_bytesNumber 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
uartUART state data.
watermarkRX 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
uartUART state data.
watermarkTX FIFO watermark.
Returns
dif_uart_result_t.

Definition at line 231 of file dif_uart.c.