virtio::blk::VirtioBlk< TransportT, VirtqueueT > Class Template Reference

Virtio 块设备驱动 More...

#include <virtio_blk.hpp>

Collaboration diagram for virtio::blk::VirtioBlk< TransportT, VirtqueueT >:

Classes
struct	RequestSlot
	异步请求上下文槽 More...

Public Types
using	UserData = void *
	异步 IO 回调中使用的用户自定义上下文指针类型

Public Member Functions
auto	EnqueueRead (uint16_t queue_index, uint64_t sector, const IoVec *buffers, size_t buffer_count, UserData token=nullptr) -> Expected< void >
	异步提交读请求（仅入队描述符，不触发硬件通知）
auto	EnqueueWrite (uint16_t queue_index, uint64_t sector, const IoVec *buffers, size_t buffer_count, UserData token=nullptr) -> Expected< void >
	异步提交写请求（仅入队描述符，不触发硬件通知）
auto	Kick (uint16_t queue_index) -> void
	批量触发硬件通知
template<typename CompletionCallback >
auto	HandleInterrupt (CompletionCallback &&on_complete) -> void
	中断处理（带完成回调）
auto	HandleInterrupt () -> void
	中断处理（简化版，无回调）
auto	Read (uint64_t sector, uint8_t *data) -> Expected< void >
	同步读取一个扇区
auto	Write (uint64_t sector, const uint8_t *data) -> Expected< void >
	同步写入一个扇区
auto	ReadConfig () const -> BlkConfig
	读取块设备配置空间
auto	GetCapacity () const -> uint64_t
	获取设备容量
auto	GetNegotiatedFeatures () const -> uint64_t
	获取协商后的特性位
auto	GetStats () const -> VirtioStats
	获取性能监控统计数据
构造/析构函数
	VirtioBlk ()=delete
	VirtioBlk (VirtioBlk &&other) noexcept
auto	operator= (VirtioBlk &&other) noexcept -> VirtioBlk &
	VirtioBlk (const VirtioBlk &)=delete
auto	operator= (const VirtioBlk &) -> VirtioBlk &=delete
	~VirtioBlk ()=default

Static Public Member Functions
static constexpr auto	GetRequiredVqMemSize (uint16_t queue_count, uint32_t queue_size) -> std::pair< size_t, size_t >
	获取多队列所需的总 DMA 内存大小
static constexpr auto	CalcDmaSize (uint16_t queue_size=128) -> size_t
	计算单个 Virtqueue DMA 缓冲区所需的字节数（向后兼容）
static constexpr auto	GetRequiredSlotMemSize () -> std::pair< size_t, size_t >
	计算 RequestSlot DMA 内存所需字节数
static auto	Create (uint64_t mmio_base, const DmaRegion &vq_dma, const DmaRegion &slot_dma, VirtToPhysFunc virt_to_phys=IdentityVirtToPhys, uint16_t queue_count=1, uint32_t queue_size=128, uint64_t driver_features=0) -> Expected< VirtioBlk >
	创建并初始化块设备

Static Public Attributes
static constexpr uint16_t	kMaxInflight = 64
	每个设备的最大并发(in-flight)请求数
static constexpr size_t	kMaxSgElements = 18
	每个 Scatter-Gather 请求的最大 IoVec 数量（含请求头和状态字节）

Private Member Functions
	VirtioBlk (TransportT transport, VirtqueueT vq, uint64_t features, const DmaRegion &slot_dma, VirtToPhysFunc v2p)
	私有构造函数
auto	DoEnqueue (ReqType type, uint16_t queue_index, uint64_t sector, const IoVec *buffers, size_t buffer_count, UserData token) -> Expected< void >
	异步入队请求的内部实现
template<typename CompletionCallback >
auto	ProcessCompletions (CompletionCallback &&on_complete) -> void
	处理 Used Ring 中已完成的请求
auto	AllocRequestSlot () -> Expected< uint16_t >
	从请求槽池中分配一个空闲槽（O(1) 位图算法）
auto	FreeRequestSlot (uint16_t idx) -> void
	释放请求槽
auto	FindSlotByDescHead (uint16_t desc_head) const -> uint16_t
	根据描述符链头索引查找请求槽
auto	UpdateUsedEvent () -> void
	更新 avail->used_event 字段
auto	SubmitSyncRequest (ReqType type, uint64_t sector, const IoVec *buffers, size_t buffer_count) -> Expected< void >
	同步提交请求的内部实现

Static Private Member Functions
static auto	MapBlkStatus (uint8_t status) -> ErrorCode
	将设备 BlkStatus 映射为 ErrorCode
static auto	VringNeedEvent (uint16_t event_idx, uint16_t new_idx, uint16_t old_idx) -> bool
	判断是否需要发送通知（处理 wrap-around）

Private Attributes
TransportT	transport_
	传输层实例
VirtqueueT	vq_
	Virtqueue 实例（当前支持单队列）
uint64_t	negotiated_features_ {0}
	协商后的特性位掩码
DmaRegion	slot_dma_ {}
	DMA region backing the request slot pool.
RequestSlot *	slots_ {nullptr}
	Pointer to request slot array (lives in slot_dma_ memory)
VirtToPhysFunc	virt_to_phys_ {IdentityVirtToPhys}
	Address translation callback.
VirtioStats	stats_
	性能统计数据
uint64_t	slot_bitmap_ {}
	请求槽占用位图（bit i = 1 表示 slots_[i] 被占用）
uint16_t	old_avail_idx_ {0}
	上次 Kick 时的 avail idx（用于 Event Index 通知抑制）
volatile bool	request_completed_ {false}
	请求完成标志（由简化版 HandleInterrupt 在中断上下文中设置）

Detailed Description

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>
class virtio::blk::VirtioBlk< TransportT, VirtqueueT >

Virtio 块设备驱动

virtio 块设备是一个简单的虚拟块设备（即磁盘）。 读写请求（以及其他特殊请求）被放置在请求队列中，由设备服务（可能乱序）。

该类封装了 VirtIO 块设备的完整生命周期：

• 传输层的创建和管理（通过 TransportT 模板参数泛化）
• Virtqueue 的创建和管理（通过 VirtqueueT 模板参数泛化）
• 设备初始化序列（特性协商、队列配置、设备激活）
• 异步 IO 接口（Enqueue/Kick/HandleInterrupt 回调模型）
• 同步读写便捷方法（基于异步接口实现）

用户只需提供 MMIO 基地址和 DMA 缓冲区， 即可通过 Read() / Write() 或异步接口进行块设备操作。

Template Parameters

TransportT	传输层类型（默认 MmioTransport）
VirtqueueT	Virtqueue 类型（默认 SplitVirtqueue）
VirtqueueT	Virtqueue 模板（默认 SplitVirtqueue）

See also

virtio-v1.2#5.2 Block Device

架构文档 §3

Definition at line 50 of file virtio_blk.hpp.

Member Typedef Documentation

UserData

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

using virtio::blk::VirtioBlk< TransportT, VirtqueueT >::UserData = void*

异步 IO 回调中使用的用户自定义上下文指针类型

Definition at line 53 of file virtio_blk.hpp.

Constructor & Destructor Documentation

VirtioBlk() [1/4]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

virtio::blk::VirtioBlk< TransportT, VirtqueueT >::VirtioBlk ( )

delete

Here is the caller graph for this function:

VirtioBlk() [2/4]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

virtio::blk::VirtioBlk< TransportT, VirtqueueT >::VirtioBlk ( VirtioBlk< TransportT, VirtqueueT > &&  other )

inlinenoexcept

Definition at line 479 of file virtio_blk.hpp.

      : transport_(std::move(other.transport_)),
        vq_(std::move(other.vq_)),
        negotiated_features_(other.negotiated_features_),
        slot_dma_(other.slot_dma_),
        slots_(other.slots_),
        virt_to_phys_(other.virt_to_phys_),
        stats_(other.stats_),
        slot_bitmap_(other.slot_bitmap_),
        old_avail_idx_(other.old_avail_idx_),
        request_completed_(other.request_completed_) {
    other.slots_ = nullptr;
    other.slot_bitmap_ = 0;
  }

VirtioBlk() [3/4]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

virtio::blk::VirtioBlk< TransportT, VirtqueueT >::VirtioBlk ( const VirtioBlk< TransportT, VirtqueueT > &  )

delete

~VirtioBlk()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

virtio::blk::VirtioBlk< TransportT, VirtqueueT >::~VirtioBlk ( )

default

VirtioBlk() [4/4]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

virtio::blk::VirtioBlk< TransportT, VirtqueueT >::VirtioBlk ( TransportT  transport, VirtqueueT  vq, uint64_t  features, const DmaRegion &  slot_dma, VirtToPhysFunc  v2p  )

inlineprivate

私有构造函数

只能通过 Create() 静态工厂方法创建实例。

Definition at line 539 of file virtio_blk.hpp.

      : transport_(std::move(transport)),
        vq_(std::move(vq)),
        negotiated_features_(features),
        slot_dma_(slot_dma),
        slots_(reinterpret_cast<RequestSlot*>(slot_dma.Data())),
        virt_to_phys_(v2p),
        stats_{},
        slot_bitmap_(0),
        old_avail_idx_(0),
        request_completed_(false) {}

Member Function Documentation

AllocRequestSlot()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::AllocRequestSlot ( ) -> Expected<uint16_t>

inlineprivate

从请求槽池中分配一个空闲槽（O(1) 位图算法）

使用 __builtin_ctzll 找到 slot_bitmap_ 中最低的 0 位。

Returns

成功返回槽索引，失败返回错误

Definition at line 679 of file virtio_blk.hpp.

                                                              {
    uint64_t free_bits = ~slot_bitmap_;
    if (free_bits == 0) {
      return std::unexpected(Error{ErrorCode::kNoFreeDescriptors});
    }
    auto idx = static_cast<uint16_t>(__builtin_ctzll(free_bits));
    if (idx >= kMaxInflight) {
      return std::unexpected(Error{ErrorCode::kNoFreeDescriptors});
    }
    slot_bitmap_ |= (uint64_t{1} << idx);
    return idx;
  }

Here is the caller graph for this function:

CalcDmaSize()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

static constexpr auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::CalcDmaSize ( uint16_t  queue_size = 128 ) -> size_t

inlinestaticconstexpr

计算单个 Virtqueue DMA 缓冲区所需的字节数（向后兼容）

Parameters

queue_size

队列大小（2 的幂，默认 128）

Returns

所需的 DMA 内存字节数

Definition at line 86 of file virtio_blk.hpp.

                {
    // 始终按 event_idx=true 分配，确保空间充足
    return VirtqueueT::CalcSize(queue_size, true);
  }

Create()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

static auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::Create ( uint64_t  mmio_base, const DmaRegion &  vq_dma, const DmaRegion &  slot_dma, VirtToPhysFunc  virt_to_phys = IdentityVirtToPhys, uint16_t  queue_count = 1, uint32_t  queue_size = 128, uint64_t  driver_features = 0  ) -> Expected<VirtioBlk>

inlinestatic

创建并初始化块设备

内部自动完成：

1. Transport 初始化和验证
2. Virtqueue 创建
3. VirtIO 设备初始化序列（重置、特性协商、队列配置、设备激活）

Parameters

mmio_base	MMIO 设备基地址
vq_dma	预分配的 Virtqueue DMA 内存区域 （页对齐，已清零，大小 >= GetRequiredVqMemSize()）
slot_dma	预分配的 RequestSlot DMA 内存区域 （大小 >= GetRequiredSlotMemSize()）
virt_to_phys	虚拟地址到物理地址转换函数（默认恒等映射）
queue_count	期望的队列数量（当前仅支持 1）
queue_size	每个队列的描述符数量（2 的幂，默认 128）
driver_features	额外的驱动特性位（VERSION_1 自动包含）

Returns

成功返回 VirtioBlk 实例，失败返回错误

See also

virtio-v1.2#3.1.1 Driver Requirements: Device Initialization

Definition at line 122 of file virtio_blk.hpp.

                                                           {
    if (queue_count == 0) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
    if (queue_count > 1) {
    }
 
    // 1. 创建传输层
    TransportT transport(mmio_base);
    if (!transport.IsValid()) {
      return std::unexpected(Error{ErrorCode::kTransportNotInitialized});
    }
 
    // 2. 设备初始化序列
    DeviceInitializer<TransportT> initializer(transport);
 
    uint64_t wanted_features =
        static_cast<uint64_t>(ReservedFeature::kVersion1) |
        static_cast<uint64_t>(ReservedFeature::kEventIdx) | driver_features;
    auto negotiated_result = initializer.Init(wanted_features);
    if (!negotiated_result) {
      return std::unexpected(negotiated_result.error());
    }
    uint64_t negotiated = *negotiated_result;
 
    if ((negotiated & static_cast<uint64_t>(ReservedFeature::kVersion1)) == 0) {
      return std::unexpected(Error{ErrorCode::kFeatureNegotiationFailed});
    }
 
    // 根据协商结果决定是否启用 Event Index
    bool event_idx =
        (negotiated & static_cast<uint64_t>(ReservedFeature::kEventIdx)) != 0;
    if (event_idx) {
    }
    // 3. 创建 Virtqueue
    VirtqueueT vq(vq_dma, static_cast<uint16_t>(queue_size), event_idx);
    if (!vq.IsValid()) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
 
    // 4. 配置队列
    const uint32_t queue_idx = 0;
    auto setup_result = initializer.SetupQueue(
        queue_idx, vq.DescPhys(), vq.AvailPhys(), vq.UsedPhys(), vq.Size());
    if (!setup_result) {
      return std::unexpected(setup_result.error());
    }
 
    // 5. 激活设备
    auto activate_result = initializer.Activate();
    if (!activate_result) {
      return std::unexpected(activate_result.error());
    }
 
    return VirtioBlk(std::move(transport), std::move(vq), negotiated, slot_dma,
                     virt_to_phys);
  }

Here is the call graph for this function:

Here is the caller graph for this function:

DoEnqueue()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::DoEnqueue ( ReqType  type, uint16_t  queue_index, uint64_t  sector, const IoVec *  buffers, size_t  buffer_count, UserData  token  ) -> Expected<void>

inlineprivate

异步入队请求的内部实现

分配请求槽，填充请求头，构建 Scatter-Gather 描述符链，提交到 Available Ring。

Parameters

type	请求类型（kIn/kOut）
queue_index	队列索引
sector	起始扇区号
buffers	数据缓冲区 IoVec 数组
buffer_count	缓冲区数量
token	用户上下文指针

Returns

成功或失败

Definition at line 566 of file virtio_blk.hpp.

                        {
    if (queue_index != 0) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
 
    if (buffer_count + 2 > kMaxSgElements) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
 
    auto slot_result = AllocRequestSlot();
    if (!slot_result) {
      stats_.queue_full_errors++;
      return std::unexpected(slot_result.error());
    }
    uint16_t slot_idx = *slot_result;
    auto& slot = slots_[slot_idx];
 
    slot.header.type = static_cast<uint32_t>(type);
    slot.header.reserved = 0;
    slot.header.sector = sector;
    slot.status = 0xFF;  // sentinel：设备完成后会覆写
    slot.token = token;
 
    std::array<IoVec, kMaxSgElements> readable_iovs{};
    std::array<IoVec, kMaxSgElements> writable_iovs{};
    size_t readable_count = 0;
    size_t writable_count = 0;
 
    auto slot_base_phys =
        slot_dma_.phys + static_cast<size_t>(slot_idx) * sizeof(RequestSlot);
    readable_iovs[readable_count++] = {
        slot_base_phys + offsetof(RequestSlot, header), sizeof(BlkReqHeader)};
 
    if (type == ReqType::kIn) {
      for (size_t i = 0; i < buffer_count; ++i) {
        writable_iovs[writable_count++] = buffers[i];
      }
    } else {
      for (size_t i = 0; i < buffer_count; ++i) {
        readable_iovs[readable_count++] = buffers[i];
      }
    }
 
    // 状态字节始终为 device-writable
    writable_iovs[writable_count++] = {
        slot_base_phys + offsetof(RequestSlot, status), sizeof(uint8_t)};
 
    cpu_io::Wmb();
 
    auto chain_result = vq_.SubmitChain(readable_iovs.data(), readable_count,
                                        writable_iovs.data(), writable_count);
    if (!chain_result) {
      FreeRequestSlot(slot_idx);
      stats_.queue_full_errors++;
      return std::unexpected(chain_result.error());
    }
 
    slot.desc_head = *chain_result;
 
    return {};
  }

Here is the call graph for this function:

Here is the caller graph for this function:

EnqueueRead()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::EnqueueRead ( uint16_t  queue_index, uint64_t  sector, const IoVec *  buffers, size_t  buffer_count, UserData  token = nullptr  ) -> Expected<void>

inline

异步提交读请求（仅入队描述符，不触发硬件通知）

构建 virtio-blk 请求描述符链（header + data buffers + status）， 提交到 Available Ring，但不通知设备。调用者需随后调用 Kick() 通知。

Parameters

queue_index	队列索引（当前仅支持 0）
sector	起始扇区号（以 512 字节为单位）
buffers	数据缓冲区 IoVec 数组（物理地址 + 长度）
buffer_count	buffers 数组中的元素数量
token	用户自定义上下文指针，在 HandleInterrupt 回调时原样传回

Returns

成功或失败

See also

virtio-v1.2#5.2.6 Device Operation

Definition at line 200 of file virtio_blk.hpp.

                                                                             {
    return DoEnqueue(ReqType::kIn, queue_index, sector, buffers, buffer_count,
                     token);
  }

Here is the call graph for this function:

EnqueueWrite()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::EnqueueWrite ( uint16_t  queue_index, uint64_t  sector, const IoVec *  buffers, size_t  buffer_count, UserData  token = nullptr  ) -> Expected<void>

inline

异步提交写请求（仅入队描述符，不触发硬件通知）

构建 virtio-blk 请求描述符链（header + data buffers + status）， 提交到 Available Ring，但不通知设备。调用者需随后调用 Kick() 通知。

针对 Write 操作，数据缓冲区的描述符 flag 为设备只读（无 VRING_DESC_F_WRITE）。

Parameters

queue_index	队列索引（当前仅支持 0）
sector	起始扇区号（以 512 字节为单位）
buffers	数据缓冲区 IoVec 数组（物理地址 + 长度）
buffer_count	buffers 数组中的元素数量
token	用户自定义上下文指针，在 HandleInterrupt 回调时原样传回

Returns

成功或失败

See also

virtio-v1.2#5.2.6 Device Operation

Definition at line 224 of file virtio_blk.hpp.

                                                                              {
    return DoEnqueue(ReqType::kOut, queue_index, sector, buffers, buffer_count,
                     token);
  }

Here is the call graph for this function:

FindSlotByDescHead()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::FindSlotByDescHead ( uint16_t  desc_head ) const -> uint16_t

inlineprivate

根据描述符链头索引查找请求槽

Parameters

desc_head

描述符链头索引

Returns

匹配的槽索引，未找到则返回 kMaxInflight

Definition at line 709 of file virtio_blk.hpp.

                                                                              {
    uint64_t used = slot_bitmap_;
    while (used != 0) {
      auto i = static_cast<uint16_t>(__builtin_ctzll(used));
      if (slots_[i].desc_head == desc_head) {
        return i;
      }
      used &= used - 1;  // clear lowest set bit
    }
    return kMaxInflight;
  }

Here is the caller graph for this function:

FreeRequestSlot()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::FreeRequestSlot ( uint16_t  idx ) -> void

inlineprivate

释放请求槽

Parameters

idx

槽索引

Definition at line 697 of file virtio_blk.hpp.

                                             {
    if (idx < kMaxInflight) {
      slot_bitmap_ &= ~(uint64_t{1} << idx);
    }
  }

Here is the caller graph for this function:

GetCapacity()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::GetCapacity ( ) const -> uint64_t

inline

获取设备容量

Returns

设备容量（以 512 字节扇区为单位）

See also

virtio-v1.2#5.2.4

Definition at line 454 of file virtio_blk.hpp.

                                                     {
    return transport_.ReadConfigU64(
        static_cast<uint32_t>(BlkConfigOffset::kCapacity));
  }

Here is the caller graph for this function:

GetNegotiatedFeatures()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::GetNegotiatedFeatures ( ) const -> uint64_t

inline

获取协商后的特性位

Returns

设备和驱动程序都支持的特性位掩码

Definition at line 464 of file virtio_blk.hpp.

                                                               {
    return negotiated_features_;
  }

GetRequiredSlotMemSize()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

static constexpr auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::GetRequiredSlotMemSize ( ) -> std::pair<size_t, size_t>

inlinestaticconstexpr

计算 RequestSlot DMA 内存所需字节数

Returns

pair.first = 总字节数，pair.second = 对齐要求（字节）

Definition at line 97 of file virtio_blk.hpp.

                                 {
    return {sizeof(RequestSlot) * kMaxInflight, alignof(RequestSlot)};
  }

Here is the caller graph for this function:

GetRequiredVqMemSize()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

static constexpr auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::GetRequiredVqMemSize ( uint16_t  queue_count, uint32_t  queue_size  ) -> std::pair<size_t, size_t>

inlinestaticconstexpr

获取多队列所需的总 DMA 内存大小

调用者应根据此值预分配页对齐、已清零的 DMA 内存。

Parameters

queue_count	请求的队列数量
queue_size	每个队列的描述符数量（必须为 2 的幂）

Returns

pair.first = 总字节数，pair.second = 对齐要求（字节）

See also

架构文档 §3

Definition at line 71 of file virtio_blk.hpp.

                                 {
    // 始终按 event_idx=true 分配，因为特性协商在分配之后
    size_t per_queue =
        VirtqueueT::CalcSize(static_cast<uint16_t>(queue_size), true);
    return {per_queue * queue_count, 4096};
  }

GetStats()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::GetStats ( ) const -> VirtioStats

inline

获取性能监控统计数据

Returns

当前统计数据的快照

See also

架构文档 §3

Definition at line 474 of file virtio_blk.hpp.

{ return stats_; }

HandleInterrupt() [1/2]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::HandleInterrupt ( ) -> void

inline

中断处理（简化版，无回调）

仅确认设备中断并设置完成标志，供同步轮询使用。 不处理 Used Ring 和描述符回收。

Note

此方法可在中断上下文中安全调用（ISR-safe）

See also

virtio-v1.2#2.3 Notifications

Definition at line 300 of file virtio_blk.hpp.

                                 {
    uint32_t status = transport_.GetInterruptStatus();
    if (status != 0) {
      transport_.AckInterrupt(status);
    }
    stats_.interrupts_handled++;
    request_completed_ = true;
    cpu_io::Wmb();
  }

Here is the call graph for this function:

HandleInterrupt() [2/2]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

template<typename CompletionCallback >

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::HandleInterrupt ( CompletionCallback &&  on_complete ) -> void

inline

中断处理（带完成回调）

在 ISR 或轮询循环中调用。确认设备中断，遍历 Used Ring 中已完成的请求， 对每个请求调用 on_complete 回调，释放描述符链和请求槽。

Template Parameters

CompletionCallback

签名要求：void(UserData token, ErrorCode status) token: 提交时传入的用户上下文指针 status: 设备返回的完成状态映射为 ErrorCode

Parameters

on_complete

完成回调函数

See also

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

Definition at line 279 of file virtio_blk.hpp.

                                                                 {
    // 确认中断
    uint32_t isr_status = transport_.GetInterruptStatus();
    if (isr_status != 0) {
      transport_.AckInterrupt(isr_status);
    }
    stats_.interrupts_handled++;
 
    ProcessCompletions(static_cast<CompletionCallback&&>(on_complete));
    UpdateUsedEvent();
  }

Here is the call graph for this function:

Kick()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::Kick ( uint16_t  queue_index ) -> void

inline

批量触发硬件通知

通知设备 Available Ring 中有新的待处理请求。 调用者应在 EnqueueRead/EnqueueWrite 后调用此方法。

Parameters

queue_index

队列索引（当前仅支持 0）

See also

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

Definition at line 240 of file virtio_blk.hpp.

                                          {
    if (queue_index != 0) {
      return;
    }
    // 写屏障：确保 Available Ring 更新对设备可见
    cpu_io::Wmb();
 
    if (vq_.EventIdxEnabled()) {
      auto* avail_event_ptr = vq_.UsedAvailEvent();
      if (avail_event_ptr != nullptr) {
        uint16_t avail_event = *avail_event_ptr;
        uint16_t new_idx = vq_.AvailIdx();
        if (VringNeedEvent(avail_event, new_idx, old_avail_idx_)) {
          transport_.NotifyQueue(queue_index);
        } else {
          stats_.kicks_elided++;
        }
        old_avail_idx_ = new_idx;
      } else {
        transport_.NotifyQueue(queue_index);
      }
    } else {
      transport_.NotifyQueue(queue_index);
    }
  }

Here is the call graph for this function:

Here is the caller graph for this function:

MapBlkStatus()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

static auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::MapBlkStatus ( uint8_t  status ) -> ErrorCode

inlinestaticprivate

将设备 BlkStatus 映射为 ErrorCode

Parameters

status

设备返回的原始状态字节

Returns

对应的 ErrorCode

Definition at line 727 of file virtio_blk.hpp.

                                                                      {
    switch (status) {
      case static_cast<uint8_t>(BlkStatus::kOk):
        return ErrorCode::kSuccess;
      case static_cast<uint8_t>(BlkStatus::kIoErr):
        return ErrorCode::kIoError;
      case static_cast<uint8_t>(BlkStatus::kUnsupp):
        return ErrorCode::kNotSupported;
      default:
        return ErrorCode::kDeviceError;
    }
  }

Here is the caller graph for this function:

operator=() [1/2]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::operator= ( const VirtioBlk< TransportT, VirtqueueT > &  ) -> VirtioBlk &=delete

delete

operator=() [2/2]

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::operator= ( VirtioBlk< TransportT, VirtqueueT > &&  other ) -> VirtioBlk&

inlinenoexcept

Definition at line 493 of file virtio_blk.hpp.

                                                           {
    if (this != &other) {
      transport_ = std::move(other.transport_);
      vq_ = std::move(other.vq_);
      negotiated_features_ = other.negotiated_features_;
      slot_dma_ = other.slot_dma_;
      slots_ = other.slots_;
      virt_to_phys_ = other.virt_to_phys_;
      stats_ = other.stats_;
      slot_bitmap_ = other.slot_bitmap_;
      old_avail_idx_ = other.old_avail_idx_;
      request_completed_ = other.request_completed_;
      other.slots_ = nullptr;
      other.slot_bitmap_ = 0;
    }
    return *this;
  }

ProcessCompletions()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

template<typename CompletionCallback >

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::ProcessCompletions ( CompletionCallback &&  on_complete ) -> void

inlineprivate

处理 Used Ring 中已完成的请求

遍历 Used Ring，对每个已完成的请求：

1. 查找对应的请求槽
2. 读取设备返回的状态字节
3. 调用回调函数
4. 释放描述符链和请求槽

Template Parameters

CompletionCallback

void(UserData token, ErrorCode status)

Parameters

on_complete

完成回调

Definition at line 644 of file virtio_blk.hpp.

                                                                    {
    cpu_io::Rmb();
 
    while (vq_.HasUsed()) {
      auto elem_result = vq_.PopUsed();
      if (!elem_result) {
        break;
      }
 
      auto elem = *elem_result;
      auto head = static_cast<uint16_t>(elem.id);
 
      uint16_t slot_idx = FindSlotByDescHead(head);
      if (slot_idx < kMaxInflight) {
        auto& slot = slots_[slot_idx];
 
        cpu_io::Rmb();
 
        ErrorCode ec = MapBlkStatus(slot.status);
        on_complete(slot.token, ec);
        stats_.bytes_transferred += elem.len;
        FreeRequestSlot(slot_idx);
      }
 
      (void)vq_.FreeChain(head);
    }
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Read()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::Read ( uint64_t  sector, uint8_t *  data  ) -> Expected<void>

inline

同步读取一个扇区

基于异步接口实现：EnqueueRead → Kick → 轮询 HandleInterrupt → 返回。

Parameters

sector	起始扇区号（以 512 字节为单位）
data	数据缓冲区（至少 kSectorSize 字节，必须位于 DMA 可访问内存）

Returns

成功或失败

Note

缓冲区在函数返回前不得释放或修改

See also

virtio-v1.2#5.2.6 Device Operation

Definition at line 323 of file virtio_blk.hpp.

                                                                            {
    if (data == nullptr) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
    IoVec data_iov{virt_to_phys_(reinterpret_cast<uintptr_t>(data)),
                   kSectorSize};
    return SubmitSyncRequest(ReqType::kIn, sector, &data_iov, 1);
  }

Here is the call graph for this function:

Here is the caller graph for this function:

ReadConfig()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::ReadConfig ( ) const -> BlkConfig

inline

读取块设备配置空间

读取设备的配置信息，包括容量、几何信息、拓扑信息等。 配置空间的可用字段取决于协商的特性位。

Returns

块设备配置结构

See also

virtio-v1.2#5.2.4 Device configuration layout

Definition at line 365 of file virtio_blk.hpp.

                                                     {
    BlkConfig config{};
 
    config.capacity = transport_.ReadConfigU64(
        static_cast<uint32_t>(BlkConfigOffset::kCapacity));
    config.size_max = transport_.ReadConfigU32(
        static_cast<uint32_t>(BlkConfigOffset::kSizeMax));
    config.seg_max = transport_.ReadConfigU32(
        static_cast<uint32_t>(BlkConfigOffset::kSegMax));
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kGeometry)) != 0) {
      config.geometry.cylinders = transport_.ReadConfigU16(
          static_cast<uint32_t>(BlkConfigOffset::kGeometryCylinders));
      config.geometry.heads = transport_.ReadConfigU8(
          static_cast<uint32_t>(BlkConfigOffset::kGeometryHeads));
      config.geometry.sectors = transport_.ReadConfigU8(
          static_cast<uint32_t>(BlkConfigOffset::kGeometrySectors));
    }
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kBlkSize)) != 0) {
      config.blk_size = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kBlkSize));
    }
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kTopology)) != 0) {
      config.topology.physical_block_exp = transport_.ReadConfigU8(
          static_cast<uint32_t>(BlkConfigOffset::kTopologyPhysBlockExp));
      config.topology.alignment_offset = transport_.ReadConfigU8(
          static_cast<uint32_t>(BlkConfigOffset::kTopologyAlignOffset));
      config.topology.min_io_size = transport_.ReadConfigU16(
          static_cast<uint32_t>(BlkConfigOffset::kTopologyMinIoSize));
      config.topology.opt_io_size = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kTopologyOptIoSize));
    }
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kConfigWce)) != 0) {
      config.writeback = transport_.ReadConfigU8(
          static_cast<uint32_t>(BlkConfigOffset::kWriteback));
    }
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kDiscard)) != 0) {
      config.max_discard_sectors = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kMaxDiscardSectors));
      config.max_discard_seg = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kMaxDiscardSeg));
      config.discard_sector_alignment = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kDiscardSectorAlignment));
    }
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kWriteZeroes)) != 0) {
      config.max_write_zeroes_sectors = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kMaxWriteZeroesSectors));
      config.max_write_zeroes_seg = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kMaxWriteZeroesSeg));
      config.write_zeroes_may_unmap = transport_.ReadConfigU8(
          static_cast<uint32_t>(BlkConfigOffset::kWriteZeroesMayUnmap));
    }
 
    if ((negotiated_features_ &
         static_cast<uint64_t>(BlkFeatureBit::kSecureErase)) != 0) {
      config.max_secure_erase_sectors = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kMaxSecureEraseSectors));
      config.max_secure_erase_seg = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kMaxSecureEraseSeg));
      config.secure_erase_sector_alignment = transport_.ReadConfigU32(
          static_cast<uint32_t>(BlkConfigOffset::kSecureEraseSectorAlignment));
    }
 
    if ((negotiated_features_ & static_cast<uint64_t>(BlkFeatureBit::kMq)) !=
        0) {
      config.num_queues = transport_.ReadConfigU16(
          static_cast<uint32_t>(BlkConfigOffset::kNumQueues));
    }
 
    return config;
  }

SubmitSyncRequest()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::SubmitSyncRequest ( ReqType  type, uint64_t  sector, const IoVec *  buffers, size_t  buffer_count  ) -> Expected<void>

inlineprivate

同步提交请求的内部实现

Read()/Write() 的共享实现：入队 → Kick → 轮询等待 → 处理完成 → 返回。 轮询上限固定为 100000000 次迭代。

Parameters

type	请求类型（kIn/kOut）
sector	起始扇区号
buffers	数据缓冲区 IoVec 数组
buffer_count	缓冲区数量

Returns

成功或失败

Definition at line 788 of file virtio_blk.hpp.

                                                                              {
    auto enq = DoEnqueue(type, 0, sector, buffers, buffer_count, nullptr);
    if (!enq) {
      return std::unexpected(enq.error());
    }
 
    Kick(0);
 
    uint32_t spin_limit = 100000000U;
 
    for (uint32_t i = 0; i < spin_limit; ++i) {
      cpu_io::Rmb();
      if (vq_.HasUsed()) {
        break;
      }
    }
 
    if (!vq_.HasUsed()) {
      klog::Warn("Sync request timeout: sector={}", sector);
      return std::unexpected(Error{ErrorCode::kTimeout});
    }
 
    ErrorCode result = ErrorCode::kSuccess;
    bool done = false;
    ProcessCompletions([&done, &result](UserData, ErrorCode status) {
      done = true;
      result = status;
    });
    UpdateUsedEvent();
 
    if (!done) {
      return std::unexpected(Error{ErrorCode::kTimeout});
    }
    if (result != ErrorCode::kSuccess) {
      return std::unexpected(Error{result});
    }
    return {};
  }

Here is the call graph for this function:

Here is the caller graph for this function:

UpdateUsedEvent()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::UpdateUsedEvent ( ) -> void

inlineprivate

更新 avail->used_event 字段

在处理完 Used Ring 后调用，告知设备下次在此索引之后再发送中断。 仅在协商了 VIRTIO_F_EVENT_IDX 时生效。

See also

virtio-v1.2#2.7.10 Available Buffer Notification Suppression

Definition at line 766 of file virtio_blk.hpp.

                                 {
    if (vq_.EventIdxEnabled()) {
      auto* used_event_ptr = vq_.AvailUsedEvent();
      if (used_event_ptr != nullptr) {
        *used_event_ptr = vq_.LastUsedIdx();
        cpu_io::Wmb();
      }
    }
  }

Here is the call graph for this function:

Here is the caller graph for this function:

VringNeedEvent()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

static auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::VringNeedEvent ( uint16_t  event_idx, uint16_t  new_idx, uint16_t  old_idx  ) -> bool

inlinestaticprivate

判断是否需要发送通知（处理 wrap-around）

基于 virtio 规范中的 vring_need_event 算法：检查 event_idx 是否落在 (old, new] 区间内（含 uint16_t 回绕处理）。

Parameters

event_idx	设备/驱动期望的通知阈值
new_idx	当前索引
old_idx	上次通知时的索引

Returns

true 表示需要发送通知

See also

virtio-v1.2#2.7.10 Available Buffer Notification Suppression

Definition at line 752 of file virtio_blk.hpp.

                                                                     {
    return static_cast<uint16_t>(new_idx - event_idx - 1) <
           static_cast<uint16_t>(new_idx - old_idx);
  }

Here is the caller graph for this function:

Write()

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

auto virtio::blk::VirtioBlk< TransportT, VirtqueueT >::Write ( uint64_t  sector, const uint8_t *  data  ) -> Expected<void>

inline

同步写入一个扇区

基于异步接口实现：EnqueueWrite → Kick → 轮询 HandleInterrupt → 返回。

Parameters

sector	起始扇区号（以 512 字节为单位）
data	数据缓冲区（至少 kSectorSize 字节，必须位于 DMA 可访问内存）

Returns

成功或失败

Note

如果设备协商了 VIRTIO_BLK_F_RO，写请求将返回错误

See also

virtio-v1.2#5.2.6 Device Operation

Definition at line 343 of file virtio_blk.hpp.

                        {
    if (data == nullptr) {
      return std::unexpected(Error{ErrorCode::kInvalidArgument});
    }
    IoVec data_iov{
        virt_to_phys_(reinterpret_cast<uintptr_t>(const_cast<uint8_t*>(data))),
        kSectorSize};
    return SubmitSyncRequest(ReqType::kOut, sector, &data_iov, 1);
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

kMaxInflight

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

constexpr uint16_t virtio::blk::VirtioBlk< TransportT, VirtqueueT >::kMaxInflight = 64

staticconstexpr

每个设备的最大并发(in-flight)请求数

Definition at line 56 of file virtio_blk.hpp.

kMaxSgElements

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

constexpr size_t virtio::blk::VirtioBlk< TransportT, VirtqueueT >::kMaxSgElements = 18

staticconstexpr

每个 Scatter-Gather 请求的最大 IoVec 数量（含请求头和状态字节）

Definition at line 59 of file virtio_blk.hpp.

negotiated_features_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

uint64_t virtio::blk::VirtioBlk< TransportT, VirtqueueT >::negotiated_features_ {0}

private

协商后的特性位掩码

Definition at line 833 of file virtio_blk.hpp.

{0};

old_avail_idx_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

uint16_t virtio::blk::VirtioBlk< TransportT, VirtqueueT >::old_avail_idx_ {0}

private

上次 Kick 时的 avail idx（用于 Event Index 通知抑制）

Definition at line 845 of file virtio_blk.hpp.

{0};

request_completed_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

volatile bool virtio::blk::VirtioBlk< TransportT, VirtqueueT >::request_completed_ {false}

private

请求完成标志（由简化版 HandleInterrupt 在中断上下文中设置）

Definition at line 847 of file virtio_blk.hpp.

{false};

slot_bitmap_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

uint64_t virtio::blk::VirtioBlk< TransportT, VirtqueueT >::slot_bitmap_ {}

private

请求槽占用位图（bit i = 1 表示 slots_[i] 被占用）

Definition at line 843 of file virtio_blk.hpp.

{};

slot_dma_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

DmaRegion virtio::blk::VirtioBlk< TransportT, VirtqueueT >::slot_dma_ {}

private

DMA region backing the request slot pool.

Definition at line 835 of file virtio_blk.hpp.

{};

slots_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

RequestSlot* virtio::blk::VirtioBlk< TransportT, VirtqueueT >::slots_ {nullptr}

private

Pointer to request slot array (lives in slot_dma_ memory)

Definition at line 837 of file virtio_blk.hpp.

{nullptr};

stats_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

VirtioStats virtio::blk::VirtioBlk< TransportT, VirtqueueT >::stats_

private

性能统计数据

Definition at line 841 of file virtio_blk.hpp.

transport_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

TransportT virtio::blk::VirtioBlk< TransportT, VirtqueueT >::transport_

private

传输层实例

Definition at line 829 of file virtio_blk.hpp.

virt_to_phys_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

VirtToPhysFunc virtio::blk::VirtioBlk< TransportT, VirtqueueT >::virt_to_phys_ {IdentityVirtToPhys}

private

Address translation callback.

Definition at line 839 of file virtio_blk.hpp.

{IdentityVirtToPhys};

vq_

template<typename TransportT = MmioTransport, typename VirtqueueT = SplitVirtqueue>

VirtqueueT virtio::blk::VirtioBlk< TransportT, VirtqueueT >::vq_

private

Virtqueue 实例（当前支持单队列）

Definition at line 831 of file virtio_blk.hpp.

---

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

• /workspaces/SimpleKernel/src/device/virtio/device/blk/virtio_blk.hpp