# 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` 等调用比例。