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
17 extern "C" {
18 #endif
19 
20 typedef struct uart_inst uart_inst_t;
21 
22 extern uart_inst_t * const uart0;
23 extern uart_inst_t * const uart1;
24 #define uart_default uart0
25 
26 typedef enum {
27     UART_PARITY_NONE,
28     UART_PARITY_EVEN,
29     UART_PARITY_ODD
30 } uart_parity_t;
31 
32 // ----------------------------------------------------------------------------
33 // Setup
34 
35 // Put the UART into a known state, and enable it. Must be called before other
36 // functions.
37 uint 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.
41 void uart_deinit(uart_inst_t *uart);
42 
43 // Set baud rate as close as possible to requested, and return actual rate.
44 uint 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
48 void 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
51 void 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.
54 void 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.
61 size_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.
65 size_t uart_is_readable(uart_inst_t *uart);
66 
67 // Write len bytes directly from src to the UART
68 void 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
71 void uart_read_blocking(uart_inst_t *uart, uint8_t *dst, size_t len);
72 
73 // ----------------------------------------------------------------------------
74 // UART-specific operations and aliases
75 
76 void uart_putc(uart_inst_t *uart, char c);
77 
78 void uart_puts(uart_inst_t *uart, const char *s);
79 
80 char uart_getc(uart_inst_t *uart);
81 
82 // en: assert break condition (TX held low) if true. Clear break condition if false.
83 void uart_set_break(uart_inst_t *uart, bool en);
84 
85 void uart_default_tx_wait_blocking();
86 
87 #ifdef __cplusplus
88 }
89 #endif
90 
91 #endif
92