espressif/ESP8266_RTOS_SDK
1
0
Fork 0
mirror of https://github.com/espressif/ESP8266_RTOS_SDK.git synced 2025-05-22 09:37:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

refactor(driver): Refactor uart driver for esp8266 idf

Browse Source
This commit is contained in:
xiewenxiang
2018-06-13 19:48:16 +08:00
committed by XiongYu
parent 220c26ad48
commit 97335027c7
16 changed files with 3762 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
.gitignore vendored
View File

@ -5,6 +5,9 @@
.cproject
.project
# vscode setting
.vscode
# Example project files
examples/**/sdkconfig
examples/**/sdkconfig.old

1022
components/esp8266/driver/uart.c Normal file
View File

File diff suppressed because it is too large Load Diff

547
components/esp8266/include/driver/uart.h Normal file
View File

@ -0,0 +1,547 @@
// Copyright 2018-2025 Espressif Systems (Shanghai) PTE LTD
//
// 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.
#ifndef _DRIVER_UART_H_
#define _DRIVER_UART_H_
#ifdef __cplusplus
extern "C" {
#endif
#include "esp_err.h"
#include "esp_log.h"
#include "freertos/queue.h"
#define UART_FIFO_LEN (128) /*!< Length of the hardware FIFO buffers */
#define UART_INTR_MASK 0x1ff /*!< Mask of all UART interrupts */
#define UART_LINE_INV_MASK (0x3f << 19) /*!< TBD */
#define UART_INVERSE_DISABLE (0x0) /*!< Disable UART signal inverse*/
#define UART_INVERSE_RXD (BIT(19)) /*!< UART RXD input inverse*/
#define UART_INVERSE_CTS (BIT(20)) /*!< UART CTS input inverse*/
#define UART_INVERSE_TXD (BIT(22)) /*!< UART TXD output inverse*/
#define UART_INVERSE_RTS (BIT(23)) /*!< UART RTS output inverse*/
/**
* @brief UART mode selection
*/
typedef enum {
UART_MODE_UART = 0x00, /*!< mode: regular UART mode*/
} uart_mode_t;
/**
* @brief UART word length constants
*/
typedef enum {
UART_DATA_5_BITS = 0x0, /*!< word length: 5bits*/
UART_DATA_6_BITS = 0x1, /*!< word length: 6bits*/
UART_DATA_7_BITS = 0x2, /*!< word length: 7bits*/
UART_DATA_8_BITS = 0x3, /*!< word length: 8bits*/
UART_DATA_BITS_MAX = 0x4,
} uart_word_length_t;
/**
* @brief UART stop bits number
*/
typedef enum {
UART_STOP_BITS_1 = 0x1, /*!< stop bit: 1bit*/
UART_STOP_BITS_1_5 = 0x2, /*!< stop bit: 1.5bits*/
UART_STOP_BITS_2 = 0x3, /*!< stop bit: 2bits*/
UART_STOP_BITS_MAX = 0x4,
} uart_stop_bits_t;
/**
* @brief UART peripheral number
*/
typedef enum {
UART_NUM_0 = 0x0,
UART_NUM_1 = 0x1,
UART_NUM_MAX,
} uart_port_t;
/**
* @brief UART parity constants
*/
typedef enum {
UART_PARITY_DISABLE = 0x0, /*!< Disable UART parity*/
UART_PARITY_EVEN = 0x2, /*!< Enable UART even parity*/
UART_PARITY_ODD = 0x3 /*!< Enable UART odd parity*/
} uart_parity_t;
/**
* @brief UART hardware flow control modes
*/
typedef enum {
UART_HW_FLOWCTRL_DISABLE = 0x0, /*!< disable hardware flow control*/
UART_HW_FLOWCTRL_RTS = 0x1, /*!< enable RX hardware flow control (rts)*/
UART_HW_FLOWCTRL_CTS = 0x2, /*!< enable TX hardware flow control (cts)*/
UART_HW_FLOWCTRL_CTS_RTS = 0x3, /*!< enable hardware flow control*/
UART_HW_FLOWCTRL_MAX = 0x4,
} uart_hw_flowcontrol_t;
/**
* @brief UART configuration parameters for uart_param_config function
*/
typedef struct {
int baud_rate; /*!< UART baud rate*/
uart_word_length_t data_bits; /*!< UART byte size*/
uart_parity_t parity; /*!< UART parity mode*/
uart_stop_bits_t stop_bits; /*!< UART stop bits*/
uart_hw_flowcontrol_t flow_ctrl; /*!< UART HW flow control mode (cts/rts)*/
uint8_t rx_flow_ctrl_thresh; /*!< UART HW RTS threshold*/
} uart_config_t;
/**
* @brief UART interrupt configuration parameters for uart_intr_config function
*/
typedef struct {
uint32_t intr_enable_mask; /*!< UART interrupt enable mask, choose from UART_XXXX_INT_ENA_M under UART_INT_ENA_REG(i), connect with bit-or operator*/
uint8_t rx_timeout_thresh; /*!< UART timeout interrupt threshold (unit: time of sending one byte)*/
uint8_t txfifo_empty_intr_thresh; /*!< UART TX empty interrupt threshold.*/
uint8_t rxfifo_full_thresh; /*!< UART RX full interrupt threshold.*/
} uart_intr_config_t;
/**
* @brief UART event types used in the ring buffer
*/
typedef enum {
UART_DATA, /*!< UART data event*/
UART_BUFFER_FULL, /*!< UART RX buffer full event*/
UART_FIFO_OVF, /*!< UART FIFO overflow event*/
UART_FRAME_ERR, /*!< UART RX frame error event*/
UART_PARITY_ERR, /*!< UART RX parity event*/
UART_EVENT_MAX, /*!< UART event max index*/
} uart_event_type_t;
/**
* @brief Event structure used in UART event queue
*/
typedef struct {
uart_event_type_t type; /*!< UART event type */
size_t size; /*!< UART data size for UART_DATA event*/
} uart_event_t;
/**
* @brief Set UART data bits.
*
* @param uart_num Uart port number.
* @param data_bit Uart data bits.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_word_length(uart_port_t uart_num, uart_word_length_t data_bit);
/**
* @brief Get UART data bits.
*
* @param uart_num Uart port number.
* @param data_bit Pointer to accept value of UART data bits.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_word_length(uart_port_t uart_num, uart_word_length_t *data_bit);
/**
* @brief Set UART stop bits.
*
* @param uart_num Uart port number
* @param stop_bits Uart stop bits
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_stop_bits(uart_port_t uart_num, uart_stop_bits_t stop_bits);
/**
* @brief Get UART stop bits.
*
* @param uart_num Uart port number.
* @param stop_bits Pointer to accept value of UART stop bits.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_stop_bits(uart_port_t uart_num, uart_stop_bits_t *stop_bits);
/**
* @brief Set UART parity mode.
*
* @param uart_num Uart port number.
* @param parity_mode The enum of uart parity configuration.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_parity(uart_port_t uart_num, uart_parity_t parity_mode);
/**
* @brief Get UART parity mode.
*
* @param uart_num Uart port number
* @param parity_mode Pointer to accept value of UART parity mode.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_parity(uart_port_t uart_num, uart_parity_t *parity_mode);
/**
* @brief Set UART baud rate.
*
* @param uart_num Uart port number
* @param baudrate UART baud rate.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_baudrate(uart_port_t uart_num, uint32_t baudrate);
/**
* @brief Get UART baud rate.
*
* @param uart_num Uart port number.
* @param baudrate Pointer to accept value of Uart baud rate.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_baudrate(uart_port_t uart_num, uint32_t *baudrate);
/**
* @brief Set UART line inverse mode
*
* @param uart_num UART_NUM_0
* @param inverse_mask Choose the wires that need to be inverted.
* Inverse_mask should be chosen from
* UART_INVERSE_RXD / UART_INVERSE_TXD / UART_INVERSE_RTS / UART_INVERSE_CTS,
* combined with OR operation.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_line_inverse(uart_port_t uart_num, uint32_t inverse_mask);
/**
* @brief Configure Hardware flow control.
*
* @param uart_num Uart port number.
* @param flow_ctrl Hardware flow control mode.
* @param rx_thresh Threshold of Hardware flow control.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t flow_ctrl, uint8_t rx_thresh);
/**
* @brief Get hardware flow control mode
*
* @param uart_num Uart port number.
* @param flow_ctrl Option for different flow control mode.
*
* @return
* - ESP_OK Success, result will be put in (*flow_ctrl)
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_hw_flow_ctrl(uart_port_t uart_num, uart_hw_flowcontrol_t *flow_ctrl);
/**
* @brief UART0 swap.
* Use MTCK as UART0 RX, MTDO as UART0 TX, so ROM log will not output from
* this new UART0. We also need to use MTDO (U0RTS) and MTCK (U0CTS) as UART0 in hardware.
*
* @return
* - ESP_OK Success
*/
esp_err_t uart_enable_swap(void);
/**
* @brief Disable UART0 swap.
* Use the original UART0, not MTCK and MTDO.
*
* @return
* - ESP_OK Success
*/
esp_err_t uart_disable_swap(void);
/**
* @brief Clear uart interrupts status.
*
* @param uart_num Uart port number.
* @param mask Uart interrupt bits mask.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_clear_intr_status(uart_port_t uart_num, uint32_t mask);
/**
* @brief Set UART interrupt enable
*
* @param uart_num Uart port number
* @param enable_mask Bit mask of the enable bits.
* The bit mask should be composed from the fields of register UART_INT_ENA_REG.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_enable_intr_mask(uart_port_t uart_num, uint32_t enable_mask);
/**
* @brief Clear UART interrupt enable bits
*
* @param uart_num Uart port number
* @param disable_mask Bit mask of the disable bits.
* The bit mask should be composed from the fields of register UART_INT_ENA_REG.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_disable_intr_mask(uart_port_t uart_num, uint32_t disable_mask);
/**
* @brief Enable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
*
* @param uart_num UART_NUM_0
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_enable_rx_intr(uart_port_t uart_num);
/**
* @brief Disable UART RX interrupt (RX_FULL & RX_TIMEOUT INTERRUPT)
*
* @param uart_num UART_NUM_0
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_disable_rx_intr(uart_port_t uart_num);
/**
* @brief Disable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
*
* @param uart_num UART_NUM_0
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_disable_tx_intr(uart_port_t uart_num);
/**
* @brief Enable UART TX interrupt (TX_FULL & TX_TIMEOUT INTERRUPT)
*
* @param uart_num UART_NUM_0
* @param enable 1: enable; 0: disable
* @param thresh Threshold of TX interrupt, 0 ~ UART_FIFO_LEN
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_enable_tx_intr(uart_port_t uart_num, int enable, int thresh);
/**
* @brief Register UART interrupt handler (ISR).
*
* @param uart_num UART_NUM_0
* @param fn Interrupt handler function.
* @param arg parameter for handler function
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_isr_register(uart_port_t uart_num, void (*fn)(void *), void *arg);
/**
* @brief Config Common parameters of serial ports.
*
* @param uart_num Uart port number.
* @param uart_conf Uart config parameters.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_param_config(uart_port_t uart_num, uart_config_t *uart_conf);
/**
* @brief Config types of uarts.
*
* @param uart_num Uart port number.
* @param uart_intr_conf Uart interrupt config parameters.
*
* @return
* - ESP_OK success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_intr_config(uart_port_t uart_num, uart_intr_config_t *uart_intr_conf);
/**
* @brief Install UART driver.
*
* @note Rx_buffer_size should be greater than UART_FIFO_LEN. Tx_buffer_size should be either zero or greater than UART_FIFO_LEN.
*
* @param uart_num Uart port number.
* @param rx_buffer_size UART RX ring buffer size.
* @param tx_buffer_size UART TX ring buffer size.
* If set to zero, driver will not use TX buffer, TX function will block task until all data have been sent out.
* @param queue_size UART event queue size/depth.
* @param uart_queue UART event queue handle (out param). On success, a new queue handle is written here to provide
* access to UART events. If set to NULL, driver will not use an event queue.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
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);
/**
* @brief Uninstall UART driver.
*
* @param uart_num Uart port number.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_driver_delete(uart_port_t uart_num);
/**
* @brief Send data to the UART port from a given buffer and length.
*
* This function will not wait for enough space in TX FIFO. It will just fill the available TX FIFO and return when the FIFO is full.
* @note This function should only be used when UART TX buffer is not enabled.
*
* @param uart_num Uart port number.
* @param buffer data buffer address
* @param len data length to send
*
* @return
* - (-1) Parameter error
* - OTHERS (>=0) The number of bytes pushed to the TX FIFO
*/
int uart_tx_chars(uart_port_t uart_num, const char *buffer, uint32_t len);
/**
* @brief Send data to the UART port from a given buffer and length,
*
* If the UART driver's parameter 'tx_buffer_size' is set to zero:
* This function will not return until all the data have been sent out, or at least pushed into TX FIFO.
*
* Otherwise, if the 'tx_buffer_size' > 0, this function will return after copying all the data to tx ring buffer,
* UART ISR will then move data from the ring buffer to TX FIFO gradually.
*
* @param uart_num Uart port number.
* @param src data buffer address
* @param size data length to send
*
* @return
* - (-1) Parameter error
* - OTHERS (>=0) The number of bytes pushed to the TX FIFO
*/
int uart_write_bytes(uart_port_t uart_num, const char *src, size_t size);
/**
* @brief UART read bytes from UART buffer
*
* @param uart_num Uart port number.
* @param buf pointer to the buffer.
* @param length data length
* @param ticks_to_wait sTimeout, count in RTOS ticks
*
* @return
* - (-1) Error
* - OTHERS (>=0) The number of bytes read from UART FIFO
*/
int uart_read_bytes(uart_port_t uart_num, uint8_t *buf, uint32_t length, TickType_t ticks_to_wait);
/**
* @brief Alias of uart_flush_input.
* UART ring buffer flush. This will discard all data in the UART RX buffer.
* @note Instead of waiting the data sent out, this function will clear UART rx buffer.
* In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.
* @param uart_num UART port number.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_flush(uart_port_t uart_num);
/**
* @brief Clear input buffer, discard all the data is in the ring-buffer.
* @note In order to send all the data in tx FIFO, we can use uart_wait_tx_done function.
* @param uart_num UART port number.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_flush_input(uart_port_t uart_num);
/**
* @brief UART get RX ring buffer cached data length
*
* @param uart_num UART port number.
* @param size Pointer of size_t to accept cached data length
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t *size);
/**
* @brief UART set threshold timeout for TOUT feature
*
* @param uart_num Uart number to configure
* @param tout_thresh This parameter defines timeout threshold in uart symbol periods. The maximum value of threshold is 126.
* tout_thresh = 1, defines TOUT interrupt timeout equal to transmission time of one symbol (~11 bit) on current baudrate.
* If the time is expired the UART_RXFIFO_TOUT_INT interrupt is triggered. If tout_thresh == 0,
* the TOUT feature is disabled.
*
* @return
* - ESP_OK Success
* - ESP_ERR_INVALID_ARG Parameter error
*/
esp_err_t uart_set_rx_timeout(uart_port_t uart_num, const uint8_t tout_thresh);
#ifdef __cplusplus
}
#endif
#endif // _DRIVER_UART_H_

85
components/esp8266/include/esp8266/uart_register.h
View File

@ -1,31 +1,25 @@
/*
* ESPRSSIF MIT License
*
* Copyright (c) 2015 <ESPRESSIF SYSTEMS (SHANGHAI) PTE LTD>
*
* Permission is hereby granted for use on ESPRESSIF SYSTEMS ESP8266 only, in which case,
* it is free of charge, to any person obtaining a copy of this software and associated
* documentation files (the "Software"), to deal in the Software without restriction, including
* without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
* and/or sell copies of the Software, and to permit persons to whom the Software is furnished
* to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all copies or
* substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*
*/
// Copyright 2018-2025 Espressif Systems (Shanghai) PTE LTD
//
// 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.
#ifndef UART_REGISTER_H_
#define UART_REGISTER_H_
#include "eagle_soc.h"
#include "esp8266/eagle_soc.h"
#ifdef __cplusplus
extern "C" {
#endif
#define REG_UART_BASE(i) (0x60000000 + (i)*0xf00)
//version value:32'h062000
@ -78,6 +72,36 @@
#define UART_TXFIFO_EMPTY_INT_CLR (BIT(1))
#define UART_RXFIFO_FULL_INT_CLR (BIT(0))
#define UART_RXFIFO_FULL_INT_ENA (BIT(0))
#define UART_RXFIFO_FULL_INT_ENA_M (BIT(0))
#define UART_RXFIFO_FULL_INT_ST_M (BIT(0))
#define UART_RXFIFO_FULL_INT_CLR_M (BIT(0))
#define UART_TXFIFO_EMPTY_INT_ENA (BIT(1))
#define UART_TXFIFO_EMPTY_INT_ENA_M (BIT(1))
#define UART_TXFIFO_EMPTY_INT_ST_M (BIT(1))
#define UART_TXFIFO_EMPTY_INT_CLR_M (BIT(1))
#define UART_PARITY_ERR_INT_ENA (BIT(2))
#define UART_PARITY_ERR_INT_ENA_M (BIT(2))
#define UART_PARITY_ERR_INT_ST_M (BIT(2))
#define UART_PARITY_ERR_INT_CLR_M (BIT(2))
#define UART_FRM_ERR_INT_ENA (BIT(3))
#define UART_FRM_ERR_INT_ENA_M (BIT(3))
#define UART_FRM_ERR_INT_ST_M (BIT(3))
#define UART_FRM_ERR_INT_CLR_M (BIT(3))
#define UART_RXFIFO_OVF_INT_ENA (BIT(4))
#define UART_RXFIFO_OVF_INT_ENA_M (BIT(4))
#define UART_RXFIFO_OVF_INT_ST_M (BIT(4))
#define UART_RXFIFO_OVF_INT_CLR_M (BIT(4))
#define UART_RXFIFO_TOUT_INT_ENA (BIT(8))
#define UART_RXFIFO_TOUT_INT_ENA_M (BIT(8))
#define UART_RXFIFO_TOUT_INT_ST_M (BIT(8))
#define UART_RXFIFO_TOUT_INT_CLR_M (BIT(8))
#define UART_CLKDIV(i) (REG_UART_BASE(i) + 0x14)
#define UART_CLKDIV_CNT 0x000FFFFF
#define UART_CLKDIV_S 0
@ -124,7 +148,11 @@
#define UART_BIT_NUM 0x00000003
#define UART_BIT_NUM_S 2
#define UART_PARITY_EN (BIT(1))
#define UART_PARITY_EN_M 0x00000001
#define UART_PARITY_EN_S 1
#define UART_PARITY (BIT(0))
#define UART_PARITY_M 0x00000001
#define UART_PARITY_S 0
#define UART_CONF1(i) (REG_UART_BASE(i) + 0x24)
#define UART_RX_TOUT_EN (BIT(31))
@ -153,4 +181,11 @@
#define UART_DATE(i) (REG_UART_BASE(i) + 0x78)
#define UART_ID(i) (REG_UART_BASE(i) + 0x7C)
#endif // UART_REGISTER_H_INCLUDED
#define UART_SWAP_REG 0x3FF00028
#ifdef __cplusplus
}
#endif /* end of __cplusplus */
#endif /* _UART_REGISTER_H_ */

204
components/esp8266/include/esp8266/uart_struct.h Normal file
View File

@ -0,0 +1,204 @@
/*
* Copyright 2018 Espressif Systems (Shanghai) PTE LTD
*
* 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.
*
*/
#ifndef _UART_STRUCT_H_
#define _UART_STRUCT_H_
#include <stdint.h>
#include "esp8266/eagle_soc.h"
#ifdef __cplusplus
extern "C" {
#endif
/* ESP8266 UART Register Definitions */
typedef volatile struct {
union {
struct {
uint8_t rw_byte; /*This register stores one byte data read by rx fifo.*/
uint8_t reserved[3];
};
__RO__ uint32_t val;
} fifo;
union {
struct {
uint32_t rxfifo_full: 1; /*This interrupt raw bit turns to high level when receiver receives more data than (rx_flow_thrhd_h3 rx_flow_thrhd).*/
uint32_t txfifo_empty: 1; /*This interrupt raw bit turns to high level when the amount of data in transmitter's fifo is less than ((tx_mem_cnttxfifo_cnt) .*/
uint32_t parity_err: 1; /*This interrupt raw bit turns to high level when receiver detects the parity error of data.*/
uint32_t frm_err: 1; /*This interrupt raw bit turns to high level when receiver detects data's frame error .*/
uint32_t rxfifo_ovf: 1; /*This interrupt raw bit turns to high level when receiver receives more data than the fifo can store.*/
uint32_t dsr_chg: 1; /*This interrupt raw bit turns to high level when receiver detects the edge change of dsrn signal.*/
uint32_t cts_chg: 1; /*This interrupt raw bit turns to high level when receiver detects the edge change of ctsn signal.*/
uint32_t brk_det: 1; /*This interrupt raw bit turns to high level when receiver detects the 0 after the stop bit.*/
uint32_t rxfifo_tout: 1; /*This interrupt raw bit turns to high level when receiver takes more time than rx_tout_thrhd to receive a byte.*/
uint32_t reserved9: 23;
};
__RO__ uint32_t val;
} int_raw;
union {
struct {
uint32_t rxfifo_full: 1; /*This is the status bit for rxfifo_full_int_raw when rxfifo_full_int_ena is set to 1.*/
uint32_t txfifo_empty: 1; /*This is the status bit for txfifo_empty_int_raw when txfifo_empty_int_ena is set to 1.*/
uint32_t parity_err: 1; /*This is the status bit for parity_err_int_raw when parity_err_int_ena is set to 1.*/
uint32_t frm_err: 1; /*This is the status bit for frm_err_int_raw when fm_err_int_ena is set to 1.*/
uint32_t rxfifo_ovf: 1; /*This is the status bit for rxfifo_ovf_int_raw when rxfifo_ovf_int_ena is set to 1.*/
uint32_t dsr_chg: 1; /*This is the status bit for dsr_chg_int_raw when dsr_chg_int_ena is set to 1.*/
uint32_t cts_chg: 1; /*This is the status bit for cts_chg_int_raw when cts_chg_int_ena is set to 1.*/
uint32_t brk_det: 1; /*This is the status bit for brk_det_int_raw when brk_det_int_ena is set to 1.*/
uint32_t rxfifo_tout: 1; /*This is the status bit for rxfifo_tout_int_raw when rxfifo_tout_int_ena is set to 1.*/
uint32_t reserved9: 23;
};
__RO__ uint32_t val;
} int_st;
union {
struct {
uint32_t rxfifo_full: 1; /*This is the enable bit for rxfifo_full_int_st register.*/
uint32_t txfifo_empty: 1; /*This is the enable bit for rxfifo_full_int_st register.*/
uint32_t parity_err: 1; /*This is the enable bit for parity_err_int_st register.*/
uint32_t frm_err: 1; /*This is the enable bit for frm_err_int_st register.*/
uint32_t rxfifo_ovf: 1; /*This is the enable bit for rxfifo_ovf_int_st register.*/
uint32_t dsr_chg: 1; /*This is the enable bit for dsr_chg_int_st register.*/
uint32_t cts_chg: 1; /*This is the enable bit for cts_chg_int_st register.*/
uint32_t brk_det: 1; /*This is the enable bit for brk_det_int_st register.*/
uint32_t rxfifo_tout: 1; /*This is the enable bit for rxfifo_tout_int_st register.*/
uint32_t reserved9: 23;
};
__RW__ uint32_t val;
} int_ena;
union {
struct {
uint32_t rxfifo_full: 1; /*Set this bit to clear the rxfifo_full_int_raw interrupt.*/
uint32_t txfifo_empty: 1; /*Set this bit to clear txfifo_empty_int_raw interrupt.*/
uint32_t parity_err: 1; /*Set this bit to clear parity_err_int_raw interrupt.*/
uint32_t frm_err: 1; /*Set this bit to clear frm_err_int_raw interrupt.*/
uint32_t rxfifo_ovf: 1; /*Set this bit to clear rxfifo_ovf_int_raw interrupt.*/
uint32_t dsr_chg: 1; /*Set this bit to clear the dsr_chg_int_raw interrupt.*/
uint32_t cts_chg: 1; /*Set this bit to clear the cts_chg_int_raw interrupt.*/
uint32_t brk_det: 1; /*Set this bit to clear the brk_det_int_raw interrupt.*/
uint32_t rxfifo_tout: 1; /*Set this bit to clear the rxfifo_tout_int_raw interrupt.*/
uint32_t reserved9: 23;
};
__WO__ uint32_t val;
} int_clr;
union {
struct {
uint32_t div_int: 20; /*The register value is the integer part of the frequency divider's factor.*/
uint32_t reserved20: 12;
};
__RW__ uint32_t val;
} clk_div;
union {
struct {
uint32_t en: 1; /*This is the enable bit for detecting baudrate.*/
uint32_t reserved1: 7;
uint32_t glitch_filt: 8; /*when input pulse width is lower then this value ignore this pulse.this register is used in auto-baud detect process.*/
uint32_t reserved16: 16;
};
__RW__ uint32_t val;
} auto_baud;
union {
struct {
uint32_t rxfifo_cnt: 8; /*(rx_mem_cnt rxfifo_cnt) stores the byte number of valid data in receiver's fifo. rx_mem_cnt register stores the 3 most significant bits rxfifo_cnt stores the 8 least significant bits.*/
uint32_t reserved8: 5;
uint32_t dsrn: 1; /*This register stores the level value of the internal uart dsr signal.*/
uint32_t ctsn: 1; /*This register stores the level value of the internal uart cts signal.*/
uint32_t rxd: 1; /*This register stores the level value of the internal uart rxd signal.*/
uint32_t txfifo_cnt: 8; /*(tx_mem_cnt txfifo_cnt) stores the byte number of valid data in transmitter's fifo.tx_mem_cnt stores the 3 most significant bits txfifo_cnt stores the 8 least significant bits.*/
uint32_t reserved24: 5;
uint32_t dtrn: 1; /*The register represent the level value of the internal uart dsr signal.*/
uint32_t rtsn: 1; /*This register represent the level value of the internal uart cts signal.*/
uint32_t txd: 1; /*This register represent the level value of the internal uart rxd signal.*/
};
__RO__ uint32_t val;
} status;
union {
struct {
uint32_t parity: 1; /*This register is used to configure the parity check mode. 0:even 1:odd*/
uint32_t parity_en: 1; /*Set this bit to enable uart parity check.*/
uint32_t bit_num: 2; /*This register is used to set the length of data: 0:5bits 1:6bits 2:7bits 3:8bits*/
uint32_t stop_bit_num: 2; /*This register is used to set the length of stop bit. 1:1bit 2:1.5bits 3:2bits*/
uint32_t sw_rts: 1; /*This register is used to configure the software rts signal which is used in software flow control.*/
uint32_t sw_dtr: 1; /*This register is used to configure the software dtr signal which is used in software flow control..*/
uint32_t txd_brk: 1; /*Set this bit to enable transmitter to send 0 when the process of sending data is done.*/
uint32_t irda_dplx: 1; /*Set this bit to enable irda loop-back mode.*/
uint32_t irda_tx_en: 1; /*This is the start enable bit for irda transmitter.*/
uint32_t irda_wctl: 1; /*1：the irda transmitter's 11th bit is the same to the 10th bit. 0：set irda transmitter's 11th bit to 0.*/
uint32_t irda_tx_inv: 1; /*Set this bit to inverse the level value of irda transmitter's level.*/
uint32_t irda_rx_inv: 1; /*Set this bit to inverse the level value of irda receiver's level.*/
uint32_t loopback: 1; /*Set this bit to enable uart loop-back test mode.*/
uint32_t tx_flow_en: 1; /*Set this bit to enable transmitter's flow control function.*/
uint32_t irda_en: 1; /*Set this bit to enable irda protocol.*/
uint32_t rxfifo_rst: 1; /*Set this bit to reset uart receiver's fifo.*/
uint32_t txfifo_rst: 1; /*Set this bit to reset uart transmitter's fifo.*/
uint32_t rxd_inv: 1; /*Set this bit to inverse the level value of uart rxd signal.*/
uint32_t cts_inv: 1; /*Set this bit to inverse the level value of uart cts signal.*/
uint32_t dsr_inv: 1; /*Set this bit to inverse the level value of uart dsr signal.*/
uint32_t txd_inv: 1; /*Set this bit to inverse the level value of uart txd signal.*/
uint32_t rts_inv: 1; /*Set this bit to inverse the level value of uart rts signal.*/
uint32_t dtr_inv: 1; /*Set this bit to inverse the level value of uart dtr signal.*/
uint32_t reserved25: 7;
};
__RW__ uint32_t val;
} conf0;
union {
struct {
uint32_t rxfifo_full_thrhd: 7; /*When receiver receives more data than its threshold value，receiver will produce rxfifo_full_int_raw interrupt.the threshold value is (rx_flow_thrhd_h3 rxfifo_full_thrhd).*/
uint32_t reserved7: 1;
uint32_t txfifo_empty_thrhd: 7; /*when the data amount in transmitter fifo is less than its threshold value， it will produce txfifo_empty_int_raw interrupt. the threshold value is (tx_mem_empty_thresh txfifo_empty_thrhd)*/
uint32_t reserved15: 1;
uint32_t rx_flow_thrhd: 7; /*when receiver receives more data than its threshold value， receiver produce signal to tell the transmitter stop transferring data. the threshold value is (rx_flow_thrhd_h3 rx_flow_thrhd).*/
uint32_t rx_flow_en: 1; /*This is the flow enable bit for uart receiver. 1:choose software flow control with configuring sw_rts signal*/
uint32_t rx_tout_thrhd: 7; /*This register is used to configure the timeout value for uart receiver receiving a byte.*/
uint32_t rx_tout_en: 1; /*This is the enable bit for uart receiver's timeout function.*/
};
__RW__ uint32_t val;
} conf1;
union {
struct {
uint32_t min_cnt: 20; /*This register stores the value of the minimum duration time for the low level pulse， it is used in baudrate-detect process.*/
uint32_t reserved20: 12;
};
__RO__ uint32_t val;
} lowpulse;
union {
struct {
uint32_t min_cnt: 20; /*This register stores the value of the maximum duration time for the high level pulse， it is used in baudrate-detect process.*/
uint32_t reserved20: 12;
};
__RO__ uint32_t val;
} highpulse;
union {
struct {
uint32_t edge_cnt: 10; /*This register stores the count of rxd edge change， it is used in baudrate-detect process.*/
uint32_t reserved10: 22;
};
__RO__ uint32_t val;
} rxd_cnt;
uint32_t reserved[18];
__RW__ uint32_t date; /**/
__RW__ uint32_t id; /**/
} uart_dev_t;
extern uart_dev_t uart0;
extern uart_dev_t uart1;
#ifdef __cplusplus
}
#endif /* end of __cplusplus */
#endif /* _UART_STRUCT_H_ */

5
components/esp8266/ld/esp8266.peripherals.ld
View File

@ -1 +1,4 @@
PROVIDE ( GPIO = 0x60000300);
PROVIDE ( GPIO = 0x60000300);
PROVIDE ( uart0 = 0x60000000 );
PROVIDE ( uart1 = 0x60000f00 );

1184
components/freertos/freertos/ringbuf.c Normal file
View File

File diff suppressed because it is too large Load Diff

415
components/freertos/include/freertos/ringbuf.h Normal file
View File

@ -0,0 +1,415 @@
// Copyright 2015-2018 Espressif Systems (Shanghai) PTE LTD
//
// 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.
#ifndef FREERTOS_RINGBUF_H
#define FREERTOS_RINGBUF_H
#ifndef INC_FREERTOS_H
#error "include FreeRTOS.h" must appear in source files before "include ringbuf.h"
#endif
#ifdef __cplusplus
extern "C" {
#endif
#include <freertos/queue.h>
/**
* Type by which ring buffers are referenced. For example, a call to xRingbufferCreate()
* returns a RingbufHandle_t variable that can then be used as a parameter to
* xRingbufferSend(), xRingbufferReceive(), etc.
*/
typedef void * RingbufHandle_t;
typedef enum {
/**
* No-split buffers will only store an item in contiguous memory and will
* never split an item. Each item requires an 8 byte overhead for a header
* and will always internally occupy a 32-bit aligned size of space.
*/
RINGBUF_TYPE_NOSPLIT = 0,
/**
* Allow-split buffers will split an item into two parts if necessary in
* order to store it. Each item requires an 8 byte overhead for a header,
* splitting incurs an extra header. Each item will always internally occupy
* a 32-bit aligned size of space.
*/
RINGBUF_TYPE_ALLOWSPLIT,
/**
* Byte buffers store data as a sequence of bytes and do not maintain separate
* items, therefore byte buffers have no overhead. All data is stored as a
* sequence of byte and any number of bytes can be sent or retrieved each
* time.
*/
RINGBUF_TYPE_BYTEBUF
} ringbuf_type_t;
/**
* @brief Create a ring buffer
*
* @param[in] xBufferSize Size of the buffer in bytes. Note that items require
* space for overhead in no-split/allow-split buffers
* @param[in] xBufferType Type of ring buffer, see documentation.
*
* @note xBufferSize of no-split/allow-split buffers will be rounded up to the nearest 32-bit aligned size.
*
* @return A handle to the created ring buffer, or NULL in case of error.
*/
RingbufHandle_t xRingbufferCreate(size_t xBufferSize, ringbuf_type_t xBufferType);
/**
* @brief Create a ring buffer of type RINGBUF_TYPE_NOSPLIT for a fixed item_size
*
* This API is similar to xRingbufferCreate(), but it will internally allocate
* additional space for the headers.
*
* @param[in] xItemSize Size of each item to be put into the ring buffer
* @param[in] xItemNum Maximum number of items the buffer needs to hold simultaneously
*
* @return A RingbufHandle_t handle to the created ring buffer, or NULL in case of error.
*/
RingbufHandle_t xRingbufferCreateNoSplit(size_t xItemSize, size_t xItemNum);
/**
* @brief Insert an item into the ring buffer
*
* Attempt to insert an item into the ring buffer. This function will block until
* enough free space is available or until it timesout.
*
* @param[in] xRingbuffer Ring buffer to insert the item into
* @param[in] pvItem Pointer to data to insert. NULL is allowed if xItemSize is 0.
* @param[in] xItemSize Size of data to insert.
* @param[in] xTicksToWait Ticks to wait for room in the ring buffer.
*
* @note For no-split/allow-split ring buffers, the actual size of memory that
* the item will occupy will be rounded up to the nearest 32-bit aligned
* size. This is done to ensure all items are always stored in 32-bit
* aligned fashion.
*
* @return
* - pdTRUE if succeeded
* - pdFALSE on time-out or when the data is larger than the maximum permissible size of the buffer
*/
BaseType_t xRingbufferSend(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize, TickType_t xTicksToWait);
/**
* @brief Insert an item into the ring buffer in an ISR
*
* Attempt to insert an item into the ring buffer from an ISR. This function
* will return immediately if there is insufficient free space in the buffer.
*
* @param[in] xRingbuffer Ring buffer to insert the item into
* @param[in] pvItem Pointer to data to insert. NULL is allowed if xItemSize is 0.
* @param[in] xItemSize Size of data to insert.
* @param[out] pxHigherPriorityTaskWoken Value pointed to will be set to pdTRUE if the function woke up a higher priority task.
*
* @note For no-split/allow-split ring buffers, the actual size of memory that
* the item will occupy will be rounded up to the nearest 32-bit aligned
* size. This is done to ensure all items are always stored in 32-bit
* aligned fashion.
*
* @return
* - pdTRUE if succeeded
* - pdFALSE when the ring buffer does not have space.
*/
BaseType_t xRingbufferSendFromISR(RingbufHandle_t xRingbuffer, const void *pvItem, size_t xItemSize, BaseType_t *pxHigherPriorityTaskWoken);
/**
* @brief Retrieve an item from the ring buffer
*
* Attempt to retrieve an item from the ring buffer. This function will block
* until an item is available or until it timesout.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] pxItemSize Pointer to a variable to which the size of the retrieved item will be written.
* @param[in] xTicksToWait Ticks to wait for items in the ring buffer.
*
* @note A call to vRingbufferReturnItem() is required after this to free the item retrieved.
*
* @return
* - Pointer to the retrieved item on success; *pxItemSize filled with the length of the item.
* - NULL on timeout, *pxItemSize is untouched in that case.
*/
void *xRingbufferReceive(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTicksToWait);
/**
* @brief Retrieve an item from the ring buffer in an ISR
*
* Attempt to retrieve an item from the ring buffer. This function returns immediately
* if there are no items available for retrieval
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] pxItemSize Pointer to a variable to which the size of the
* retrieved item will be written.
*
* @note A call to vRingbufferReturnItemFromISR() is required after this to free the item retrieved.
* @note Byte buffers do not allow multiple retrievals before returning an item
*
* @return
* - Pointer to the retrieved item on success; *pxItemSize filled with the length of the item.
* - NULL when the ring buffer is empty, *pxItemSize is untouched in that case.
*/
void *xRingbufferReceiveFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize);
/**
* @brief Retrieve a split item from an allow-split ring buffer
*
* Attempt to retrieve a split item from an allow-split ring buffer. If the item
* is not split, only a single item is retried. If the item is split, both parts
* will be retrieved. This function will block until an item is available or
* until it timesout.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] ppvHeadItem Double pointer to first part (set to NULL if no items were retrieved)
* @param[out] ppvTailItem Double pointer to second part (set to NULL if item is not split)
* @param[out] pxHeadItemSize Pointer to size of first part (unmodified if no items were retrieved)
* @param[out] pxTailItemSize Pointer to size of second part (unmodified if item is not split)
* @param[in] xTicksToWait Ticks to wait for items in the ring buffer.
*
* @note Call(s) to vRingbufferReturnItem() is required after this to free up the item(s) retrieved.
* @note This function should only be called on allow-split buffers
*
* @return
* - pdTRUE if an item (split or unsplit) was retrieved
* - pdFALSE when no item was retrieved
*/
BaseType_t xRingbufferReceiveSplit(RingbufHandle_t xRingbuffer, void **ppvHeadItem, void **ppvTailItem, size_t *pxHeadItemSize, size_t *pxTailItemSize, TickType_t xTicksToWait);
/**
* @brief Retrieve a split item from an allow-split ring buffer in an ISR
*
* Attempt to retrieve a split item from an allow-split ring buffer. If the item
* is not split, only a single item is retried. If the item is split, both parts
* will be retrieved. This function returns immediately if there are no items
* available for retrieval
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] ppvHeadItem Double pointer to first part (set to NULL if no items were retrieved)
* @param[out] ppvTailItem Double pointer to second part (set to NULL if item is not split)
* @param[out] pxHeadItemSize Pointer to size of first part (unmodified if no items were retrieved)
* @param[out] pxTailItemSize Pointer to size of second part (unmodified if item is not split)
*
* @note Calls to vRingbufferReturnItemFromISR() is required after this to free up the item(s) retrieved.
* @note This function should only be called on allow-split buffers
*
* @return
* - pdTRUE if an item (split or unsplit) was retrieved
* - pdFALSE when no item was retrieved
*/
BaseType_t xRingbufferReceiveSplitFromISR(RingbufHandle_t xRingbuffer, void **ppvHeadItem, void **ppvTailItem, size_t *pxHeadItemSize, size_t *pxTailItemSize);
/**
* @brief Retrieve bytes from a byte buffer, specifying the maximum amount of bytes to retrieve
*
* Attempt to retrieve data from a byte buffer whilst specifying a maximum number
* of bytes to retrieve. This function will block until there is data available
* for retrieval or until it timesout.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] pxItemSize Pointer to a variable to which the size of the retrieved item will be written.
* @param[in] xTicksToWait Ticks to wait for items in the ring buffer.
* @param[in] xMaxSize Maximum number of bytes to return.
*
* @note A call to vRingbufferReturnItem() is required after this to free up the data retrieved.
* @note This function should only be called on byte buffers
* @note Byte buffers do not allow multiple retrievals before returning an item
*
* @return
* - Pointer to the retrieved item on success; *pxItemSize filled with
* the length of the item.
* - NULL on timeout, *pxItemSize is untouched in that case.
*/
void *xRingbufferReceiveUpTo(RingbufHandle_t xRingbuffer, size_t *pxItemSize, TickType_t xTicksToWait, size_t xMaxSize);
/**
* @brief Retrieve bytes from a byte buffer, specifying the maximum amount of
* bytes to retrieve. Call this from an ISR.
*
* Attempt to retrieve bytes from a byte buffer whilst specifying a maximum number
* of bytes to retrieve. This function will return immediately if there is no data
* available for retrieval.
*
* @param[in] xRingbuffer Ring buffer to retrieve the item from
* @param[out] pxItemSize Pointer to a variable to which the size of the retrieved item will be written.
* @param[in] xMaxSize Maximum number of bytes to return.
*
* @note A call to vRingbufferReturnItemFromISR() is required after this to free up the data received.
* @note This function should only be called on byte buffers
* @note Byte buffers do not allow multiple retrievals before returning an item
*
* @return
* - Pointer to the retrieved item on success; *pxItemSize filled with
* the length of the item.
* - NULL when the ring buffer is empty, *pxItemSize is untouched in that case.
*/
void *xRingbufferReceiveUpToFromISR(RingbufHandle_t xRingbuffer, size_t *pxItemSize, size_t xMaxSize);
/**
* @brief Return a previously-retrieved item to the ring buffer
*
* @param[in] xRingbuffer Ring buffer the item was retrieved from
* @param[in] pvItem Item that was received earlier
*
* @note If a split item is retrieved, both parts should be returned by calling this function twice
*/
void vRingbufferReturnItem(RingbufHandle_t xRingbuffer, void *pvItem);
/**
* @brief Return a previously-retrieved item to the ring buffer from an ISR
*
* @param[in] xRingbuffer Ring buffer the item was retrieved from
* @param[in] pvItem Item that was received earlier
* @param[out] pxHigherPriorityTaskWoken Value pointed to will be set to pdTRUE
* if the function woke up a higher priority task.
*
* @note If a split item is retrieved, both parts should be returned by calling this function twice
*/
void vRingbufferReturnItemFromISR(RingbufHandle_t xRingbuffer, void *pvItem, BaseType_t *pxHigherPriorityTaskWoken);
/**
* @brief Delete a ring buffer
*
* @param[in] xRingbuffer Ring buffer to delete
*/
void vRingbufferDelete(RingbufHandle_t xRingbuffer);
/**
* @brief Get maximum size of an item that can be placed in the ring buffer
*
* This function returns the maximum size an item can have if it was placed in
* an empty ring buffer.
*
* @param[in] xRingbuffer Ring buffer to query
*
* @return Maximum size, in bytes, of an item that can be placed in a ring buffer.
*/
size_t xRingbufferGetMaxItemSize(RingbufHandle_t xRingbuffer);
/**
* @brief Get current free size available for an item/data in the buffer
*
* This gives the real time free space available for an item/data in the ring
* buffer. This represents the maximum size an item/data can have if it was
* currently sent to the ring buffer.
*
* @warning This API is not thread safe. So, if multiple threads are accessing
* the same ring buffer, it is the application's responsibility to
* ensure atomic access to this API and the subsequent Send
*
* @param[in] xRingbuffer Ring buffer to query
*
* @return Current free size, in bytes, available for an entry
*/
size_t xRingbufferGetCurFreeSize(RingbufHandle_t xRingbuffer);
/**
* @brief Add the ring buffer's read semaphore to a queue set.
*
* The ring buffer's read semaphore indicates that data has been written
* to the ring buffer. This function adds the ring buffer's read semaphore to
* a queue set.
*
* @param[in] xRingbuffer Ring buffer to add to the queue set
* @param[in] xQueueSet Queue set to add the ring buffer's read semaphore to
*
* @return
* - pdTRUE on success, pdFALSE otherwise
*/
BaseType_t xRingbufferAddToQueueSetRead(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet);
/**
* @brief Check if the selected queue set member is the ring buffer's read semaphore
*
* This API checks if queue set member returned from xQueueSelectFromSet()
* is the read semaphore of this ring buffer. If so, this indicates the ring buffer
* has items waiting to be retrieved.
*
* @param[in] xRingbuffer Ring buffer which should be checked
* @param[in] xMember Member returned from xQueueSelectFromSet
*
* @return
* - pdTRUE when semaphore belongs to ring buffer
* - pdFALSE otherwise.
*/
BaseType_t xRingbufferCanRead(RingbufHandle_t xRingbuffer, QueueSetMemberHandle_t xMember);
/**
* @brief Remove the ring buffer's read semaphore from a queue set.
*
* This specifically removes a ring buffer's read semaphore from a queue set. The
* read semaphore is used to indicate when data has been written to the ring buffer
*
* @param[in] xRingbuffer Ring buffer to remove from the queue set
* @param[in] xQueueSet Queue set to remove the ring buffer's read semaphore from
*
* @return
* - pdTRUE on success
* - pdFALSE otherwise
*/
BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet);
/**
* @brief Get information about ring buffer status
*
* Get information of the a ring buffer's current status such as
* free/read/write pointer positions, and number of items waiting to be retrieved.
* Arguments can be set to NULL if they are not required.
*
* @param[in] xRingbuffer Ring buffer to remove from the queue set
* @param[out] uxFree Pointer use to store free pointer position
* @param[out] uxRead Pointer use to store read pointer position
* @param[out] uxWrite Pointer use to store write pointer position
* @param[out] uxItemsWaiting Pointer use to store number of items (bytes for byte buffer) waiting to be retrieved
*/
void vRingbufferGetInfo(RingbufHandle_t xRingbuffer, UBaseType_t *uxFree, UBaseType_t *uxRead, UBaseType_t *uxWrite, UBaseType_t *uxItemsWaiting);
/**
* @brief Debugging function to print the internal pointers in the ring buffer
*
* @param xRingbuffer Ring buffer to show
*/
void xRingbufferPrintInfo(RingbufHandle_t xRingbuffer);
/* -------------------------------- Deprecated Functions --------------------------- */
/** @cond */ //Doxygen command to hide deprecated function from API Reference
/*
* Deprecated as function is not thread safe and does not check if an item is
* actually available for retrieval. Use xRingbufferReceiveSplit() instead for
* thread safe method of retrieve a split item.
*/
bool xRingbufferIsNextItemWrapped(RingbufHandle_t xRingbuffer) __attribute__((deprecated));
/*
* Deprecated as queue sets are not meant to be used for writing to buffers. Adding
* the ring buffer write semaphore to a queue set will break queue set usage rules,
* as every read of a semaphore must be preceded by a call to xQueueSelectFromSet().
* QueueSetWrite no longer supported.
*/
BaseType_t xRingbufferAddToQueueSetWrite(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet) __attribute__((deprecated));
/*
* Deprecated as queue sets are not meant to be used for writing to buffers.
* QueueSetWrite no longer supported.
*/
BaseType_t xRingbufferRemoveFromQueueSetWrite(RingbufHandle_t xRingbuffer, QueueSetHandle_t xQueueSet) __attribute__((deprecated));
/** @endcond */
#ifdef __cplusplus
}
#endif
#endif /* FREERTOS_RINGBUF_H */

9
examples/peripherals/uart_echo/Makefile Normal file
View File

@ -0,0 +1,9 @@
#
# This is a project Makefile. It is assumed the directory this Makefile resides in is a
# project subdirectory.
#
PROJECT_NAME := uart_echo
include $(IDF_PATH)/make/project.mk

61
examples/peripherals/uart_echo/README.md Normal file
View File

@ -0,0 +1,61 @@
# _UART Echo Example_
_This is an example which echoes any data it receives on UART0 back to the sender._
## How to use example
### Hardware Required
1. Connect an external serial interface to an ESP8266 board. The external interface should have 3.3V outputs. You may use e.g. 3.3V compatible USB-to-serial dongle:
| ESP8266 Interface | #define | ESP8266 Pin | External UART Pin |
| --- | --- | --- | --- |
| Transmit Data (TxD) | ECHO_TEST_TXD | GPIO26 | RxD |
| Receive Data (RxD) | ECHO_TEST_RXD | GPIO25 | TxD |
| Ground | n/a | GND | GND |
2. Verify if echo indeed comes from ESP8266 by disconnecting either 'TxD' or 'RxD' pin. There should be no any echo once any pin is disconnected.
* Using a hardware flow control
This is an optional check to verify if the hardware flow control works. To set it up you need an external serial interface that has RTS and CTS signals.
1. Connect the extra RTS/CTS signals as below
| ESP8266 Interface | #define | ESP8266 Pin | External UART Pin |
| --- | --- | --- | --- |
| Request to Send (RTS) | ECHO_TEST_RTS | GPIO13 | CTS |
| Clear to Send (CTS) | ECHO_TEST_CTS | GPIO12 | RTS |
2. Configure UART0 driver to use the hardware flow control by setting `.flow_ctrl = UART_HW_FLOWCTRL_CTS_RTS` and adding `.rx_flow_ctrl_thresh = 122`
### Configure the project
```
make menuconfig
```
* Set serial port under Serial Flasher Options.
* `make monitor` baud rate set to what you set in the example.
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
make -j4 flash monitor
```
(To exit the serial monitor, type ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example Output
```
I (180) boot: Loaded app from partition at offset 0x10000
I (0) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
I (0) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
0123456789
```

3
examples/peripherals/uart_echo/main/component.mk Normal file
View File

@ -0,0 +1,3 @@
#
# Main Makefile. This is basically the same as a component makefile.
#

65
examples/peripherals/uart_echo/main/uart_echo_example_main.c Normal file
View File

@ -0,0 +1,65 @@
// Copyright 2018-2025 Espressif Systems (Shanghai) PTE LTD
//
// 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.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/uart.h"
/**
* This is an example which echos any data it receives on UART0 back to the sender,
* with hardware flow control turned off. It does not use UART driver event queue.
*
* - Port: UART0
* - Receive (Rx) buffer: on
* - Transmit (Tx) buffer: off
* - Flow control: off
* - Event queue: off
*/
#define BUF_SIZE (1024)
static void echo_task()
{
// Configure parameters of an UART driver,
// communication pins and install the driver
uart_config_t uart_config = {
.baud_rate = 74880,
.data_bits = UART_DATA_8_BITS,
.parity = UART_PARITY_DISABLE,
.stop_bits = UART_STOP_BITS_1,
.flow_ctrl = UART_HW_FLOWCTRL_DISABLE
};
uart_param_config(UART_NUM_0, &uart_config);
uart_driver_install(UART_NUM_0, BUF_SIZE * 2, 0, 0, NULL);
// Configure a temporary buffer for the incoming data
uint8_t *data = (uint8_t *) malloc(BUF_SIZE);
while (1) {
// Read data from the UART
int len = uart_read_bytes(UART_NUM_0, data, BUF_SIZE, 20 / portTICK_RATE_MS);
// Write data back to the UART
uart_write_bytes(UART_NUM_0, (const char *) data, len);
}
}
void app_main()
{
xTaskCreate(echo_task, "uart_echo_task", 1024, NULL, 10, NULL);
}

9
examples/peripherals/uart_events/Makefile Normal file
View File

@ -0,0 +1,9 @@
#
# This is a project Makefile. It is assumed the directory this Makefile resides in is a
# project subdirectory.
#
PROJECT_NAME := uart_events
include $(IDF_PATH)/make/project.mk

45
examples/peripherals/uart_events/README.md Normal file
View File

@ -0,0 +1,45 @@
# _UART Events Example_
_This example shows how to use the UART driver to handle special UART events. It also reads data from UART0 directly, and echoes it to console._
* Compile and load example from terminl running `make flash monitor`
* Being in 'monotor' type samething to see the `UART_DATA` events and the typed data displayed.
## How to use example
### Configure the project
```
make menuconfig
```
* Set serial port under Serial Flasher Options.
* `make monitor` baud rate set to what you set in the example.
### Build and Flash
Build the project and flash it to the board, then run monitor tool to view serial output:
```
make -j4 flash monitor
```
(To exit the serial monitor, type ``Ctrl-]``.)
See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
## Example Output
* Paste `0123456789` to monitor, the `UART DATA` event will be received.
```
I (185) boot: Loaded app from partition at offset 0x10000
I (0) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
I (0) system_api: Base MAC address is not set, read default base MAC address from BLK0 of EFUSE
I (0) uart: queue free spaces: 100
I (15) uart_events: uart[0] event:
I (15) uart_events: [UART DATA]: 10
I (15) uart_events: [DATA EVT]:
0123456789
```

3
examples/peripherals/uart_events/main/component.mk Normal file
View File

@ -0,0 +1,3 @@
#
# Main Makefile. This is basically the same as a component makefile.
#

128
examples/peripherals/uart_events/main/uart_events_example_main.c Normal file
View File

@ -0,0 +1,128 @@
// Copyright 2018-2025 Espressif Systems (Shanghai) PTE LTD
//
// 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.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "freertos/queue.h"
#include "driver/uart.h"
#include "esp_log.h"
static const char *TAG = "uart_events";
/**
* This example shows how to use the UART driver to handle special UART events.
*
* It also reads data from UART0 directly, and echoes it to console.
*
* - Port: UART0
* - Receive (Rx) buffer: on
* - Transmit (Tx) buffer: on
* - Flow control: off
* - Event queue: on
* - Pin assignment: TxD (default), RxD (default)
*/
#define EX_UART_NUM UART_NUM_0
#define BUF_SIZE (1024)
#define RD_BUF_SIZE (BUF_SIZE)
static QueueHandle_t uart0_queue;
static void uart_event_task(void *pvParameters)
{
uart_event_t event;
size_t buffered_size;
uint8_t *dtmp = (uint8_t *) malloc(RD_BUF_SIZE);
for (;;) {
// Waiting for UART event.
if (xQueueReceive(uart0_queue, (void *)&event, (portTickType)portMAX_DELAY)) {
bzero(dtmp, RD_BUF_SIZE);
ESP_LOGI(TAG, "uart[%d] event:", EX_UART_NUM);
switch (event.type) {
// Event of UART receving data
// We'd better handler data event fast, there would be much more data events than
// other types of events. If we take too much time on data event, the queue might be full.
case UART_DATA:
ESP_LOGI(TAG, "[UART DATA]: %d", event.size);
uart_read_bytes(EX_UART_NUM, dtmp, event.size, portMAX_DELAY);
ESP_LOGI(TAG, "[DATA EVT]:");
uart_write_bytes(EX_UART_NUM, (const char *) dtmp, event.size);
break;
// Event of HW FIFO overflow detected
case UART_FIFO_OVF:
ESP_LOGI(TAG, "hw fifo overflow");
// If fifo overflow happened, you should consider adding flow control for your application.
// The ISR has already reset the rx FIFO,
// As an example, we directly flush the rx buffer here in order to read more data.
uart_flush_input(EX_UART_NUM);
xQueueReset(uart0_queue);
break;
// Event of UART ring buffer full
case UART_BUFFER_FULL:
ESP_LOGI(TAG, "ring buffer full");
// If buffer full happened, you should consider encreasing your buffer size
// As an example, we directly flush the rx buffer here in order to read more data.
uart_flush_input(EX_UART_NUM);
xQueueReset(uart0_queue);
break;
case UART_PARITY_ERR:
ESP_LOGI(TAG, "uart parity error");
break;
// Event of UART frame error
case UART_FRAME_ERR:
ESP_LOGI(TAG, "uart frame error");
break;
// Others
default:
ESP_LOGI(TAG, "uart event type: %d", event.type);
break;
}
}
}
free(dtmp);
dtmp = NULL;
vTaskDelete(NULL);
}
void app_main()
{
// Configure parameters of an UART driver,
// communication pins and install the driver
uart_config_t uart_config = {
.baud_rate = 74880,
.data_bits = UART_DATA_8_BITS,
.parity = UART_PARITY_DISABLE,
.stop_bits = UART_STOP_BITS_1,
.flow_ctrl = UART_HW_FLOWCTRL_DISABLE
};
uart_param_config(EX_UART_NUM, &uart_config);
// Install UART driver, and get the queue.
uart_driver_install(EX_UART_NUM, BUF_SIZE * 2, BUF_SIZE * 2, 100, &uart0_queue);
// Create a task to handler UART event from ISR
xTaskCreate(uart_event_task, "uart_event_task", 2048, NULL, 12, NULL);
}