UART Device Interface Functions More...
#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_params |
Hardware instantiation parameters for UART. More... | |
struct | dif_uart_config |
Runtime configuration for UART. More... | |
struct | dif_uart |
A handle to UART. More... | |
Typedefs | |
typedef enum dif_uart_toggle | dif_uart_toggle_t |
A toggle state: enabled, or disabled. More... | |
typedef enum dif_uart_parity | dif_uart_parity_t |
A parity state: odd, or even. | |
typedef struct dif_uart_params | dif_uart_params_t |
Hardware instantiation parameters for UART. More... | |
typedef struct dif_uart_config | dif_uart_config_t |
Runtime configuration for UART. More... | |
typedef struct dif_uart | dif_uart_t |
A handle to UART. More... | |
typedef enum dif_uart_result | dif_uart_result_t |
The result of a UART operation. | |
typedef enum dif_uart_config_result | dif_uart_config_result_t |
The result of a UART operation. | |
typedef enum dif_uart_irq | dif_uart_irq_t |
A UART interrupt request type. | |
typedef uint32_t | dif_uart_irq_snapshot_t |
A snapshot of the enablement state of the interrupts for UART. More... | |
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. | |
Variables | |
const uint32_t | kDifUartFifoSizeBytes |
The size of the UART TX and RX FIFOs, in bytes. | |
UART Device Interface Functions
Definition in file dif_uart.h.
struct dif_uart_params |
Hardware instantiation parameters for UART.
This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.
Definition at line 60 of file dif_uart.h.
Data Fields | ||
---|---|---|
mmio_region_t | base_addr | The base address for the UART hardware registers. |
struct dif_uart_config |
Runtime configuration for UART.
This struct describes runtime information for one-time configuration of the hardware.
Definition at line 73 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_uart_toggle_t | parity_enable | Whether to enable parity checking. |
struct dif_uart |
A handle to UART.
This type should be treated as opaque by users.
Definition at line 97 of file dif_uart.h.
Data Fields | ||
---|---|---|
dif_uart_params_t | params |
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.
typedef uint32_t dif_uart_irq_snapshot_t |
A snapshot of the enablement state of the interrupts for UART.
This is an opaque type, to be used with the dif_uart_irq_disable_all()
and dif_uart_irq_restore_all()
functions.
Definition at line 193 of file dif_uart.h.
typedef struct dif_uart_params dif_uart_params_t |
Hardware instantiation parameters for UART.
This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.
typedef struct dif_uart dif_uart_t |
A handle to UART.
This type should be treated as opaque by users.
typedef enum dif_uart_toggle dif_uart_toggle_t |
A toggle state: enabled, or disabled.
This enum may be used instead of a bool
when describing an enabled/disabled state.
The result of a UART operation.
Definition at line 123 of file dif_uart.h.
enum dif_uart_fifo_reset |
A UART FIFO reset selection.
Definition at line 224 of file dif_uart.h.
enum dif_uart_irq |
A UART interrupt request type.
Definition at line 152 of file dif_uart.h.
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 242 of file dif_uart.h.
enum dif_uart_parity |
A parity state: odd, or even.
Enumerator | |
---|---|
kDifUartParityOdd | Indicates the "odd" parity. |
kDifUartParityEven | Indicates the "even" parity. |
Definition at line 42 of file dif_uart.h.
enum dif_uart_result |
The result of a UART operation.
Definition at line 102 of file dif_uart.h.
enum dif_uart_toggle |
A toggle state: enabled, or disabled.
This enum may be used instead of a bool
when describing an enabled/disabled state.
Enumerator | |
---|---|
kDifUartToggleEnabled | The "enabled" state. |
kDifUartToggleDisabled | The "disabled" state. |
Definition at line 28 of file dif_uart.h.
enum dif_uart_watermark |
A UART FIFO watermark depth configuration.
Definition at line 198 of file dif_uart.h.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. | |
[out] | byte | Received byte. |
Definition at line 452 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. |
byte | Byte to be transmitted. |
Definition at line 432 of file dif_uart.c.
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 | ||
) |
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.
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). |
Definition at line 416 of file dif_uart.c.
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 | ||
) |
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.
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). |
Definition at line 399 of file dif_uart.c.
DIF_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
.
uart | A UART handle. |
config | Runtime configuration parameters. |
Definition at line 143 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. |
Definition at line 550 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_enable_rx_timeout | ( | const dif_uart_t * | uart, |
uint32_t | duration_ticks | ||
) |
Enables the RX timeout with the given duration.
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]. |
Definition at line 535 of file dif_uart.c.
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.
Resets one or both FIFOs. If the byte is in transit, this function will not abort the operation.
uart | A UART handle. |
reset | FIFO to reset (RX, TX or both). |
Definition at line 497 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_get_rx_timeout | ( | const dif_uart_t * | uart, |
dif_uart_toggle_t * | status, | ||
uint32_t * | duration_ticks | ||
) |
Gets the current status of the RX timeout control.
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). |
Definition at line 563 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_init | ( | dif_uart_params_t | params, |
dif_uart_t * | uart | ||
) |
Creates a new handle for UART.
This function does not actuate the hardware.
params | Hardware instantiation parameters. |
uart | Out param for the initialized handle. |
Definition at line 134 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_acknowledge | ( | const dif_uart_t * | uart, |
dif_uart_irq_t | irq | ||
) |
Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.
uart | A UART handle. |
irq | An interrupt type. |
Definition at line 217 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_disable_all | ( | const dif_uart_t * | uart, |
dif_uart_irq_snapshot_t * | snapshot | ||
) |
Disables all interrupts, optionally snapshotting all toggle state for later restoration.
uart | A UART handle. |
snapshot | Out-param for the snapshot; may be NULL . |
Definition at line 235 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_force | ( | const dif_uart_t * | uart, |
dif_uart_irq_t | irq | ||
) |
Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.
uart | A UART handle. |
irq | An interrupt type. |
Definition at line 307 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_get_enabled | ( | const dif_uart_t * | uart, |
dif_uart_irq_t | irq, | ||
dif_uart_toggle_t * | state | ||
) |
Checks whether a particular interrupt is currently enabled or disabled.
uart | A UART handle. |
irq | An interrupt type. |
state | Out-param toggle state of the interrupt. |
Definition at line 265 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_is_pending | ( | const dif_uart_t * | uart, |
dif_uart_irq_t | irq, | ||
bool * | is_pending | ||
) |
Returns whether a particular interrupt is currently pending.
uart | A UART handle. |
irq | An interrupt type. |
is_pending | Out-param for whether the interrupt is pending. |
Definition at line 198 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_restore_all | ( | const dif_uart_t * | uart, |
const dif_uart_irq_snapshot_t * | snapshot | ||
) |
Restores interrupts from the given snapshot.
This function can be used with dif_uart_irq_disable_all()
to temporary interrupt save-and-restore.
uart | A UART handle. |
snapshot | A snapshot to restore from. |
Definition at line 253 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_result_t dif_uart_irq_set_enabled | ( | const dif_uart_t * | uart, |
dif_uart_irq_t | irq, | ||
dif_uart_toggle_t | state | ||
) |
Sets whether a particular interrupt is currently enabled or disabled.
uart | A UART handle. |
irq | An interrupt type. |
state | The new toggle state for the interrupt. |
Definition at line 286 of file dif_uart.c.
dif_uart_result_t dif_uart_loopback_set | ( | const dif_uart_t * | uart, |
dif_uart_loopback_t | loopback, | ||
dif_uart_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.uart | A UART handle. |
loopback | Loopback type (transmit/receive). |
enable | Enable/disable control flag. |
Definition at line 519 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. | |
[out] | num_bytes | Number of bytes available to be read. |
Definition at line 467 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. | |
[out] | num_bytes | Number of bytes available to be written. |
Definition at line 481 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. |
watermark | RX FIFO watermark. |
Definition at line 325 of file dif_uart.c.
DIF_WARN_UNUSED_RESULT dif_uart_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.
uart | A UART handle. |
watermark | TX FIFO watermark. |
Definition at line 363 of file dif_uart.c.