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

#include <stm32_uart.hpp>

Inheritance diagram for LibXR::STM32UART:

Collaboration diagram for LibXR::STM32UART:

Public Member Functions
	STM32UART (UART_HandleTypeDef *uart_handle, RawData dma_buff_rx, RawData dma_buff_tx, uint32_t tx_queue_size=5)
	构造串口并关联 DMA 缓冲区 / Construct a UART with DMA buffers.

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

void	SetRxDMA (bool in_isr=false)
	初始化循环接收 DMA 并检查启动结果 / Initialize circular RX DMA and check startup.

void	TxCompleteIRQHandler ()
	通知发送完成，交给后端释放半区 / Notify TX completion to release the active half.

void	RxEventIRQHandler ()
	通知接收位置变化 / Notify RX position changes.

void	ErrorIRQHandler ()
	通知错误，由后端处理器启动中止 / Report an error; the service initiates the abort.

void	AbortCompleteIRQHandler ()

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
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.

UART_HandleTypeDef *	uart_handle_

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

stm32_uart_id_t	id_ = STM32_UART_ID_ERROR

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

WritePort *	write_port_
	写入端口 / Write port

Static Public Attributes
static STM32UART *	map [STM32_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 和双缓冲发送的 STM32 串口 / STM32 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.; H5 的 RX 句柄已挂接静止的循环链表，缓冲区长度是 4 的倍数，每段不超过 65535 字节；TX 使用普通单次 DMA。相关 UART/DMA 中断具有相同抢占优先级。 On H5, RX starts with a stopped circular seed list. The buffer size is a multiple of four, with at most 65535 bytes per node; TX uses normal one-shot DMA. Related UART/DMA IRQs share a preemption priority.

Definition at line 137 of file stm32_uart.hpp.

Constructor & Destructor Documentation

◆ STM32UART()

STM32UART::STM32UART	(	UART_HandleTypeDef *	uart_handle,
		RawData	dma_buff_rx,
		RawData	dma_buff_tx,
		uint32_t	tx_queue_size = 5 )

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

Parameters

uart_handle	已初始化的 HAL 句柄 / Initialized HAL handle.
dma_buff_rx	接收 DMA 缓冲区 / RX DMA buffer.
dma_buff_tx	双缓冲发送存储，每半区容纳一个请求 / TX storage, one request per half.
tx_queue_size	写请求队列容量，启用发送时须大于零 / Positive TX request capacity.

Definition at line 398 of file stm32_uart.cpp.

    : UART(&_read_port, &_write_port),
      _read_port(dma_buff_rx.size_),
      _write_port(tx_queue_size, dma_buff_tx.size_ / 2),
      dma_buff_rx_(dma_buff_rx),
      dma_buff_tx_(dma_buff_tx),
      uart_handle_(uart_handle),
      id_(stm32_uart_get_id(uart_handle_->Instance))
#if defined(LIBXR_STM32_UART_GPDMA)
      ,
      gpdma_adapter_(uart_handle)
#endif
{
  ASSERT(id_ != STM32_UART_ID_ERROR);
  ASSERT(dma_buff_rx.size_ == 0U || dma_buff_rx.addr_ != nullptr);
 
  map[id_] = this;
 
  if ((uart_handle->Init.Mode & UART_MODE_TX) == UART_MODE_TX)
  {
    ASSERT(tx_queue_size > 0U);
    ASSERT(uart_handle_->hdmatx != NULL);
#if defined(LIBXR_STM32_UART_GPDMA)
    ASSERT(uart_handle_->hdmatx->Mode == DMA_NORMAL);
#endif
    _write_port = WriteFun;
  }
 
#if defined(LIBXR_STM32_UART_GPDMA)
  tx_service_.Invoke(TX_EVENT_START_RX, false, [this](uint32_t events, bool in_isr)
                     { HandleTxService(events, in_isr); });
#else
  SetRxDMA(false);
#endif
}

Member Function Documentation

◆ AbortCompleteIRQHandler()

void STM32UART::AbortCompleteIRQHandler ( )

通知 HAL 中止完成，由后端恢复收发 / Notify HAL abort completion for backend recovery.

Definition at line 653 of file stm32_uart.cpp.

{
  tx_service_.Invoke(TX_EVENT_ABORT, true, [this](uint32_t events, bool in_isr)
                     { HandleTxService(events, in_isr); });
}

◆ ErrorIRQHandler()

void STM32UART::ErrorIRQHandler ( )

通知错误，由后端处理器启动中止 / Report an error; the service initiates the abort.

Definition at line 647 of file stm32_uart.cpp.

{
  tx_service_.Invoke(TX_EVENT_ERROR, true, [this](uint32_t events, bool in_isr)
                     { HandleTxService(events, in_isr); });
}

◆ RxEventIRQHandler()

void STM32UART::RxEventIRQHandler ( )

通知接收位置变化 / Notify RX position changes.

Definition at line 641 of file stm32_uart.cpp.

{
  tx_service_.Invoke(TX_EVENT_RX_WORK, true, [this](uint32_t events, bool in_isr)
                     { HandleTxService(events, in_isr); });
}

◆ SetConfig()

ErrorCode STM32UART::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 435 of file stm32_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 (!Stm32DataBitsSupported(config))
  {
    return ErrorCode::ARG_ERR;
  }
 
  if (!Stm32StopBitsSupported(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;
}

◆ SetRxDMA()

void STM32UART::SetRxDMA ( bool in_isr = false )

初始化循环接收 DMA 并检查启动结果 / Initialize circular RX DMA and check startup.

Definition at line 553 of file stm32_uart.cpp.

{
  if ((uart_handle_->Init.Mode & UART_MODE_RX) == UART_MODE_RX)
  {
    ASSERT(uart_handle_->hdmarx != NULL);
 
#if defined(LIBXR_STM32_UART_GPDMA)
    [[maybe_unused]] const auto start_linked_list_dma_rx_result =
        gpdma_adapter_.StartLinkedListDmaRx(static_cast<uint8_t*>(dma_buff_rx_.addr_),
                                            dma_buff_rx_.size_, in_isr);
    REQUIRE_FROM_CALLBACK(start_linked_list_dma_rx_result == HAL_OK, in_isr);
#else
    uart_handle_->hdmarx->Init.Mode = DMA_CIRCULAR;
    [[maybe_unused]] const auto dma_init_result = HAL_DMA_Init(uart_handle_->hdmarx);
    REQUIRE_FROM_CALLBACK(dma_init_result == HAL_OK, in_isr);
 
    [[maybe_unused]] const auto uart_ex_receive_to_idle_dma_result =
        HAL_UARTEx_ReceiveToIdle_DMA(uart_handle_,
                                     reinterpret_cast<uint8_t*>(dma_buff_rx_.addr_),
                                     dma_buff_rx_.size_);
    REQUIRE_FROM_CALLBACK(uart_ex_receive_to_idle_dma_result == HAL_OK, in_isr);
#endif
  }
}

◆ TxCompleteIRQHandler()

void STM32UART::TxCompleteIRQHandler ( )

通知发送完成，交给后端释放半区 / Notify TX completion to release the active half.

Definition at line 635 of file stm32_uart.cpp.

{
  tx_service_.Invoke(TX_EVENT_DONE, true, [this](uint32_t events, bool in_isr)
                     { HandleTxService(events, in_isr); });
}

◆ WriteFun()

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

static

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

Definition at line 219 of file stm32_uart.cpp.

{
  auto* uart = LibXR::ContainerOf(&port, &STM32UART::_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::STM32UART::_read_port

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

Definition at line 181 of file stm32_uart.hpp.

◆ _write_port

WritePort LibXR::STM32UART::_write_port

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

Definition at line 183 of file stm32_uart.hpp.

◆ dma_buff_rx_

RawData LibXR::STM32UART::dma_buff_rx_

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

Definition at line 186 of file stm32_uart.hpp.

◆ dma_buff_tx_

DoubleBuffer LibXR::STM32UART::dma_buff_tx_

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

Definition at line 188 of file stm32_uart.hpp.

◆ id_

stm32_uart_id_t LibXR::STM32UART::id_ = STM32_UART_ID_ERROR

Definition at line 198 of file stm32_uart.hpp.

◆ last_rx_pos_

size_t LibXR::STM32UART::last_rx_pos_ = 0

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

Definition at line 191 of file stm32_uart.hpp.

◆ map

STM32UART * STM32UART::map = {nullptr}

static

Definition at line 200 of file stm32_uart.hpp.

◆ tx_busy_

Flag::Plain LibXR::STM32UART::tx_busy_

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

Definition at line 196 of file stm32_uart.hpp.

◆ uart_handle_

UART_HandleTypeDef* LibXR::STM32UART::uart_handle_

Definition at line 193 of file stm32_uart.hpp.

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

driver/st/stm32_uart.hpp
driver/st/stm32_uart.cpp

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Additional Inherited Members