hardware_uart

Hardware UART API. More...

Enumerations

enum  uart_parity_t { UART_PARITY_NONE, UART_PARITY_EVEN, UART_PARITY_ODD }
 UART Parity enumeration.
 

Functions

static uint uart_get_index (uart_inst_t *uart)
 Convert UART instance to hardware instance number. More...
 
uint uart_init (uart_inst_t *uart, uint baudrate)
 Initialise a UART. More...
 
void uart_deinit (uart_inst_t *uart)
 DeInitialise a UART. More...
 
uint uart_set_baudrate (uart_inst_t *uart, uint baudrate)
 Set UART baud rate. More...
 
static void uart_set_hw_flow (uart_inst_t *uart, bool cts, bool rts)
 Set UART flow control CTS/RTS. More...
 
static void uart_set_format (uart_inst_t *uart, uint data_bits, uint stop_bits, uart_parity_t parity)
 Set UART data format. More...
 
static void uart_set_irq_enables (uart_inst_t *uart, bool rx_has_data, bool tx_needs_data)
 Setup UART interrupts. More...
 
static bool uart_is_enabled (uart_inst_t *uart)
 Test if specific UART is enabled. More...
 
static void uart_set_fifo_enabled (uart_inst_t *uart, bool enabled)
 Enable/Disable the FIFOs on specified UART. More...
 
static bool uart_is_writable (uart_inst_t *uart)
 Determine if space is available in the TX FIFO. More...
 
static void uart_tx_wait_blocking (uart_inst_t *uart)
 Wait for the UART TX fifo to be drained. More...
 
static bool uart_is_readable (uart_inst_t *uart)
 Determine whether data is waiting in the RX FIFO. More...
 
static void uart_write_blocking (uart_inst_t *uart, const uint8_t *src, size_t len)
 Write to the UART for transmission. More...
 
static void uart_read_blocking (uart_inst_t *uart, uint8_t *dst, size_t len)
 Read from the UART. More...
 
static void uart_putc_raw (uart_inst_t *uart, char c)
 Write single character to UART for transmission. More...
 
static void uart_putc (uart_inst_t *uart, char c)
 Write single character to UART for transmission, with optional CR/LF conversions. More...
 
static void uart_puts (uart_inst_t *uart, const char *s)
 Write string to UART for transmission, doing any CR/LF conversions. More...
 
static char uart_getc (uart_inst_t *uart)
 Read a single character to UART. More...
 
static void uart_set_break (uart_inst_t *uart, bool en)
 Assert a break condition on the UART transmission. More...
 
void uart_set_translate_crlf (uart_inst_t *uart, bool translate)
 Set CR/LF conversion on UART. More...
 
static void uart_default_tx_wait_blocking (void)
 Wait for the default UART's TX FIFO to be drained.
 
bool uart_is_readable_within_us (uart_inst_t *uart, uint32_t us)
 Wait for up to a certain number of microseconds for the RX FIFO to be non empty. More...
 
static uint uart_get_dreq (uart_inst_t *uart, bool is_tx)
 Return the DREQ to use for pacing transfers to/from a particular UART instance. More...
 
#define uart0   ((uart_inst_t * const)uart0_hw)
 Identifier for UART instance 0. More...
 
#define uart1   ((uart_inst_t * const)uart1_hw)
 Identifier for UART instance 1.
 

Detailed Description

Hardware UART API.

RP2040 has 2 identical instances of a UART peripheral, based on the ARM PL011. Each UART can be connected to a number of GPIO pins as defined in the GPIO muxing.

Only the TX, RX, RTS, and CTS signals are connected, meaning that the modem mode and IrDA mode of the PL011 are not supported.

Example

int main() {
// Initialise UART 0
uart_init(uart0, 115200);
// Set the GPIO pin mux to the UART - 0 is TX, 1 is RX
gpio_set_function(0, GPIO_FUNC_UART);
gpio_set_function(1, GPIO_FUNC_UART);
uart_puts(uart0, "Hello world!");
}

Macro Definition Documentation

◆ uart0

#define uart0   ((uart_inst_t * const)uart0_hw)

Identifier for UART instance 0.

The UART identifiers for use in UART functions.

e.g. uart_init(uart1, 48000)

Function Documentation

◆ uart_deinit()

void uart_deinit ( uart_inst_t *  uart)

DeInitialise a UART.

Disable the UART if it is no longer used. Must be reinitialised before being used again.

Parameters
uartUART instance. uart0 or uart1

◆ uart_get_dreq()

static uint uart_get_dreq ( uart_inst_t *  uart,
bool  is_tx 
)
inlinestatic

Return the DREQ to use for pacing transfers to/from a particular UART instance.

Parameters
uartUART instance. uart0 or uart1
is_txtrue for sending data to the UART instance, false for receiving data from the UART instance

◆ uart_get_index()

static uint uart_get_index ( uart_inst_t *  uart)
inlinestatic

Convert UART instance to hardware instance number.

Parameters
uartUART instance
Returns
Number of UART, 0 or 1.

◆ uart_getc()

static char uart_getc ( uart_inst_t *  uart)
inlinestatic

Read a single character to UART.

This function will block until the character has been read

Parameters
uartUART instance. uart0 or uart1
Returns
The character read.

◆ uart_init()

uint uart_init ( uart_inst_t *  uart,
uint  baudrate 
)

Initialise a UART.

Put the UART into a known state, and enable it. Must be called before other functions.

Note
There is no guarantee that the baudrate requested will be possible, the nearest will be chosen, and this function will return the configured baud rate.
Parameters
uartUART instance. uart0 or uart1
baudrateBaudrate of UART in Hz
Returns
Actual set baudrate

◆ uart_is_enabled()

static bool uart_is_enabled ( uart_inst_t *  uart)
inlinestatic

Test if specific UART is enabled.

Parameters
uartUART instance. uart0 or uart1
Returns
true if the UART is enabled

◆ uart_is_readable()

static bool uart_is_readable ( uart_inst_t *  uart)
inlinestatic

Determine whether data is waiting in the RX FIFO.

Parameters
uartUART instance. uart0 or uart1
Returns
0 if no data available, otherwise the number of bytes, at least, that can be read
Note
HW limitations mean this function will return either 0 or 1.

◆ uart_is_readable_within_us()

bool uart_is_readable_within_us ( uart_inst_t *  uart,
uint32_t  us 
)

Wait for up to a certain number of microseconds for the RX FIFO to be non empty.

Parameters
uartUART instance. uart0 or uart1
usthe number of microseconds to wait at most (may be 0 for an instantaneous check)
Returns
true if the RX FIFO became non empty before the timeout, false otherwise

◆ uart_is_writable()

static bool uart_is_writable ( uart_inst_t *  uart)
inlinestatic

Determine if space is available in the TX FIFO.

Parameters
uartUART instance. uart0 or uart1
Returns
false if no space available, true otherwise

◆ uart_putc()

static void uart_putc ( uart_inst_t *  uart,
char  c 
)
inlinestatic

Write single character to UART for transmission, with optional CR/LF conversions.

This function will block until the character has been sent

Parameters
uartUART instance. uart0 or uart1
cThe character to send

◆ uart_putc_raw()

static void uart_putc_raw ( uart_inst_t *  uart,
char  c 
)
inlinestatic

Write single character to UART for transmission.

This function will block until the entire character has been sent

Parameters
uartUART instance. uart0 or uart1
cThe character to send

◆ uart_puts()

static void uart_puts ( uart_inst_t *  uart,
const char *  s 
)
inlinestatic

Write string to UART for transmission, doing any CR/LF conversions.

This function will block until the entire string has been sent

Parameters
uartUART instance. uart0 or uart1
sThe null terminated string to send

◆ uart_read_blocking()

static void uart_read_blocking ( uart_inst_t *  uart,
uint8_t *  dst,
size_t  len 
)
inlinestatic

Read from the UART.

This function will block until all the data has been received from the UART

Parameters
uartUART instance. uart0 or uart1
dstBuffer to accept received bytes
lenThe number of bytes to receive.

◆ uart_set_baudrate()

uint uart_set_baudrate ( uart_inst_t *  uart,
uint  baudrate 
)

Set UART baud rate.

Set baud rate as close as possible to requested, and return actual rate selected.

Parameters
uartUART instance. uart0 or uart1
baudrateBaudrate in Hz
Returns
Actual set baudrate

◆ uart_set_break()

static void uart_set_break ( uart_inst_t *  uart,
bool  en 
)
inlinestatic

Assert a break condition on the UART transmission.

Parameters
uartUART instance. uart0 or uart1
enAssert break condition (TX held low) if true. Clear break condition if false.

◆ uart_set_fifo_enabled()

static void uart_set_fifo_enabled ( uart_inst_t *  uart,
bool  enabled 
)
inlinestatic

Enable/Disable the FIFOs on specified UART.

Parameters
uartUART instance. uart0 or uart1
enabledtrue to enable FIFO (default), false to disable

◆ uart_set_format()

static void uart_set_format ( uart_inst_t *  uart,
uint  data_bits,
uint  stop_bits,
uart_parity_t  parity 
)
inlinestatic

Set UART data format.

Configure the data format (bits etc() for the UART

Parameters
uartUART instance. uart0 or uart1
data_bitsNumber of bits of data. 5..8
stop_bitsNumber of stop bits 1..2
parityParity option.

◆ uart_set_hw_flow()

static void uart_set_hw_flow ( uart_inst_t *  uart,
bool  cts,
bool  rts 
)
inlinestatic

Set UART flow control CTS/RTS.

Parameters
uartUART instance. uart0 or uart1
ctsIf true enable flow control of TX by clear-to-send input
rtsIf true enable assertion of request-to-send output by RX flow control

◆ uart_set_irq_enables()

static void uart_set_irq_enables ( uart_inst_t *  uart,
bool  rx_has_data,
bool  tx_needs_data 
)
inlinestatic

Setup UART interrupts.

Enable the UART's interrupt output. An interrupt handler will need to be installed prior to calling this function.

Parameters
uartUART instance. uart0 or uart1
rx_has_dataIf true an interrupt will be fired when the RX FIFO contains data.
tx_needs_dataIf true an interrupt will be fired when the TX FIFO needs data.

◆ uart_set_translate_crlf()

void uart_set_translate_crlf ( uart_inst_t *  uart,
bool  translate 
)

Set CR/LF conversion on UART.

Parameters
uartUART instance. uart0 or uart1
translateIf true, convert line feeds to carriage return on transmissions

◆ uart_tx_wait_blocking()

static void uart_tx_wait_blocking ( uart_inst_t *  uart)
inlinestatic

Wait for the UART TX fifo to be drained.

Parameters
uartUART instance. uart0 or uart1

◆ uart_write_blocking()

static void uart_write_blocking ( uart_inst_t *  uart,
const uint8_t *  src,
size_t  len 
)
inlinestatic

Write to the UART for transmission.

This function will block until all the data has been sent to the UART

Parameters
uartUART instance. uart0 or uart1
srcThe bytes to send
lenThe number of bytes to send
uart0
#define uart0
Identifier for UART instance 0.
Definition: uart.h:81
gpio_set_function
void gpio_set_function(uint gpio, enum gpio_function fn)
Select GPIO function.
Definition: gpio.c:30
uart_init
uint uart_init(uart_inst_t *uart, uint baudrate)
Initialise a UART.
Definition: uart.c:39
uart_puts
static void uart_puts(uart_inst_t *uart, const char *s)
Write string to UART for transmission, doing any CR/LF conversions.
Definition: uart.h:364