uart.h

Go to the documentation of this file.

/*****************************************************************************
 *   Copyright(C)2009-2026 by VSF Team                                       *
 *                                                                           *
 *  Licensed under the Apache License, Version 2.0 (the "License");          *
 *  you may not use this file except in compliance with the License.         *
 *  You may obtain a copy of the License at                                  *
 *                                                                           *
 *     http://www.apache.org/licenses/LICENSE-2.0                            *
 *                                                                           *
 *  Unless required by applicable law or agreed to in writing, software      *
 *  distributed under the License is distributed on an "AS IS" BASIS,        *
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
 *  See the License for the specific language governing permissions and      *
 *  limitations under the License.                                           *
 *                                                                           *
 ****************************************************************************/
 
/*
 * Clean-room re-implementation of ESP-IDF public API "driver/uart.h".
 * Authored from ESP-IDF v5.1 public API only; no ESP-IDF source was
 * copied. The VSF port bridges onto
 *
 *     hal/driver/common/template/vsf_template_usart.h
 *
 * via a cfg-injected pool of vsf_usart_t* instances (same pattern as
 * driver/gptimer.h). uart_port_t (UART_NUM_0, 1, ...) indexes into
 * this pool.
 *
 * Supported API:
 *   uart_driver_install, uart_driver_delete, uart_is_driver_installed,
 *   uart_param_config,
 *   uart_set_baudrate/get_baudrate,
 *   uart_set_word_length/get_word_length,
 *   uart_set_stop_bits/get_stop_bits,
 *   uart_set_parity/get_parity,
 *   uart_set_hw_flow_ctrl/get_hw_flow_ctrl,
 *   uart_write_bytes, uart_write_bytes_with_break,
 *   uart_read_bytes,
 *   uart_get_buffered_data_len, uart_get_tx_buffer_free_size,
 *   uart_flush, uart_flush_input,
 *   uart_set_mode, uart_set_rx_timeout.
 *
 * NOT_SUPPORTED:
 *   uart_set_pin        (VSF does not manage external pin routing),
 *   uart_set_rts        (hardware-managed when flow-ctrl enabled),
 *   uart_set_dtr,
 *   uart_set_tx_idle_num,
 *   uart_wait_tx_done   (use uart_flush instead),
 *   uart_pattern_*      (ESP-IDF pattern detect is HW-specific).
 */
 
#ifndef __VSF_ESPIDF_DRIVER_UART_H__
#define __VSF_ESPIDF_DRIVER_UART_H__
 
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
 
#include "esp_err.h"
 
/* FreeRTOS types used by the driver API (QueueHandle_t, TickType_t). */
#include "freertos/FreeRTOS.h"
#include "freertos/queue.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*============================ MACROS ========================================*/
 
#define UART_PIN_NO_CHANGE      (-1)
 
#define UART_HW_FIFO_LEN       (128)
 
/*============================ TYPES =========================================*/
 
typedef int uart_port_t;
 
#define UART_NUM_0              (0)
#define UART_NUM_1              (1)
#define UART_NUM_2              (2)
#define UART_NUM_MAX            (3)     
typedef enum {
    UART_DATA_5_BITS = 0,               
    UART_DATA_6_BITS = 1,               
    UART_DATA_7_BITS = 2,               
    UART_DATA_8_BITS = 3,               
    UART_DATA_BITS_MAX = 4,
} uart_word_length_t;
 
typedef enum {
    UART_STOP_BITS_1   = 1,             
    UART_STOP_BITS_1_5 = 2,             
    UART_STOP_BITS_2   = 3,             
    UART_STOP_BITS_MAX = 4,
} uart_stop_bits_t;
 
typedef enum {
    UART_PARITY_DISABLE = 0,            
    UART_PARITY_EVEN    = 2,            
    UART_PARITY_ODD     = 3,            
} uart_parity_t;
 
typedef enum {
    UART_HW_FLOWCTRL_DISABLE = 0,       
    UART_HW_FLOWCTRL_RTS     = 1,       
    UART_HW_FLOWCTRL_CTS     = 2,       
    UART_HW_FLOWCTRL_CTS_RTS = 3,       
    UART_HW_FLOWCTRL_MAX     = 4,
} uart_hw_flowcontrol_t;
 
typedef enum {
    UART_MODE_UART           = 0,       
    UART_MODE_RS485_HALF_DUPLEX = 1,    
    UART_MODE_IRDA           = 2,       
    UART_MODE_RS485_COLLISION_DETECT = 3,
    UART_MODE_RS485_APP_CTRL = 4,
} uart_mode_t;
 
typedef enum {
    UART_SCLK_DEFAULT = 0,
    UART_SCLK_APB     = 1,
    UART_SCLK_XTAL    = 2,
    UART_SCLK_RTC     = 3,
} uart_sclk_t;
 
typedef struct {
    int                     baud_rate;
    uart_word_length_t      data_bits;
    uart_parity_t           parity;
    uart_stop_bits_t        stop_bits;
    uart_hw_flowcontrol_t   flow_ctrl;
    uint8_t                 rx_flow_ctrl_thresh;    
    uart_sclk_t             source_clk;             
} uart_config_t;
 
typedef enum {
    UART_DATA              = 0,         
    UART_BREAK             = 1,         
    UART_BUFFER_FULL       = 2,         
    UART_FIFO_OVF          = 3,         
    UART_FRAME_ERR         = 4,         
    UART_PARITY_ERR        = 5,         
    UART_DATA_BREAK        = 6,         
    UART_PATTERN_DET       = 7,         
    UART_EVENT_MAX         = 8,
} uart_event_type_t;
 
typedef struct {
    uart_event_type_t       type;       
    size_t                  size;       
    bool                    timeout_flag; 
} uart_event_t;
 
/*============================ DRIVER LIFECYCLE ==============================*/
 
extern esp_err_t uart_driver_install(uart_port_t uart_num,
                                     int rx_buffer_size,
                                     int tx_buffer_size,
                                     int queue_size,
                                     QueueHandle_t *uart_queue,
                                     int intr_alloc_flags);
 
extern esp_err_t uart_driver_delete(uart_port_t uart_num);
 
extern bool      uart_is_driver_installed(uart_port_t uart_num);
 
/*============================ CONFIGURATION =================================*/
 
extern esp_err_t uart_param_config(uart_port_t uart_num,
                                   const uart_config_t *uart_config);
 
extern esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate);
extern esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate);
 
extern esp_err_t uart_set_word_length(uart_port_t uart_num,
                                      uart_word_length_t data_bit);
extern esp_err_t uart_get_word_length(uart_port_t uart_num,
                                      uart_word_length_t *data_bit);
 
extern esp_err_t uart_set_stop_bits(uart_port_t uart_num,
                                    uart_stop_bits_t stop_bits);
extern esp_err_t uart_get_stop_bits(uart_port_t uart_num,
                                    uart_stop_bits_t *stop_bits);
 
extern esp_err_t uart_set_parity(uart_port_t uart_num,
                                 uart_parity_t parity_mode);
extern esp_err_t uart_get_parity(uart_port_t uart_num,
                                 uart_parity_t *parity_mode);
 
extern esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num,
                                       uart_hw_flowcontrol_t flow_ctrl,
                                       uint8_t rx_thresh);
extern esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num,
                                       uart_hw_flowcontrol_t *flow_ctrl);
 
/*============================ I/O ===========================================*/
 
extern int uart_write_bytes(uart_port_t uart_num,
                            const void *src, size_t size);
 
extern int uart_write_bytes_with_break(uart_port_t uart_num,
                                       const void *src, size_t size,
                                       int brk_len);
 
extern int uart_read_bytes(uart_port_t uart_num,
                           void *buf, uint32_t length,
                           TickType_t ticks_to_wait);
 
/*============================ BUFFER STATUS =================================*/
 
extern esp_err_t uart_get_buffered_data_len(uart_port_t uart_num,
                                            size_t *size);
 
extern esp_err_t uart_get_tx_buffer_free_size(uart_port_t uart_num,
                                              size_t *size);
 
extern esp_err_t uart_flush(uart_port_t uart_num);
 
extern esp_err_t uart_flush_input(uart_port_t uart_num);
 
/*============================ PIN ROUTING ===================================*/
 
extern esp_err_t uart_set_pin(uart_port_t uart_num,
                              int tx_io_num, int rx_io_num,
                              int rts_io_num, int cts_io_num);
 
/*============================ MODE / TIMEOUT ================================*/
 
extern esp_err_t uart_set_mode(uart_port_t uart_num, uart_mode_t mode);
 
extern esp_err_t uart_set_rx_timeout(uart_port_t uart_num, uint8_t tout);
 
/*============================ WAIT TX DONE ==================================*/
 
extern esp_err_t uart_wait_tx_done(uart_port_t uart_num,
                                   TickType_t ticks_to_wait);
 
#ifdef __cplusplus
}
#endif
 
#endif      /* __VSF_ESPIDF_DRIVER_UART_H__ */