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

(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"

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

Runtime configuration for UART.

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

Enumeration Type Documentation

◆ 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

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

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

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

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
uartA UART handle.
[out]byteReceived 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
uartA UART handle.
byteByte 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
uartA UART handle.
bytes_requestedNumber of bytes requested to be read by the caller.
[out]dataBuffer for up to bytes_requested bytes of read data.
[out]bytes_readNumber 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
uartA UART handle.
dataData to be written.
bytes_requestedNumber of bytes requested to be written by the caller.
[out]bytes_writtenNumber 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
uartA UART handle.
configRuntime 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
uartA 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
uartA UART handle.
duration_ticksRX 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()

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
uartA UART handle.
resetFIFO 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
uartA UART handle.
[out]statusThe status of the RX timeout control (enabled or disabled).
[out]duration_ticksRX 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_addrBase address of the UART peripheral.
[out]uartOut 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
uartA UART handle.
loopbackLoopback type (transmit/receive).
enableEnable/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
uartA UART handle.
[out]num_bytesNumber 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
uartA UART handle.
[out]num_bytesNumber 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
uartA UART handle.
watermarkRX 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
uartA UART handle.
watermarkTX FIFO watermark.
Returns
The result of the operation.

Definition at line 190 of file dif_uart.c.