LibXR::UartCircularDmaRxModel Class Reference

UART 基于位置的循环 DMA 接收模型 / Position-based circular DMA RX model for UART. More...

#include <uart_circular_dma_rx_model.hpp>

Collaboration diagram for LibXR::UartCircularDmaRxModel:

Public Member Functions
	UartCircularDmaRxModel (RawData storage)
	使用平台提供的 DMA 存储区构造接收模型 / Construct the RX model with platform-provided DMA storage
template<typename Backend >
void	Start (Backend &backend)
	复位读取位置并启动循环 DMA / Reset the read position and start circular DMA
template<typename Backend >
void	OnDataAvailable (Backend &backend, ReadPort &port, bool in_isr)
	消费上次 DMA 事件后新产生的数据 / Consume bytes produced since the previous DMA event
void	ResetPosition ()
	将软件读取位置复位到 DMA 缓冲区起点 / Reset the software read position to the start of the DMA buffer
uint8_t *	Buffer () const
	获取 DMA 可写缓冲区起始地址 / Get the DMA-writable buffer start address
size_t	BufferSize () const
	获取循环 DMA 缓冲区容量 / Get the circular DMA buffer capacity
size_t	LastPosition () const
	获取上次已消费的 DMA 写入位置 / Get the last consumed DMA write position

Private Attributes
RawData	storage_
size_t	last_position_ = 0U

Detailed Description

UART 基于位置的循环 DMA 接收模型 / Position-based circular DMA RX model for UART.

模型管理 DMA 存储区视图和软件读取位置。平台后端负责启动循环 DMA、返回剩余传输计数， 并在 CPU 读取前执行所需的缓存维护。 The model owns the DMA storage view and software read position. The platform backend starts circular DMA, reports the remaining transfer count, and performs any cache maintenance required before CPU access.

为保持现有 UART 行为，软件队列写满时仍推进读取位置，无法写入的数据会被丢弃。 To preserve existing UART behavior, the read position advances when the software queue is full, and bytes that cannot be queued are dropped.

Warning

同一模型实例的 RX 事件入口不得重入。若 UART IDLE 与 RX DMA HT/TC 使用 不同中断源，平台驱动必须把这些中断配置为相同的抢占优先级，保证任意时刻只有一个 OnDataAvailable() 修改读取位置并作为软件队列 producer。 Calls delivering RX events to one model instance must not overlap. When UART IDLE and RX DMA HT/TC use different interrupt sources, the platform driver must configure them with the same preemption priority and target-core affinity so only one OnDataAvailable() call can modify the read position and act as the software-queue producer at a time. Configuration on another core must use a separate hardware-state handoff such as UartRxConfigGate.

Definition at line 35 of file uart_circular_dma_rx_model.hpp.

Constructor & Destructor Documentation

UartCircularDmaRxModel()

LibXR::UartCircularDmaRxModel::UartCircularDmaRxModel ( RawData storage )

inlineexplicit

使用平台提供的 DMA 存储区构造接收模型 / Construct the RX model with platform-provided DMA storage

Parameters

storage

DMA 可写的循环接收缓冲区 / DMA-writable circular receive buffer

Definition at line 43 of file uart_circular_dma_rx_model.hpp.

: storage_(storage) {}

Member Function Documentation

Buffer()

uint8_t * LibXR::UartCircularDmaRxModel::Buffer ( ) const

inlinenodiscard

获取 DMA 可写缓冲区起始地址 / Get the DMA-writable buffer start address

Returns

DMA 缓冲区起始地址 / DMA buffer start address

Definition at line 117 of file uart_circular_dma_rx_model.hpp.

{ return static_cast<uint8_t*>(storage_.addr_); }

BufferSize()

size_t LibXR::UartCircularDmaRxModel::BufferSize ( ) const

inlinenodiscard

获取循环 DMA 缓冲区容量 / Get the circular DMA buffer capacity

Returns

缓冲区字节数 / Buffer capacity in bytes

Definition at line 123 of file uart_circular_dma_rx_model.hpp.

{ return storage_.size_; }

LastPosition()

size_t LibXR::UartCircularDmaRxModel::LastPosition ( ) const

inlinenodiscard

获取上次已消费的 DMA 写入位置 / Get the last consumed DMA write position

Returns

相对缓冲区起点的字节偏移 / Byte offset from the start of the buffer

Definition at line 129 of file uart_circular_dma_rx_model.hpp.

{ return last_position_; }

OnDataAvailable()

template<typename Backend >

void LibXR::UartCircularDmaRxModel::OnDataAvailable ( Backend & backend, ReadPort & port, bool in_isr )

inline

消费上次 DMA 事件后新产生的数据 / Consume bytes produced since the previous DMA event

Template Parameters

Backend

静态绑定的平台后端类型 / Statically bound platform backend type

Parameters

backend	提供剩余计数和缓存维护操作的平台后端 / Platform backend providing remaining-count and cache-maintenance operations
port	接收新增数据的读端口 / Read port receiving newly produced bytes
in_isr	是否在中断上下文完成 pending 读取 / Whether pending reads are completed in interrupt context

Warning

调用方必须保证同一模型实例上的调用不重入；相关 UART 与 RX DMA IRQ 必须 使用相同抢占优先级。Calls for the same model instance must not overlap; related UART and RX DMA IRQs must use the same preemption priority.

Definition at line 72 of file uart_circular_dma_rx_model.hpp.

  {
    uint8_t* const buffer = Buffer();
    const size_t capacity = BufferSize();
    const size_t remaining = backend.GetCircularDmaRxRemaining();
    if (remaining > capacity)
    {
      ASSERT(false);
      return;
    }
 
    const size_t current_position = capacity - remaining;
    backend.PrepareCircularDmaRxForCpu(buffer, capacity);
 
    if (current_position == last_position_)
    {
      return;
    }
 
    if (current_position > last_position_)
    {
      (void)port.queue_data_->PushBatch(&buffer[last_position_],
                                        current_position - last_position_);
    }
    else
    {
      (void)port.queue_data_->PushBatch(&buffer[last_position_],
                                        capacity - last_position_);
      (void)port.queue_data_->PushBatch(buffer, current_position);
    }
 
    last_position_ = current_position;
    port.ProcessPendingReads(in_isr);
  }

ResetPosition()

void LibXR::UartCircularDmaRxModel::ResetPosition ( )

inline

将软件读取位置复位到 DMA 缓冲区起点 / Reset the software read position to the start of the DMA buffer

Definition at line 111 of file uart_circular_dma_rx_model.hpp.

{ last_position_ = 0U; }

Start()

template<typename Backend >

void LibXR::UartCircularDmaRxModel::Start ( Backend & backend )

inline

复位读取位置并启动循环 DMA / Reset the read position and start circular DMA

Template Parameters

Backend

静态绑定的平台后端类型 / Statically bound platform backend type

Parameters

backend

提供 StartCircularDmaRx() 的平台后端 / Platform backend providing StartCircularDmaRx()

Definition at line 52 of file uart_circular_dma_rx_model.hpp.

  {
    ResetPosition();
    backend.StartCircularDmaRx(Buffer(), BufferSize());
  }

Field Documentation

last_position_

size_t LibXR::UartCircularDmaRxModel::last_position_ = 0U

private

Definition at line 133 of file uart_circular_dma_rx_model.hpp.

storage_

RawData LibXR::UartCircularDmaRxModel::storage_

private

Definition at line 132 of file uart_circular_dma_rx_model.hpp.

---

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

• src/driver/model/uart_circular_dma_rx_model.hpp