Components/arch_driver/src/include/driver/uart.h

Go to the documentation of this file.

/*
 uart.h - UART HAL
 
 Copyright (c) 2014 Ivan Grokhotkov. All rights reserved.
 This file is part of the esp8266 core for Arduino environment.
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation; either
 version 2.1 of the License, or (at your option) any later version.
 
 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the Free Software
 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 
*/
 
/*
 * @author 21/8/2018 mikee47 <mike@sillyhouse.net>
 *
 * SerialBuffer class added to manage FIFO for both RX and TX
 * Buffering is optional; if size is 0 will just use Hardware FIFOS (128 bytes each)
 * For uart_write_xxx functions, if there is no space in the tx FIFO it will return a short count. It will not wait.
 * Trivial check routines have been moved into this header as static inlines.
 * Code is now C++ only; reference to this header has been removed from esp_systemapi.h uart structure should be
 * treated as opaque and only accessed using the functions defined in this header.
 * Callback is invoked on transmit completion.
 *
 * Note: uart_detach_all() should be called at startup, i.e. from user_init().
 */
 
#pragma once
 
#include <c_types.h>
#include <esp_attr.h>
#include <sming_attr.h>
 
#if defined(__cplusplus)
extern "C" {
#endif
 
#define UART_NO -1 
 
#define UART_PIN_DEFAULT (255)  
#define UART_PIN_NO_CHANGE (-1) 
 
enum smg_uart_bits_t {
    UART_NB_BIT_5 = 0,
    UART_NB_BIT_6 = 1,
    UART_NB_BIT_7 = 2,
    UART_NB_BIT_8 = 3,
};
 
enum smg_uart_parity_t {
    UART_PARITY_NONE = 0,
    UART_PARITY_EVEN = 2,
    UART_PARITY_ODD = 3,
};
 
enum smg_uart_stop_bits_t {
    UART_NB_STOP_BIT_0 = 0,
    UART_NB_STOP_BIT_1 = 1,
    UART_NB_STOP_BIT_15 = 2,
    UART_NB_STOP_BIT_2 = 3,
};
 
enum smg_uart_format_settings_t {
    UART_PARITY_MASK = 0B00000011,
    UART_PARITY_SHIFT = 0,
    UART_NB_BIT_MASK = 0B00001100,
    UART_NB_BIT_SHIFT = 2,
    UART_NB_STOP_BIT_MASK = 0B00110000,
    UART_NB_STOP_BIT_SHIFT = 4,
};
 
static inline constexpr uint8_t SMG_UART_FORMAT(smg_uart_bits_t databits, smg_uart_stop_bits_t stopbits,
                                                smg_uart_parity_t parity)
{
    return (databits << UART_NB_BIT_SHIFT) | (stopbits << UART_NB_STOP_BIT_SHIFT) | (parity << UART_PARITY_SHIFT);
}
 
union smg_uart_config_format_t {
    struct {
        smg_uart_parity_t parity : 2;
        smg_uart_bits_t bits : 2;
        smg_uart_stop_bits_t stop_bits : 2;
    };
    uint8_t val;
};
 
enum smg_uart_format_t {
    UART_5N1 = SMG_UART_FORMAT(UART_NB_BIT_5, UART_NB_STOP_BIT_1, UART_PARITY_NONE),
    UART_6N1 = SMG_UART_FORMAT(UART_NB_BIT_6, UART_NB_STOP_BIT_1, UART_PARITY_NONE),
    UART_7N1 = SMG_UART_FORMAT(UART_NB_BIT_7, UART_NB_STOP_BIT_1, UART_PARITY_NONE),
    UART_8N1 = SMG_UART_FORMAT(UART_NB_BIT_8, UART_NB_STOP_BIT_1, UART_PARITY_NONE),
    UART_5N2 = SMG_UART_FORMAT(UART_NB_BIT_5, UART_NB_STOP_BIT_2, UART_PARITY_NONE),
    UART_6N2 = SMG_UART_FORMAT(UART_NB_BIT_6, UART_NB_STOP_BIT_2, UART_PARITY_NONE),
    UART_7N2 = SMG_UART_FORMAT(UART_NB_BIT_7, UART_NB_STOP_BIT_2, UART_PARITY_NONE),
    UART_8N2 = SMG_UART_FORMAT(UART_NB_BIT_8, UART_NB_STOP_BIT_2, UART_PARITY_NONE),
    UART_5E1 = SMG_UART_FORMAT(UART_NB_BIT_5, UART_NB_STOP_BIT_1, UART_PARITY_EVEN),
    UART_6E1 = SMG_UART_FORMAT(UART_NB_BIT_6, UART_NB_STOP_BIT_1, UART_PARITY_EVEN),
    UART_7E1 = SMG_UART_FORMAT(UART_NB_BIT_7, UART_NB_STOP_BIT_1, UART_PARITY_EVEN),
    UART_8E1 = SMG_UART_FORMAT(UART_NB_BIT_8, UART_NB_STOP_BIT_1, UART_PARITY_EVEN),
    UART_5E2 = SMG_UART_FORMAT(UART_NB_BIT_5, UART_NB_STOP_BIT_2, UART_PARITY_EVEN),
    UART_6E2 = SMG_UART_FORMAT(UART_NB_BIT_6, UART_NB_STOP_BIT_2, UART_PARITY_EVEN),
    UART_7E2 = SMG_UART_FORMAT(UART_NB_BIT_7, UART_NB_STOP_BIT_2, UART_PARITY_EVEN),
    UART_8E2 = SMG_UART_FORMAT(UART_NB_BIT_8, UART_NB_STOP_BIT_2, UART_PARITY_EVEN),
    UART_5O1 = SMG_UART_FORMAT(UART_NB_BIT_5, UART_NB_STOP_BIT_1, UART_PARITY_ODD),
    UART_6O1 = SMG_UART_FORMAT(UART_NB_BIT_6, UART_NB_STOP_BIT_1, UART_PARITY_ODD),
    UART_7O1 = SMG_UART_FORMAT(UART_NB_BIT_7, UART_NB_STOP_BIT_1, UART_PARITY_ODD),
    UART_8O1 = SMG_UART_FORMAT(UART_NB_BIT_8, UART_NB_STOP_BIT_1, UART_PARITY_ODD),
    UART_5O2 = SMG_UART_FORMAT(UART_NB_BIT_5, UART_NB_STOP_BIT_2, UART_PARITY_ODD),
    UART_6O2 = SMG_UART_FORMAT(UART_NB_BIT_6, UART_NB_STOP_BIT_2, UART_PARITY_ODD),
    UART_7O2 = SMG_UART_FORMAT(UART_NB_BIT_7, UART_NB_STOP_BIT_2, UART_PARITY_ODD),
    UART_8O2 = SMG_UART_FORMAT(UART_NB_BIT_8, UART_NB_STOP_BIT_2, UART_PARITY_ODD),
};
 
// Status values
enum smg_uart_status_t {
    UART_STATUS_TX_DONE = BIT(14), 
    UART_STATUS_RXFIFO_TOUT = BIT(8),
    UART_STATUS_BRK_DET = BIT(7),
    UART_STATUS_CTS_CHG = BIT(6),
    UART_STATUS_DSR_CHG = BIT(5),
    UART_STATUS_RXFIFO_OVF = BIT(4),
    UART_STATUS_FRM_ERR = BIT(3),
    UART_STATUS_PARITY_ERR = BIT(2),
    UART_STATUS_TXFIFO_EMPTY = BIT(1),
    UART_STATUS_RXFIFO_FULL = BIT(0),
};
 
enum smg_uart_mode_t {
    UART_FULL,  
    UART_RX_ONLY, 
    UART_TX_ONLY  
};
 
using uart_options_t = uint8_t;
 
enum smg_uart_option_bits_t {
    UART_OPT_TXWAIT,       
    UART_OPT_CALLBACK_RAW, 
};
 
#define UART_RX_FIFO_SIZE 0x80
#define UART_TX_FIFO_SIZE 0x80
 
struct smg_uart_t;
 
typedef void (*smg_uart_callback_t)(smg_uart_t* uart, uint32_t status);
 
/*
 * Port notifications
 */
 
enum smg_uart_notify_code_t {
    UART_NOTIFY_AFTER_OPEN,
 
    UART_NOTIFY_BEFORE_CLOSE,
 
    UART_NOTIFY_AFTER_WRITE,
 
    UART_NOTIFY_BEFORE_READ,
 
    UART_NOTIFY_WAIT_TX,
};
 
using smg_uart_notify_callback_t = void (*)(smg_uart_t* uart, smg_uart_notify_code_t code);
 
bool smg_uart_set_notify(unsigned uart_nr, smg_uart_notify_callback_t callback);
 
struct SerialBuffer;
 
struct smg_uart_t {
    uint8_t uart_nr;
    uint32_t baud_rate;
    smg_uart_mode_t mode;
    uint8_t options;
    uint8_t rx_pin;
    uint8_t tx_pin;
    uint8_t rx_headroom;            
    uint16_t status;                
    struct SerialBuffer* rx_buffer; 
    struct SerialBuffer* tx_buffer; 
    smg_uart_callback_t callback;   
    void* param;                    
};
 
struct smg_uart_config_t {
    uint8_t uart_nr;
    uint8_t tx_pin; 
    uint8_t rx_pin;
    smg_uart_mode_t mode; 
    uart_options_t options;
    uint32_t baudrate;        
    smg_uart_format_t format; 
    size_t rx_size;
    size_t tx_size;
};
 
// @deprecated Use `smg_uart_init_ex()` instead
smg_uart_t* smg_uart_init(uint8_t uart_nr, uint32_t baudrate, smg_uart_format_t format, smg_uart_mode_t mode,
                          uint8_t tx_pin, size_t rx_size, size_t tx_size = 0);
 
smg_uart_t* smg_uart_init_ex(const smg_uart_config_t& cfg);
 
void smg_uart_uninit(smg_uart_t* uart);
 
void smg_uart_set_format(smg_uart_t* uart, smg_uart_format_t format);
 
typedef struct {
    uint8_t rx_timeout_thresh;
    uint8_t txfifo_empty_intr_thresh;
    uint8_t rxfifo_full_thresh; 
    uint8_t reserved;
    uint32_t intr_mask;   
    uint32_t intr_enable; 
} smg_uart_intr_config_t;
 
bool smg_uart_intr_config(smg_uart_t* uart, const smg_uart_intr_config_t* config);
 
__forceinline int smg_uart_get_nr(smg_uart_t* uart)
{
    return uart ? uart->uart_nr : -1;
}
 
smg_uart_t* smg_uart_get_uart(uint8_t uart_nr);
 
void smg_uart_set_callback(smg_uart_t* uart, smg_uart_callback_t callback, void* param);
 
__forceinline void* smg_uart_get_callback_param(smg_uart_t* uart)
{
    return uart ? uart->param : nullptr;
}
 
static inline void smg_uart_set_options(smg_uart_t* uart, uart_options_t options)
{
    if(uart)
        uart->options = options;
}
 
uint8_t IRAM_ATTR smg_uart_get_status(smg_uart_t* uart);
 
static inline uart_options_t smg_uart_get_options(smg_uart_t* uart)
{
    return uart ? uart->options : 0;
}
 
void smg_uart_swap(smg_uart_t* uart, int tx_pin);
bool smg_uart_set_tx(smg_uart_t* uart, int tx_pin);
bool smg_uart_set_pins(smg_uart_t* uart, int tx_pin, int rx_pin);
 
__forceinline bool smg_uart_tx_enabled(smg_uart_t* uart)
{
    return uart && uart->mode != UART_RX_ONLY;
}
 
__forceinline bool smg_uart_rx_enabled(smg_uart_t* uart)
{
    return uart && uart->mode != UART_TX_ONLY;
}
 
uint32_t smg_uart_set_baudrate_reg(int uart_nr, uint32_t baud_rate);
 
uint32_t smg_uart_set_baudrate(smg_uart_t* uart, uint32_t baud_rate);
 
uint32_t smg_uart_get_baudrate(smg_uart_t* uart);
 
size_t smg_uart_resize_rx_buffer(smg_uart_t* uart, size_t new_size);
size_t smg_uart_rx_buffer_size(smg_uart_t* uart);
size_t smg_uart_resize_tx_buffer(smg_uart_t* uart, size_t new_size);
size_t smg_uart_tx_buffer_size(smg_uart_t* uart);
 
size_t smg_uart_write(smg_uart_t* uart, const void* buffer, size_t size);
 
static inline size_t smg_uart_write_char(smg_uart_t* uart, char c)
{
    return smg_uart_write(uart, &c, 1);
}
 
size_t smg_uart_read(smg_uart_t* uart, void* buffer, size_t size);
 
static inline int smg_uart_read_char(smg_uart_t* uart)
{
    char c;
    return smg_uart_read(uart, &c, 1) ? c : -1;
}
 
int smg_uart_peek_char(smg_uart_t* uart);
 
int smg_uart_peek_last_char(smg_uart_t* uart);
 
/*
 * @brief Find a character in the receive buffer
 * @param uart
 * @param char c character to search for
 * @retval size_t position relative to start of buffer, -1 if not found
 */
int smg_uart_rx_find(smg_uart_t* uart, char c);
 
size_t smg_uart_rx_available(smg_uart_t* uart);
 
size_t smg_uart_tx_free(smg_uart_t* uart);
 
void smg_uart_wait_tx_empty(smg_uart_t* uart);
 
void smg_uart_set_break(smg_uart_t* uart, bool state);
 
void smg_uart_flush(smg_uart_t* uart, smg_uart_mode_t mode = UART_FULL);
 
void smg_uart_set_debug(int uart_nr);
int smg_uart_get_debug();
 
void smg_uart_start_isr(smg_uart_t* uart);
 
void __forceinline smg_uart_stop_isr(smg_uart_t* uart)
{
    extern void smg_uart_detach(int);
    if(uart != nullptr) {
        smg_uart_detach(uart->uart_nr);
    }
}
 
void smg_uart_detach(int uart_nr);
 
void smg_uart_detach_all();
 
uint8_t smg_uart_disable_interrupts();
 
void smg_uart_restore_interrupts();
 
// Internal routine
bool smg_uart_realloc_buffer(SerialBuffer*& buffer, size_t new_size);
 
#if defined(__cplusplus)
} // extern "C"
#endif