使用循环接收 DMA 和双缓冲发送的 CH32 串口 / CH32 UART with circular RX DMA and double-buffered TX. More...

#include <ch32_uart.hpp>

Inheritance diagram for LibXR::CH32UART:

Collaboration diagram for LibXR::CH32UART:

Public Member Functions
	CH32UART (ch32_uart_id_t id, RawData dma_rx, RawData dma_tx, GPIO_TypeDef tx_gpio_port, uint16_t tx_gpio_pin, GPIO_TypeDef rx_gpio_port, uint16_t rx_gpio_pin, uint32_t pin_remap=0, uint32_t tx_queue_size=5, UART::Configuration config={115200, UART::Parity::NO_PARITY, 8, 1})
	构造串口并关联 DMA 缓冲区 / Construct a UART with DMA buffers.

ErrorCode	SetConfig (UART::Configuration config, bool in_isr=false) override
	提交串口配置请求 / Submit a UART configuration request.

void	TxDmaIRQHandler ()
	处理发送 DMA 完成通知 / Handle TX DMA completion.

void	RxDmaIRQHandler ()
	处理接收 DMA 进展通知 / Handle RX DMA progress.

void	UartIRQHandler ()
	处理接收空闲和发送完成中断 / Handle RX idle and TX complete interrupts.

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)
	通知后端处理已提交的写请求 / Notify the backend of released writes.

Public Attributes
ch32_uart_id_t	id_

uint16_t	uart_mode_

ReadPort	_read_port
	接收字节队列与读请求 / RX byte queue and read requests.

WritePort	_write_port
	写请求及发送字节队列 / Write requests and TX byte queue.

RawData	dma_buff_rx_
	调用者提供的接收 DMA 缓冲区 / Caller-provided RX DMA buffer.

DoubleBuffer	dma_buff_tx_
	当前与待发送的 DMA 半区 / Active and pending TX DMA halves.

size_t	last_rx_pos_ = 0
	上次已处理的 DMA 接收位置 / Last processed RX DMA position.

USART_TypeDef *	instance_

DMA_Channel_TypeDef *	dma_rx_channel_

DMA_Channel_TypeDef *	dma_tx_channel_

Flag::Plain	tx_busy_
	发送半区是否在使用，仅后端处理器访问 / TX half in use; service-only access.

Public Attributes inherited from LibXR::UART
ReadPort *	read_port_
	读取端口 / Read port

WritePort *	write_port_
	写入端口 / Write port

Static Public Attributes
static CH32UART *	map_ [CH32_UART_NUMBER] = {nullptr}

Additional Inherited Members
Public Types inherited from LibXR::UART
enum class	Parity : uint8_t { NO_PARITY = 0 , EVEN = 1 , ODD = 2 }
	奇偶校验模式 / Parity mode More...

Detailed Description

使用循环接收 DMA 和双缓冲发送的 CH32 串口 / CH32 UART with circular RX DMA and double-buffered TX.

写请求完整复制到发送缓冲半区后完成，DMA 完成仅释放半区。接收持续运行，按 DMA 位置变化向 ReadPort 发布数据；软件队列放不下的部分作为接收溢出丢弃。 Writes complete once copied into a TX half; DMA completion only releases that half. RX runs continuously and publishes observed DMA bytes to ReadPort, discarding any overflow beyond available software capacity.

Precondition: 调用遵守 ReadPort/WritePort 约定；DMA 缓冲区满足平台访问和对齐要求，运行期间有效。 Follow the port contracts. DMA buffers must meet platform access/alignment requirements and remain valid throughout operation.

Definition at line 32 of file ch32_uart.hpp.

Constructor & Destructor Documentation

◆ CH32UART()

CH32UART::CH32UART	(	ch32_uart_id_t	id,
		RawData	dma_rx,
		RawData	dma_tx,
		GPIO_TypeDef *	tx_gpio_port,
		uint16_t	tx_gpio_pin,
		GPIO_TypeDef *	rx_gpio_port,
		uint16_t	rx_gpio_pin,
		uint32_t	pin_remap = 0,
		uint32_t	tx_queue_size = 5,
		UART::Configuration	config = {115200, UART::Parity::NO_PARITY, 8, 1} )

构造串口并关联 DMA 缓冲区 / Construct a UART with DMA buffers.

Parameters

id	串口编号 / UART identifier.
dma_rx	接收 DMA 缓冲区 / RX DMA buffer.
dma_tx	双缓冲发送存储，每半区容纳一个请求 / TX storage, one request per half.
tx_gpio_port	发送引脚端口 / TX GPIO port.
tx_gpio_pin	发送引脚 / TX GPIO pin.
rx_gpio_port	接收引脚端口 / RX GPIO port.
rx_gpio_pin	接收引脚 / RX GPIO pin.
pin_remap	引脚重映射配置，默认零 / Pin remapping, zero by default.
tx_queue_size	写请求队列容量，启用发送时须大于零 / Positive TX request capacity.
config	初始串口配置 / Initial UART configuration.

Definition at line 35 of file ch32_uart.cpp.

    : UART(&_read_port, &_write_port),
      id_(id),
      _read_port(dma_rx.size_),
      _write_port(tx_queue_size, dma_tx.size_ / 2),
      dma_buff_rx_(dma_rx),
      dma_buff_tx_(dma_tx),
      instance_(ch32_uart_get_instance_id(id)),
      dma_rx_channel_(CH32_UART_RX_DMA_CHANNEL_MAP[id]),
      dma_tx_channel_(CH32_UART_TX_DMA_CHANNEL_MAP[id])
{
  map_[id] = this;
 
  bool tx_enable = dma_tx.size_ > 1;
  bool rx_enable = dma_rx.size_ > 0;
 
  ASSERT(tx_enable || rx_enable);
  if (tx_enable)
  {
    ASSERT(tx_queue_size > 0U);
    ASSERT(dma_tx_channel_ != nullptr);
    ASSERT(CH32_UART_TX_DMA_IT_MAP[id] != 0);
  }
  if (rx_enable)
  {
    ASSERT(dma_rx_channel_ != nullptr);
    ASSERT(CH32_UART_RX_DMA_IT_TC_MAP[id] != 0);
    ASSERT(CH32_UART_RX_DMA_IT_HT_MAP[id] != 0);
  }
 
  // TX 使用复用推挽，RX 使用浮空输入 / TX alternate push-pull; RX floating input.
  GPIO_InitTypeDef gpio_init = {};
  gpio_init.GPIO_Speed = GPIO_Speed_50MHz;
 
  if (tx_enable)
  {
    RCC_APB2PeriphClockCmd(ch32_get_gpio_periph(tx_gpio_port), ENABLE);
    gpio_init.GPIO_Pin = tx_gpio_pin;
    gpio_init.GPIO_Mode = GPIO_Mode_AF_PP;
    GPIO_Init(tx_gpio_port, &gpio_init);
    (*write_port_) = WriteFun;
  }
 
  if (rx_enable)
  {
    RCC_APB2PeriphClockCmd(ch32_get_gpio_periph(rx_gpio_port), ENABLE);
    gpio_init.GPIO_Pin = rx_gpio_pin;
    gpio_init.GPIO_Mode = GPIO_Mode_IN_FLOATING;
    GPIO_Init(rx_gpio_port, &gpio_init);
  }
 
  // 可选引脚重映射 / Optional pin remapping.
  if (pin_remap != 0)
  {
    RCC_APB2PeriphClockCmd(RCC_APB2Periph_AFIO, ENABLE);
    GPIO_PinRemapConfig(pin_remap, ENABLE);
  }
 
  // 开启串口外设时钟 / Enable the UART peripheral clock.
  if (CH32_UART_APB_MAP[id] == 1)
  {
    RCC_APB1PeriphClockCmd(CH32_UART_RCC_PERIPH_MAP[id], ENABLE);
  }
  else if (CH32_UART_APB_MAP[id] == 2)
  {
    RCC_APB2PeriphClockCmd(CH32_UART_RCC_PERIPH_MAP[id], ENABLE);
  }
  else
  {
    DEV_ASSERT(false);
  }
  RCC_AHBPeriphClockCmd(CH32_UART_RCC_PERIPH_MAP_DMA[id], ENABLE);
 
  // 设置初始串口参数 / Apply initial UART settings.
  ASSERT(config.baudrate > 0U);
  ASSERT(Ch32DataBitsSupported(config));
  ASSERT(Ch32StopBitsSupported(config));
  USART_InitTypeDef usart_cfg = {};
  usart_cfg.USART_BaudRate = config.baudrate;
  usart_cfg.USART_StopBits =
      (config.stop_bits == 2) ? USART_StopBits_2 : USART_StopBits_1;
  switch (config.parity)
  {
    case UART::Parity::NO_PARITY:
      usart_cfg.USART_Parity = USART_Parity_No;
      usart_cfg.USART_WordLength = USART_WordLength_8b;
      break;
    case UART::Parity::EVEN:
      usart_cfg.USART_Parity = USART_Parity_Even;
      usart_cfg.USART_WordLength =
          config.data_bits == 7U ? USART_WordLength_8b : USART_WordLength_9b;
      break;
    case UART::Parity::ODD:
      usart_cfg.USART_Parity = USART_Parity_Odd;
      usart_cfg.USART_WordLength =
          config.data_bits == 7U ? USART_WordLength_8b : USART_WordLength_9b;
      break;
    default:
      ASSERT(false);
  }
 
  usart_cfg.USART_HardwareFlowControl = USART_HardwareFlowControl_None;
  usart_cfg.USART_Mode =
      (tx_enable ? USART_Mode_Tx : 0) | (rx_enable ? USART_Mode_Rx : 0);
  uart_mode_ = usart_cfg.USART_Mode;
  USART_Init(instance_, &usart_cfg);
 
  // 配置收发 DMA / Configure RX and TX DMA.
  DMA_InitTypeDef dma_init = {};
  dma_init.DMA_PeripheralInc = DMA_PeripheralInc_Disable;
  dma_init.DMA_MemoryInc = DMA_MemoryInc_Enable;
  dma_init.DMA_PeripheralDataSize = DMA_PeripheralDataSize_Byte;
  dma_init.DMA_MemoryDataSize = DMA_MemoryDataSize_Byte;
  dma_init.DMA_Priority = DMA_Priority_High;
  dma_init.DMA_M2M = DMA_M2M_Disable;
 
  if (rx_enable)
  {
    ch32_dma_callback_t rx_cb_fun = [](void* arg)
    { reinterpret_cast<CH32UART*>(arg)->RxDmaIRQHandler(); };
 
    ch32_dma_register_callback(ch32_dma_get_id(CH32_UART_RX_DMA_CHANNEL_MAP[id]),
                               rx_cb_fun, this);
 
    DMA_DeInit(dma_rx_channel_);
    dma_init.DMA_PeripheralBaseAddr = (uint32_t)&instance_->DATAR;
    dma_init.DMA_MemoryBaseAddr = (uint32_t)dma_buff_rx_.addr_;
    dma_init.DMA_DIR = DMA_DIR_PeripheralSRC;
    dma_init.DMA_Mode = DMA_Mode_Circular;
    dma_init.DMA_BufferSize = dma_buff_rx_.size_;
    DMA_Init(dma_rx_channel_, &dma_init);
    DMA_Cmd(dma_rx_channel_, ENABLE);
    DMA_ITConfig(dma_rx_channel_, DMA_IT_TC, ENABLE);
    DMA_ITConfig(dma_rx_channel_, DMA_IT_HT, ENABLE);
    USART_DMACmd(instance_, USART_DMAReq_Rx, ENABLE);
  }
 
  if (tx_enable)
  {
    ch32_dma_callback_t tx_cb_fun = [](void* arg)
    { reinterpret_cast<CH32UART*>(arg)->TxDmaIRQHandler(); };
 
    ch32_dma_register_callback(ch32_dma_get_id(CH32_UART_TX_DMA_CHANNEL_MAP[id]),
                               tx_cb_fun, this);
    DMA_DeInit(dma_tx_channel_);
    dma_init.DMA_PeripheralBaseAddr = (u32)(&instance_->DATAR);
    dma_init.DMA_MemoryBaseAddr = 0;
    dma_init.DMA_DIR = DMA_DIR_PeripheralDST;
    dma_init.DMA_Mode = DMA_Mode_Normal;
    dma_init.DMA_BufferSize = 0;
    DMA_Init(dma_tx_channel_, &dma_init);
    DMA_ITConfig(dma_tx_channel_, DMA_IT_TC, ENABLE);
    USART_DMACmd(instance_, USART_DMAReq_Tx, ENABLE);
  }
 
  // 开启串口及对应中断 / Enable the UART and its interrupts.
  USART_Cmd(instance_, ENABLE);
 
  if (rx_enable)
  {
    USART_ITConfig(instance_, USART_IT_IDLE, ENABLE);
    NVIC_EnableIRQ(CH32_DMA_IRQ_MAP[ch32_dma_get_id(dma_rx_channel_)]);
  }
 
  if (tx_enable)
  {
    NVIC_EnableIRQ(CH32_DMA_IRQ_MAP[ch32_dma_get_id(dma_tx_channel_)]);
  }
 
  NVIC_EnableIRQ(CH32_UART_IRQ_MAP[id]);
}

Member Function Documentation

◆ RxDmaIRQHandler()

void CH32UART::RxDmaIRQHandler ( )

处理接收 DMA 进展通知 / Handle RX DMA progress.

清除接收 DMA 中断标志并通知后端 / Clear RX DMA flags and notify the backend.

Definition at line 573 of file ch32_uart.cpp.

{
  if (DMA_GetITStatus(CH32_UART_RX_DMA_IT_HT_MAP[id_]) == SET)
  {
    DMA_ClearITPendingBit(CH32_UART_RX_DMA_IT_HT_MAP[id_]);
    tx_service_.Invoke(TX_EVENT_RX_WORK, true, [this](uint32_t events, bool in_isr)
                       { HandleTxService(events, in_isr); });
  }
 
  if (DMA_GetITStatus(CH32_UART_RX_DMA_IT_TC_MAP[id_]) == SET)
  {
    DMA_ClearITPendingBit(CH32_UART_RX_DMA_IT_TC_MAP[id_]);
    tx_service_.Invoke(TX_EVENT_RX_WORK, true, [this](uint32_t events, bool in_isr)
                       { HandleTxService(events, in_isr); });
  }
}

◆ SetConfig()

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

overridevirtual

提交串口配置请求 / Submit a UART configuration request.

Parameters

config	目标配置 / Requested configuration.
in_isr	当前调用是否在中断中 / Whether this call is in an ISR.

Returns: 接纳返回 OK，配置槽被占用返回 BUSY，参数不支持返回 ARG_ERR 或 NOT_SUPPORT。 OK on admission, BUSY for an occupied slot, ARG_ERR or NOT_SUPPORT for unsupported settings.

Note: 接纳后在发送空闲时应用，期间保留已准备的 DMA 数据；不保证返回前已经生效。 Applies when TX is idle while preserving prepared DMA data. May apply after return.

Implements LibXR::UART.

Definition at line 210 of file ch32_uart.cpp.

{
  if (config.baudrate == 0U)
  {
    return ErrorCode::ARG_ERR;
  }
 
  switch (config.parity)
  {
    case UART::Parity::NO_PARITY:
    case UART::Parity::EVEN:
    case UART::Parity::ODD:
      break;
    default:
      return ErrorCode::NOT_SUPPORT;
  }
 
  if (!Ch32DataBitsSupported(config))
  {
    return ErrorCode::ARG_ERR;
  }
 
  if (!Ch32StopBitsSupported(config))
  {
    return ErrorCode::ARG_ERR;
  }
 
  ConfigState expected = ConfigState::EMPTY;
  if (!config_state_.compare_exchange_strong(expected, ConfigState::RESERVED,
                                             std::memory_order_acq_rel,
                                             std::memory_order_acquire))
  {
    return ErrorCode::BUSY;
  }
 
  pending_config_ = config;
  tx_service_.Invoke(TX_EVENT_CONFIG, in_isr, [this](uint32_t events, bool owner_in_isr)
                     { HandleTxService(events, owner_in_isr); });
  return ErrorCode::OK;
}

◆ TxDmaIRQHandler()

void CH32UART::TxDmaIRQHandler ( )

处理发送 DMA 完成通知 / Handle TX DMA completion.

Definition at line 555 of file ch32_uart.cpp.

{
  if (DMA_GetITStatus(CH32_UART_TX_DMA_IT_MAP[id_]) == RESET)
  {
    return;
  }
 
  if (dma_tx_channel_->CNTR == 0)
  {
    DMA_ClearITPendingBit(CH32_UART_TX_DMA_IT_MAP[id_]);
    tx_service_.Invoke(TX_EVENT_DMA_DONE, true, [this](uint32_t events, bool in_isr)
                       { HandleTxService(events, in_isr); });
  }
}

◆ UartIRQHandler()

void CH32UART::UartIRQHandler ( )

处理接收空闲和发送完成中断 / Handle RX idle and TX complete interrupts.

Definition at line 517 of file ch32_uart.cpp.

{
  const bool idle = USART_GetITStatus(instance_, USART_IT_IDLE) != RESET;
  const bool tc = USART_GetITStatus(instance_, USART_IT_TC) != RESET;
 
  if (idle)
  {
    USART_ReceiveData(instance_);
    tx_service_.Invoke(TX_EVENT_RX_WORK, true, [this](uint32_t events, bool in_isr)
                       { HandleTxService(events, in_isr); });
  }
 
  if (tc)
  {
    if (config_state_.load(std::memory_order_acquire) != ConfigState::EMPTY)
    {
      USART_ITConfig(instance_, USART_IT_TC, DISABLE);
      tx_service_.Invoke(TX_EVENT_TC, true, [this](uint32_t events, bool in_isr)
                         { HandleTxService(events, in_isr); });
    }
    else
    {
      USART_ITConfig(instance_, USART_IT_TC, DISABLE);
    }
  }
}

◆ WriteFun()

void CH32UART::WriteFun	(	WritePort &	port,
		bool	in_isr )

static

通知后端处理已提交的写请求 / Notify the backend of released writes.

Definition at line 299 of file ch32_uart.cpp.

{
  auto* uart = LibXR::ContainerOf(&port, &CH32UART::_write_port);
 
  uart->tx_service_.Invoke(TX_EVENT_WRITE, in_isr,
                           [uart](uint32_t events, bool owner_in_isr)
                           { uart->HandleTxService(events, owner_in_isr); });
}

Member Data Documentation

◆ _read_port

ReadPort LibXR::CH32UART::_read_port

接收字节队列与读请求 / RX byte queue and read requests.

Definition at line 81 of file ch32_uart.hpp.

◆ _write_port

WritePort LibXR::CH32UART::_write_port

写请求及发送字节队列 / Write requests and TX byte queue.

Definition at line 83 of file ch32_uart.hpp.

◆ dma_buff_rx_

RawData LibXR::CH32UART::dma_buff_rx_

调用者提供的接收 DMA 缓冲区 / Caller-provided RX DMA buffer.

Definition at line 86 of file ch32_uart.hpp.

◆ dma_buff_tx_

DoubleBuffer LibXR::CH32UART::dma_buff_tx_

当前与待发送的 DMA 半区 / Active and pending TX DMA halves.

Definition at line 88 of file ch32_uart.hpp.

◆ dma_rx_channel_

DMA_Channel_TypeDef* LibXR::CH32UART::dma_rx_channel_

Definition at line 94 of file ch32_uart.hpp.

◆ dma_tx_channel_

DMA_Channel_TypeDef* LibXR::CH32UART::dma_tx_channel_

Definition at line 95 of file ch32_uart.hpp.

◆ id_

ch32_uart_id_t LibXR::CH32UART::id_

Definition at line 77 of file ch32_uart.hpp.

◆ instance_

USART_TypeDef* LibXR::CH32UART::instance_

Definition at line 93 of file ch32_uart.hpp.

◆ last_rx_pos_

size_t LibXR::CH32UART::last_rx_pos_ = 0

上次已处理的 DMA 接收位置 / Last processed RX DMA position.

Definition at line 91 of file ch32_uart.hpp.

◆ map_

CH32UART * CH32UART::map_ = {nullptr}

static

Definition at line 100 of file ch32_uart.hpp.

◆ tx_busy_

Flag::Plain LibXR::CH32UART::tx_busy_

发送半区是否在使用，仅后端处理器访问 / TX half in use; service-only access.

Definition at line 98 of file ch32_uart.hpp.

◆ uart_mode_

uint16_t LibXR::CH32UART::uart_mode_

Definition at line 78 of file ch32_uart.hpp.

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

driver/ch/ch32_uart.hpp
driver/ch/ch32_uart.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members