LibXR::ESP32UART Class Reference

支持 FIFO 和 GDMA 的 ESP UART 后端 / ESP UART backend with FIFO and GDMA. 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)
	构造并初始化 ESP UART / Construct and initialize an ESP UART.
ErrorCode	SetConfig (UART::Configuration config, bool in_isr=false) override
	提交帧格式和波特率配置 / Submit framing and baud configuration.
ErrorCode	SetLoopback (bool enable)
	切换 UART 内部环回模式 / Toggle UART internal loopback.
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 void	WriteFun (WritePort &port, bool in_isr)
	WritePort 使用的队列驱动 TX 入口 / Queue-driven TX entry used by WritePort.

Static Public Attributes
static constexpr int	PIN_NO_CHANGE
	保持引脚映射不变 / Keep pin mapping unchanged.

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...
Public Attributes inherited from LibXR::UART
ReadPort *	read_port_
	读取端口 / Read port
WritePort *	write_port_
	写入端口 / Write port

Detailed Description

支持 FIFO 和 GDMA 的 ESP UART 后端 / ESP UART backend with FIFO and GDMA.

FIFO 按硬件实际接收量消费 WriteQueue；GDMA 将完整请求复制到发送半区后完成请求， DMA 完成仅释放半区。接收通过 ReadQueue 发布，配置和中断进展由同一处理器串行执行。 FIFO consumes actual accepted prefixes; GDMA completes requests after copying them into TX halves, with DMA completion only releasing storage. RX uses ReadQueue; one service serializes configuration and interrupt progress.

Note

UART 使用普通中断，Flash 擦写导致缓存关闭时暂缓执行；持续接收可能溢出。 UART interrupts are deferred while flash operations disable cache; sustained input may overflow hardware storage.

接收 FIFO 满时保留数据等待软件空间；GDMA 则回收已完成描述符，丢弃放不下的尾部。 FIFO RX retains bytes until software space is available; GDMA recycles completed descriptors and discards excess bytes that do not fit.

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

构造并初始化 ESP UART / Construct and initialize an ESP UART.

Parameters

uart_num	UART 外设编号 / UART peripheral number.
tx_pin	发送 GPIO / TX GPIO.
rx_pin	接收 GPIO / RX GPIO.
rts_pin	RTS GPIO，PIN_NO_CHANGE 表示不修改 / RTS GPIO, or PIN_NO_CHANGE.
cts_pin	CTS GPIO，PIN_NO_CHANGE 表示不修改 / CTS GPIO, or PIN_NO_CHANGE.
rx_buffer_size	接收软件队列容量 / RX software queue capacity.
tx_buffer_size	发送软件队列和单个 DMA 半区容量 / TX queue and DMA half capacity.
tx_queue_size	写请求队列容量，须大于零 / Positive write request capacity.
config	初始帧格式和波特率 / Initial framing and baud rate.
enable_dma	在芯片支持时使用 GDMA，否则使用 FIFO / Use GDMA if supported, else FIFO.

Definition at line 146 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);
  ASSERT(tx_queue_size > 0U);
 
  INIT_CRIT_SECTION_LOCK_RUNTIME(&irq_lock_);
 
  tx_dma_buffer_.Init({tx_storage_, tx_buffer_size * 2U});
 
  _write_port = WriteFun;
 
  if (InitUartHardware() != ErrorCode::OK)
  {
    REQUIRE(false);
    return;
  }
 
#if SOC_GDMA_SUPPORTED && SOC_UHCI_SUPPORTED
  if (dma_requested_)
  {
    if (InitDmaBackend() != ErrorCode::OK)
    {
      REQUIRE(false);
      return;
    }
  }
 
  if (!dma_backend_enabled_)
  {
    if (InstallUartIsr() != ErrorCode::OK)
    {
      REQUIRE(false);
      return;
    }
    ConfigureRxInterruptPath();
  }
#else
  if (InstallUartIsr() != ErrorCode::OK)
  {
    REQUIRE(false);
    return;
  }
  ConfigureRxInterruptPath();
#endif
}

Member Function Documentation

SetConfig()

ErrorCode LibXR::ESP32UART::SetConfig ( UART::Configuration config, bool in_isr = false )

overridevirtual

提交帧格式和波特率配置 / Submit framing and baud configuration.

Parameters

config	目标配置 / Requested configuration.
in_isr	当前是否在中断中 / Whether called in an ISR.

Returns

接纳返回 OK，配置槽被占用返回 BUSY，参数不支持返回 ARG_ERR； 硬件尚未初始化时返回 STATE_ERR。 OK on admission, BUSY for an occupied slot, ARG_ERR for unsupported settings, STATE_ERR before hardware initialization.

Note

GDMA 等已有半区传输结束后应用；FIFO 等软件队列和硬件 FIFO 空闲后应用。 GDMA waits for claimed transfers; FIFO waits for software and hardware drain.

初始化时选定的源时钟频率须保持不变 / Keep the selected source clock frequency fixed.

Implements LibXR::UART.

Definition at line 226 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 (config.baudrate == 0U || !ResolveWordLength(config.data_bits, word_length) ||
      !ResolveStopBits(config.stop_bits, stop_bits) ||
      (config.parity != UART::Parity::NO_PARITY && config.parity != UART::Parity::EVEN &&
       config.parity != UART::Parity::ODD))
  {
    return ErrorCode::ARG_ERR;
  }
 
  // 使用初始化时的时钟快照，校验时不访问硬件。
  // Validate against the initial clock snapshot without touching hardware.
  if (!IsBaudrateRepresentable(config.baudrate, uart_sclk_hz_))
  {
    return ErrorCode::ARG_ERR;
  }
 
  uint8_t expected = static_cast<uint8_t>(ConfigState::EMPTY);
  if (!config_state_.compare_exchange_strong(
          expected, static_cast<uint8_t>(ConfigState::RESERVED),
          std::memory_order_acq_rel, std::memory_order_acquire))
  {
    return ErrorCode::BUSY;
  }
 
  requested_config_ = config;
  config_state_.store(static_cast<uint8_t>(ConfigState::PUBLISHED),
                      std::memory_order_release);
  service_.Invoke(EVENT_CONFIG, in_isr, [this](uint32_t events, bool owner_isr)
                  { ServiceEvents(events, owner_isr); });
  return ErrorCode::OK;
}

SetLoopback()

ErrorCode LibXR::ESP32UART::SetLoopback

(

bool

enable

)

切换 UART 内部环回模式 / Toggle UART internal loopback.

Parameters

enable

是否启用 / Whether to enable loopback.

Returns

成功为 OK，未初始化为 STATE_ERR / OK on success, STATE_ERR before initialization.

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

WriteFun()

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

static

WritePort 使用的队列驱动 TX 入口 / Queue-driven TX entry used by WritePort.

Definition at line 473 of file esp_uart.cpp.

{
  auto* uart = LibXR::ContainerOf(&port, &ESP32UART::_write_port);
  uart->service_.Invoke(ESP32UART::EVENT_WRITE, in_isr,
                        [uart](uint32_t events, bool owner_isr)
                        { uart->ServiceEvents(events, owner_isr); });
}

Friends And Related Symbol Documentation

ESP32UARTReadPort

friend class ESP32UARTReadPort

friend

Definition at line 82 of file esp_uart.hpp.

Member Data Documentation

PIN_NO_CHANGE

int LibXR::ESP32UART::PIN_NO_CHANGE

staticconstexpr

Initial value:

=
      -1

保持引脚映射不变 / Keep pin mapping unchanged.

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