uart.h
Go to the documentation of this file.
1 /*
2  uart.h - UART HAL
3 
4  Copyright (c) 2014 Ivan Grokhotkov. All rights reserved.
5  This file is part of the esp8266 core for Arduino environment.
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public
9  License as published by the Free Software Foundation; either
10  version 2.1 of the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful,
13  but WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License along with this library; if not, write to the Free Software
19  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
20 
21 */
22 
23 /*
24  * @author 21/8/2018 mikee47 <mike@sillyhouse.net>
25  *
26  * SerialBuffer class added to manage FIFO for both RX and TX
27  * Buffering is optional; if size is 0 will just use Hardware FIFOS (128 bytes each)
28  * For uart_write_xxx functions, if there is no space in the tx FIFO it will return a short count. It will not wait.
29  * Trivial check routines have been moved into this header as static inlines.
30  * Code is now C++ only; reference to this header has been removed from esp_systemapi.h uart structure should be
31  * treated as opaque and only accessed using the functions defined in this header.
32  * Callback is invoked on transmit completion.
33  *
34  * Note: uart_detach_all() should be called at startup, i.e. from user_init().
35  */
36 
37 #pragma once
38 
39 #if defined (__cplusplus)
40 extern "C" {
41 #endif
42 
43 #include <esp_systemapi.h>
44 
51 #define UART0 0
52 #define UART1 1
53 #define UART2 2
54 #define UART_NO -1
55 #define UART_PHYSICAL_COUNT 2
56 #define UART_COUNT 3
57 
58 // Options for `config` argument of uart_init
59 #define UART_NB_BIT_MASK 0B00001100
60 #define UART_NB_BIT_5 0B00000000
61 #define UART_NB_BIT_6 0B00000100
62 #define UART_NB_BIT_7 0B00001000
63 #define UART_NB_BIT_8 0B00001100
64 
65 #define UART_PARITY_MASK 0B00000011
66 #define UART_PARITY_NONE 0B00000000
67 #define UART_PARITY_EVEN 0B00000010
68 #define UART_PARITY_ODD 0B00000011
69 
70 #define UART_NB_STOP_BIT_MASK 0B00110000
71 #define UART_NB_STOP_BIT_0 0B00000000
72 #define UART_NB_STOP_BIT_1 0B00010000
73 #define UART_NB_STOP_BIT_15 0B00100000
74 #define UART_NB_STOP_BIT_2 0B00110000
75 
76 #define UART_5N1 ( UART_NB_BIT_5 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
77 #define UART_6N1 ( UART_NB_BIT_6 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
78 #define UART_7N1 ( UART_NB_BIT_7 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
79 #define UART_8N1 ( UART_NB_BIT_8 | UART_PARITY_NONE | UART_NB_STOP_BIT_1 )
80 #define UART_5N2 ( UART_NB_BIT_5 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
81 #define UART_6N2 ( UART_NB_BIT_6 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
82 #define UART_7N2 ( UART_NB_BIT_7 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
83 #define UART_8N2 ( UART_NB_BIT_8 | UART_PARITY_NONE | UART_NB_STOP_BIT_2 )
84 #define UART_5E1 ( UART_NB_BIT_5 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
85 #define UART_6E1 ( UART_NB_BIT_6 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
86 #define UART_7E1 ( UART_NB_BIT_7 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
87 #define UART_8E1 ( UART_NB_BIT_8 | UART_PARITY_EVEN | UART_NB_STOP_BIT_1 )
88 #define UART_5E2 ( UART_NB_BIT_5 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
89 #define UART_6E2 ( UART_NB_BIT_6 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
90 #define UART_7E2 ( UART_NB_BIT_7 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
91 #define UART_8E2 ( UART_NB_BIT_8 | UART_PARITY_EVEN | UART_NB_STOP_BIT_2 )
92 #define UART_5O1 ( UART_NB_BIT_5 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
93 #define UART_6O1 ( UART_NB_BIT_6 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
94 #define UART_7O1 ( UART_NB_BIT_7 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
95 #define UART_8O1 ( UART_NB_BIT_8 | UART_PARITY_ODD | UART_NB_STOP_BIT_1 )
96 #define UART_5O2 ( UART_NB_BIT_5 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
97 #define UART_6O2 ( UART_NB_BIT_6 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
98 #define UART_7O2 ( UART_NB_BIT_7 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
99 #define UART_8O2 ( UART_NB_BIT_8 | UART_PARITY_ODD | UART_NB_STOP_BIT_2 )
100 
106 };
107 typedef enum uart_mode_ uart_mode_t;
108 
109 typedef uint8_t uart_options_t;
116 };
117 
118 #define UART_RX_FIFO_SIZE 0x80
119 #define UART_TX_FIFO_SIZE 0x80
120 
121 struct uart_;
122 typedef struct uart_ uart_t;
123 
135 typedef void (*uart_callback_t)(uart_t* uart, uint32_t status);
136 
137 
138 /*
139  * Port notifications
140  */
141 
147 
150 
153 
156 
159 };
160 
165 typedef void (*uart_notify_callback_t)(uart_t* uart, uart_notify_code_t code);
166 
173 
174 
175 struct SerialBuffer;
176 
177 struct uart_ {
178  uint8_t uart_nr;
179  uint32_t baud_rate;
180  uart_mode_t mode;
181  uint8_t options;
182  uint8_t rx_pin;
183  uint8_t tx_pin;
184  uint8_t rx_headroom;
186  struct SerialBuffer* rx_buffer;
187  struct SerialBuffer* tx_buffer;
189  void* param;
190 };
191 
192 
193 struct uart_config {
194  uint8_t uart_nr;
195  uint8_t tx_pin;
196  uart_mode_t mode;
197  uart_options_t options;
198  uint32_t baudrate;
199  uint32_t config;
200  size_t rx_size;
201  size_t tx_size;
202 };
203 
204 // @deprecated Use `uart_init_ex()` instead
205 uart_t* uart_init(uint8_t uart_nr, uint32_t baudrate, uint32_t config, uart_mode_t mode, uint8_t tx_pin, size_t rx_size, size_t tx_size = 0);
206 
207 uart_t* uart_init_ex(const uart_config& cfg);
208 
209 void uart_uninit(uart_t* uart);
210 
212 {
213  return uart ? uart->uart_nr : -1;
214 }
215 
220 uart_t* uart_get_uart(uint8_t uart_nr);
221 
228 
234 {
235  return uart ? uart->param : nullptr;
236 }
237 
242 static inline void uart_set_options(uart_t* uart, uart_options_t options)
243 {
244  if (uart)
245  uart->options = options;
246 }
247 
259 uint8_t IRAM_ATTR uart_get_status(uart_t* uart);
260 
261 static inline uart_options_t uart_get_options(uart_t* uart)
262 {
263  return uart ? uart->options : 0;
264 }
265 
266 void uart_swap(uart_t* uart, int tx_pin);
267 void uart_set_tx(uart_t* uart, int tx_pin);
268 void uart_set_pins(uart_t* uart, int tx, int rx);
269 
271 {
272  return uart && uart->mode != UART_RX_ONLY;
273 }
274 
276 {
277  return uart && uart->mode != UART_TX_ONLY;
278 }
279 
285 uint32_t uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate);
286 
292 uint32_t uart_set_baudrate(uart_t* uart, uint32_t baud_rate);
293 
298 uint32_t uart_get_baudrate(uart_t* uart);
299 
300 size_t uart_resize_rx_buffer(uart_t* uart, size_t new_size);
301 size_t uart_rx_buffer_size(uart_t* uart);
302 size_t uart_resize_tx_buffer(uart_t* uart, size_t new_size);
303 size_t uart_tx_buffer_size(uart_t* uart);
304 
305 
312 size_t uart_write(uart_t* uart, const void* buffer, size_t size);
313 
319 static inline size_t uart_write_char(uart_t* uart, char c)
320 {
321  return uart_write(uart, &c, 1);
322 }
323 
330 size_t uart_read(uart_t* uart, void* buffer, size_t size);
331 
336 static inline int uart_read_char(uart_t* uart)
337 {
338  char c;
339  return uart_read(uart, &c, 1) ? c : -1;
340 }
341 
348 int uart_peek_char(uart_t* uart);
349 
356 int uart_peek_last_char(uart_t* uart);
357 
358 /*
359  * @brief Find a character in the receive buffer
360  * @param uart
361  * @param char c character to search for
362  * @retval size_t position relative to start of buffer, -1 if not found
363  */
364 int uart_rx_find(uart_t* uart, char c);
365 
371 size_t uart_rx_available(uart_t* uart);
372 
374 size_t uart_tx_free(uart_t* uart);
375 
377 void uart_wait_tx_empty(uart_t* uart);
378 
383 void uart_set_break(uart_t* uart, bool state);
384 
390 void uart_flush(uart_t* uart, uart_mode_t mode = UART_FULL);
391 
392 void uart_set_debug(int uart_nr);
393 int uart_get_debug();
394 
398 void uart_start_isr(uart_t* uart);
399 
404 {
405  extern void uart_detach(int);
406  if (uart != nullptr) {
407  uart_detach(uart->uart_nr);
408  }
409 }
410 
414 void uart_detach(int uart_nr);
415 
419 void uart_detach_all();
420 
421 
425 uint8_t uart_disable_interrupts();
426 
430 
433 #if defined (__cplusplus)
434 } // extern "C"
435 #endif
int uart_peek_last_char(uart_t *uart)
fetch last character read out of FIFO
void(* uart_callback_t)(uart_t *uart, uint32_t status)
callback invoked directly from ISR
Definition: uart.h:135
uint8_t tx_pin
Definition: uart.h:183
uint8_t rx_pin
Definition: uart.h:182
Called immediately before uart is closed and destroyed.
Definition: uart.h:149
void * uart_get_callback_param(uart_t *uart)
Get the callback parameter specified by uart_set_callback()
Definition: uart.h:233
#define __forceinline
Definition: sming_attr.h:13
size_t uart_rx_available(uart_t *uart)
determine available data which can be read
size_t uart_tx_free(uart_t *uart)
return free space in transmit buffer
If buffers are full then uart_write() will wait for free space.
Definition: uart.h:114
int uart_get_debug()
void uart_start_isr(uart_t *uart)
enable interrupts for a UART
Called when uart has been iniitialised successfully.
Definition: uart.h:146
Called before data is read from rx buffer.
Definition: uart.h:155
bool uart_rx_enabled(uart_t *uart)
Definition: uart.h:275
uint8_t uart_nr
Definition: uart.h:194
static uart_options_t uart_get_options(uart_t *uart)
Definition: uart.h:261
uint32_t uart_set_baudrate(uart_t *uart, uint32_t baud_rate)
set UART baud rate
uint16_t status
All status flags reported to callback since last uart_get_status() call.
Definition: uart.h:185
void uart_detach(int uart_nr)
detach a UART interrupt service routine
static size_t uart_write_char(uart_t *uart, char c)
queue a single character for output
Definition: uart.h:319
size_t uart_rx_buffer_size(uart_t *uart)
uint32_t uart_get_baudrate(uart_t *uart)
get the actual baud rate in use
void * param
User-supplied callback parameter.
Definition: uart.h:189
Both receive and transmit - will revert to TX only if RX not supported.
Definition: uart.h:103
uint32_t uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate)
set UART baud rate, given the UART number
int uart_get_nr(uart_t *uart)
Definition: uart.h:211
uart_callback_t callback
Optional User callback routine.
Definition: uart.h:188
int uart_rx_find(uart_t *uart, char c)
void uart_swap(uart_t *uart, int tx_pin)
enum uart_mode_ uart_mode_t
Definition: uart.h:107
uint32_t baud_rate
Definition: uart.h:179
void uart_restore_interrupts()
re-enable interrupts after calling uart_disable_interrupts()
uart_options_t options
Definition: uart.h:197
size_t uart_resize_rx_buffer(uart_t *uart, size_t new_size)
static int uart_read_char(uart_t *uart)
read a received character
Definition: uart.h:336
int uart_peek_char(uart_t *uart)
see what the next character in the rx buffer is
void uart_detach_all()
detach all UART interrupt service routines
uint8_t uart_nr
Definition: uart.h:178
uint8_t uart_disable_interrupts()
disable interrupts and return current interrupt state
uint8_t rx_headroom
Callback when rx_buffer free space <= headroom.
Definition: uart.h:184
void uart_set_break(uart_t *uart, bool state)
Set or clear a break condition on the TX line.
ISR invokes user callback function with no pre-processing.
Definition: uart.h:115
size_t uart_write(uart_t *uart, const void *buffer, size_t size)
write a block of data
uart_t * uart_init_ex(const uart_config &cfg)
uart_t * uart_get_uart(uint8_t uart_nr)
Get the uart structure for the given number.
void uart_uninit(uart_t *uart)
size_t uart_read(uart_t *uart, void *buffer, size_t size)
read a block of data
bool uart_tx_enabled(uart_t *uart)
Definition: uart.h:270
Transmit only.
Definition: uart.h:105
void(* uart_notify_callback_t)(uart_t *uart, uart_notify_code_t code)
Port notification callback function type.
Definition: uart.h:165
uint32_t config
UART CONF0 register bits.
Definition: uart.h:199
void uart_set_pins(uart_t *uart, int tx, int rx)
size_t uart_resize_tx_buffer(uart_t *uart, size_t new_size)
Definition: uart.h:177
static void uart_set_options(uart_t *uart, uart_options_t options)
Set option flags.
Definition: uart.h:242
Called after data has been written into tx buffer.
Definition: uart.h:152
uint32_t baudrate
Requested baudrate; actual baudrate may differ.
Definition: uart.h:198
bool uart_set_notify(unsigned uart_nr, uart_notify_callback_t callback)
Set the notification callback function.
Called to ensure all buffered data is output.
Definition: uart.h:158
uart_mode_t mode
Whether to enable receive, transmit or both.
Definition: uart.h:196
uart_option_bits_t
bit values for options argument of uart_init
Definition: uart.h:113
uart_t * uart_init(uint8_t uart_nr, uint32_t baudrate, uint32_t config, uart_mode_t mode, uint8_t tx_pin, size_t rx_size, size_t tx_size=0)
uint8_t tx_pin
Specify 2 for alternate pin, otherwise defaults to pin 1.
Definition: uart.h:195
void uart_set_debug(int uart_nr)
void uart_wait_tx_empty(uart_t *uart)
void uart_stop_isr(uart_t *uart)
disable interrupts for a UART
Definition: uart.h:403
uint8_t options
Definition: uart.h:181
uint8_t uart_get_status(uart_t *uart)
Get error flags and clear them.
uart_mode_t mode
Definition: uart.h:180
struct SerialBuffer * rx_buffer
Optional receive buffer.
Definition: uart.h:186
void uart_set_tx(uart_t *uart, int tx_pin)
uint8_t uart_options_t
Definition: uart.h:109
size_t rx_size
Definition: uart.h:200
uart_notify_code_t
Indicates notification, parameters refer to uart_notify_info_t structure.
Definition: uart.h:144
void uart_set_callback(uart_t *uart, uart_callback_t callback, void *param)
Set callback handler for serial port.
size_t tx_size
Definition: uart.h:201
uart_mode_
values for mode argument of uart_init
Definition: uart.h:102
Receive only.
Definition: uart.h:104
void uart_flush(uart_t *uart, uart_mode_t mode=UART_FULL)
discard any buffered data and reset hardware FIFOs
Definition: uart.h:193
size_t uart_tx_buffer_size(uart_t *uart)
struct SerialBuffer * tx_buffer
Optional transmit buffer.
Definition: uart.h:187