hardware_uart

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...
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...
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 from the UART. More...
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 *)uart0_hw)
	Identifier for UART instance 0. More...
#define	uart1   ((uart_inst_t *)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 *)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

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

uart	UART instance. uart0 or uart1
is_tx	true 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

uart	UART instance

Returns

Number of UART, 0 or 1.

uart_getc()

static char uart_getc ( uart_inst_t *  uart )

inlinestatic

Read a single character from the UART.

This function will block until a character has been read

Parameters

uart	UART 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.

This function always enables the FIFOs, and configures the UART for the following default line format:

• 8 data bits
• No parity bit
• One stop bit

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

uart	UART instance. uart0 or uart1
baudrate	Baudrate 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

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

uart	UART instance. uart0 or uart1

Returns

true if the RX FIFO is not empty, otherwise false.

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

uart	UART instance. uart0 or uart1
us	the 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

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

uart	UART instance. uart0 or uart1
c	The 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

uart	UART instance. uart0 or uart1
c	The 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

uart	UART instance. uart0 or uart1
s	The 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 blocks until len characters have been read from the UART

Parameters

uart	UART instance. uart0 or uart1
dst	Buffer to accept received bytes
len	The 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.

The UART is paused for around two character periods whilst the settings are changed. Data received during this time may be dropped by the UART.

Any characters still in the transmit buffer will be sent using the new updated baud rate. uart_tx_wait_blocking() can be called before this function to ensure all characters at the old baud rate have been sent before the rate is changed.

This function should not be called from an interrupt context, and the UART interrupt should be disabled before calling this function.

Parameters

uart	UART instance. uart0 or uart1
baudrate	Baudrate in Hz

Returns

Actual set baudrate

uart_set_break()

void uart_set_break	(	uart_inst_t *	uart,
		bool	en
	)

Assert a break condition on the UART transmission.

Parameters

uart	UART instance. uart0 or uart1
en	Assert break condition (TX held low) if true. Clear break condition if false.

uart_set_fifo_enabled()

void uart_set_fifo_enabled	(	uart_inst_t *	uart,
		bool	enabled
	)

Enable/Disable the FIFOs on specified UART.

The UART is paused for around two character periods whilst the settings are changed. Data received during this time may be dropped by the UART.

Any characters still in the transmit FIFO will be lost if the FIFO is disabled. uart_tx_wait_blocking() can be called before this function to avoid this.

This function should not be called from an interrupt context, and the UART interrupt should be disabled when calling this function.

Parameters

uart	UART instance. uart0 or uart1
enabled	true to enable FIFO (default), false to disable

uart_set_format()

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

Set UART data format.

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

The UART is paused for around two character periods whilst the settings are changed. Data received during this time may be dropped by the UART.

Any characters still in the transmit buffer will be sent using the new updated data format. uart_tx_wait_blocking() can be called before this function to ensure all characters needing the old format have been sent before the format is changed.

This function should not be called from an interrupt context, and the UART interrupt should be disabled before calling this function.

Parameters

uart	UART instance. uart0 or uart1
data_bits	Number of bits of data. 5..8
stop_bits	Number of stop bits 1..2
parity	Parity 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

uart	UART instance. uart0 or uart1
cts	If true enable flow control of TX by clear-to-send input
rts	If 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

uart	UART instance. uart0 or uart1
rx_has_data	If true an interrupt will be fired when the RX FIFO contains data.
tx_needs_data	If 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

uart	UART instance. uart0 or uart1
translate	If 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

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

uart	UART instance. uart0 or uart1
src	The bytes to send
len	The number of bytes to send