hardware_uart

Hardware UART API. More...

Macros
#define	UART_NUM(uart)
	Returns the UART number for a UART instance.
#define	UART_INSTANCE(num)
	Returns the UART instance with the given UART number.
#define	UART_IS_INSTANCE(uart)
	Returns true if the UART instance is one of the h/w UART instances.
#define	UART_DREQ_NUM(uart, is_tx)
	Returns the dreq_num_t used for pacing DMA transfers to or from this UART instance. If is_tx is true, then it is for transfers to the UART else for transfers from the UART.
#define	UART_CLOCK_NUM(uart)
	Returns clock_num_t of the clock for the given UART instance.
#define	UART_FUNCSEL_NUM(uart, gpio)
	Returns gpio_function_t needed to select the UART function for the given UART instance on the given GPIO number.
#define	UART_IRQ_NUM(uart)
	Returns the irq_num_t for processor interrupts from the given UART instance.
#define	UART_RESET_NUM(uart)
	Returns the reset_num_t used to reset a given UART instance.

Typedefs
typedef struct uart_inst	uart_inst_t
	Opaque type representing a UART instance.

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.
static uart_inst_t *	uart_get_instance (uint num)
	Get the UART instance from an instance number.
static uart_hw_t *	uart_get_hw (uart_inst_t *uart)
	Get the real hardware UART instance from a UART instance.
uint	uart_init (uart_inst_t *uart, uint baudrate)
	Initialise a UART.
void	uart_deinit (uart_inst_t *uart)
	DeInitialise a UART.
uint	uart_set_baudrate (uart_inst_t *uart, uint baudrate)
	Set UART baud rate.
static void	uart_set_hw_flow (uart_inst_t *uart, bool cts, bool rts)
	Set UART flow control CTS/RTS.
void	uart_set_format (uart_inst_t *uart, uint data_bits, uint stop_bits, uart_parity_t parity)
	Set UART data format.
static void	uart_set_irqs_enabled (uart_inst_t *uart, bool rx_has_data, bool tx_needs_data)
	Enable/Disable UART interrupt outputs.
static bool	uart_is_enabled (uart_inst_t *uart)
	Test if specific UART is enabled.
void	uart_set_fifo_enabled (uart_inst_t *uart, bool enabled)
	Enable/Disable the FIFOs on specified UART.
static bool	uart_is_writable (uart_inst_t *uart)
	Determine if space is available in the TX FIFO.
static void	uart_tx_wait_blocking (uart_inst_t *uart)
	Wait for the UART TX fifo to be drained.
static bool	uart_is_readable (uart_inst_t *uart)
	Determine whether data is waiting in the RX FIFO.
static void	uart_write_blocking (uart_inst_t *uart, const uint8_t *src, size_t len)
	Write to the UART for transmission.
static void	uart_read_blocking (uart_inst_t *uart, uint8_t *dst, size_t len)
	Read from the UART.
static void	uart_putc_raw (uart_inst_t *uart, char c)
	Write single character to UART for transmission.
static void	uart_putc (uart_inst_t *uart, char c)
	Write single character to UART for transmission, with optional CR/LF conversions.
static void	uart_puts (uart_inst_t *uart, const char *s)
	Write string to UART for transmission, doing any CR/LF conversions.
static char	uart_getc (uart_inst_t *uart)
	Read a single character from the UART.
void	uart_set_break (uart_inst_t *uart, bool en)
	Assert a break condition on the UART transmission.
void	uart_set_translate_crlf (uart_inst_t *uart, bool translate)
	Set CR/LF conversion on UART.
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.
static uint	uart_get_dreq_num (uart_inst_t *uart, bool is_tx)
	Return the dreq_num_t to use for pacing transfers to/from a particular UART instance.
static uint	uart_get_reset_num (uart_inst_t *uart)
	Return the reset_num_t to use to reset a particular UART instance.
#define	uart0   ((uart_inst_t *)uart0_hw)
	Identifier for UART instance 0.
#define	uart1   ((uart_inst_t *)uart1_hw)
	Identifier for UART instance 1.

Detailed Description

Hardware UART API.

RP-series microcontrollers have 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() {
 
    // Set the GPIO pin mux to the UART - pin 0 is TX, 1 is RX; note use of UART_FUNCSEL_NUM for the general
    // case where the func sel used for UART depends on the pin number
    // Do this before calling uart_init to avoid losing data
    gpio_set_function(0, UART_FUNCSEL_NUM(uart0, 0));
    gpio_set_function(1, UART_FUNCSEL_NUM(uart0, 1));
 
    // Initialise UART 0
    uart_init(uart0, 115200);
 
    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)

UART_CLOCK_NUM

#define UART_CLOCK_NUM

(

uart

)

Returns clock_num_t of the clock for the given UART instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_DREQ_NUM

#define UART_DREQ_NUM	(		uart,
			is_tx
	)

Returns the dreq_num_t used for pacing DMA transfers to or from this UART instance. If is_tx is true, then it is for transfers to the UART else for transfers from the UART.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_FUNCSEL_NUM

#define UART_FUNCSEL_NUM	(		uart,
			gpio
	)

Returns gpio_function_t needed to select the UART function for the given UART instance on the given GPIO number.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_INSTANCE

#define UART_INSTANCE

(

num

)

Returns the UART instance with the given UART number.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_IRQ_NUM

#define UART_IRQ_NUM

(

uart

)

Returns the irq_num_t for processor interrupts from the given UART instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_IS_INSTANCE

#define UART_IS_INSTANCE

(

uart

)

Returns true if the UART instance is one of the h/w UART instances.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_NUM

#define UART_NUM

(

uart

)

Returns the UART number for a UART instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

UART_RESET_NUM

#define UART_RESET_NUM

(

uart

)

Returns the reset_num_t used to reset a given UART instance.

Note this macro is intended to resolve at compile time, and does no parameter checking

Typedef Documentation

uart_inst_t

typedef struct uart_inst uart_inst_t

Opaque type representing a UART instance.

Use uart0 or uart1 rather than constructing this directly.

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_num()

static uint uart_get_dreq_num ( uart_inst_t *  uart, bool  is_tx  )

inlinestatic

Return the dreq_num_t 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_hw()

static uart_hw_t * uart_get_hw ( uart_inst_t *  uart )

inlinestatic

Get the real hardware UART instance from a UART instance.

This extra level of abstraction was added to facilitate adding PIO UARTs in the future. It currently does nothing, and costs nothing.

Parameters

uart	UART instance

Returns

The uart_hw_t pointer to the UART instance registers

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_get_instance()

static uart_inst_t * uart_get_instance ( uint  num )

inlinestatic

Get the UART instance from an instance number.

Parameters

num	Number of UART, 0 or 1

Returns

UART instance

uart_get_reset_num()

static uint uart_get_reset_num ( uart_inst_t *  uart )

inlinestatic

Return the reset_num_t to use to reset a particular UART instance.

Parameters

uart	UART instance. uart0 or uart1

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 to the UART transmit buffer

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 to the UART transmit buffer

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 to the UART transmit buffer

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_irqs_enabled()

static void uart_set_irqs_enabled ( uart_inst_t *  uart, bool  rx_has_data, bool  tx_needs_data  )

inlinestatic

Enable/Disable UART interrupt outputs.

Enable/Disable the UART's interrupt outputs. An interrupt handler should 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 transmit buffer hardware. Note: Serial data transmission will continue until the Tx FIFO and the transmit shift register (not programmer-accessible) are empty. To ensure the UART FIFO has been emptied, you can use uart_tx_wait_blocking()

Parameters

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