zvfs/plan/phase1_validation.md

Phase 1 验证方案（用户执行）

背景：本轮已完成 phase1 代码改造，但当前代理环境无法在 root + SPDK 运行条件下完成端到端验证。下面步骤请你在本机执行。

0) 目标

验证 3 件事：

1. zvfs_io_req 解耦后，read/write 旧路径行为不回退。
2. 新增 zvfs_pread/zvfs_pwrite API 能正确处理 offset I/O。
3. 构建产物 libzvfs.so 可正常编译链接。

---

1) 构建验证

cd /home/lian/share/10.1-spdk/zvfs
make -C zvfs -j

期望：

• 编译成功，无报错。
• 生成 /home/lian/share/10.1-spdk/zvfs/zvfs/libzvfs.so。

---

2) Phase1 新 API 验证（不依赖 LD_PRELOAD hook）

2.1 生成临时测试程序

cat >/tmp/phase1_api_check.c <<'EOF'
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "zvfs.h"

static int expect_eq(const char *name, const void *got, const void *exp, size_t n) {
    if (memcmp(got, exp, n) != 0) {
        fprintf(stderr, "[FAIL] %s mismatch\n", name);
        return -1;
    }
    printf("[OK] %s\n", name);
    return 0;
}

int main(void) {
    int rc = 1;
    int mounted = 0;
    int created = 0;
    if (zvfs_env_setup() != 0) {
        fprintf(stderr, "zvfs_env_setup failed\n");
        return rc;
    }

    zvfs_t *fs = calloc(1, sizeof(*fs));
    zvfs_file_t *file = calloc(1, sizeof(*file));
    zvfs_dirent_t *dirent = calloc(1, sizeof(*dirent));
    if (!fs || !file || !dirent) {
        rc = 2;
        goto out;
    }

    if (!zvfs_mount(fs)) {
        fprintf(stderr, "zvfs_mount failed\n");
        rc = 3;
        goto out;
    }
    mounted = 1;

    file->fs = fs;
    file->dirent = dirent;
    if (!zvfs_create(file)) {
        fprintf(stderr, "zvfs_create failed\n");
        rc = 4;
        goto out;
    }
    created = 1;

    /* 验证 pwrite + pread 的 offset 语义 */
    const char *a = "AAAA";
    const char *b = "BBBB";
    if (zvfs_pwrite(file, (const uint8_t *)a, 4, 0) != 4) { rc = 5; goto out; }
    if (zvfs_pwrite(file, (const uint8_t *)b, 4, 8) != 4) { rc = 6; goto out; }

    uint8_t got[12] = {0};
    uint8_t exp[12] = {'A','A','A','A',0,0,0,0,'B','B','B','B'};
    if (zvfs_pread(file, got, sizeof(got), 0) != 12) { rc = 7; goto out; }
    if (expect_eq("pread/pwrite-hole", got, exp, sizeof(exp)) != 0) { rc = 8; goto out; }

    /* 验证旧 read/write 顺序语义未回退 */
    file->current_offset = 0;
    const char *c = "CCCC";
    if (zvfs_write(file, (const uint8_t *)c, 4) != 4) { rc = 9; goto out; }
    file->current_offset = 0;
    uint8_t got2[4] = {0};
    if (zvfs_read(file, got2, sizeof(got2)) != 4) { rc = 10; goto out; }
    if (expect_eq("read/write-seq", got2, c, 4) != 0) { rc = 11; goto out; }

    rc = 0;
    printf("[PASS] phase1_api_check\n");

out:
    if (created) {
        (void)zvfs_close(file);
        (void)zvfs_delete(file);
    }
    if (mounted) {
        (void)zvfs_umount(fs);
    }

    free(dirent);
    free(file);
    free(fs);
    return rc;
}
EOF

2.2 编译并运行

gcc -O2 -Wall -Wextra -std=gnu11 \
  -I/home/lian/share/10.1-spdk/zvfs/zvfs \
  -I/home/lian/share/10.1-spdk/zvfs/spdk/include \
  -o /tmp/phase1_api_check /tmp/phase1_api_check.c \
  /home/lian/share/10.1-spdk/zvfs/zvfs/libzvfs.so -ldl

sudo /tmp/phase1_api_check

期望：

• 输出包含：
  • [OK] pread/pwrite-hole
  • [OK] read/write-seq
  • [PASS] phase1_api_check

---

3) 旧 POSIX 路径回归（LD_PRELOAD）

cd /home/lian/share/10.1-spdk/zvfs
make -C test -j

sudo env LD_PRELOAD=/home/lian/share/10.1-spdk/zvfs/zvfs/libzvfs.so ./test/bin/test_basic /zvfs
sudo env LD_PRELOAD=/home/lian/share/10.1-spdk/zvfs/zvfs/libzvfs.so ./test/bin/test_lseek /zvfs
sudo env LD_PRELOAD=/home/lian/share/10.1-spdk/zvfs/zvfs/libzvfs.so ./test/bin/test_two_files /zvfs

期望：

• test_basic、test_lseek、test_two_files 通过。
• 无崩溃、无明显数据错乱。

若出现一次性 zvfs_mount failed，建议先确保没有残留测试进程，再重跑一次验证命令。

---

4) 验证完成后回填

请把验证结果回填到 plan/plan.md 的 phase1 区域：

• ### 阶段验收
• ### 正确性验证方案

若任何一项失败，请附上：

1. 命令；
2. 错误输出；
3. 是否可稳定复现。