uart.h
1/*
2 * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3 *
4 * SPDX-License-Identifier: BSD-3-Clause
5 */
6
7#ifndef _HARDWARE_UART_H
8#define _HARDWARE_UART_H
9
10#include "pico.h"
11
12#ifndef PARAM_ASSERTIONS_ENABLED_UART
13#define PARAM_ASSERTIONS_ENABLED_UART 0
14#endif
15
16#ifdef __cplusplus
17extern "C" {
18#endif
19
20typedef struct uart_inst uart_inst_t;
21
22extern uart_inst_t * const uart0;
23extern uart_inst_t * const uart1;
24#define uart_default uart0
25
26typedef enum {
27 UART_PARITY_NONE,
28 UART_PARITY_EVEN,
29 UART_PARITY_ODD
31
32// ----------------------------------------------------------------------------
33// Setup
34
35// Put the UART into a known state, and enable it. Must be called before other
36// functions.
37uint uart_init(uart_inst_t *uart, uint baudrate);
38
39// Disable the UART if it is no longer used. Must be reinitialised before
40// being used again.
41void uart_deinit(uart_inst_t *uart);
42
43// Set baud rate as close as possible to requested, and return actual rate.
44uint uart_set_baudrate(uart_inst_t *uart, uint baudrate);
45
46// cts: enable flow control of TX by clear-to-send input
47// rts: enable assertion of request-to-send output by RX flow control
48void uart_set_hw_flow(uart_inst_t *uart, bool cts, bool rts);
49
50// Configure how the UART serialises and deserialises data on the wire
51void uart_set_format(uart_inst_t *uart, uint data_bits, uint stop_bits, uart_parity_t parity);
52
53// Enable the UART's interrupt output. Need to install an interrupt handler first.
54void uart_set_irq_enables(uart_inst_t *uart, bool rx_has_data, bool tx_needs_data);
55
56// ----------------------------------------------------------------------------
57// Generic input/output
58
59// If returns 0, no space is available in the UART to write more data.
60// If returns nonzero, at least that many bytes can be written without blocking.
61size_t uart_is_writable(uart_inst_t *uart);
62
63// If returns 0, no data is available to be read from UART.
64// If returns nonzero, at least that many bytes can be written without blocking.
65size_t uart_is_readable(uart_inst_t *uart);
66
67// Write len bytes directly from src to the UART
68void uart_write_blocking(uart_inst_t *uart, const uint8_t *src, size_t len);
69
70// Read len bytes directly from the UART to dst
71void uart_read_blocking(uart_inst_t *uart, uint8_t *dst, size_t len);
72
73// ----------------------------------------------------------------------------
74// UART-specific operations and aliases
75
76void uart_putc(uart_inst_t *uart, char c);
77
78void uart_puts(uart_inst_t *uart, const char *s);
79
80char uart_getc(uart_inst_t *uart);
81
82// en: assert break condition (TX held low) if true. Clear break condition if false.
83void uart_set_break(uart_inst_t *uart, bool en);
84
86
87#ifdef __cplusplus
88}
89#endif
90
91#endif
static void uart_putc(uart_inst_t *uart, char c)
Write single character to UART for transmission, with optional CR/LF conversions.
Definition: uart.h:347
static void uart_set_format(uart_inst_t *uart, uint data_bits, uint stop_bits, uart_parity_t parity)
Set UART data format.
Definition: uart.h:187
static bool uart_is_readable(uart_inst_t *uart)
Determine whether data is waiting in the RX FIFO.
Definition: uart.h:285
#define uart0
The UART identifiers for use in UART functions.
Definition: uart.h:81
static void uart_set_hw_flow(uart_inst_t *uart, bool cts, bool rts)
Set UART flow control CTS/RTS.
Definition: uart.h:171
static void uart_set_break(uart_inst_t *uart, bool en)
Assert a break condition on the UART transmission.
Definition: uart.h:401
uint uart_init(uart_inst_t *uart, uint baudrate)
Initialise a UART.
Definition: uart.c:75
static char uart_getc(uart_inst_t *uart)
Read a single character to UART.
Definition: uart.h:389
uart_parity_t
UART Parity enumeration.
Definition: uart.h:119
void uart_deinit(uart_inst_t *uart)
DeInitialise a UART.
Definition: uart.c:67
static void uart_set_irq_enables(uart_inst_t *uart, bool rx_has_data, bool tx_needs_data)
Setup UART interrupts.
Definition: uart.h:212
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
static bool uart_is_writable(uart_inst_t *uart)
Determine if space is available in the TX FIFO.
Definition: uart.h:264
static void uart_default_tx_wait_blocking(void)
Wait for the default UART's TX FIFO to be drained.
Definition: uart.h:419
uint uart_set_baudrate(uart_inst_t *uart, uint baudrate)
Set UART baud rate.
Definition: uart.c:73
#define uart1
Identifier for UART instance 1.
Definition: uart.h:82
static void uart_write_blocking(uart_inst_t *uart, const uint8_t *src, size_t len)
Write to the UART for transmission.
Definition: uart.h:299
static void uart_read_blocking(uart_inst_t *uart, uint8_t *dst, size_t len)
Read from the UART.
Definition: uart.h:316