LibXR::ESP32UART Class Reference

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)
ErrorCode	SetConfig (UART::Configuration config) override
	设置 UART 配置 / Sets the UART configuration
ErrorCode	SetLoopback (bool enable)
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)
static ErrorCode	ReadFun (ReadPort &port, bool in_isr)

Static Public Attributes
static constexpr int	PIN_NO_CHANGE = -1

Private Member Functions
ErrorCode	InitUartHardware ()
ErrorCode	ConfigurePins ()
ErrorCode	InstallUartIsr ()
void	ConfigureRxInterruptPath ()
ErrorCode	TryStartTx (bool in_isr)
bool	LoadActiveTxFromQueue (bool in_isr)
bool	LoadPendingTxFromQueue (bool in_isr)
bool	DequeueTxToBuffer (uint8_t *buffer, size_t &size, WriteInfoBlock &info, bool in_isr)
bool	StartActiveTransfer (bool in_isr)
bool	StartAndReportActive (bool in_isr)
void	ClearActiveTx ()
void	ClearPendingTx ()
void	FillTxFifo (bool in_isr)
void	PushRxBytes (const uint8_t *data, size_t size, bool in_isr)
void	DrainRxFifoFromIsr ()
void	HandleRxInterrupt (uint32_t uart_intr_status)
void	HandleTxInterrupt (uint32_t uart_intr_status)
void	HandleUartInterrupt ()
void	OnTxTransferDone (bool in_isr, ErrorCode result)

Static Private Member Functions
static uint8_t *	AllocateTxStorage (size_t size)
static ErrorCode	ResolveUartPeriph (uart_port_t uart_num, periph_module_t &out)
static bool	ResolveWordLength (uint8_t data_bits, uart_word_length_t &out)
static bool	ResolveStopBits (uint8_t stop_bits, uart_stop_bits_t &out)
static uart_parity_t	ResolveParity (UART::Parity parity)
static void	UartIsrEntry (void *arg)

Private Attributes
uart_port_t	uart_num_
int	tx_pin_
int	rx_pin_
int	rts_pin_
int	cts_pin_
UART::Configuration	config_
uint8_t *	rx_isr_buffer_ = nullptr
size_t	rx_isr_buffer_size_ = 0
uint8_t *	tx_storage_ = nullptr
size_t	tx_storage_size_ = 0
size_t	tx_buffer_size_ = 0
uint8_t *	tx_active_buffer_ = nullptr
uint8_t *	tx_pending_buffer_ = nullptr
size_t	tx_active_length_ = 0
size_t	tx_pending_length_ = 0
size_t	tx_active_offset_ = 0
WriteInfoBlock	tx_active_info_ = {}
WriteInfoBlock	tx_pending_info_ = {}
Flag::Plain	tx_busy_
Flag::Plain	in_tx_isr_
bool	tx_active_valid_ = false
bool	tx_pending_valid_ = false
bool	uart_hw_enabled_ = false
uart_hal_context_t	uart_hal_ = {}
intr_handle_t	uart_intr_handle_ = nullptr
bool	uart_isr_installed_ = false
bool	dma_requested_ = true
ReadPort	_read_port
WritePort	_write_port

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

Definition at line 27 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 )

Definition at line 73 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 (std::nothrow) uint8_t[rx_buffer_size]),
      rx_isr_buffer_size_(rx_buffer_size),
      tx_storage_(AllocateTxStorage(tx_buffer_size * 2)),
      tx_storage_size_(tx_buffer_size * 2),
      tx_buffer_size_(tx_buffer_size),
      dma_requested_(enable_dma),
      _read_port(rx_buffer_size),
      _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);
  ASSERT(rx_isr_buffer_ != nullptr);
  ASSERT(tx_storage_ != nullptr);
  ASSERT(tx_storage_size_ >= (tx_buffer_size_ * 2U));
 
  tx_active_buffer_ = tx_storage_;
  tx_pending_buffer_ = tx_storage_ + tx_buffer_size_;
  tx_active_length_ = 0;
  tx_pending_length_ = 0;
 
  _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

Definition at line 40 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

Definition at line 402 of file esp_uart.cpp.

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

ClearPendingTx()

void IRAM_ATTR LibXR::ESP32UART::ClearPendingTx ( )

private

Definition at line 410 of file esp_uart.cpp.

{
  tx_pending_length_ = 0;
  tx_pending_info_ = {};
  tx_pending_valid_ = false;
}

ConfigurePins()

ErrorCode LibXR::ESP32UART::ConfigurePins ( )

private

Definition at line 352 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

Definition at line 144 of file esp_uart.cpp.

{
  const size_t rx_full_floor = 16;
  const size_t rx_full_ceil = std::max<size_t>(rx_full_floor, SOC_UART_FIFO_LEN / 4);
  const uint16_t full_thr = static_cast<uint16_t>(std::min<size_t>(
      rx_full_ceil, std::max<size_t>(rx_full_floor, rx_isr_buffer_size_ / 16)));
 
  uart_hal_set_rxfifo_full_thr(&uart_hal_, full_thr);
  uart_hal_set_rx_timeout(&uart_hal_, kRxToutThreshold);
  uart_hal_clr_intsts_mask(&uart_hal_, kUartRxIntrMask);
  uart_hal_ena_intr_mask(&uart_hal_, kUartRxIntrMask);
}

DequeueTxToBuffer()

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

private

Definition at line 502 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;
  }
 
  if (peek_info.data.size_ > tx_buffer_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;
}

DrainRxFifoFromIsr()

void IRAM_ATTR LibXR::ESP32UART::DrainRxFifoFromIsr ( )

private

Definition at line 126 of file esp_uart_fifo.cpp.

{
  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(true);
  }
}

FillTxFifo()

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

private

Definition at line 52 of file esp_uart_fifo.cpp.

{
  if (!tx_active_valid_)
  {
    return;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_backend_enabled_)
  {
    while (tx_active_offset_ < tx_active_length_)
    {
      if (uart_hal_get_txfifo_len(&uart_hal_) == 0)
      {
        break;
      }
 
      uint32_t write_size = 0;
      const uint8_t* src = tx_active_buffer_ + tx_active_offset_;
      const uint32_t remaining =
          static_cast<uint32_t>(tx_active_length_ - tx_active_offset_);
 
      uart_hal_write_txfifo(&uart_hal_, src, remaining, &write_size);
      if (write_size == 0)
      {
        break;
      }
 
      tx_active_offset_ += write_size;
    }
  }
  else
#endif
  {
    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

Definition at line 167 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);
  }
 
  DrainRxFifoFromIsr();
  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

Definition at line 189 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

Definition at line 201 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 & kUartRxIntrMask)
    {
      HandleRxInterrupt(uart_intr_status);
    }
 
    if (uart_intr_status & kUartTxIntrMask)
    {
      HandleTxInterrupt(uart_intr_status);
    }
 
    uart_intr_status = uart_hal_get_intsts_mask(&uart_hal_);
  }
}

InitUartHardware()

ErrorCode LibXR::ESP32UART::InitUartHardware ( )

private

Definition at line 306 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

Definition at line 26 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 kUartIntrFlags = 0;
#else
  constexpr int kUartIntrFlags = ESP_INTR_FLAG_IRAM;
#endif
 
  const esp_err_t err = esp_intr_alloc(uart_periph_signal[uart_num_].irq, kUartIntrFlags,
                                       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

Definition at line 467 of file esp_uart.cpp.

{
  (void)in_isr;
 
  size_t active_length = 0U;
  if (!DequeueTxToBuffer(tx_active_buffer_, active_length, tx_active_info_, in_isr))
  {
    return false;
  }
 
  tx_active_length_ = active_length;
  tx_active_valid_ = true;
  return true;
}

LoadPendingTxFromQueue()

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

private

Definition at line 482 of file esp_uart.cpp.

{
  (void)in_isr;
 
  if (tx_pending_valid_)
  {
    return false;
  }
 
  size_t pending_length = 0U;
  if (!DequeueTxToBuffer(tx_pending_buffer_, pending_length, tx_pending_info_, in_isr))
  {
    return false;
  }
 
  tx_pending_length_ = pending_length;
  tx_pending_valid_ = true;
  return true;
}

OnTxTransferDone()

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

private

Definition at line 600 of file esp_uart.cpp.

{
  Flag::ScopedRestore tx_flag(in_tx_isr_);
  tx_busy_.Clear();
 
  ClearActiveTx();
 
  if ((result != ErrorCode::OK) && tx_pending_valid_)
  {
    write_port_->Finish(in_isr, ErrorCode::FAILED, tx_pending_info_);
    ClearPendingTx();
  }
 
  if (result != ErrorCode::OK)
  {
    ClearPendingTx();
    return;
  }
 
  if (tx_pending_valid_)
  {
    std::swap(tx_active_buffer_, tx_pending_buffer_);
    tx_active_length_ = tx_pending_length_;
    tx_pending_length_ = 0;
    tx_active_info_ = tx_pending_info_;
    tx_active_valid_ = true;
    ClearPendingTx();
    (void)StartAndReportActive(in_isr);
  }
  else
  {
    if (LoadActiveTxFromQueue(in_isr))
    {
      (void)StartAndReportActive(in_isr);
    }
  }
 
  if (!tx_pending_valid_)
  {
    (void)LoadPendingTxFromQueue(in_isr);
  }
}

PushRxBytes()

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

private

Definition at line 573 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

Definition at line 253 of file esp_uart.cpp.

{ return ErrorCode::PENDING; }

ResolveParity()

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

staticprivate

Definition at line 291 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

Definition at line 276 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

Definition at line 53 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

Definition at line 255 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

设置 UART 配置 / Sets the UART configuration

Parameters

config

UART 配置信息 / UART configuration settings

Returns

返回操作状态，成功时返回 ErrorCode::OK，否则返回相应错误码 / Returns the operation status, ErrorCode::OK if successful, otherwise an error code

该方法为纯虚函数，子类必须实现具体的 UART 配置逻辑。 This is a pure virtual function. Subclasses must implement the specific UART configuration logic.

Implements LibXR::UART.

Definition at line 157 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_, kTxEmptyThreshold);
  // 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_, kUartTxIntrMask);
      uart_hal_ena_intr_mask(&uart_hal_, kUartTxIntrMask);
      FillTxFifo(false);
    }
  }
 
  config_ = config;
  return ErrorCode::OK;
}

SetLoopback()

ErrorCode LibXR::ESP32UART::SetLoopback

(

bool

enable

)

Definition at line 236 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

Definition at line 539 of file esp_uart.cpp.

{
  if (!tx_active_valid_)
  {
    return false;
  }
 
  if (tx_busy_.TestAndSet())
  {
    return true;
  }
 
  tx_active_offset_ = 0;
 
#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_, kUartTxIntrMask);
  uart_hal_ena_intr_mask(&uart_hal_, kUartTxIntrMask);
  FillTxFifo(false);
 
  return true;
}

StartAndReportActive()

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

private

Definition at line 417 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;
}

TryStartTx()

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

private

Definition at line 432 of file esp_uart.cpp.

{
  if (in_tx_isr_.IsSet())
  {
    return ErrorCode::PENDING;
  }
  if (!tx_active_valid_)
  {
    (void)LoadActiveTxFromQueue(in_isr);
  }
 
  if (!tx_busy_.IsSet() && tx_active_valid_)
  {
    if (!StartActiveTransfer(in_isr))
    {
      ClearActiveTx();
      return ErrorCode::FAILED;
    }
 
    // Current op completion is reported by WritePort when TryStartTx returns OK.
    if (!tx_pending_valid_)
    {
      (void)LoadPendingTxFromQueue(in_isr);
    }
    return ErrorCode::OK;
  }
 
  if (!tx_pending_valid_)
  {
    (void)LoadPendingTxFromQueue(in_isr);
  }
 
  return ErrorCode::PENDING;
}

UartIsrEntry()

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

staticprivate

Definition at line 17 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

Definition at line 247 of file esp_uart.cpp.

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

Field Documentation

_read_port

ReadPort LibXR::ESP32UART::_read_port

private

Definition at line 166 of file esp_uart.hpp.

_write_port

WritePort LibXR::ESP32UART::_write_port

private

Definition at line 167 of file esp_uart.hpp.

config_

UART::Configuration LibXR::ESP32UART::config_

private

Definition at line 139 of file esp_uart.hpp.

cts_pin_

int LibXR::ESP32UART::cts_pin_

private

Definition at line 137 of file esp_uart.hpp.

dma_requested_

bool LibXR::ESP32UART::dma_requested_ = true

private

Definition at line 164 of file esp_uart.hpp.

in_tx_isr_

Flag::Plain LibXR::ESP32UART::in_tx_isr_

private

Definition at line 156 of file esp_uart.hpp.

PIN_NO_CHANGE

int LibXR::ESP32UART::PIN_NO_CHANGE = -1

staticconstexpr

Definition at line 30 of file esp_uart.hpp.

rts_pin_

int LibXR::ESP32UART::rts_pin_

private

Definition at line 136 of file esp_uart.hpp.

rx_isr_buffer_

uint8_t* LibXR::ESP32UART::rx_isr_buffer_ = nullptr

private

Definition at line 141 of file esp_uart.hpp.

rx_isr_buffer_size_

size_t LibXR::ESP32UART::rx_isr_buffer_size_ = 0

private

Definition at line 142 of file esp_uart.hpp.

rx_pin_

int LibXR::ESP32UART::rx_pin_

private

Definition at line 135 of file esp_uart.hpp.

tx_active_buffer_

uint8_t* LibXR::ESP32UART::tx_active_buffer_ = nullptr

private

Definition at line 147 of file esp_uart.hpp.

tx_active_info_

WriteInfoBlock LibXR::ESP32UART::tx_active_info_ = {}

private

Definition at line 153 of file esp_uart.hpp.

{};

tx_active_length_

size_t LibXR::ESP32UART::tx_active_length_ = 0

private

Definition at line 149 of file esp_uart.hpp.

tx_active_offset_

size_t LibXR::ESP32UART::tx_active_offset_ = 0

private

Definition at line 151 of file esp_uart.hpp.

tx_active_valid_

bool LibXR::ESP32UART::tx_active_valid_ = false

private

Definition at line 157 of file esp_uart.hpp.

tx_buffer_size_

size_t LibXR::ESP32UART::tx_buffer_size_ = 0

private

Definition at line 146 of file esp_uart.hpp.

tx_busy_

Flag::Plain LibXR::ESP32UART::tx_busy_

private

Definition at line 155 of file esp_uart.hpp.

tx_pending_buffer_

uint8_t* LibXR::ESP32UART::tx_pending_buffer_ = nullptr

private

Definition at line 148 of file esp_uart.hpp.

tx_pending_info_

WriteInfoBlock LibXR::ESP32UART::tx_pending_info_ = {}

private

Definition at line 154 of file esp_uart.hpp.

{};

tx_pending_length_

size_t LibXR::ESP32UART::tx_pending_length_ = 0

private

Definition at line 150 of file esp_uart.hpp.

tx_pending_valid_

bool LibXR::ESP32UART::tx_pending_valid_ = false

private

Definition at line 158 of file esp_uart.hpp.

tx_pin_

int LibXR::ESP32UART::tx_pin_

private

Definition at line 134 of file esp_uart.hpp.

tx_storage_

uint8_t* LibXR::ESP32UART::tx_storage_ = nullptr

private

Definition at line 144 of file esp_uart.hpp.

tx_storage_size_

size_t LibXR::ESP32UART::tx_storage_size_ = 0

private

Definition at line 145 of file esp_uart.hpp.

uart_hal_

uart_hal_context_t LibXR::ESP32UART::uart_hal_ = {}

private

Definition at line 161 of file esp_uart.hpp.

{};

uart_hw_enabled_

bool LibXR::ESP32UART::uart_hw_enabled_ = false

private

Definition at line 160 of file esp_uart.hpp.

uart_intr_handle_

intr_handle_t LibXR::ESP32UART::uart_intr_handle_ = nullptr

private

Definition at line 162 of file esp_uart.hpp.

uart_isr_installed_

bool LibXR::ESP32UART::uart_isr_installed_ = false

private

Definition at line 163 of file esp_uart.hpp.

uart_num_

uart_port_t LibXR::ESP32UART::uart_num_

private

Definition at line 133 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