Split Virtqueue 管理类 More...

#include <split.hpp>

Inheritance diagram for virtio::SplitVirtqueue:

Collaboration diagram for virtio::SplitVirtqueue:

Classes
struct	Avail
	Virtqueue Available Ring. More...

struct	Desc
	Virtqueue 描述符表条目 More...

struct	Used
	Virtqueue Used Ring. More...

struct	UsedElem
	Virtqueue Used Ring 元素 More...

Public Types
enum class	DescFlags : uint16_t { kDescFNext = 1 , kDescFWrite = 2 , kDescFIndirect = 4 }
	Descriptor Flags. More...

enum class	AvailFlags : uint16_t { kAvailFNoInterrupt = 1 }
	Available Ring Flags. More...

enum class	UsedFlags : uint16_t { kUsedFNoNotify = 1 }
	Used Ring Flags. More...

Public Member Functions
	SplitVirtqueue (const DmaRegion &dma, uint16_t queue_size, bool event_idx, size_t used_align=Used::kAlign)
	从预分配的 DMA 缓冲区构造 SplitVirtqueue

auto	IsValid () const -> bool
	检查 virtqueue 是否成功初始化

auto	AllocDesc () -> Expected< uint16_t >
	从空闲链表分配一个描述符

auto	FreeDesc (uint16_t idx) -> Expected< void >
	归还描述符到空闲链表

auto	GetDesc (uint16_t idx) -> Expected< volatile Desc * >
	获取描述符的可变引用

auto	GetDesc (uint16_t idx) const -> Expected< const volatile Desc * >
	获取描述符的只读引用

auto	Submit (uint16_t head) -> void
	将描述符链提交到 Available Ring

auto	HasUsed () const -> bool
	检查 Used Ring 中是否有已完成的缓冲区

auto	PopUsed () -> Expected< UsedElem >
	从 Used Ring 弹出一个已完成的元素

auto	SubmitChain (const IoVec readable, size_t readable_count, const IoVec writable, size_t writable_count) -> Expected< uint16_t >
	提交 Scatter-Gather 描述符链

auto	FreeChain (uint16_t head) -> Expected< void >
	释放整条描述符链

auto	DescPhys () const -> uint64_t
	获取描述符表的物理地址

auto	AvailPhys () const -> uint64_t
	获取 Available Ring 的物理地址

auto	UsedPhys () const -> uint64_t
	获取 Used Ring 的物理地址

auto	Size () const -> uint16_t
	获取队列大小

auto	NumFree () const -> uint16_t
	获取当前空闲描述符数量

auto	AvailUsedEvent () -> volatile uint16_t *
	获取 Available Ring 的 used_event 字段

auto	AvailUsedEvent () const -> const volatile uint16_t *

auto	UsedAvailEvent () -> volatile uint16_t *
	获取 Used Ring 的 avail_event 字段

auto	UsedAvailEvent () const -> const volatile uint16_t *

auto	EventIdxEnabled () const -> bool
	检查是否启用了 VIRTIO_F_EVENT_IDX 特性

auto	AvailIdx () const -> uint16_t
	获取当前 Available Ring 索引

auto	LastUsedIdx () const -> uint16_t
	获取驱动程序上次处理到的 Used Ring 索引

构造/析构函数
	SplitVirtqueue ()=delete

	SplitVirtqueue (const SplitVirtqueue &)=delete

auto	operator= (const SplitVirtqueue &) -> SplitVirtqueue &=delete

auto	operator= (SplitVirtqueue &&) -> SplitVirtqueue &=delete

	SplitVirtqueue (SplitVirtqueue &&other) noexcept

	~SplitVirtqueue ()=default

Public Member Functions inherited from virtio::VirtqueueBase
auto	SubmitChainWithBarrier (this auto &&self, const IoVec readable, size_t readable_count, const IoVec writable, size_t writable_count) -> Expected< uint16_t >
	提交 Scatter-Gather 链并通知设备

template<typename Callback >
auto	ProcessUsedWithCallback (this auto &&self, Callback &&callback) -> uint32_t
	处理已完成的缓冲区并释放描述符链

Static Public Member Functions
static constexpr auto	CalcSize (uint16_t queue_size, bool event_idx=true, size_t used_align=Used::kAlign) -> size_t
	计算给定队列大小所需的 DMA 内存字节数

Private Attributes
volatile Desc *	desc_ {nullptr}
	描述符表指针（指向 DMA 内存）

volatile Avail *	avail_ {nullptr}
	Available Ring 指针（指向 DMA 内存）

volatile Used *	used_ {nullptr}
	Used Ring 指针（指向 DMA 内存）

uint16_t	queue_size_ {0}
	队列大小（描述符数量，必须为 2 的幂）

uint16_t	free_head_ {0}
	空闲描述符链表头索引

uint16_t	num_free_ {0}
	空闲描述符数量

uint16_t	last_used_idx_ {0}
	上次处理到的 Used Ring 索引（用于 PopUsed）

uint64_t	phys_base_ {0}
	DMA 内存物理基地址（客户机物理地址）

size_t	desc_offset_ {0}
	描述符表在 DMA 内存中的偏移量（字节）

size_t	avail_offset_ {0}
	Available Ring 在 DMA 内存中的偏移量（字节）

size_t	used_offset_ {0}
	Used Ring 在 DMA 内存中的偏移量（字节）

bool	event_idx_enabled_ {false}
	是否启用 VIRTIO_F_EVENT_IDX 特性

bool	is_valid_ {false}
	初始化是否成功

Additional Inherited Members
Protected Member Functions inherited from virtio::VirtqueueBase
	VirtqueueBase ()=default

	~VirtqueueBase ()=default

	VirtqueueBase (VirtqueueBase &&) noexcept=default

auto	operator= (VirtqueueBase &&) noexcept -> VirtqueueBase &=default

	VirtqueueBase (const VirtqueueBase &)=delete

auto	operator= (const VirtqueueBase &) -> VirtqueueBase &=delete

Detailed Description

Split Virtqueue 管理类

管理 split virtqueue 的描述符分配/释放、缓冲区提交、已用缓冲区回收。使用预分配的 DMA 内存，自身不进行任何堆内存分配。

内存布局（在 DMA 缓冲区中连续排列）：

[Descriptor Table]  aligned to 16
[Available Ring]    aligned to 2
[Used Ring]         aligned to 4

Warning: 非线程安全：此类的所有方法均不是线程安全的。如果多个线程/核需要访问同一个 virtqueue，调用者必须使用外部同步机制（如自旋锁或互斥锁）。; 单生产者-单消费者：描述符分配和提交应由同一线程执行，已用缓冲区回收应由另一线程执行（通常在中断处理程序中）。

See also: cpu_io::Wmb/Rmb for barrier semantics; virtio-v1.2#2.7

Definition at line 38 of file split.hpp.

Member Enumeration Documentation

◆ AvailFlags

enum class virtio::SplitVirtqueue::AvailFlags : uint16_t

strong

Available Ring Flags.

See also: virtio-v1.2#2.7.6 The Virtqueue Available Ring

Enumerator
kAvailFNoInterrupt	设备应该不发送中断

Definition at line 57 of file split.hpp.

                        : uint16_t {
    kAvailFNoInterrupt = 1
  };

◆ DescFlags

enum class virtio::SplitVirtqueue::DescFlags : uint16_t

strong

Descriptor Flags.

See also: virtio-v1.2#2.7.5 The Virtqueue Descriptor Table

Enumerator
kDescFNext	标记缓冲区通过 next 字段继续
kDescFWrite	标记缓冲区为设备只写(否则为设备只读)
kDescFIndirect	标记缓冲区包含描述符列表(间接描述符)

Definition at line 44 of file split.hpp.

                       : uint16_t {
    kDescFNext = 1,
    kDescFWrite = 2,
    kDescFIndirect = 4
  };

◆ UsedFlags

enum class virtio::SplitVirtqueue::UsedFlags : uint16_t

strong

Used Ring Flags.

See also: virtio-v1.2#2.7.8 The Virtqueue Used Ring

Enumerator
kUsedFNoNotify	驱动不需要通知

Definition at line 66 of file split.hpp.

                       : uint16_t {
    kUsedFNoNotify = 1
  };

Constructor & Destructor Documentation

◆ SplitVirtqueue() [1/4]

virtio::SplitVirtqueue::SplitVirtqueue	(	const DmaRegion &	dma,
		uint16_t	queue_size,
		bool	event_idx,
		size_t	used_align = `Used::kAlign`
	)

inline

从预分配的 DMA 缓冲区构造 SplitVirtqueue

Parameters

dma	DMA 区域描述符（包含虚拟地址、物理地址和大小，必须已清零，大小 >= CalcSize()）
queue_size	队列大小（必须为 2 的幂）
event_idx	是否启用 VIRTIO_F_EVENT_IDX 特性
used_align	Used Ring 的对齐要求（modern = 4，legacy MMIO = 4096）

See also: virtio-v1.2#2.7

Definition at line 240 of file split.hpp.

      : queue_size_(queue_size),
        phys_base_(dma.phys),
        event_idx_enabled_(event_idx) {
    if (!dma.IsValid() || !IsPowerOfTwo(queue_size)) {
      return;
    }
 
    size_t desc_total = static_cast<size_t>(sizeof(Desc)) * queue_size;
    size_t avail_total = sizeof(uint16_t) * (2 + queue_size);
    if (event_idx) {
      avail_total += sizeof(uint16_t);
    }
 
    desc_offset_ = 0;
    avail_offset_ = AlignUp(desc_total, Avail::kAlign);
    size_t used_total = sizeof(uint16_t) * 2 + sizeof(UsedElem) * queue_size;
    if (event_idx) {
      used_total += sizeof(uint16_t);
    }
    used_offset_ = AlignUp(avail_offset_ + avail_total, used_align);
 
    auto* base = dma.Data();
    desc_ = reinterpret_cast<volatile Desc*>(base + desc_offset_);
    avail_ = reinterpret_cast<volatile Avail*>(base + avail_offset_);
    used_ = reinterpret_cast<volatile Used*>(base + used_offset_);
 
    for (uint16_t i = 0; i < queue_size; ++i) {
      desc_[i].next = static_cast<uint16_t>(i + 1);
    }
    // 末尾描述符使用 sentinel 值，避免越界索引
    desc_[queue_size - 1].next = 0xFFFF;
    free_head_ = 0;
    num_free_ = queue_size;
    last_used_idx_ = 0;
 
    is_valid_ = true;
  }

Here is the call graph for this function:

◆ SplitVirtqueue() [2/4]

virtio::SplitVirtqueue::SplitVirtqueue ( )

delete

◆ SplitVirtqueue() [3/4]

virtio::SplitVirtqueue::SplitVirtqueue ( const SplitVirtqueue & )

delete

◆ SplitVirtqueue() [4/4]

virtio::SplitVirtqueue::SplitVirtqueue ( SplitVirtqueue && other )

inlinenoexcept

Definition at line 643 of file split.hpp.

      : VirtqueueBase(std::move(other)),
        desc_(other.desc_),
        avail_(other.avail_),
        used_(other.used_),
        queue_size_(other.queue_size_),
        free_head_(other.free_head_),
        num_free_(other.num_free_),
        last_used_idx_(other.last_used_idx_),
        phys_base_(other.phys_base_),
        desc_offset_(other.desc_offset_),
        avail_offset_(other.avail_offset_),
        used_offset_(other.used_offset_),
        event_idx_enabled_(other.event_idx_enabled_),
        is_valid_(other.is_valid_) {
    other.is_valid_ = false;
    other.desc_ = nullptr;
    other.avail_ = nullptr;
    other.used_ = nullptr;
  }

◆ ~SplitVirtqueue()

virtio::SplitVirtqueue::~SplitVirtqueue ( )

default

Member Function Documentation

◆ AllocDesc()

auto virtio::SplitVirtqueue::AllocDesc ( ) -> Expected<uint16_t>

inline

从空闲链表分配一个描述符

从空闲描述符链表中取出一个描述符，供上层使用。调用者必须填充描述符的 addr、len、flags 和 next 字段。

Returns: 成功返回描述符索引（range: 0 ~ queue_size-1）；空闲链表为空时返回 ErrorCode::kNoFreeDescriptors

Warning: 非线程安全：多个线程同时调用可能导致竞态条件

See also: virtio-v1.2#2.7.5 The Virtqueue Descriptor Table; virtio-v1.2#2.7.13 Supplying Buffers to The Device

Definition at line 298 of file split.hpp.

                                                       {
    if (num_free_ == 0) {
      return std::unexpected(Error{ErrorCode::kNoFreeDescriptors});
    }
 
    uint16_t idx = free_head_;
    free_head_ = desc_[free_head_].next;
    --num_free_;
 
    return idx;
  }

◆ AvailIdx()

auto virtio::SplitVirtqueue::AvailIdx ( ) const -> uint16_t

inline

获取当前 Available Ring 索引

Definition at line 630 of file split.hpp.

630{ return avail_->idx; }

virtio::SplitVirtqueue::Avail::idx

uint16_t idx

驱动程序将下一个描述符条目放入环中的位置(模 queue_size) (little-endian)

Definition split.hpp:109

◆ AvailPhys()

auto virtio::SplitVirtqueue::AvailPhys ( ) const -> uint64_t

inline

获取 Available Ring 的物理地址

See also: virtio-v1.2#2.7.6

Definition at line 570 of file split.hpp.

                                                   {
    return phys_base_ + avail_offset_;
  }

◆ AvailUsedEvent() [1/2]

auto virtio::SplitVirtqueue::AvailUsedEvent ( ) -> volatile uint16_t*

inline

获取 Available Ring 的 used_event 字段

Returns: used_event 字段指针，未启用 EVENT_IDX 则返回 nullptr

See also: virtio-v1.2#2.7.10

Definition at line 598 of file split.hpp.

                                                            {
    return event_idx_enabled_ ? avail_->used_event(queue_size_) : nullptr;
  }

Here is the call graph for this function:

◆ AvailUsedEvent() [2/2]

auto virtio::SplitVirtqueue::AvailUsedEvent ( ) const -> const volatile uint16_t*

inline

Definition at line 602 of file split.hpp.

                                                                        {
    return event_idx_enabled_ ? avail_->used_event(queue_size_) : nullptr;
  }

Here is the call graph for this function:

◆ CalcSize()

static constexpr auto virtio::SplitVirtqueue::CalcSize	(	uint16_t	queue_size,
		bool	event_idx = `true`,
		size_t	used_align = `Used::kAlign`
	)		-> size_t

inlinestaticconstexpr

计算给定队列大小所需的 DMA 内存字节数

Parameters

queue_size	队列大小（必须为 2 的幂）
event_idx	是否启用 VIRTIO_F_EVENT_IDX 特性
used_align	Used Ring 的对齐要求

Returns: 所需的 DMA 内存字节数

See also: virtio-v1.2#2.6 Split Virtqueues

Definition at line 203 of file split.hpp.

                {
    // Descriptor Table: sizeof(Desc) * queue_size
    size_t desc_total = static_cast<size_t>(sizeof(Desc)) * queue_size;
 
    // Available Ring: flags(2) + idx(2) + ring[N](2*N) + used_event(2, 可选)
    size_t avail_total = sizeof(uint16_t) * (2 + queue_size);
    if (event_idx) {
      avail_total += sizeof(uint16_t);
    }
 
    // Used Ring: flags(2) + idx(2) + ring[N](sizeof(UsedElem)*N) +
    // avail_event(2, 可选)
    size_t used_total = sizeof(uint16_t) * 2 + sizeof(UsedElem) * queue_size;
    if (event_idx) {
      used_total += sizeof(uint16_t);
    }
 
    // 按对齐要求排列
    size_t avail_off = AlignUp(desc_total, Avail::kAlign);
    size_t used_off = AlignUp(avail_off + avail_total, used_align);
 
    return used_off + used_total;
  }

Here is the call graph for this function:

◆ DescPhys()

auto virtio::SplitVirtqueue::DescPhys ( ) const -> uint64_t

inline

获取描述符表的物理地址

See also: virtio-v1.2#2.7.5

Definition at line 562 of file split.hpp.

                                                  {
    return phys_base_ + desc_offset_;
  }

◆ EventIdxEnabled()

auto virtio::SplitVirtqueue::EventIdxEnabled ( ) const -> bool

inline

检查是否启用了 VIRTIO_F_EVENT_IDX 特性

Definition at line 623 of file split.hpp.

                                                     {
    return event_idx_enabled_;
  }

◆ FreeChain()

auto virtio::SplitVirtqueue::FreeChain ( uint16_t head ) -> Expected<void>

inline

释放整条描述符链

从链头开始，沿 next 指针遍历并释放所有描述符，直到遇到不含 kDescFNext 标志的描述符为止。

典型用法：在 PopUsed() 获取已完成请求的 head 后，用此方法一次性归还整条链的描述符。

Parameters

head 描述符链头索引

Returns: 成功或失败（如 head 索引无效）

Warning: 非线程安全

See also: virtio-v1.2#2.7.14 Receiving Used Buffers From The Device

Definition at line 530 of file split.hpp.

                                                  {
    if (head >= queue_size_) {
      return std::unexpected(Error{ErrorCode::kInvalidDescriptor});
    }
 
    uint16_t idx = head;
    while (true) {
      if (idx >= queue_size_) {
        return std::unexpected(Error{ErrorCode::kInvalidDescriptor});
      }
 
      uint16_t next = desc_[idx].next;
      bool has_next =
          (desc_[idx].flags & std::to_underlying(DescFlags::kDescFNext)) != 0;
 
      desc_[idx].next = free_head_;
      free_head_ = idx;
      ++num_free_;
 
      if (!has_next) {
        break;
      }
      idx = next;
    }
 
    return {};
  }

◆ FreeDesc()

auto virtio::SplitVirtqueue::FreeDesc ( uint16_t idx ) -> Expected<void>

inline

归还描述符到空闲链表

将不再使用的描述符放回空闲链表，供后续分配使用。对于描述符链，调用者必须按正确的顺序释放链中的每个描述符。

Parameters

idx	要释放的描述符索引（必须为之前分配的有效索引）

Warning: 非线程安全：多个线程同时调用可能导致竞态条件; 释放已释放的描述符或无效索引会导致空闲链表损坏

See also: virtio-v1.2#2.7.14 Receiving Used Buffers From The Device

Definition at line 322 of file split.hpp.

                                                {
    if (idx >= queue_size_) {
      return std::unexpected(Error{ErrorCode::kInvalidDescriptor});
    }
    desc_[idx].next = free_head_;
    free_head_ = idx;
    ++num_free_;
    return {};
  }

◆ GetDesc() [1/2]

auto virtio::SplitVirtqueue::GetDesc ( uint16_t idx ) -> Expected<volatile Desc*>

inline

获取描述符的可变引用

用于设置描述符的 addr、len、flags 和 next 字段。调用者必须确保索引有效（通过 AllocDesc() 分配）。

Parameters

idx	描述符索引（必须 < queue_size）

Returns: 描述符的 volatile 引用（用于与设备共享内存）

See also: virtio-v1.2#2.7.5 The Virtqueue Descriptor Table

Definition at line 342 of file split.hpp.

                                                                       {
    if (idx >= queue_size_) {
      return std::unexpected(Error{ErrorCode::kInvalidDescriptor});
    }
    return &desc_[idx];
  }

◆ GetDesc() [2/2]

auto virtio::SplitVirtqueue::GetDesc ( uint16_t idx ) const -> Expected<const volatile Desc*>

inline

获取描述符的只读引用

Parameters

idx	描述符索引（必须 < queue_size）

Returns: 描述符的 const volatile 指针，失败返回错误

Definition at line 355 of file split.hpp.

                                        {
    if (idx >= queue_size_) {
      return std::unexpected(Error{ErrorCode::kInvalidDescriptor});
    }
    return &desc_[idx];
  }

◆ HasUsed()

auto virtio::SplitVirtqueue::HasUsed ( ) const -> bool

inline

检查 Used Ring 中是否有已完成的缓冲区

通过比较驱动程序上次处理的 idx 与设备当前的 idx，判断是否有新的已处理缓冲区可供回收。

Returns: true 表示有已完成的缓冲区可用，false 表示没有

See also: virtio-v1.2#2.7.14 Receiving Used Buffers From The Device

Definition at line 399 of file split.hpp.

                                             {
    return last_used_idx_ != used_->idx;
  }

Here is the caller graph for this function:

◆ IsValid()

auto virtio::SplitVirtqueue::IsValid ( ) const -> bool

inline

检查 virtqueue 是否成功初始化

Definition at line 283 of file split.hpp.

283{ return is_valid_; }

◆ LastUsedIdx()

auto virtio::SplitVirtqueue::LastUsedIdx ( ) const -> uint16_t

inline

获取驱动程序上次处理到的 Used Ring 索引

Definition at line 635 of file split.hpp.

635{ return last_used_idx_; }

◆ NumFree()

auto virtio::SplitVirtqueue::NumFree ( ) const -> uint16_t

inline

获取当前空闲描述符数量

Definition at line 590 of file split.hpp.

590{ return num_free_; }

◆ operator=() [1/2]

auto virtio::SplitVirtqueue::operator= ( const SplitVirtqueue & ) -> SplitVirtqueue &=delete

delete

◆ operator=() [2/2]

auto virtio::SplitVirtqueue::operator= ( SplitVirtqueue && ) -> SplitVirtqueue &=delete

delete

◆ PopUsed()

auto virtio::SplitVirtqueue::PopUsed ( ) -> Expected<UsedElem>

inline

从 Used Ring 弹出一个已完成的元素

从 Used Ring 中取出下一个设备已处理完成的缓冲区。返回的 UsedElem 包含：

id: 描述符链头索引（对应之前提交的 head）
len: 设备写入的字节数（仅对 Device-writable 缓冲区有意义）

Returns: 成功返回 UsedElem{id, len}；无可用元素时返回 ErrorCode::kNoUsedBuffers

Warning: 非线程安全：多个线程同时调用可能导致竞态条件

See also: virtio-v1.2#2.7.14 Receiving Used Buffers From The Device

Definition at line 417 of file split.hpp.

                                                     {
    if (!HasUsed()) {
      return std::unexpected(Error{ErrorCode::kNoUsedBuffers});
    }
 
    uint16_t idx = last_used_idx_ % queue_size_;
    UsedElem elem;
    elem.id = used_->ring[idx].id;
    elem.len = used_->ring[idx].len;
 
    ++last_used_idx_;
 
    return elem;
  }

Here is the call graph for this function:

◆ Size()

auto virtio::SplitVirtqueue::Size ( ) const -> uint16_t

inline

获取队列大小

Definition at line 585 of file split.hpp.

585{ return queue_size_; }

◆ Submit()

auto virtio::SplitVirtqueue::Submit ( uint16_t head ) -> void

inline

将描述符链提交到 Available Ring

将描述符链的头部索引放入 Available Ring，使其对设备可见。调用此方法后，调用者应使用内存屏障确保 idx 更新对设备可见，然后通过 Transport::NotifyQueue() 通知设备。

Parameters

head	描述符链头部索引（必须为有效的已分配描述符）

Note: 调用者必须在调用此方法前确保描述符写入已完成; 调用者必须在调用此方法后通知设备（如 Transport::NotifyQueue()）

See also: cpu_io::Wmb() 用于确保 ring 写入在 idx 更新之前对设备可见

Warning: 非线程安全：多个线程同时调用可能导致竞态条件

See also: virtio-v1.2#2.7.13 Supplying Buffers to The Device

Definition at line 380 of file split.hpp.

                                     {
    uint16_t idx = avail_->idx;
    avail_->ring[idx % queue_size_] = head;
 
    // 写屏障：确保 ring 写入在 idx 更新之前对设备可见
    cpu_io::Wmb();
 
    avail_->idx = idx + 1;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SubmitChain()

auto virtio::SplitVirtqueue::SubmitChain	(	const IoVec *	readable,
		size_t	readable_count,
		const IoVec *	writable,
		size_t	writable_count
	)		-> Expected<uint16_t>

inline

提交 Scatter-Gather 描述符链

从空闲链表分配描述符，按顺序组装 readable（设备只读）和 writable（设备可写）缓冲区为描述符链，自动设置 NEXT 标志串联，并提交到 Available Ring。

描述符链顺序：[readable_0, ..., readable_N, writable_0, ..., writable_M]

readable 部分：flags = kDescFNext（无 kDescFWrite）
writable 部分：flags = kDescFNext | kDescFWrite
最后一个描述符清除 kDescFNext

调用者在调用此方法后仍需调用内存屏障 + Transport::NotifyQueue() 通知设备。

Parameters

readable	设备只读缓冲区数组（如请求头、写入数据）
readable_count	readable 数组中的元素数量
writable	设备可写缓冲区数组（如读取数据、状态字节）
writable_count	writable 数组中的元素数量

Returns: 成功返回描述符链头索引（可用作 token）；失败返回错误

Precondition: readable_count + writable_count > 0; readable_count + writable_count <= NumFree()

Postcondition: 描述符链已提交到 Available Ring

Warning: 非线程安全

See also: virtio-v1.2#2.7.13 Supplying Buffers to The Device; 架构文档 §3 Scatter-Gather

Definition at line 460 of file split.hpp.

                            {
    size_t total = readable_count + writable_count;
    if (total == 0) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
    if (num_free_ < static_cast<uint16_t>(total)) {
      return std::unexpected(Error{ErrorCode::kNoFreeDescriptors});
    }
 
    uint16_t head = free_head_;
    uint16_t prev_idx = 0xFFFF;
 
    for (size_t i = 0; i < readable_count; ++i) {
      uint16_t idx = free_head_;
      free_head_ = desc_[free_head_].next;
      --num_free_;
 
      desc_[idx].addr = readable[i].phys_addr;
      desc_[idx].len = static_cast<uint32_t>(readable[i].len);
      desc_[idx].flags = std::to_underlying(DescFlags::kDescFNext);
 
      if (prev_idx != 0xFFFF) {
        desc_[prev_idx].next = idx;
      }
      prev_idx = idx;
    }
 
    for (size_t i = 0; i < writable_count; ++i) {
      uint16_t idx = free_head_;
      free_head_ = desc_[free_head_].next;
      --num_free_;
 
      desc_[idx].addr = writable[i].phys_addr;
      desc_[idx].len = static_cast<uint32_t>(writable[i].len);
      desc_[idx].flags = std::to_underlying(DescFlags::kDescFNext) |
                         std::to_underlying(DescFlags::kDescFWrite);
      if (prev_idx != 0xFFFF) {
        desc_[prev_idx].next = idx;
      }
      prev_idx = idx;
    }
 
    desc_[prev_idx].flags =
        desc_[prev_idx].flags & ~std::to_underlying(DescFlags::kDescFNext);
 
    // 写屏障：确保描述符写入在 Available Ring 更新之前对设备可见
    cpu_io::Wmb();
 
    Submit(head);
 
    return head;
  }

Here is the call graph for this function:

◆ UsedAvailEvent() [1/2]

auto virtio::SplitVirtqueue::UsedAvailEvent ( ) -> volatile uint16_t*

inline

获取 Used Ring 的 avail_event 字段

Returns: avail_event 字段指针，未启用 EVENT_IDX 则返回 nullptr

See also: virtio-v1.2#2.7.10

Definition at line 612 of file split.hpp.

                                                            {
    return event_idx_enabled_ ? used_->avail_event(queue_size_) : nullptr;
  }

Here is the call graph for this function:

◆ UsedAvailEvent() [2/2]

auto virtio::SplitVirtqueue::UsedAvailEvent ( ) const -> const volatile uint16_t*

inline

Definition at line 616 of file split.hpp.

                                                                        {
    return event_idx_enabled_ ? used_->avail_event(queue_size_) : nullptr;
  }

Here is the call graph for this function:

◆ UsedPhys()

auto virtio::SplitVirtqueue::UsedPhys ( ) const -> uint64_t

inline

获取 Used Ring 的物理地址

See also: virtio-v1.2#2.7.8

Definition at line 578 of file split.hpp.

                                                  {
    return phys_base_ + used_offset_;
  }

Member Data Documentation

◆ avail_

volatile Avail* virtio::SplitVirtqueue::avail_ {nullptr}

private

Available Ring 指针（指向 DMA 内存）

Definition at line 670 of file split.hpp.

670{nullptr};

◆ avail_offset_

size_t virtio::SplitVirtqueue::avail_offset_ {0}

private

Available Ring 在 DMA 内存中的偏移量（字节）

Definition at line 688 of file split.hpp.

688{0};

◆ desc_

volatile Desc* virtio::SplitVirtqueue::desc_ {nullptr}

private

描述符表指针（指向 DMA 内存）

Definition at line 668 of file split.hpp.

668{nullptr};

◆ desc_offset_

size_t virtio::SplitVirtqueue::desc_offset_ {0}

private

描述符表在 DMA 内存中的偏移量（字节）

Definition at line 686 of file split.hpp.

686{0};

◆ event_idx_enabled_

bool virtio::SplitVirtqueue::event_idx_enabled_ {false}

private

是否启用 VIRTIO_F_EVENT_IDX 特性

Definition at line 692 of file split.hpp.

692{false};

◆ free_head_

uint16_t virtio::SplitVirtqueue::free_head_ {0}

private

空闲描述符链表头索引

Definition at line 677 of file split.hpp.

677{0};

◆ is_valid_

bool virtio::SplitVirtqueue::is_valid_ {false}

private

初始化是否成功

Definition at line 694 of file split.hpp.

694{false};

◆ last_used_idx_

uint16_t virtio::SplitVirtqueue::last_used_idx_ {0}

private

上次处理到的 Used Ring 索引（用于 PopUsed）

Definition at line 681 of file split.hpp.

681{0};

◆ num_free_

uint16_t virtio::SplitVirtqueue::num_free_ {0}

private

空闲描述符数量

Definition at line 679 of file split.hpp.

679{0};

◆ phys_base_

uint64_t virtio::SplitVirtqueue::phys_base_ {0}

private

DMA 内存物理基地址（客户机物理地址）

Definition at line 684 of file split.hpp.

684{0};

◆ queue_size_

uint16_t virtio::SplitVirtqueue::queue_size_ {0}

private

队列大小（描述符数量，必须为 2 的幂）

Definition at line 675 of file split.hpp.

675{0};

◆ used_

volatile Used* virtio::SplitVirtqueue::used_ {nullptr}

private

Used Ring 指针（指向 DMA 内存）

Definition at line 672 of file split.hpp.

672{nullptr};

◆ used_offset_

size_t virtio::SplitVirtqueue::used_offset_ {0}

private

Used Ring 在 DMA 内存中的偏移量（字节）

Definition at line 690 of file split.hpp.

690{0};

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

/workspaces/SimpleKernel/src/device/virtio/virt_queue/split.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ AvailFlags

◆ DescFlags

◆ UsedFlags

Constructor & Destructor Documentation

◆ SplitVirtqueue() [1/4]

◆ SplitVirtqueue() [2/4]

◆ SplitVirtqueue() [3/4]

◆ SplitVirtqueue() [4/4]

◆ ~SplitVirtqueue()

Member Function Documentation

◆ AllocDesc()

◆ AvailIdx()

◆ AvailPhys()

◆ AvailUsedEvent() [1/2]

◆ AvailUsedEvent() [2/2]

◆ CalcSize()

◆ DescPhys()

◆ EventIdxEnabled()

◆ FreeChain()

◆ FreeDesc()

◆ GetDesc() [1/2]

◆ GetDesc() [2/2]

◆ HasUsed()

◆ IsValid()

◆ LastUsedIdx()

◆ NumFree()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PopUsed()

◆ Size()

◆ Submit()

◆ SubmitChain()

◆ UsedAvailEvent() [1/2]

◆ UsedAvailEvent() [2/2]

◆ UsedPhys()

Member Data Documentation

◆ avail_

◆ avail_offset_

◆ desc_

◆ desc_offset_

◆ event_idx_enabled_

◆ free_head_

◆ is_valid_

◆ last_used_idx_

◆ num_free_

◆ phys_base_

◆ queue_size_

◆ used_

◆ used_offset_