ReadPort class for handling read operations. More...

#include <read_port.hpp>

Inheritance diagram for LibXR::ReadPort:

Collaboration diagram for LibXR::ReadPort:

Public Types
enum class	BusyState : uint32_t { IDLE = 0 , PENDING = 1 , CLEARING = 2 , BLOCK_CLAIMED = 3 , BLOCK_DETACHED = 4 , EVENT = UINT32_MAX }

Public Member Functions
	ReadPort (size_t buffer_size=128)
	Constructs a ReadPort with queue sizes.

size_t	EmptySize ()
	获取队列的剩余可用空间。 Gets the remaining available space in the queue.

size_t	Size ()
	获取当前队列的已使用大小。 Gets the currently used size of the queue.

bool	Readable ()
	Checks if read operations are supported.

ReadPort &	operator= (ReadFun fun)
	赋值运算符重载，用于设置读取函数。 Overloaded assignment operator to set the read function.

void	Finish (bool in_isr, ErrorCode ans, ReadInfoBlock &info)
	完成已由队列路径认领的读取操作。 Completes a read operation already claimed by the queue path.

void	MarkAsRunning (ReadInfoBlock &info)
	标记读取操作为运行中。 Marks the read operation as running.

ErrorCode	operator() (RawData data, ReadOperation &op, bool in_isr=false)
	读取操作符重载，用于执行读取操作。 Overloaded function call operator to perform a read operation.

virtual void	OnRxDequeue (bool)
	RX 数据从软件队列成功出队后的通知。 Notification after bytes are popped from RX data queue.

ErrorCode	ClearQueuedData (bool in_isr=false)
	清空当前已排队的 RX 字节。

void	ProcessPendingReads (bool in_isr)
	Processes pending reads.

void	FailAndClearAll (ErrorCode reason, bool in_isr)
	失败完成并清空当前所有挂起读操作。

Data Fields
ReadFun	read_fun_ = nullptr
	Driver/backend read notification entry. 底层驱动或后端读取通知入口。

LockFreeQueue< uint8_t > *	queue_data_ = nullptr
	RX payload queue. 接收数据字节队列。

ReadInfoBlock	info_ {}
	In-flight read request metadata. 当前在途读取请求的元数据。

std::atomic< BusyState >	busy_ {BusyState::IDLE}
	Shared read-progress handoff state. 共享的读进度交接状态。

ErrorCode	block_result_ = ErrorCode::OK
	Final status for the current BLOCK read.

Detailed Description

ReadPort class for handling read operations.

处理读取操作的ReadPort类。

Definition at line 17 of file read_port.hpp.

Member Enumeration Documentation

◆ BusyState

enum class LibXR::ReadPort::BusyState : uint32_t

strong

Enumerator
IDLE	No active waiter and no pending completion. 无等待者、无挂起完成。
PENDING	Driver accepted the request; completion still owns progress. 请求已交给底层推进。
CLEARING	ClearQueuedData() owns software dequeue progress. ClearQueuedData() 占有软件出队进度。
BLOCK_CLAIMED	BLOCK wakeup already belongs to the current waiter. 当前 BLOCK 唤醒已被本次等待者认领。
BLOCK_DETACHED	Timeout detached the waiter; completion must stay silent. 超时已分离等待者，完成侧不得再唤醒。
EVENT	Data arrived before a waiter was armed; next caller must re-check queue. 数据先到，后续调用者要重查队列。

Definition at line 38 of file read_port.hpp.

  {
    IDLE = 0,     
    PENDING = 1,  
    CLEARING = 2,  
    BLOCK_CLAIMED = 3,   
    BLOCK_DETACHED = 4,  
    EVENT = UINT32_MAX   
  };

Constructor & Destructor Documentation

◆ ReadPort()

ReadPort::ReadPort ( size_t buffer_size = 128 )

Constructs a ReadPort with queue sizes.

以指定队列大小构造ReadPort。

Parameters

buffer_size Size of the RX byte queue. 接收字节队列的容量。

Note: 包含动态内存分配。 Contains dynamic memory allocation.

Definition at line 7 of file read_port.cpp.

    : queue_data_(buffer_size > 0 ? new (std::align_val_t(LibXR::CACHE_LINE_SIZE))
                                        LockFreeQueue<uint8_t>(buffer_size)
                                  : nullptr)
{
}

Member Function Documentation

◆ ClearQueuedData()

ErrorCode ReadPort::ClearQueuedData ( bool in_isr = false )

nodiscard

清空当前已排队的 RX 字节。

Discards the RX bytes currently queued in software.

该接口只丢弃当前 queue_data_ 中已经排队的字节，不参与 backend teardown，也不会失败完成挂起读请求。若存在正在推进的读请求，则返回 BUSY。 This API only discards the bytes already queued in queue_data_. It does not participate in backend teardown and does not fail-complete an in-flight read. Returns BUSY when a read request is currently in progress.

Note: After this call claims CLEARING, ordinary reads can no longer consume the current software-queue snapshot. Bytes that arrive after the snapshot may remain queued for a later reader/clear call.; 本次调用 claim CLEARING 之后，普通读不会再消费当前软件队列快照；在快照之后新到达的字节，可以留给后续读取或下次清队列。

Parameters

in_isr 是否在 ISR 上下文 / Whether running in ISR context

Returns: OK 表示本次清队列成功完成；BUSY 表示当前有读请求占有该端口。 OK means the clear operation completed; BUSY means an active read still owns this port.

Definition at line 257 of file read_port.cpp.

{
  ASSERT(queue_data_ != nullptr);
 
  while (true)
  {
    auto state = busy_.load(std::memory_order_acquire);
    if (state != BusyState::IDLE && state != BusyState::EVENT)
    {
      return ErrorCode::BUSY;
    }
 
    BusyState expected = state;
    if (!busy_.compare_exchange_strong(expected, BusyState::CLEARING,
                                       std::memory_order_acq_rel,
                                       std::memory_order_acquire))
    {
      if (expected != BusyState::IDLE && expected != BusyState::EVENT)
      {
        return ErrorCode::BUSY;
      }
      continue;
    }
 
    const size_t queued_size = queue_data_->Size();
    if (queued_size == 0)
    {
      busy_.store(BusyState::IDLE, std::memory_order_release);
      return ErrorCode::OK;
    }
 
    const ErrorCode pop_ans = queue_data_->PopBatch(nullptr, queued_size);
    if (pop_ans == ErrorCode::OK)
    {
      OnRxDequeue(in_isr);
    }
    else
    {
      // With CLEARING, ordinary reads cannot race this pop. EMPTY here means a
      // stronger path such as FailAndClearAll() reset the queue concurrently.
      // 有了 CLEARING 之后，普通读不会再与本次 Pop 竞争。这里如果是 EMPTY，
      // 说明是 FailAndClearAll() 之类更强的路径并发 reset 了队列。
      ASSERT(pop_ans == ErrorCode::EMPTY);
    }
 
    busy_.store(queue_data_->Size() > 0 ? BusyState::EVENT : BusyState::IDLE,
                std::memory_order_release);
    return ErrorCode::OK;
  }
}

◆ EmptySize()

size_t ReadPort::EmptySize ( )

获取队列的剩余可用空间。 Gets the remaining available space in the queue.

该函数返回 queue_data_ 中当前可用的空闲空间大小。 This function returns the size of the available empty space in queue_data_.

Returns: 返回队列的空闲大小（单位：字节）。 Returns the empty size of the queue (in bytes).

Definition at line 14 of file read_port.cpp.

{
  ASSERT(queue_data_ != nullptr);
  return queue_data_->EmptySize();
}

◆ FailAndClearAll()

void ReadPort::FailAndClearAll	(	ErrorCode	reason,
		bool	in_isr )

失败完成并清空当前所有挂起读操作。

Fail-complete and clear all currently pending read operations.

Note: Driver-only: call this only after the backend is known to be unavailable.; 仅供驱动层在后端已明确不可用后调用。; The surrounding driver must already guarantee that no new front-end submissions or back-end completion/data events can still arrive for this port.; 外围驱动还必须先保证：这条端口后续不会再收到新的前端提交，也不会再收到新的后端完成或数据事件。

Parameters

reason	最终失败原因 / Final failure reason
in_isr	是否在 ISR 上下文 / Whether running in ISR context

Definition at line 308 of file read_port.cpp.

{
  ASSERT(queue_data_ != nullptr);
  queue_data_->Reset();
 
  auto state = busy_.load(std::memory_order_acquire);
  if (state == BusyState::PENDING)
  {
    if (info_.op.type == ReadOperation::OperationType::BLOCK)
    {
      // Backend is already unavailable. Claim the waiter and complete it with
      // the requested failure reason instead of leaving it to timeout.
      // 后端已经不可用。这里直接 claim waiter，并用指定错误收口，
      // 而不是让它继续超时等待。
      BusyState expected = BusyState::PENDING;
      if (busy_.compare_exchange_strong(expected, BusyState::BLOCK_CLAIMED,
                                        std::memory_order_acq_rel,
                                        std::memory_order_acquire))
      {
        Finish(in_isr, reason, info_);
        return;
      }
      state = expected;
    }
    else
    {
      busy_.store(BusyState::IDLE, std::memory_order_release);
      info_.op.UpdateStatus(in_isr, reason);
      return;
    }
  }
 
  if (state == BusyState::BLOCK_CLAIMED || state == BusyState::BLOCK_DETACHED)
  {
    return;
  }
 
  block_result_ = ErrorCode::OK;
  busy_.store(BusyState::IDLE, std::memory_order_release);
}

◆ Finish()

void ReadPort::Finish	(	bool	in_isr,
		ErrorCode	ans,
		ReadInfoBlock &	info )

完成已由队列路径认领的读取操作。 Completes a read operation already claimed by the queue path.

Parameters

in_isr	指示是否在中断上下文中执行。 Indicates whether the operation is executed in an interrupt context.
ans	错误码，用于指示操作的结果。 Error code indicating the result of the operation.
info	需要更新状态的 ReadInfoBlock 引用。 Reference to the ReadInfoBlock whose status needs to be updated.

Definition at line 34 of file read_port.cpp.

{
  if (info.op.type == ReadOperation::OperationType::BLOCK)
  {
    // Read completion is queue-driven. ProcessPendingReads() must claim the
    // BLOCK waiter before data is copied and Finish() is called.
    // 读完成只走队列路径。ProcessPendingReads() 必须先 claim BLOCK waiter，
    // 再拷贝数据并调用 Finish()。
    ASSERT(busy_.load(std::memory_order_acquire) == BusyState::BLOCK_CLAIMED);
    block_result_ = ans;
    info.op.data.sem_info.sem->PostFromCallback(in_isr);
    return;
  }
 
  busy_.store(BusyState::IDLE, std::memory_order_release);
  info.op.UpdateStatus(in_isr, ans);
}

◆ MarkAsRunning()

void ReadPort::MarkAsRunning ( ReadInfoBlock & info )

标记读取操作为运行中。 Marks the read operation as running.

该函数用于将 info.op_ 标记为运行状态，以指示当前正在进行读取操作。 This function marks info.op_ as running to indicate an ongoing read operation.

Parameters

info	需要更新状态的 ReadInfoBlock 引用。 Reference to the ReadInfoBlock whose status needs to be updated.

Definition at line 52 of file read_port.cpp.

52{ info.op.MarkAsRunning(); }

LibXR::Operation::MarkAsRunning

void MarkAsRunning()

标记操作为运行状态。 Marks the operation as running.

Definition operation.hpp:199

◆ OnRxDequeue()

virtual void LibXR::ReadPort::OnRxDequeue ( bool )

inlinevirtual

RX 数据从软件队列成功出队后的通知。 Notification after bytes are popped from RX data queue.

Parameters

in_isr 指示是否在中断上下文中执行。 Indicates whether the operation is executed in an interrupt context.

Reimplemented in LibXR::USB::CDCUartReadPort.

Definition at line 171 of file read_port.hpp.

171{}

◆ operator()()

ErrorCode ReadPort::operator()	(	RawData	data,
		ReadOperation &	op,
		bool	in_isr = false )

读取操作符重载，用于执行读取操作。 Overloaded function call operator to perform a read operation.

该函数检查端口是否可读，并根据 data.size_ 和 op 的类型执行不同的操作。 This function checks if the port is readable and performs different actions based on data.size_ and the type of op.

Parameters

data	包含要读取的数据。 Contains the data to be read.

Note: data.size_ == 0 is a readiness read: it completes when the RX queue is non-empty, does not consume bytes, and does not call OnRxDequeue().; data.size_ == 0 表示可读通知：RX 队列非空即完成，不消费字节，也不调用 OnRxDequeue()。

Parameters

op	读取操作对象，包含操作类型和同步机制。 Read operation object containing the operation type and synchronization mechanism.
in_isr	指示是否在中断上下文中执行。 Indicates whether the operation is executed in an interrupt context.

Returns: 返回操作的 ErrorCode，指示操作结果。 Returns an ErrorCode indicating the result of the operation.

Definition at line 54 of file read_port.cpp.

{
  if (Readable())
  {
    BusyState is_busy = busy_.load(std::memory_order_acquire);
 
    if (is_busy != BusyState::IDLE && is_busy != BusyState::EVENT)
    {
      return ErrorCode::BUSY;
    }
 
    while (true)
    {
      busy_.store(BusyState::IDLE, std::memory_order_release);
 
      auto readable_size = queue_data_->Size();
 
      if (readable_size >= data.size_ && readable_size != 0)
      {
        if (data.size_ > 0)
        {
          auto ans =
              queue_data_->PopBatch(reinterpret_cast<uint8_t*>(data.addr_), data.size_);
          ASSERT(ans == ErrorCode::OK);
          OnRxDequeue(in_isr);
        }
 
        if (op.type != ReadOperation::OperationType::BLOCK)
        {
          op.UpdateStatus(in_isr, ErrorCode::OK);
        }
        return ErrorCode::OK;
      }
 
      info_ = ReadInfoBlock{data, op};
 
      op.MarkAsRunning();
 
      BusyState expected = BusyState::IDLE;
      if (!busy_.compare_exchange_strong(expected, BusyState::PENDING,
                                         std::memory_order_acq_rel,
                                         std::memory_order_acquire))
      {
        ASSERT(expected == BusyState::EVENT);
        continue;
      }
 
      auto ans = read_fun_(*this, in_isr);
      if (static_cast<int8_t>(ans) >= 0)
      {
        break;
      }
 
      // read_fun_ failed while arming/notifying the backend. Roll back only if no
      // producer has completed this pending read concurrently.
      // read_fun_ 挂起/通知底层失败；只有未被 producer 并发完成时，才回滚 pending。
      expected = BusyState::PENDING;
      if (busy_.compare_exchange_strong(expected, BusyState::IDLE,
                                        std::memory_order_acq_rel,
                                        std::memory_order_acquire))
      {
        if (op.type != ReadOperation::OperationType::BLOCK)
        {
          op.UpdateStatus(in_isr, ans);
        }
        return ans;
      }
 
      if (expected == BusyState::BLOCK_DETACHED)
      {
        return ErrorCode::TIMEOUT;
      }
      if (expected == BusyState::IDLE)
      {
        // A non-BLOCK read may have completed through ProcessPendingReads() before the
        // arm failure returned.
        // 非 BLOCK 读可能在挂起失败返回前，已经通过 ProcessPendingReads() 完成。
        ASSERT(op.type != ReadOperation::OperationType::BLOCK);
        return ErrorCode::OK;
      }
      ASSERT(expected == BusyState::BLOCK_CLAIMED);
      break;
    }
 
    if (op.type == ReadOperation::OperationType::BLOCK)
    {
      ASSERT(!in_isr);
      auto wait_ans = op.data.sem_info.sem->Wait(op.data.sem_info.timeout);
      if (wait_ans == ErrorCode::OK)
      {
        // BLOCK_CLAIMED is always released by the waiter itself.
        // BLOCK_CLAIMED 始终由 waiter 自己释放。
#ifdef LIBXR_DEBUG_BUILD
        auto state = busy_.load(std::memory_order_acquire);
        ASSERT(state == BusyState::BLOCK_CLAIMED);
#endif
        busy_.store(BusyState::IDLE, std::memory_order_release);
        return block_result_;
      }
 
      // BLOCK wait timed out after the backend had accepted the read. Cancel only if
      // completion has not claimed this waiter.
      // 底层已接受读请求后，BLOCK 等待超时；只有完成侧尚未 claim 当前 waiter 时才取消。
      BusyState expected = BusyState::PENDING;
      if (busy_.compare_exchange_strong(expected, BusyState::IDLE,
                                        std::memory_order_acq_rel,
                                        std::memory_order_acquire))
      {
        return ErrorCode::TIMEOUT;
      }
 
      if (expected == BusyState::BLOCK_DETACHED)
      {
        // The waiter had already detached before the timeout-side cancel won.
        // 当前 waiter 已经先分离；超时侧负责把端口收回 IDLE。
        busy_.store(BusyState::IDLE, std::memory_order_release);
        return ErrorCode::TIMEOUT;
      }
 
      ASSERT(expected == BusyState::BLOCK_CLAIMED);
 
      // Timeout lost after completion had already claimed the waiter.
      // 超时发生得太晚，完成侧已经 claim 了当前 waiter。
      auto finish_wait_ans = op.data.sem_info.sem->Wait(UINT32_MAX);
      UNUSED(finish_wait_ans);
      ASSERT(finish_wait_ans == ErrorCode::OK);
      busy_.store(BusyState::IDLE, std::memory_order_release);
      return block_result_;
    }
    else
    {
      return ErrorCode::OK;
    }
  }
  else
  {
    return ErrorCode::NOT_SUPPORT;
  }
}

◆ operator=()

ReadPort & ReadPort::operator= ( ReadFun fun )

赋值运算符重载，用于设置读取函数。 Overloaded assignment operator to set the read function.

该函数允许使用 ReadFun 类型的函数对象赋值给 ReadPort，从而设置 read_fun_。 This function allows assigning a ReadFun function object to ReadPort, setting read_fun_.

Parameters

fun	要分配的读取函数。 The read function to be assigned.

Returns: 返回自身的引用，以支持链式调用。 Returns a reference to itself for chaining.

Definition at line 28 of file read_port.cpp.

{
  read_fun_ = fun;
  return *this;
}

◆ ProcessPendingReads()

void ReadPort::ProcessPendingReads ( bool in_isr )

Processes pending reads.

处理挂起的读取请求。

Parameters

in_isr 指示是否在中断上下文中执行。 Indicates whether the operation is executed in an interrupt context.

Definition at line 194 of file read_port.cpp.

{
  ASSERT(queue_data_ != nullptr);
 
  while (true)
  {
    auto is_busy = busy_.load(std::memory_order_acquire);
 
    if (is_busy == BusyState::PENDING)
    {
      auto size = queue_data_->Size();
      if (size > 0 && size >= info_.data.size_)
      {
        if (info_.op.type == ReadOperation::OperationType::BLOCK)
        {
          // Read BLOCK completion is claimed here before copying data.
          // BLOCK 读完成在这里先 claim，再拷数据。
          BusyState expected = BusyState::PENDING;
          if (!busy_.compare_exchange_strong(expected, BusyState::BLOCK_CLAIMED,
                                             std::memory_order_acq_rel,
                                             std::memory_order_acquire))
          {
            continue;
          }
        }
 
        if (info_.data.size_ > 0)
        {
          auto ans = queue_data_->PopBatch(reinterpret_cast<uint8_t*>(info_.data.addr_),
                                           info_.data.size_);
          UNUSED(ans);
          ASSERT(ans == ErrorCode::OK);
          Finish(in_isr, ErrorCode::OK, info_);
          OnRxDequeue(in_isr);
        }
        else
        {
          Finish(in_isr, ErrorCode::OK, info_);
        }
      }
      return;
    }
 
    if (is_busy == BusyState::IDLE)
    {
      // Data arrived before a waiter was armed. This must be a CAS: a reader may
      // publish PENDING after the load above, and EVENT must not overwrite it.
      // 数据先于 waiter 到达。这里必须用 CAS：读线程可能在上面的 load 之后发布
      // PENDING，EVENT 不能覆盖它。
      BusyState expected = BusyState::IDLE;
      if (busy_.compare_exchange_strong(expected, BusyState::EVENT,
                                        std::memory_order_acq_rel,
                                        std::memory_order_acquire))
      {
        return;
      }
      continue;
    }
 
    return;
  }
}

◆ Readable()

bool ReadPort::Readable ( )

Checks if read operations are supported.

检查是否支持读取操作。

Definition at line 26 of file read_port.cpp.

26{ return read_fun_ != nullptr; }

◆ Size()

size_t ReadPort::Size ( )

获取当前队列的已使用大小。 Gets the currently used size of the queue.

该函数返回 queue_data_ 当前已占用的空间大小。 This function returns the size of the space currently used in queue_data_.

Returns: 返回队列的已使用大小（单位：字节）。 Returns the used size of the queue (in bytes).

Definition at line 20 of file read_port.cpp.

{
  ASSERT(queue_data_ != nullptr);
  return queue_data_->Size();
}

Field Documentation

◆ block_result_

ErrorCode LibXR::ReadPort::block_result_ = ErrorCode::OK

Final status for the current BLOCK read.

Definition at line 57 of file read_port.hpp.

◆ busy_

std::atomic<BusyState> LibXR::ReadPort::busy_ {BusyState::IDLE}

Shared read-progress handoff state. 共享的读进度交接状态。

Definition at line 56 of file read_port.hpp.

56{BusyState::IDLE};

◆ info_

ReadInfoBlock LibXR::ReadPort::info_ {}

In-flight read request metadata. 当前在途读取请求的元数据。

Definition at line 55 of file read_port.hpp.

55{};

◆ queue_data_

LockFreeQueue<uint8_t>* LibXR::ReadPort::queue_data_ = nullptr

RX payload queue. 接收数据字节队列。

Definition at line 54 of file read_port.hpp.

◆ read_fun_

ReadFun LibXR::ReadPort::read_fun_ = nullptr

Driver/backend read notification entry. 底层驱动或后端读取通知入口。

Definition at line 53 of file read_port.hpp.

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

src/core/rw/read_port.hpp
src/core/rw/read_port.cpp

Public Types

Public Member Functions

Data Fields

Detailed Description

Member Enumeration Documentation

◆ BusyState

Constructor & Destructor Documentation

◆ ReadPort()

Member Function Documentation

◆ ClearQueuedData()

◆ EmptySize()

◆ FailAndClearAll()

◆ Finish()

◆ MarkAsRunning()

◆ OnRxDequeue()

◆ operator()()

◆ operator=()

◆ ProcessPendingReads()

◆ Readable()

◆ Size()

Field Documentation

◆ block_result_

◆ busy_

◆ info_

◆ queue_data_

◆ read_fun_