zvfs/plan/rocksdb_syscall_matrix.md

Phase 0 - RocksDB syscall 兼容矩阵

• 日期: 2026-03-02
• 采样对象: /home/lian/env/rocksdb-test/db_bench
• 当前 LD_PRELOAD: /home/lian/share/10.1-spdk/zvfs/zvfs/libzvfs.so
• 说明: 本矩阵基于 phase0 的 fillseq 最小工作负载和失败分支采样；用于定义 phase2 必做 hook 范围。

1) 采样结论（关键）

1.1 成功基线（不启用 LD_PRELOAD，--db=/tmp/rdb_phase0_plain）

关键 syscall 计数（来自 strace 汇总）：

syscall	count
openat	91
fcntl	82
read	56
fstat	56
getdents64	36
stat	14
mkdir	12
unlink	12
access	11
fsync	10
fdatasync	10
rename	9
pread64	8
ftruncate	5
fallocate	5
lseek	1

路径级（仅匹配 DB 路径）高频调用：

• openat, mkdir, access, rename, unlink, rmdir

1.2 失败分支（启用 LD_PRELOAD，--db=/zvfs/rdb_phase0_preload）

观察到的关键失败：

• SPDK 初始化失败：Cannot use IOVA as PA，随后 spdk_env_init 失败。
• RocksDB 目录创建路径使用 openat + mkdir，对 /zvfs/rdb_phase0_preload 返回 ENOENT。
• 与 DB 路径相关错误码分布：ENOENT x4。

结论：仅 hook open/read/write/close/unlink/lseek 无法支撑 RocksDB；至少要覆盖目录/元数据/同步/随机读写相关 syscall。

2) 当前实现 vs RocksDB 需求

当前已实现 hook（zvfs_hook.c）：

• open, read, write, close, unlink, lseek

当前缺失但在 phase0 中已观测到（或由 RocksDB 常规路径强依赖）：

• openat/openat64, mkdir, rmdir
• pread64/pwrite64（pwrite 在 fillseq 未显式出现，但 RocksDB 通常依赖）
• fsync/fdatasync
• ftruncate/fallocate
• fcntl（文件锁）
• stat/fstat/lstat/newfstatat（含 statx 兼容策略）
• rename（CURRENT / OPTIONS / MANIFEST 原子更新）
• access/faccessat, unlinkat

3) Phase 2 必做清单（来自 phase0 证据）

这是“必须实现或必须可正确透传”的最小集合。

API/syscall	证据来源	当前状态	Phase2 目标
open/open64	现有 hook + RocksDB 文件创建	部分支持	补齐 flag 语义（O_TRUNC/O_APPEND/O_EXCL）
openat/openat2	phase0 strace 高频	缺失	必须支持 /zvfs 路径
close	已实现	支持	保持并修复错误传播
read/write	已实现	支持	保持
pread64/pwrite64	phase0 观测到 pread64	缺失	必须支持 offset I/O
fsync/fdatasync	phase0 高频	缺失	必须支持（至少语义正确）
ftruncate	phase0 观测到	缺失	必须支持
fallocate	phase0 观测到	缺失	必须支持或明确降级策略
fcntl(F_SETLK等)	phase0 高频	缺失	必须支持最小锁语义
stat/fstat/lstat/newfstatat	phase0 高频	缺失	必须支持最小元数据语义
mkdir/rmdir	phase0 路径级高频	缺失	必须支持 /zvfs 目录层
rename	phase0 路径级高频	缺失	必须支持原子替换语义
unlink/unlinkat	unlink 已有，unlinkat 缺失	部分支持	补齐 unlinkat
access/faccessat	phase0 路径级高频	缺失	必须支持或一致透传

4) 可降级透传（phase2 可先不接管）

• getdents64, readlink, statfs/fstatfs 可先透传（前提：不作用于 /zvfs 或语义可接受）。
• 若作用于 /zvfs 路径，必须在 phase2 给出明确行为（支持或返回可解释错误）。

5) 风险与备注

1. 当前机器环境下 SPDK 初始化存在 IOVA/PA 限制，影响“真实 I/O 路径”验证，需要在 phase1 前先明确运行环境策略。
2. 仅凭 fillseq 不能覆盖全部 syscall；phase2 开始前建议补 readrandom/overwrite 采样以确认 pwrite64 等调用比例。