UART 单次 DMA 发送执行模型 / UART one-shot DMA TX execution model. More...

#include <uart_dma_tx_model.hpp>

Collaboration diagram for LibXR::UartDmaTxModel< Backend >:

Data Structures
struct	SubmitContext

Public Member Functions
	UartDmaTxModel (Backend &backend, WritePort &port, RawData storage)
	绑定平台后端、写端口和 DMA 双缓冲区 / Bind the backend, write port, and DMA double buffer

ErrorCode	Submit (bool in_isr)
	发布 WRITE 事件并推进队首请求 / Publish WRITE and advance the head request

void	OnTransferDone (bool in_isr)
	发布正常完成事件 / Publish a normal completion event

void	OnTransferError (bool in_isr)
	在平台恢复旧 DMA 后发布错误终止事件 / Publish an error terminal event after platform recovery

void	RequestConfig (bool in_isr)
	发布最高优先级配置事件 / Publish the highest-priority configuration event

bool	IsBusy () const
	查询 DMA 是否持有 active 请求 / Check whether DMA owns an active request

uint8_t *	Buffer (int block) const

size_t	BufferSize () const

Private Types
enum class	TxEvent : uint32_t { WRITE = 1U << 0U , COMPLETE = 1U << 1U , ERROR = 1U << 2U , CONFIG = 1U << 3U }

Private Member Functions
void	ServiceTx (uint32_t events, bool in_isr, SubmitContext *submit) noexcept

bool	PopPayload (uint8_t *destination, size_t size)

bool	DiscardPayload (size_t size)

bool	PopActiveInfo (WriteInfoBlock &info)

bool	StagePending (const WriteInfoBlock &info)

bool	StageNextPending (bool in_isr)

bool	PromotePending (WriteInfoBlock &info)

bool	StartActive ()

bool	ReleaseActive ()

bool	PromoteAndStartPending (bool in_isr)

void	StartQueuedActive (bool in_isr, SubmitContext *submit)

bool	ApplyConfig (bool in_isr)

void	FailPublishedQueued (bool in_isr, size_t count)

void	ClearActive ()

Static Private Member Functions
static constexpr uint32_t	EventMask (TxEvent event)

static constexpr bool	HasEvent (uint32_t events, TxEvent event)

Private Attributes
Backend &	backend_

WritePort &	port_

DoubleBuffer	buffers_

SerializedService	service_ {}

size_t	active_length_ = 0U

size_t	config_prefix_count_ = 0U

bool	busy_ = false

bool	pending_valid_ = false

bool	config_boundary_valid_ = false

Detailed Description

template<typename Backend>
class LibXR::UartDmaTxModel< Backend >

UART 单次 DMA 发送执行模型 / UART one-shot DMA TX execution model.

Submit()、正常完成和错误恢复入口只发布可合并事件。SerializedService 选出的唯一 owner 负责 active/pending buffer、WritePort 出队、DMA 启动以及 Operation 完成，避免提交线程与完成 ISR 并发推进双缓冲状态。 Submit(), normal completion, and recovered-error entries only publish coalesced events. The sole owner selected by SerializedService controls active/pending buffers, WritePort dequeue, DMA start, and Operation completion, preventing submitters and completion ISRs from advancing the double-buffer state concurrently.

Template Parameters

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

Definition at line 28 of file uart_dma_tx_model.hpp.

Member Enumeration Documentation

◆ TxEvent

template<typename Backend >

enum class LibXR::UartDmaTxModel::TxEvent : uint32_t

strongprivate

Definition at line 111 of file uart_dma_tx_model.hpp.

  {
    WRITE = 1U << 0U,
    COMPLETE = 1U << 1U,
    ERROR = 1U << 2U,
    CONFIG = 1U << 3U,
  };

Constructor & Destructor Documentation

◆ UartDmaTxModel()

template<typename Backend >

LibXR::UartDmaTxModel< Backend >::UartDmaTxModel	(	Backend &	backend,
		WritePort &	port,
		RawData	storage )

inline

绑定平台后端、写端口和 DMA 双缓冲区 / Bind the backend, write port, and DMA double buffer

Definition at line 35 of file uart_dma_tx_model.hpp.

      : backend_(backend), port_(port), buffers_(storage)
  {
  }

Member Function Documentation

◆ ApplyConfig()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::ApplyConfig ( bool in_isr )

inlineprivate

Definition at line 373 of file uart_dma_tx_model.hpp.

  {
    // Metadata is the operation publication boundary. Fix the old prefix before any
    // Finish callback can append another request. Payload without metadata belongs to
    // an in-progress producer and is intentionally left for its later WRITE event.
    // metadata 是操作发布边界。在任何 Finish callback 可能追加新请求前固定旧前缀；
    // 只有 payload、尚无 metadata 的生产者仍在发布中，留给其后续 WRITE 事件处理。
    if (!config_boundary_valid_)
    {
      config_prefix_count_ = port_.queue_info_->Size();
      config_boundary_valid_ = true;
    }
 
    if (!backend_.ApplyPendingConfig(in_isr))
    {
      return false;
    }
 
    size_t remaining = config_prefix_count_;
    config_prefix_count_ = 0U;
    config_boundary_valid_ = false;
 
    (void)ReleaseActive();
 
    if (pending_valid_)
    {
      ASSERT(remaining > 0U);
      pending_valid_ = false;
      WriteInfoBlock info{};
      if (!PopActiveInfo(info))
      {
        ASSERT(false);
        return false;
      }
      --remaining;
      port_.Finish(in_isr, ErrorCode::FAILED, info);
    }
 
    FailPublishedQueued(in_isr, remaining);
    return backend_.OnConfigApplied(in_isr);
  }

◆ Buffer()

template<typename Backend >

uint8_t * LibXR::UartDmaTxModel< Backend >::Buffer ( int block ) const

inlinenodiscard

Definition at line 106 of file uart_dma_tx_model.hpp.

106{ return buffers_.Buffer(block); }

LibXR::DoubleBuffer::Buffer

uint8_t * Buffer(int block) const

获取指定编号缓冲区的指针 Returns the pointer of the specified block

Definition double_buffer.cpp:57

◆ BufferSize()

template<typename Backend >

size_t LibXR::UartDmaTxModel< Backend >::BufferSize ( ) const

inlinenodiscard

Definition at line 108 of file uart_dma_tx_model.hpp.

108{ return buffers_.Size(); }

LibXR::DoubleBuffer::Size

size_t Size() const

获取每个缓冲区的大小（单位：字节） Gets the size of each buffer in bytes

Definition double_buffer.cpp:65

◆ ClearActive()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::ClearActive ( )

inlineprivate

Definition at line 434 of file uart_dma_tx_model.hpp.

434{ active_length_ = 0U; }

◆ DiscardPayload()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::DiscardPayload ( size_t size )

inlineprivate

Definition at line 189 of file uart_dma_tx_model.hpp.

  {
    while (size > 0U)
    {
      const size_t chunk = size > buffers_.Size() ? buffers_.Size() : size;
      if (!PopPayload(buffers_.ActiveBuffer(), chunk))
      {
        return false;
      }
      size -= chunk;
    }
    return true;
  }

◆ EventMask()

template<typename Backend >

static constexpr uint32_t LibXR::UartDmaTxModel< Backend >::EventMask ( TxEvent event )

inlinestaticconstexprprivate

Definition at line 124 of file uart_dma_tx_model.hpp.

  {
    return static_cast<uint32_t>(event);
  }

◆ FailPublishedQueued()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::FailPublishedQueued	(	bool	in_isr,
		size_t	count )

inlineprivate

Definition at line 415 of file uart_dma_tx_model.hpp.

  {
    for (size_t index = 0U; index < count; ++index)
    {
      WriteInfoBlock info{};
      if (port_.queue_info_->Peek(info) != ErrorCode::OK)
      {
        ASSERT(false);
        return;
      }
      if (!DiscardPayload(info.data.size_) || !PopActiveInfo(info))
      {
        ASSERT(false);
        return;
      }
      port_.Finish(in_isr, ErrorCode::FAILED, info);
    }
  }

◆ HasEvent()

template<typename Backend >

static constexpr bool LibXR::UartDmaTxModel< Backend >::HasEvent	(	uint32_t	events,
		TxEvent	event )

inlinestaticconstexprprivate

Definition at line 129 of file uart_dma_tx_model.hpp.

  {
    return (events & EventMask(event)) != 0U;
  }

◆ IsBusy()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::IsBusy ( ) const

inlinenodiscard

查询 DMA 是否持有 active 请求 / Check whether DMA owns an active request

Warning: 调用方必须与 TX service 串行化。The caller must serialize this query against the TX service.

Definition at line 104 of file uart_dma_tx_model.hpp.

104{ return busy_; }

◆ OnTransferDone()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::OnTransferDone ( bool in_isr )

inline

发布正常完成事件 / Publish a normal completion event

Parameters

in_isr 当前调用是否位于 ISR / Whether the current caller is in an ISR

Definition at line 60 of file uart_dma_tx_model.hpp.

  {
    (void)service_.Invoke(EventMask(TxEvent::COMPLETE),
                          [this, in_isr](uint32_t events) noexcept
                          { ServiceTx(events, in_isr, nullptr); });
  }

◆ OnTransferError()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::OnTransferError ( bool in_isr )

inline

在平台恢复旧 DMA 后发布错误终止事件 / Publish an error terminal event after platform recovery

Parameters

in_isr 当前调用是否位于 ISR / Whether the current caller is in an ISR

Note: 平台必须先停止/复位旧 DMA 并清除其迟到完成源，再调用本接口。The platform must stop/reset the old DMA and clear its stale completion source before this call.

Definition at line 74 of file uart_dma_tx_model.hpp.

  {
    (void)service_.Invoke(EventMask(TxEvent::ERROR),
                          [this, in_isr](uint32_t events) noexcept
                          { ServiceTx(events, in_isr, nullptr); });
  }

◆ PopActiveInfo()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::PopActiveInfo ( WriteInfoBlock & info )

inlineprivate

Definition at line 203 of file uart_dma_tx_model.hpp.

  {
    const ErrorCode result = port_.queue_info_->Pop(info);
    ASSERT(result == ErrorCode::OK);
    return result == ErrorCode::OK;
  }

◆ PopPayload()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::PopPayload	(	uint8_t *	destination,
		size_t	size )

inlineprivate

Definition at line 182 of file uart_dma_tx_model.hpp.

  {
    const ErrorCode result = port_.queue_data_->PopBatch(destination, size);
    ASSERT(result == ErrorCode::OK);
    return result == ErrorCode::OK;
  }

◆ PromoteAndStartPending()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::PromoteAndStartPending ( bool in_isr )

inlineprivate

Definition at line 291 of file uart_dma_tx_model.hpp.

  {
    WriteInfoBlock info{};
    if (!PromotePending(info))
    {
      return false;
    }
 
    const bool started = StartActive();
    if (!started)
    {
      ClearActive();
    }
    port_.Finish(in_isr, started ? ErrorCode::OK : ErrorCode::FAILED, info);
 
    if (!started)
    {
      RequestConfig(in_isr);
      return true;
    }
 
    (void)StageNextPending(in_isr);
    return true;
  }

◆ PromotePending()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::PromotePending ( WriteInfoBlock & info )

inlineprivate

Definition at line 247 of file uart_dma_tx_model.hpp.

  {
    if (!pending_valid_)
    {
      return false;
    }
 
    pending_valid_ = false;
    buffers_.FlipActiveBlock();
    if (!PopActiveInfo(info))
    {
      return false;
    }
 
    active_length_ = info.data.size_;
    return true;
  }

◆ ReleaseActive()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::ReleaseActive ( )

inlineprivate

Definition at line 279 of file uart_dma_tx_model.hpp.

  {
    if (!busy_)
    {
      return false;
    }
 
    busy_ = false;
    ClearActive();
    return true;
  }

◆ RequestConfig()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::RequestConfig ( bool in_isr )

inline

发布最高优先级配置事件 / Publish the highest-priority configuration event

Parameters

in_isr 当前调用是否位于 ISR / Whether the current caller is in an ISR

平台后端负责保存最新配置 payload。本入口只发布可合并事件；CONFIG owner 会停止并重配硬件、终止旧 TX 前缀，然后让 CONFIG 期间追加的请求在后续轮次继续推进。 The platform backend owns the latest configuration payload. This entry only publishes the coalesced event; the CONFIG owner reconfigures hardware, aborts the old TX prefix, and leaves requests appended during CONFIG for later service rounds.

Definition at line 91 of file uart_dma_tx_model.hpp.

  {
    backend_.OnConfigRequested();
    (void)service_.Invoke(EventMask(TxEvent::CONFIG),
                          [this, in_isr](uint32_t events) noexcept
                          { ServiceTx(events, in_isr, nullptr); });
  }

◆ ServiceTx()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::ServiceTx	(	uint32_t	events,
		bool	in_isr,
		SubmitContext *	submit )

inlineprivatenoexcept

Definition at line 134 of file uart_dma_tx_model.hpp.

  {
    if (HasEvent(events, TxEvent::CONFIG))
    {
      const bool resume_tx = ApplyConfig(in_isr);
      if (!config_boundary_valid_ && resume_tx)
      {
        (void)service_.Invoke(EventMask(TxEvent::WRITE),
                              [this, in_isr](uint32_t pending_events) noexcept
                              { ServiceTx(pending_events, in_isr, nullptr); });
      }
      return;
    }
 
    // A CONFIG request may be waiting for RX hardware ownership. Keep later WRITE and
    // terminal notifications coalesced in their level-triggered facts, but do not let
    // them move the fixed old-prefix boundary before CONFIG is retried.
    if (config_boundary_valid_)
    {
      return;
    }
 
    bool terminal = false;
    if (HasEvent(events, TxEvent::ERROR))
    {
      terminal = ReleaseActive();
    }
    else if (HasEvent(events, TxEvent::COMPLETE))
    {
      terminal = ReleaseActive();
    }
 
    if (terminal && PromoteAndStartPending(in_isr))
    {
      return;
    }
 
    if (!busy_ && (active_length_ == 0U))
    {
      StartQueuedActive(in_isr, submit);
    }
 
    if (busy_)
    {
      (void)StageNextPending(in_isr);
    }
  }

◆ StageNextPending()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::StageNextPending ( bool in_isr )

inlineprivate

Definition at line 221 of file uart_dma_tx_model.hpp.

  {
    while (!pending_valid_)
    {
      WriteInfoBlock info{};
      if (port_.queue_info_->Peek(info) != ErrorCode::OK)
      {
        return false;
      }
 
      if (info.data.size_ > buffers_.Size())
      {
        if (!DiscardPayload(info.data.size_) || !PopActiveInfo(info))
        {
          ASSERT(false);
          return false;
        }
        port_.Finish(in_isr, ErrorCode::FAILED, info);
        continue;
      }
 
      return StagePending(info);
    }
    return false;
  }

◆ StagePending()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::StagePending ( const WriteInfoBlock & info )

inlineprivate

Definition at line 210 of file uart_dma_tx_model.hpp.

  {
    if (pending_valid_ || !PopPayload(buffers_.PendingBuffer(), info.data.size_))
    {
      return false;
    }
 
    pending_valid_ = true;
    return true;
  }

◆ StartActive()

template<typename Backend >

bool LibXR::UartDmaTxModel< Backend >::StartActive ( )

inlineprivate

Definition at line 265 of file uart_dma_tx_model.hpp.

  {
    ASSERT(active_length_ > 0U);
    busy_ = true;
    if (backend_.StartDmaTx(buffers_.ActiveBuffer(), active_length_,
                            buffers_.ActiveBlock()))
    {
      return true;
    }
 
    busy_ = false;
    return false;
  }

◆ StartQueuedActive()

template<typename Backend >

void LibXR::UartDmaTxModel< Backend >::StartQueuedActive	(	bool	in_isr,
		SubmitContext *	submit )

inlineprivate

Definition at line 316 of file uart_dma_tx_model.hpp.

  {
    WriteInfoBlock info{};
    if (port_.queue_info_->Peek(info) != ErrorCode::OK)
    {
      return;
    }
 
    if (info.data.size_ > buffers_.Size())
    {
      if (!DiscardPayload(info.data.size_) || !PopActiveInfo(info))
      {
        ASSERT(false);
        return;
      }
      if (submit != nullptr)
      {
        submit->result = ErrorCode::FAILED;
      }
      else
      {
        port_.Finish(in_isr, ErrorCode::FAILED, info);
      }
      return;
    }
 
    if (!PopPayload(buffers_.ActiveBuffer(), info.data.size_) || !PopActiveInfo(info))
    {
      ASSERT(false);
      if (submit != nullptr)
      {
        submit->result = ErrorCode::FAILED;
      }
      return;
    }
 
    active_length_ = info.data.size_;
    const bool started = StartActive();
    if (!started)
    {
      ClearActive();
    }
 
    if (submit != nullptr)
    {
      submit->result = started ? ErrorCode::OK : ErrorCode::FAILED;
    }
    else
    {
      port_.Finish(in_isr, started ? ErrorCode::OK : ErrorCode::FAILED, info);
      if (!started)
      {
        RequestConfig(in_isr);
      }
    }
  }

◆ Submit()

template<typename Backend >

ErrorCode LibXR::UartDmaTxModel< Backend >::Submit ( bool in_isr )

inline

发布 WRITE 事件并推进队首请求 / Publish WRITE and advance the head request

Parameters

in_isr 当前调用是否位于 ISR / Whether the current caller is in an ISR

Returns: 当前请求同步启动时返回 OK，留在流水中时返回 PENDING，同步启动失败时返回错误 / OK for a synchronous start, PENDING while retained by the pipeline, or an error for a synchronous start failure

Definition at line 47 of file uart_dma_tx_model.hpp.

  {
    SubmitContext context{};
    (void)service_.Invoke(EventMask(TxEvent::WRITE),
                          [this, in_isr, &context](uint32_t events) noexcept
                          { ServiceTx(events, in_isr, &context); });
    return context.result;
  }

Definition at line 439 of file uart_dma_tx_model.hpp.

439{};

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

src/driver/model/uart_dma_tx_model.hpp

Data Structures

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ TxEvent

Constructor & Destructor Documentation

◆ UartDmaTxModel()

Member Function Documentation

◆ ApplyConfig()

◆ Buffer()

◆ BufferSize()

◆ ClearActive()

◆ DiscardPayload()

◆ EventMask()

◆ FailPublishedQueued()

◆ HasEvent()

◆ IsBusy()

◆ OnTransferDone()

◆ OnTransferError()

◆ PopActiveInfo()

◆ PopPayload()

◆ PromoteAndStartPending()

◆ PromotePending()

◆ ReleaseActive()

◆ RequestConfig()

◆ ServiceTx()

◆ StageNextPending()

◆ StagePending()

◆ StartActive()

◆ StartQueuedActive()

◆ Submit()

Field Documentation

◆ active_length_

◆ backend_

◆ buffers_

◆ busy_

◆ config_boundary_valid_

◆ config_prefix_count_

◆ pending_valid_

◆ port_

◆ service_