VirtIO-Blk 规格¶
1. 设备目标¶
VirtIO-Blk 将来宾块请求映射到用户通过 --disk 指定的宿主镜像。镜像是外部产物，路径由 CLI 传入且使用仓库根目录相对路径示例，例如 artifacts/disk/rootfs.ext4。
2. 基本参数¶
- BLK-REQ-001：逻辑扇区固定为 512 字节。
- BLK-REQ-002：capacity 以 512 字节扇区数公布，来自镜像完整大小向下取整。
- BLK-REQ-003：镜像大小不是 512 的整数倍时必须在启动阶段拒绝或明确按冻结策略处理，不能无提示截断。
- BLK-REQ-004：读写模式必须与公布的只读 feature 一致。
3. 请求链布局¶
每个请求至少包含：
- 设备只读的请求头，含 type、reserved、sector。
- 一个或多个数据描述符，方向取决于请求类型。
- 最后一个长度至少 1 字节且设备可写的 status 描述符。
链结构、字段大小和小端序按 VirtIO 规范校验。状态描述符缺失、方向错误或链过短时不得越界写入。
4. 请求类型¶
- BLK-REQ-005：至少支持
VIRTIO_BLK_T_IN，从磁盘读到来宾可写缓冲区。 - BLK-REQ-006：至少支持
VIRTIO_BLK_T_OUT，从来宾只读缓冲区写入磁盘。 - Flush、Get ID、Discard、Write Zeroes 只有在实现、测试并公布对应 feature 后才接受。
- 未支持请求返回
UNSUPP，后端 I/O 或范围错误返回IOERR。
5. 边界与偏移¶
sector × 512和offset + total_data_len必须使用检查运算。- 请求不得超出镜像 capacity。
- 多描述符数据按链顺序形成一个连续块请求。
- 读请求的来宾缓冲总长度决定实际读取范围；短宿主读取视为错误，不能以未初始化数据补齐。
- 写请求必须避免宿主部分写被错误报告为成功；失败策略和镜像一致性必须清晰诊断。
6. 完成顺序¶
- 完整验证描述符链和磁盘范围。
- 执行宿主
pread/pwrite等不依赖共享文件偏移的操作。 - 写 status 字节。
- 写 used element，
len仅统计设备写入来宾的字节数，按规范处理。 - 发布 used idx。
- 触发 VirtIO 中断并经 PLIC 注入。
失败也必须按适用规范正确完成请求；不能留下驱动永久等待，除非设备进入需要复位状态并明确通知。
7. 宿主文件安全¶
- 启动时验证文件类型、访问权限和大小。
- 不允许自动创建用户未指定的磁盘镜像。
- 不允许扩展镜像越过启动时公布 capacity。
- 默认不调用会改变宿主全局状态的缓存策略。
- 异常退出前已报告成功的写入必须满足冻结的持久性语义；若仅保证页缓存可见，文档必须明确。
8. 验收条件¶
- 真实 ext4 镜像可被 Linux 识别、挂载并持续读取。
- 在允许写入的配置中，来宾创建文件后正常关机并重新启动仍可读取。
- 覆盖首末扇区、多描述符、零长度、越界、只读和宿主短 I/O。
- used length、status 与中断顺序符合规范。
- 恶意描述符不能读写镜像范围之外或宿主其他文件。