v2.0.0
Macros | Enumerations | Functions
hardware_uart
Hardware APIs

Hardware UART API. More...

## Macros
#define | UART_NUM(uart)
| Returns the UART number for a UART instance. More...
#define | UART_INSTANCE(num)
| Returns the UART instance with the given UART number. More...
#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. More...
#define | UART_CLOCK_NUM(uart)
| Returns clock_num_t of the clock for the given UART instance. More...
#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. More...
#define | UART_IRQ_NUM(uart)
| Returns the irq_num_t for processor interrupts from the given UART instance. More...
#define | UART_RESET_NUM(uart)
| Returns the reset_num_t used to reset a given UART instance. 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...
static uart_inst_t * | uart_get_instance (uint num)
| Get the UART instance from an instance number. More...
static uart_hw_t * | uart_get_hw (uart_inst_t *uart)
| Get the real hardware UART instance from a UART instance. 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_irqs_enabled (uart_inst_t *uart, bool rx_has_data, bool tx_needs_data)
| Enable/Disable UART interrupt outputs. 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_num (uart_inst_t *uart, bool is_tx)
| Return the dreq_num_t to use for pacing transfers to/from a particular UART instance. More...
static uint | uart_get_reset_num (uart_inst_t *uart)
| Return the reset_num_t 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.

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!");
}
gpio_set_function
void gpio_set_function(uint gpio, gpio_function_t fn)
Select GPIO function.
Definition: gpio.c:38
uart0
#define uart0
Identifier for UART instance 0.
Definition: uart.h:86
uart_init
uint uart_init(uart_inst_t *uart, uint baudrate)
Initialise a UART.
Definition: uart.c:42
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 G...
Definition: uart.h:179
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:524

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

## 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

  uart | UART instance

Returns
  Number of UART, 0 or 1

## ◆ uart_get_reset_num()

static uint uart_get_reset_num | ( | uart_inst_t * | uart | ) |
| inlinestatic

Return the reset_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_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