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

(6f1e775)

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

Runtime configuration for UART.

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

Enumeration Type Documentation

◆ 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 107 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 125 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.

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 73 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 318 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 299 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 283 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 267 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
uartA UART handle.
configRuntime configuration parameters.
Returns
The result of the operation.

Definition at line 90 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 421 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 406 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
uartA UART handle.
fifoThe FIFO to reset (RX, TX or both).
Returns
The result of the operation.

Definition at line 363 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 433 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
uartA UART handle.
loopbackLoopback type (transmit/receive).
enableEnable/disable control flag.
Returns
The result of the operation.

Definition at line 391 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 333 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
uartA UART handle.
datapathThe datapath to set the enablement state of (RX, TX or both).
enabledThe enablement state to set.
Returns
The result of the operation.

Definition at line 234 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 347 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 196 of file dif_uart.c.