LibXR::ESP32UART Class Reference

ESP32 UART backend with FIFO and optional GDMA fast paths. More...

#include <esp_uart.hpp>

Inheritance diagram for LibXR::ESP32UART:

Collaboration diagram for LibXR::ESP32UART:

Public Member Functions
	ESP32UART (uart_port_t uart_num, int tx_pin, int rx_pin, int rts_pin=PIN_NO_CHANGE, int cts_pin=PIN_NO_CHANGE, size_t rx_buffer_size=1024, size_t tx_buffer_size=512, uint32_t tx_queue_size=5, UART::Configuration config={115200, UART::Parity::NO_PARITY, 8, 1}, bool enable_dma=true)
	Create and initialize one ESP32 UART instance.
ErrorCode	SetConfig (UART::Configuration config) override
	Apply a new UART framing and baud configuration.
ErrorCode	SetLoopback (bool enable)
	Toggle UART peripheral internal loopback mode.
Public Member Functions inherited from LibXR::UART
template<typename ReadPortType = ReadPort, typename WritePortType = WritePort>
	UART (ReadPortType *read_port, WritePortType *write_port)
	UART 构造函数 / UART constructor.
template<typename OperationType , typename = std::enable_if_t<std::is_base_of_v< WriteOperation, std::decay_t<OperationType>>>>
ErrorCode	Write (ConstRawData data, OperationType &&op, bool in_isr=false)
template<typename OperationType , typename = std::enable_if_t<std::is_base_of_v< ReadOperation, std::decay_t<OperationType>>>>
ErrorCode	Read (RawData data, OperationType &&op, bool in_isr=false)

Static Public Member Functions
static ErrorCode	WriteFun (WritePort &port, bool in_isr)
	Queue-driven TX entry used by WritePort.
static ErrorCode	ReadFun (ReadPort &port, bool in_isr)
	Queue-driven RX entry used by ReadPort.

Static Public Attributes
static constexpr int	PIN_NO_CHANGE = -1
	Sentinel for an unmapped GPIO.

Private Member Functions
ErrorCode	InitUartHardware ()
	Initialize UART hardware and base HAL state.
ErrorCode	ConfigurePins ()
	Configure the selected GPIO pins.
ErrorCode	InstallUartIsr ()
	Install the UART interrupt handler.
void	ConfigureRxInterruptPath ()
	Program RX interrupt thresholds and masks.
ErrorCode	TryStartTx (bool in_isr)
	Try to start queued transmit work.
bool	LoadActiveTxFromQueue (bool in_isr)
	Load one active TX request from the queue.
bool	LoadPendingTxFromQueue (bool in_isr)
	Preload one pending TX request for DMA mode.
bool	PromotePendingTxToActive ()
	Promote one preloaded DMA pending request into the active slot.
bool	StartPendingTxIfIdle (bool in_isr)
	Start the current pending DMA request when TX is fully idle.
bool	DequeueTxToBuffer (uint8_t *buffer, size_t &size, WriteInfoBlock &info, bool in_isr)
	Dequeue one TX payload into the selected buffer.
bool	StartActiveTransfer (bool in_isr)
	Start the active request on the selected TX backend.
bool	StartAndReportActive (bool in_isr)
	Start the active request and report queue completion ownership.
void	ClearActiveTx ()
	Clear active TX state.
void	ClearPendingTx ()
	Clear pending TX state.
void	FillTxFifo (bool in_isr)
	Drain active TX bytes into the UART FIFO backend.
void	PushRxBytes (const uint8_t *data, size_t size, bool in_isr)
	Push RX bytes into the software queue.
void	DrainRxFifo (bool in_isr)
	Drain pending bytes from the hardware RX FIFO.
void	HandleRxInterrupt (uint32_t uart_intr_status)
	Handle RX-side UART interrupt reasons.
void	HandleTxInterrupt (uint32_t uart_intr_status)
	Handle TX-side UART interrupt reasons.
void	HandleUartInterrupt ()
	Dispatch pending UART interrupt reasons.
void	OnTxTransferDone (bool in_isr, ErrorCode result)
	Finalize one TX transfer result.

Static Private Member Functions
static uint8_t *	AllocateTxStorage (size_t size)
	Allocate DMA-capable backing storage for TX buffers.
static ErrorCode	ResolveUartPeriph (uart_port_t uart_num, periph_module_t &out)
	Map one UART index to its peripheral module.
static bool	ResolveWordLength (uint8_t data_bits, uart_word_length_t &out)
	Convert configured data bits into the HAL enum.
static bool	ResolveStopBits (uint8_t stop_bits, uart_stop_bits_t &out)
	Convert configured stop bits into the HAL enum.
static uart_parity_t	ResolveParity (UART::Parity parity)
	Convert configured parity into the HAL enum.
static void	UartIsrEntry (void *arg)
	UART ISR trampoline.

Private Attributes
uart_port_t	uart_num_
	Selected UART peripheral index.
int	tx_pin_
	TX GPIO pin or PIN_NO_CHANGE.
int	rx_pin_
	RX GPIO pin or PIN_NO_CHANGE.
int	rts_pin_
	RTS GPIO pin or PIN_NO_CHANGE.
int	cts_pin_
	CTS GPIO pin or PIN_NO_CHANGE.
UART::Configuration	config_
	Current UART framing configuration.
uint8_t *	rx_isr_buffer_ = nullptr
	Scratch buffer used by the RX ISR path.
size_t	rx_isr_buffer_size_ = 0
	Size of rx_isr_buffer_.
uint8_t *	tx_storage_ = nullptr
	Backing storage for the TX half-buffers.
DoubleBuffer	tx_dma_buffer_ {}
	TX double-buffer view for the DMA path.
WriteInfoBlock	tx_active_info_ = {}
	Metadata for the active TX request.
size_t	tx_active_length_ = 0U
	Active TX payload length in bytes.
size_t	tx_active_offset_ = 0U
	Bytes already emitted for the active request.
bool	tx_active_valid_ = false
	Whether the active TX metadata is valid.
Flag::Plain	tx_busy_
	Hardware TX engine currently owns the request.
Flag::Plain	in_tx_isr_
	Reentry guard while processing TX ISR work.
bool	uart_hw_enabled_ = false
	UART hardware block was initialized.
uart_hal_context_t	uart_hal_ = {}
	ESP-IDF UART HAL context.
intr_handle_t	uart_intr_handle_ = nullptr
	Registered UART interrupt handle.
bool	uart_isr_installed_ = false
	UART ISR installation state.
bool	dma_requested_ = true
	Constructor preference for DMA mode.
ESP32UARTReadPort	_read_port
	Read-side queue bridge exposed to UART.
WritePort	_write_port
	Write-side queue bridge exposed to UART.
Flag::Atomic	rx_fifo_draining_ {}
	RX FIFO drain reentry gate.

Friends
class	ESP32UARTReadPort

Additional Inherited Members
Public Types inherited from LibXR::UART
enum class	Parity : uint8_t { NO_PARITY = 0 , EVEN = 1 , ODD = 2 }
	奇偶校验模式 / Parity mode More...
Data Fields inherited from LibXR::UART
ReadPort *	read_port_
	读取端口 / Read port
WritePort *	write_port_
	写入端口 / Write port

Detailed Description

ESP32 UART backend with FIFO and optional GDMA fast paths.

ESP32 UART 后端，支持 FIFO 和可选 GDMA 快路径。

The object owns the UART hardware state, software queue plumbing, and the optional DMA resources used by the ESP-specific transmit and receive paths. 该对象持有 UART 硬件状态、软件队列连接，以及 ESP 专用收发路径使用的可选 DMA 资源。

Definition at line 75 of file esp_uart.hpp.

Constructor & Destructor Documentation

ESP32UART()

LibXR::ESP32UART::ESP32UART	(	uart_port_t	uart_num,
		int	tx_pin,
		int	rx_pin,
		int	rts_pin = PIN_NO_CHANGE,
		int	cts_pin = PIN_NO_CHANGE,
		size_t	rx_buffer_size = 1024,
		size_t	tx_buffer_size = 512,
		uint32_t	tx_queue_size = 5,
		UART::Configuration	config = {115200, UART::Parity::NO_PARITY, 8, 1},
		bool	enable_dma = true )

Create and initialize one ESP32 UART instance.

创建并初始化一个 ESP32 UART 实例。

Definition at line 104 of file esp_uart.cpp.

    : UART(&_read_port, &_write_port),
      uart_num_(uart_num),
      tx_pin_(tx_pin),
      rx_pin_(rx_pin),
      rts_pin_(rts_pin),
      cts_pin_(cts_pin),
      config_(config),
      rx_isr_buffer_(new uint8_t[rx_buffer_size]),
      rx_isr_buffer_size_(rx_buffer_size),
      tx_storage_(AllocateTxStorage(tx_buffer_size * 2)),
      dma_requested_(enable_dma),
      _read_port(rx_buffer_size, *this),
      _write_port(tx_queue_size, tx_buffer_size)
{
  ASSERT(!IsConsoleUartInUse(uart_num_));
  ASSERT(uart_num_ < UART_NUM_MAX);
  ASSERT(uart_num_ < SOC_UART_HP_NUM);
  ASSERT(rx_isr_buffer_size_ > 0);
  ASSERT(tx_buffer_size > 0);
 
  tx_dma_buffer_.Init({tx_storage_, tx_buffer_size * 2U});
 
  _read_port = ReadFun;
  _write_port = WriteFun;
 
  if (InitUartHardware() != ErrorCode::OK)
  {
    ASSERT(false);
    return;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_requested_)
  {
    if (InitDmaBackend() != ErrorCode::OK)
    {
      ASSERT(false);
      return;
    }
  }
 
  if (!dma_backend_enabled_)
  {
    if (InstallUartIsr() != ErrorCode::OK)
    {
      ASSERT(false);
      return;
    }
    ConfigureRxInterruptPath();
  }
#else
  if (InstallUartIsr() != ErrorCode::OK)
  {
    ASSERT(false);
    return;
  }
  ConfigureRxInterruptPath();
#endif
}

Member Function Documentation

AllocateTxStorage()

uint8_t * LibXR::ESP32UART::AllocateTxStorage ( size_t size )

staticprivate

Allocate DMA-capable backing storage for TX buffers.

为 TX buffer 分配可 DMA 访问的 backing storage。

Definition at line 66 of file esp_uart.cpp.

{
  void* aligned = heap_caps_aligned_alloc(
      4, size, MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA | MALLOC_CAP_8BIT);
  if (aligned != nullptr)
  {
    return static_cast<uint8_t*>(aligned);
  }
 
  return static_cast<uint8_t*>(
      heap_caps_malloc(size, MALLOC_CAP_INTERNAL | MALLOC_CAP_DMA | MALLOC_CAP_8BIT));
}

ClearActiveTx()

void IRAM_ATTR LibXR::ESP32UART::ClearActiveTx ( )

private

Clear active TX state.

清除 active TX 状态。

Definition at line 451 of file esp_uart.cpp.

{
  tx_active_length_ = 0U;
  tx_active_offset_ = 0U;
  tx_active_info_ = {};
  tx_active_valid_ = false;
}

ClearPendingTx()

void IRAM_ATTR LibXR::ESP32UART::ClearPendingTx ( )

private

Clear pending TX state.

清除 pending TX 状态。

Definition at line 461 of file esp_uart.cpp.

{
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    tx_dma_buffer_.Reset();
  }
#endif
}

ConfigurePins()

ErrorCode LibXR::ESP32UART::ConfigurePins ( )

private

Configure the selected GPIO pins.

配置选定的 GPIO 引脚。

Definition at line 399 of file esp_uart.cpp.

{
  if (tx_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_OUTPUT_GPIO(tx_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    esp_rom_gpio_pad_select_gpio(static_cast<uint32_t>(tx_pin_));
    esp_rom_gpio_connect_out_signal(
        tx_pin_, UART_PERIPH_SIGNAL(uart_num_, SOC_UART_TX_PIN_IDX), false, false);
  }
 
  if (rx_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_GPIO(rx_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    gpio_input_enable(static_cast<gpio_num_t>(rx_pin_));
    esp_rom_gpio_connect_in_signal(
        rx_pin_, UART_PERIPH_SIGNAL(uart_num_, SOC_UART_RX_PIN_IDX), false);
  }
 
  if (rts_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_OUTPUT_GPIO(rts_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    esp_rom_gpio_pad_select_gpio(static_cast<uint32_t>(rts_pin_));
    esp_rom_gpio_connect_out_signal(
        rts_pin_, UART_PERIPH_SIGNAL(uart_num_, SOC_UART_RTS_PIN_IDX), false, false);
  }
 
  if (cts_pin_ >= 0)
  {
    if (!GPIO_IS_VALID_GPIO(cts_pin_))
    {
      return ErrorCode::ARG_ERR;
    }
    gpio_pullup_en(static_cast<gpio_num_t>(cts_pin_));
    gpio_input_enable(static_cast<gpio_num_t>(cts_pin_));
    esp_rom_gpio_connect_in_signal(
        cts_pin_, UART_PERIPH_SIGNAL(uart_num_, SOC_UART_CTS_PIN_IDX), false);
  }
 
  return ErrorCode::OK;
}

ConfigureRxInterruptPath()

void LibXR::ESP32UART::ConfigureRxInterruptPath ( )

private

Program RX interrupt thresholds and masks.

配置 RX 中断阈值和掩码。

Definition at line 170 of file esp_uart.cpp.

{
  const uint16_t full_thr = static_cast<uint16_t>(SOC_UART_FIFO_LEN / 2U);
 
  uart_hal_set_rxfifo_full_thr(&uart_hal_, full_thr);
  uart_hal_set_rx_timeout(&uart_hal_, RX_TOUT_THRESHOLD);
  uart_hal_clr_intsts_mask(&uart_hal_, UART_RX_INTR_MASK);
  uart_hal_ena_intr_mask(&uart_hal_, UART_RX_INTR_MASK);
}

DequeueTxToBuffer()

bool IRAM_ATTR LibXR::ESP32UART::DequeueTxToBuffer ( uint8_t * buffer, size_t & size, WriteInfoBlock & info, bool in_isr )

private

Dequeue one TX payload into the selected buffer.

将一个 TX payload 出队到选定缓冲区。

Definition at line 684 of file esp_uart.cpp.

{
  (void)in_isr;
  (void)buffer;
 
  WriteInfoBlock peek_info = {};
  if (write_port_->queue_info_->Peek(peek_info) != ErrorCode::OK)
  {
    return false;
  }
 
  size_t max_size = write_port_->queue_data_->MaxSize();
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    max_size = tx_dma_buffer_.Size();
  }
#endif
  if (peek_info.data.size_ > max_size)
  {
    ASSERT(false);
    return false;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    if (write_port_->queue_data_->PopBatch(buffer, peek_info.data.size_) != ErrorCode::OK)
    {
      return false;
    }
  }
#endif
 
  if (write_port_->queue_info_->Pop(info) != ErrorCode::OK)
  {
    return false;
  }
 
  size = peek_info.data.size_;
  return true;
}

DrainRxFifo()

void IRAM_ATTR LibXR::ESP32UART::DrainRxFifo ( bool in_isr )

private

Drain pending bytes from the hardware RX FIFO.

从硬件 RX FIFO 中取出待处理字节。

Definition at line 118 of file esp_uart_fifo.cpp.

{
  if (rx_fifo_draining_.TestAndSet())
  {
    return;
  }
 
  bool pushed_any = false;
  while (uart_hal_get_rxfifo_len(&uart_hal_) > 0U)
  {
    const size_t fifo_len = uart_hal_get_rxfifo_len(&uart_hal_);
    const size_t write_len = std::min(fifo_len, read_port_->queue_data_->EmptySize());
    if (write_len == 0U)
    {
      break;
    }
 
    const ErrorCode push_ec = read_port_->queue_data_->PushWithWriter(
        write_len,
        [this](uint8_t* buffer, size_t chunk_size) -> ErrorCode
        {
          int read_len = static_cast<int>(chunk_size);
          uart_hal_read_rxfifo(&uart_hal_, buffer, &read_len);
          return (read_len == static_cast<int>(chunk_size)) ? ErrorCode::OK
                                                            : ErrorCode::EMPTY;
        });
 
    if ((push_ec == ErrorCode::FULL) || (push_ec == ErrorCode::EMPTY))
    {
      break;
    }
    if (push_ec != ErrorCode::OK)
    {
      ASSERT(false);
      break;
    }
 
    pushed_any = true;
  }
 
  if (pushed_any)
  {
    read_port_->ProcessPendingReads(in_isr);
  }
 
  rx_fifo_draining_.Clear();
}

FillTxFifo()

void IRAM_ATTR LibXR::ESP32UART::FillTxFifo ( bool in_isr )

private

Drain active TX bytes into the UART FIFO backend.

将 active TX 字节排入 UART FIFO 后端。

Definition at line 68 of file esp_uart_fifo.cpp.

{
  if (!tx_active_valid_)
  {
    return;
  }
 
  while (tx_active_offset_ < tx_active_length_)
  {
    const uint32_t fifo_space = uart_hal_get_txfifo_len(&uart_hal_);
    if (fifo_space == 0U)
    {
      break;
    }
 
    const size_t remaining = tx_active_length_ - tx_active_offset_;
    const size_t chunk_size = std::min<size_t>(remaining, fifo_space);
 
    const ErrorCode pop_ec = write_port_->queue_data_->PopWithReader(
        chunk_size,
        [this](const uint8_t* src, size_t size) -> ErrorCode
        {
          uint32_t write_size = 0;
          uart_hal_write_txfifo(&uart_hal_, src, static_cast<uint32_t>(size),
                                &write_size);
          return (write_size == static_cast<uint32_t>(size)) ? ErrorCode::OK
                                                             : ErrorCode::EMPTY;
        });
    if (pop_ec != ErrorCode::OK)
    {
      ASSERT(false);
      break;
    }
 
    tx_active_offset_ += chunk_size;
  }
 
  if ((tx_active_offset_ < tx_active_length_) || !in_isr)
  {
    return;
  }
 
  uart_hal_disable_intr_mask(&uart_hal_, UART_INTR_TXFIFO_EMPTY);
  OnTxTransferDone(true, ErrorCode::OK);
}

HandleRxInterrupt()

void IRAM_ATTR LibXR::ESP32UART::HandleRxInterrupt ( uint32_t uart_intr_status )

private

Handle RX-side UART interrupt reasons.

处理 RX 侧 UART 中断原因。

Definition at line 170 of file esp_uart_fifo.cpp.

{
  const bool has_overflow = (uart_intr_status & UART_INTR_RXFIFO_OVF) != 0U;
  const bool has_rx_data =
      (uart_intr_status & (UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT)) != 0U;
 
  if (!has_overflow && !has_rx_data)
  {
    return;
  }
 
  if (has_overflow)
  {
    // Overrun means at least one incoming byte was dropped. Keep remaining FIFO
    // bytes to minimize extra loss instead of resetting the whole RX FIFO.
    uart_hal_clr_intsts_mask(&uart_hal_, UART_INTR_RXFIFO_OVF);
  }
 
  DrainRxFifo(true);
  uart_hal_clr_intsts_mask(&uart_hal_, UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT);
}

HandleTxInterrupt()

void IRAM_ATTR LibXR::ESP32UART::HandleTxInterrupt ( uint32_t uart_intr_status )

private

Handle TX-side UART interrupt reasons.

处理 TX 侧 UART 中断原因。

Definition at line 195 of file esp_uart_fifo.cpp.

{
  if ((uart_intr_status & UART_INTR_TXFIFO_EMPTY) == 0U)
  {
    return;
  }
 
  Flag::ScopedRestore tx_flag(in_tx_isr_);
  FillTxFifo(true);
  uart_hal_clr_intsts_mask(&uart_hal_, UART_INTR_TXFIFO_EMPTY);
}

HandleUartInterrupt()

void IRAM_ATTR LibXR::ESP32UART::HandleUartInterrupt ( )

private

Dispatch pending UART interrupt reasons.

分发待处理的 UART 中断原因。

Definition at line 211 of file esp_uart_fifo.cpp.

{
  uint32_t uart_intr_status = uart_hal_get_intsts_mask(&uart_hal_);
 
  while (uart_intr_status != 0)
  {
    if (uart_intr_status & UART_RX_INTR_MASK)
    {
      HandleRxInterrupt(uart_intr_status);
    }
 
    if (uart_intr_status & UART_TX_INTR_MASK)
    {
      HandleTxInterrupt(uart_intr_status);
    }
 
    uart_intr_status = uart_hal_get_intsts_mask(&uart_hal_);
  }
}

InitUartHardware()

ErrorCode LibXR::ESP32UART::InitUartHardware ( )

private

Initialize UART hardware and base HAL state.

初始化 UART 硬件和基础 HAL 状态。

Definition at line 351 of file esp_uart.cpp.

{
  if (uart_num_ >= UART_NUM_MAX)
  {
    return ErrorCode::NOT_SUPPORT;
  }
 
  periph_module_t uart_module = PERIPH_MODULE_MAX;
  if (ResolveUartPeriph(uart_num_, uart_module) != ErrorCode::OK)
  {
    return ErrorCode::NOT_SUPPORT;
  }
 
  uart_hal_.dev = UART_LL_GET_HW(uart_num_);
  if (uart_hal_.dev == nullptr)
  {
    return ErrorCode::NOT_SUPPORT;
  }
 
  periph_module_enable(uart_module);
  periph_module_reset(uart_module);
 
  uart_ll_sclk_enable(uart_hal_.dev);
  uart_hal_init(&uart_hal_, uart_num_);
 
  uart_hw_enabled_ = true;
  if (SetConfig(config_) != ErrorCode::OK)
  {
    uart_hw_enabled_ = false;
    return ErrorCode::INIT_ERR;
  }
 
  if (ConfigurePins() != ErrorCode::OK)
  {
    uart_hw_enabled_ = false;
    return ErrorCode::INIT_ERR;
  }
 
  uart_hal_txfifo_rst(&uart_hal_);
  uart_hal_rxfifo_rst(&uart_hal_);
  uart_hal_clr_intsts_mask(&uart_hal_, UINT32_MAX);
  uart_hal_disable_intr_mask(&uart_hal_, UINT32_MAX);
 
  return ErrorCode::OK;
}

InstallUartIsr()

ErrorCode LibXR::ESP32UART::InstallUartIsr ( )

private

Install the UART interrupt handler.

安装 UART 中断处理函数。

Definition at line 38 of file esp_uart_fifo.cpp.

{
  if (uart_isr_installed_)
  {
    return ErrorCode::OK;
  }
 
#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S3
  // Classic ESP32/S3 can enter cache-disabled flash windows while UART IRQ is active.
  // The current WritePort path is not fully IRAM-safe, so keep this IRQ non-IRAM.
  constexpr int UART_INTR_FLAGS = 0;
#else
  constexpr int UART_INTR_FLAGS = ESP_INTR_FLAG_IRAM;
#endif
 
  const esp_err_t err = esp_intr_alloc(uart_periph_signal[uart_num_].irq, UART_INTR_FLAGS,
                                       UartIsrEntry, this, &uart_intr_handle_);
  if (err != ESP_OK)
  {
    return ErrorCode::INIT_ERR;
  }
 
  uart_isr_installed_ = true;
  return ErrorCode::OK;
}

LoadActiveTxFromQueue()

bool IRAM_ATTR LibXR::ESP32UART::LoadActiveTxFromQueue ( bool in_isr )

private

Load one active TX request from the queue.

从队列装载一个 active TX 请求。

Definition at line 540 of file esp_uart.cpp.

{
  (void)in_isr;
 
  size_t active_length = 0U;
  WriteInfoBlock active_info = {};
  uint8_t* active_buffer = nullptr;
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    active_buffer = tx_dma_buffer_.ActiveBuffer();
  }
#endif
  if (!DequeueTxToBuffer(active_buffer, active_length, active_info, in_isr))
  {
    return false;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    tx_dma_buffer_.SetActiveLength(active_length);
  }
  else
#endif
  {
    tx_active_length_ = active_length;
  }
  tx_active_offset_ = 0U;
  tx_active_info_ = active_info;
  tx_active_valid_ = true;
  return true;
}

LoadPendingTxFromQueue()

bool IRAM_ATTR LibXR::ESP32UART::LoadPendingTxFromQueue ( bool in_isr )

private

Preload one pending TX request for DMA mode.

为 DMA 模式预装一个 pending TX 请求。

Definition at line 578 of file esp_uart.cpp.

{
  (void)in_isr;
 
#if !(SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED)
  return false;
#else
  if (!dma_backend_enabled_ || tx_dma_buffer_.HasPending())
  {
    return false;
  }
 
  size_t pending_length = 0U;
  WriteInfoBlock pending_info = {};
  if (write_port_->queue_info_->Peek(pending_info) != ErrorCode::OK)
  {
    return false;
  }
 
  if (pending_info.data.size_ > tx_dma_buffer_.Size())
  {
    ASSERT(false);
    return false;
  }
 
  if (write_port_->queue_data_->PopBatch(tx_dma_buffer_.PendingBuffer(),
                                         pending_info.data.size_) != ErrorCode::OK)
  {
    return false;
  }
 
  pending_length = pending_info.data.size_;
  tx_dma_buffer_.SetPendingLength(pending_length);
  tx_dma_buffer_.EnablePending();
  return true;
#endif
}

OnTxTransferDone()

void IRAM_ATTR LibXR::ESP32UART::OnTxTransferDone ( bool in_isr, ErrorCode result )

private

Finalize one TX transfer result.

收尾一次 TX 传输结果。

Definition at line 807 of file esp_uart.cpp.

{
  Flag::ScopedRestore tx_flag(in_tx_isr_);
  tx_busy_.Clear();
 
  ClearActiveTx();
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    if ((result != ErrorCode::OK) && tx_dma_buffer_.HasPending())
    {
      WriteInfoBlock dropped_info = {};
      if (write_port_->queue_info_->Pop(dropped_info) == ErrorCode::OK)
      {
        write_port_->Finish(in_isr, ErrorCode::FAILED, dropped_info);
      }
      else
      {
        ASSERT(false);
      }
      tx_dma_buffer_.Reset();
    }
 
    if (result != ErrorCode::OK)
    {
      return;
    }
 
    if (!PromotePendingTxToActive())
    {
      return;
    }
 
    if (!StartAndReportActive(in_isr))
    {
      return;
    }
 
    if (!tx_dma_buffer_.HasPending())
    {
      (void)LoadPendingTxFromQueue(in_isr);
    }
    return;
  }
#endif
 
  if (result != ErrorCode::OK)
  {
    return;
  }
 
  if (LoadActiveTxFromQueue(in_isr))
  {
    (void)StartAndReportActive(in_isr);
  }
}

PromotePendingTxToActive()

bool IRAM_ATTR LibXR::ESP32UART::PromotePendingTxToActive ( )

private

Promote one preloaded DMA pending request into the active slot.

将一个已经预装的 DMA pending 请求提升到 active 槽位。

Definition at line 620 of file esp_uart.cpp.

{
#if !(SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED)
  return false;
#else
  if (!dma_backend_enabled_)
  {
    return false;
  }
 
  if (tx_active_valid_ || !tx_dma_buffer_.HasPending())
  {
    return false;
  }
 
  const size_t pending_length = tx_dma_buffer_.GetPendingLength();
  tx_dma_buffer_.Switch();
  tx_dma_buffer_.SetActiveLength(pending_length);
 
  if (write_port_->queue_info_->Pop(tx_active_info_) != ErrorCode::OK)
  {
    ASSERT(false);
    return false;
  }
  tx_active_length_ = pending_length;
  tx_active_offset_ = 0U;
  tx_active_valid_ = true;
 
  return true;
#endif
}

PushRxBytes()

void IRAM_ATTR LibXR::ESP32UART::PushRxBytes ( const uint8_t * data, size_t size, bool in_isr )

private

Push RX bytes into the software queue.

将 RX 字节推入软件队列。

Definition at line 771 of file esp_uart.cpp.

{
  size_t offset = 0;
  bool pushed_any = false;
  while (offset < size)
  {
    const size_t free_space = read_port_->queue_data_->EmptySize();
    if (free_space == 0)
    {
      break;
    }
 
    const size_t chunk = std::min(free_space, size - offset);
    if (read_port_->queue_data_->PushBatch(data + offset, chunk) != ErrorCode::OK)
    {
      break;
    }
 
    offset += chunk;
    pushed_any = true;
  }
 
  if (pushed_any)
  {
    read_port_->ProcessPendingReads(in_isr);
  }
}

ReadFun()

ErrorCode LibXR::ESP32UART::ReadFun ( ReadPort & port, bool in_isr )

static

Queue-driven RX entry used by ReadPort.

ReadPort 使用的队列驱动 RX 入口。

Definition at line 289 of file esp_uart.cpp.

{ return ErrorCode::PENDING; }

ResolveParity()

uart_parity_t LibXR::ESP32UART::ResolveParity ( UART::Parity parity )

staticprivate

Convert configured parity into the HAL enum.

将配置的校验位转换为 HAL 枚举。

Definition at line 333 of file esp_uart.cpp.

{
  switch (parity)
  {
    case UART::Parity::NO_PARITY:
      return UART_PARITY_DISABLE;
    case UART::Parity::EVEN:
      return UART_PARITY_EVEN;
    case UART::Parity::ODD:
      return UART_PARITY_ODD;
    default:
      return UART_PARITY_DISABLE;
  }
}

ResolveStopBits()

bool LibXR::ESP32UART::ResolveStopBits ( uint8_t stop_bits, uart_stop_bits_t & out )

staticprivate

Convert configured stop bits into the HAL enum.

将配置的停止位转换为 HAL 枚举。

Definition at line 316 of file esp_uart.cpp.

{
  switch (stop_bits)
  {
    case 1:
      out = UART_STOP_BITS_1;
      return true;
    case 2:
      out = UART_STOP_BITS_2;
      return true;
    default:
      return false;
  }
}

ResolveUartPeriph()

ErrorCode LibXR::ESP32UART::ResolveUartPeriph ( uart_port_t uart_num, periph_module_t & out )

staticprivate

Map one UART index to its peripheral module.

将一个 UART 序号映射到对应的外设模块。

Definition at line 81 of file esp_uart.cpp.

{
  switch (uart_num)
  {
    case UART_NUM_0:
      out = PERIPH_UART0_MODULE;
      return ErrorCode::OK;
    case UART_NUM_1:
      out = PERIPH_UART1_MODULE;
      return ErrorCode::OK;
#if SOC_UART_HP_NUM > 2
    case UART_NUM_2:
      out = PERIPH_UART2_MODULE;
      return ErrorCode::OK;
#endif
    default:
      return ErrorCode::NOT_SUPPORT;
  }
}

ResolveWordLength()

bool LibXR::ESP32UART::ResolveWordLength ( uint8_t data_bits, uart_word_length_t & out )

staticprivate

Convert configured data bits into the HAL enum.

将配置的数据位转换为 HAL 枚举。

Definition at line 293 of file esp_uart.cpp.

{
  switch (data_bits)
  {
    case 5:
      out = UART_DATA_5_BITS;
      return true;
    case 6:
      out = UART_DATA_6_BITS;
      return true;
    case 7:
      out = UART_DATA_7_BITS;
      return true;
    case 8:
      out = UART_DATA_8_BITS;
      return true;
    default:
      return false;
  }
}

SetConfig()

ErrorCode LibXR::ESP32UART::SetConfig ( UART::Configuration config )

overridevirtual

Apply a new UART framing and baud configuration.

应用新的 UART 帧格式和波特率配置。

Implements LibXR::UART.

Definition at line 185 of file esp_uart.cpp.

{
  if (!uart_hw_enabled_)
  {
    return ErrorCode::STATE_ERR;
  }
 
  uart_word_length_t word_length = UART_DATA_8_BITS;
  uart_stop_bits_t stop_bits = UART_STOP_BITS_1;
 
  if (!ResolveWordLength(config.data_bits, word_length))
  {
    return ErrorCode::ARG_ERR;
  }
 
  if (!ResolveStopBits(config.stop_bits, stop_bits))
  {
    return ErrorCode::ARG_ERR;
  }
 
  const uart_sclk_t sclk = UART_SCLK_DEFAULT;
  uart_hal_set_sclk(&uart_hal_, static_cast<soc_module_clk_t>(sclk));
 
  uint32_t sclk_hz = 0;
  if ((esp_clk_tree_src_get_freq_hz(static_cast<soc_module_clk_t>(sclk),
                                    ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED,
                                    &sclk_hz) != ESP_OK) ||
      (sclk_hz == 0))
  {
    return ErrorCode::INIT_ERR;
  }
 
  if (!uart_hal_set_baudrate(&uart_hal_, config.baudrate, sclk_hz))
  {
    return ErrorCode::INIT_ERR;
  }
 
  uart_hal_set_data_bit_num(&uart_hal_, word_length);
  uart_hal_set_stop_bits(&uart_hal_, stop_bits);
  uart_hal_set_parity(&uart_hal_, ResolveParity(config.parity));
  uart_hal_set_hw_flow_ctrl(&uart_hal_, UART_HW_FLOWCTRL_DISABLE, 0);
  uart_hal_set_mode(&uart_hal_, UART_MODE_UART);
  uart_hal_set_txfifo_empty_thr(&uart_hal_, TX_EMPTY_THRESHOLD);
  // Drop stale hardware RX FIFO bytes from the previous baud.
  // Keep software read queue semantics aligned with ST/CH (no read_port reset).
  uart_hal_rxfifo_rst(&uart_hal_);
  uart_hal_clr_intsts_mask(&uart_hal_, UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT);
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    // Re-align the circular RX DMA window after reconfig to avoid
    // carrying stale pre-switch bytes into the next frame.
    HandleDmaRxError();
  }
#endif
 
  // Align with ST/CH SetConfig semantics: if TX was in-flight during
  // reconfiguration, keep transfer progression instead of surfacing BUSY.
  if (tx_busy_.IsSet() && tx_active_valid_)
  {
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
    if (dma_backend_enabled_)
    {
      (void)StartDmaTx();
    }
    else
#endif
    {
      uart_hal_clr_intsts_mask(&uart_hal_, UART_TX_INTR_MASK);
      uart_hal_ena_intr_mask(&uart_hal_, UART_TX_INTR_MASK);
      FillTxFifo(false);
    }
  }
 
  config_ = config;
  return ErrorCode::OK;
}

SetLoopback()

ErrorCode LibXR::ESP32UART::SetLoopback

(

bool

enable

)

Toggle UART peripheral internal loopback mode.

切换 UART 外设内部环回模式。

Definition at line 267 of file esp_uart.cpp.

{
  if (!uart_hw_enabled_)
  {
    return ErrorCode::STATE_ERR;
  }
 
  uart_ll_set_loop_back(uart_hal_.dev, enable);
  return ErrorCode::OK;
}

StartActiveTransfer()

bool IRAM_ATTR LibXR::ESP32UART::StartActiveTransfer ( bool in_isr )

private

Start the active request on the selected TX backend.

在选定 TX 后端上启动 active 请求。

Definition at line 734 of file esp_uart.cpp.

{
  if (!tx_active_valid_)
  {
    return false;
  }
 
  if (tx_busy_.TestAndSet())
  {
    return true;
  }
 
  tx_active_offset_ = 0U;
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    if (StartDmaTx())
    {
      return true;
    }
 
    tx_busy_.Clear();
    return false;
  }
#endif
 
  uart_hal_clr_intsts_mask(&uart_hal_, UART_TX_INTR_MASK);
  uart_hal_ena_intr_mask(&uart_hal_, UART_TX_INTR_MASK);
  FillTxFifo(false);
 
  return true;
}

StartAndReportActive()

bool IRAM_ATTR LibXR::ESP32UART::StartAndReportActive ( bool in_isr )

private

Start the active request and report queue completion ownership.

启动 active 请求并上报队列完成所有权交接。

Definition at line 475 of file esp_uart.cpp.

{
  if (!StartActiveTransfer(in_isr))
  {
    write_port_->Finish(in_isr, ErrorCode::FAILED, tx_active_info_);
    ClearActiveTx();
    return false;
  }
 
  // Align with STM/CH semantics: once the active write is kicked to HW,
  // WritePort owns the completion notification and the ISR only advances queues.
  write_port_->Finish(in_isr, ErrorCode::OK, tx_active_info_);
  return true;
}

StartPendingTxIfIdle()

bool IRAM_ATTR LibXR::ESP32UART::StartPendingTxIfIdle ( bool in_isr )

private

Start the current pending DMA request when TX is fully idle.

在 TX 完全空闲时启动当前 pending DMA 请求。

Definition at line 654 of file esp_uart.cpp.

{
#if !(SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED)
  (void)in_isr;
  return false;
#else
  if (!dma_backend_enabled_)
  {
    (void)in_isr;
    return false;
  }
 
  if (tx_busy_.IsSet())
  {
    return false;
  }
 
  if (!tx_active_valid_ && !PromotePendingTxToActive())
  {
    return false;
  }
 
  return StartAndReportActive(in_isr);
#endif
}

TryStartTx()

ErrorCode IRAM_ATTR LibXR::ESP32UART::TryStartTx ( bool in_isr )

private

Try to start queued transmit work.

尝试启动排队的发送工作。

Definition at line 496 of file esp_uart.cpp.

{
  if (in_tx_isr_.IsSet())
  {
    return ErrorCode::PENDING;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_ && !tx_busy_.IsSet() && StartPendingTxIfIdle(in_isr))
  {
    return ErrorCode::PENDING;
  }
#endif
 
  if (!tx_active_valid_)
  {
    (void)LoadActiveTxFromQueue(in_isr);
  }
 
  if (!tx_busy_.IsSet() && tx_active_valid_)
  {
    if (!StartActiveTransfer(in_isr))
    {
      ClearActiveTx();
      return ErrorCode::FAILED;
    }
 
    return ErrorCode::OK;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_ && tx_busy_.IsSet() && !tx_dma_buffer_.HasPending())
  {
    (void)LoadPendingTxFromQueue(in_isr);
  }
#endif
 
  return ErrorCode::PENDING;
}

UartIsrEntry()

void IRAM_ATTR LibXR::ESP32UART::UartIsrEntry ( void * arg )

staticprivate

UART ISR trampoline.

UART 中断跳板函数。

Definition at line 24 of file esp_uart_fifo.cpp.

{
  auto* self = static_cast<ESP32UART*>(arg);
  if (self != nullptr)
  {
    self->HandleUartInterrupt();
  }
}

WriteFun()

ErrorCode IRAM_ATTR LibXR::ESP32UART::WriteFun ( WritePort & port, bool in_isr )

static

Queue-driven TX entry used by WritePort.

WritePort 使用的队列驱动 TX 入口。

Definition at line 280 of file esp_uart.cpp.

{
  auto* uart = LibXR::ContainerOf(&port, &ESP32UART::_write_port);
  return uart->TryStartTx(in_isr);
}

Friends And Related Symbol Documentation

ESP32UARTReadPort

friend class ESP32UARTReadPort

friend

Definition at line 77 of file esp_uart.hpp.

Field Documentation

_read_port

ESP32UARTReadPort LibXR::ESP32UART::_read_port

private

Read-side queue bridge exposed to UART.

Definition at line 374 of file esp_uart.hpp.

_write_port

WritePort LibXR::ESP32UART::_write_port

private

Write-side queue bridge exposed to UART.

Definition at line 375 of file esp_uart.hpp.

config_

UART::Configuration LibXR::ESP32UART::config_

private

Current UART framing configuration.

Definition at line 354 of file esp_uart.hpp.

cts_pin_

int LibXR::ESP32UART::cts_pin_

private

CTS GPIO pin or PIN_NO_CHANGE.

Definition at line 352 of file esp_uart.hpp.

dma_requested_

bool LibXR::ESP32UART::dma_requested_ = true

private

Constructor preference for DMA mode.

Definition at line 372 of file esp_uart.hpp.

in_tx_isr_

Flag::Plain LibXR::ESP32UART::in_tx_isr_

private

Reentry guard while processing TX ISR work.

Definition at line 366 of file esp_uart.hpp.

PIN_NO_CHANGE

int LibXR::ESP32UART::PIN_NO_CHANGE = -1

staticconstexpr

Sentinel for an unmapped GPIO.

Definition at line 80 of file esp_uart.hpp.

rts_pin_

int LibXR::ESP32UART::rts_pin_

private

RTS GPIO pin or PIN_NO_CHANGE.

Definition at line 351 of file esp_uart.hpp.

rx_fifo_draining_

Flag::Atomic LibXR::ESP32UART::rx_fifo_draining_ {}

private

RX FIFO drain reentry gate.

Definition at line 389 of file esp_uart.hpp.

{};  

rx_isr_buffer_

uint8_t* LibXR::ESP32UART::rx_isr_buffer_ = nullptr

private

Scratch buffer used by the RX ISR path.

Definition at line 356 of file esp_uart.hpp.

rx_isr_buffer_size_

size_t LibXR::ESP32UART::rx_isr_buffer_size_ = 0

private

Size of rx_isr_buffer_.

Definition at line 357 of file esp_uart.hpp.

rx_pin_

int LibXR::ESP32UART::rx_pin_

private

RX GPIO pin or PIN_NO_CHANGE.

Definition at line 350 of file esp_uart.hpp.

tx_active_info_

WriteInfoBlock LibXR::ESP32UART::tx_active_info_ = {}

private

Metadata for the active TX request.

Definition at line 361 of file esp_uart.hpp.

{};  

tx_active_length_

size_t LibXR::ESP32UART::tx_active_length_ = 0U

private

Active TX payload length in bytes.

Definition at line 362 of file esp_uart.hpp.

tx_active_offset_

size_t LibXR::ESP32UART::tx_active_offset_ = 0U

private

Bytes already emitted for the active request.

Definition at line 363 of file esp_uart.hpp.

tx_active_valid_

bool LibXR::ESP32UART::tx_active_valid_ = false

private

Whether the active TX metadata is valid.

Definition at line 364 of file esp_uart.hpp.

tx_busy_

Flag::Plain LibXR::ESP32UART::tx_busy_

private

Hardware TX engine currently owns the request.

Definition at line 365 of file esp_uart.hpp.

tx_dma_buffer_

DoubleBuffer LibXR::ESP32UART::tx_dma_buffer_ {}

private

TX double-buffer view for the DMA path.

Definition at line 360 of file esp_uart.hpp.

{};        

tx_pin_

int LibXR::ESP32UART::tx_pin_

private

TX GPIO pin or PIN_NO_CHANGE.

Definition at line 349 of file esp_uart.hpp.

tx_storage_

uint8_t* LibXR::ESP32UART::tx_storage_ = nullptr

private

Backing storage for the TX half-buffers.

Definition at line 359 of file esp_uart.hpp.

uart_hal_

uart_hal_context_t LibXR::ESP32UART::uart_hal_ = {}

private

ESP-IDF UART HAL context.

Definition at line 369 of file esp_uart.hpp.

{};          

uart_hw_enabled_

bool LibXR::ESP32UART::uart_hw_enabled_ = false

private

UART hardware block was initialized.

Definition at line 368 of file esp_uart.hpp.

uart_intr_handle_

intr_handle_t LibXR::ESP32UART::uart_intr_handle_ = nullptr

private

Registered UART interrupt handle.

Definition at line 370 of file esp_uart.hpp.

uart_isr_installed_

bool LibXR::ESP32UART::uart_isr_installed_ = false

private

UART ISR installation state.

Definition at line 371 of file esp_uart.hpp.

uart_num_

uart_port_t LibXR::ESP32UART::uart_num_

private

Selected UART peripheral index.

Definition at line 348 of file esp_uart.hpp.

---

The documentation for this class was generated from the following files:

• driver/esp/esp_uart.hpp
• driver/esp/esp_uart.cpp
• driver/esp/esp_uart_fifo.cpp