read_port.hpp

#pragma once
 
#include <atomic>
#include <cstddef>
#include <cstdint>
 
#include "operation.hpp"
#include "queue.hpp"
 
namespace LibXR
{
 
class ReadPort
{
 public:
  // Exposed low-level state and helpers for the read-path core. Some members stay public
  // because low-level libxr tests and driver glue inspect them directly.
  // 读路径核心的低层状态与辅助类型。部分成员保持 public，
  // 是因为 libxr 的底层测试与驱动胶水层会直接检查它们。
 
  // Read BLOCK states:
  // PENDING = waiting for queue-fed completion after read_fun_ was notified
  // CLEARING = ClearQueuedData() owns software dequeue progress
  // BLOCK_CLAIMED = wakeup now belongs to the waiter
  // BLOCK_DETACHED = timeout detached the waiter
  // The same semaphore may be reused only after the previous BLOCK call
  // returns and the port goes back to IDLE.
  // 读 BLOCK 状态：
  // PENDING = 已通知 read_fun_，等待队列侧完成
  // CLEARING = ClearQueuedData() 占有软件出队进度
  // BLOCK_CLAIMED = 唤醒已经归当前 waiter 所有
  // BLOCK_DETACHED = timeout 已把 waiter 分离
  // 同一个信号量只能在上一次 BLOCK 调用返回、端口回到 IDLE 后复用。
  enum class BusyState : uint32_t
  {
    IDLE = 0,      
    PENDING = 1,   
    CLEARING = 2,  
    BLOCK_CLAIMED = 3,   
    BLOCK_DETACHED = 4,  
    EVENT = UINT32_MAX   
  };
 
  ReadFun read_fun_ =
      nullptr;  
  SPSCQueue<uint8_t>* queue_data_ = nullptr;  
  ReadInfoBlock info_{};  
  std::atomic<BusyState> busy_{
      BusyState::IDLE};  
  ErrorCode block_result_ = ErrorCode::OK;  
 
  ReadPort(size_t buffer_size = 128);
 
  virtual ~ReadPort() = default;
 
  size_t EmptySize();
 
  size_t Size();
 
  bool Readable();
 
  ReadPort& operator=(ReadFun fun);
 
  void Finish(bool in_isr, ErrorCode ans, ReadInfoBlock& info);
 
  void MarkAsRunning(ReadInfoBlock& info);
 
  ErrorCode operator()(RawData data, ReadOperation& op, bool in_isr = false);
 
  virtual void OnRxDequeue(bool) {}
 
  [[nodiscard]] ErrorCode ClearQueuedData(bool in_isr = false);
 
  void ProcessPendingReads(bool in_isr);
 
  void FailAndClearAll(ErrorCode reason, bool in_isr);
};
 
}  // namespace LibXR