ReadPort class for handling read operations. More...

#include <libxr_rw.hpp>

Inheritance diagram for LibXR::ReadPort:

Collaboration diagram for LibXR::ReadPort:

Public Types
enum class	BusyState : uint32_t { IDLE = 0 , PENDING = 1 , BLOCK_CLAIMED = 2 , BLOCK_DETACHED = 3 , 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)
	更新读取操作的状态。 Updates the status of the read operation.

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.

void	ProcessPendingReads (bool in_isr)
	Processes pending reads.

void	Reset ()
	Resets the ReadPort.

Data Fields
ReadFun	read_fun_ = nullptr

LockFreeQueue< uint8_t > *	queue_data_ = nullptr

ReadInfoBlock	info_

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

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

Detailed Description

ReadPort class for handling read operations.

处理读取操作的ReadPort类。

Definition at line 378 of file libxr_rw.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. 请求已交给底层推进。
BLOCK_CLAIMED	BLOCK wakeup already belongs to the current waiter. 当前 BLOCK 唤醒已被本次等待者认领。
BLOCK_DETACHED	Timeout/reset detached the waiter; completion must stay silent. 超时或 Reset 已分离等待者，完成侧不得再唤醒。
EVENT	Data arrived before a waiter was armed; next caller must re-check queue. 数据先到，后续调用者要重查队列。

Definition at line 392 of file libxr_rw.hpp.

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

Constructor & Destructor Documentation

◆ ReadPort()

ReadPort::ReadPort ( size_t buffer_size = 128 )

Constructs a ReadPort with queue sizes.

以指定队列大小构造ReadPort。

Parameters

queue_size	Number of queued operations.
buffer_size	Size of each buffer.

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

Definition at line 11 of file libxr_rw.cpp.

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

Member Function Documentation

◆ EmptySize()

size_t ReadPort::EmptySize ( )

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

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

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

Definition at line 18 of file libxr_rw.cpp.

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

◆ Finish()

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

更新读取操作的状态。 Updates the status of the read operation.

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 38 of file libxr_rw.cpp.

{
  if (info.op.type == ReadOperation::OperationType::BLOCK)
  {
    // Read completion must come from ProcessPendingReads(); drivers are not
    // allowed to finish a BLOCK read directly.
    // BLOCK 读完成只能来自 ProcessPendingReads()；驱动不能直接 Finish。
    BusyState expected = BusyState::BLOCK_DETACHED;
    if (busy_.compare_exchange_strong(expected, BusyState::IDLE,
                                      std::memory_order_acq_rel,
                                      std::memory_order_acquire))
    {
      return;
    }
 
    ASSERT(expected == BusyState::BLOCK_CLAIMED);
    if (expected == 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 66 of file libxr_rw.cpp.

66{ info.op.MarkAsRunning(); }

LibXR::Operation::MarkAsRunning

void MarkAsRunning()

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

Definition libxr_rw.hpp:213

◆ 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 517 of file libxr_rw.hpp.

517{}

◆ 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.
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 68 of file libxr_rw.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();
 
      auto ans = read_fun_(*this, in_isr);
 
      if (ans == ErrorCode::PENDING)
      {
        BusyState expected = BusyState::IDLE;
        if (busy_.compare_exchange_weak(expected, BusyState::PENDING,
                                        std::memory_order_acq_rel,
                                        std::memory_order_acquire))
        {
          break;
        }
        else
        {
          continue;
        }
      }
      else
      {
        if (op.type == ReadOperation::OperationType::BLOCK)
        {
          return ans;
        }
        op.UpdateStatus(in_isr, ans);
        return ErrorCode::OK;
      }
    }
 
    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_;
      }
 
      // Timeout won before completion claimed the waiter.
      // 超时先赢，完成侧还没 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_CLAIMED)
      {
        // A detached late completion may already have cleared BLOCK_DETACHED
        // back to IDLE before this waiter wakes from timeout.
        // 分离后的迟到完成可能会在当前 waiter 超时醒来前，先把
        // BLOCK_DETACHED 清回 IDLE。
        ASSERT(expected == BusyState::BLOCK_DETACHED || expected == BusyState::IDLE);
        if (expected == BusyState::BLOCK_DETACHED)
        {
          busy_.store(BusyState::IDLE, std::memory_order_release);
        }
        return ErrorCode::TIMEOUT;
      }
 
      // 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 32 of file libxr_rw.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 193 of file libxr_rw.cpp.

{
  ASSERT(queue_data_ != nullptr);
 
  auto is_busy = busy_.load(std::memory_order_relaxed);
 
  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))
        {
          return;
        }
      }
 
      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 if (is_busy == BusyState::IDLE)
  {
    busy_.store(BusyState::EVENT, std::memory_order_release);
  }
}

◆ Readable()

bool ReadPort::Readable ( )

Checks if read operations are supported.

检查是否支持读取操作。

Definition at line 30 of file libxr_rw.cpp.

30{ return read_fun_ != nullptr; }

◆ Reset()

void ReadPort::Reset ( )

Resets the ReadPort.

重置ReadPort。

Definition at line 235 of file libxr_rw.cpp.

{
  ASSERT(queue_data_ != nullptr);
  queue_data_->Reset();
 
  auto state = busy_.load(std::memory_order_acquire);
  if (state == BusyState::PENDING && info_.op.type == ReadOperation::OperationType::BLOCK)
  {
    // Reset detaches the BLOCK waiter instead of reopening the port directly.
    // Reset 先分离 BLOCK waiter，不直接重开端口。
    BusyState expected = BusyState::PENDING;
    if (busy_.compare_exchange_strong(expected, BusyState::BLOCK_DETACHED,
                                      std::memory_order_acq_rel,
                                      std::memory_order_acquire))
    {
      return;
    }
 
    state = busy_.load(std::memory_order_acquire);
  }
 
  if (state == BusyState::BLOCK_CLAIMED || state == BusyState::BLOCK_DETACHED)
  {
    return;
  }
 
  block_result_ = ErrorCode::OK;
  busy_.store(BusyState::IDLE, std::memory_order_release);
}

◆ Size()

size_t ReadPort::Size ( )

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

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

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

Definition at line 24 of file libxr_rw.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 409 of file libxr_rw.hpp.

◆ busy_

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

Definition at line 408 of file libxr_rw.hpp.

408{BusyState::IDLE};

◆ info_

ReadInfoBlock LibXR::ReadPort::info_

Definition at line 407 of file libxr_rw.hpp.

◆ queue_data_

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

Definition at line 406 of file libxr_rw.hpp.

◆ read_fun_

ReadFun LibXR::ReadPort::read_fun_ = nullptr

Definition at line 405 of file libxr_rw.hpp.

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

src/core/libxr_rw.hpp
src/core/libxr_rw.cpp

Public Types

Public Member Functions

Data Fields

Detailed Description

Member Enumeration Documentation

◆ BusyState

Constructor & Destructor Documentation

◆ ReadPort()

Member Function Documentation

◆ EmptySize()

◆ Finish()

◆ MarkAsRunning()

◆ OnRxDequeue()

◆ operator()()

◆ operator=()

◆ ProcessPendingReads()

◆ Readable()

◆ Reset()

◆ Size()

Field Documentation

◆ block_result_

◆ busy_

◆ info_

◆ queue_data_

◆ read_fun_