xt_fs → xt_vfs 迁移指南

版本：0.1 | 日期：2026-06-17

---

一、概述

xt_vfs 是 xt_fs 的替代品，从单后端全局函数升级为支持多后端挂载的虚拟文件系统。核心变化：

	xt_fs	xt_vfs
后端模型	单后端，平台层写死	多后端，ops 接口可插拔
初始化	xt_fs_init() 无参数	xt_vfs_init(&config) 需传配置
挂载	无（隐式）	显式 xt_vfs_mount(prefix, ops, ctx)
同步	flush + sync 两个函数	fsync 一个函数
类型	xt_fs_* 前缀	xt_vfs_* 前缀（完整 typedef）
权限位	**有 bug**（组/其他值冲突）	已修正为标准 POSIX 值
线程安全	平台层自管	Core 内置，宏可关

---

二、最小迁移步骤

步骤 1：替换 include

// 旧
#include "xt_fs.h"
 
// 新
#include "xt_vfs.h"

步骤 2：替换类型

xt_fs	xt_vfs
xt_fs_err_t	xt_vfs_err_t
xt_fs_size_t	xt_vfs_size_t
xt_fs_ssize_t	xt_vfs_ssize_t
xt_fs_mode_t	xt_vfs_mode_t
xt_fs_time_t	xt_vfs_time_t
xt_fs_fd_t (不存在)	xt_vfs_fd_t（新增类型）
int32_t (fd)	xt_vfs_fd_t
struct xt_fs_stat	xt_vfs_stat_t
struct xt_fs_dir	xt_vfs_dir_t
struct xt_fs_dirent	xt_vfs_dirent_t
struct xt_fs_statfs	xt_vfs_statfs_t
struct xt_fs_utimbuf	xt_vfs_utimbuf_t

步骤 3：替换错误码

全局替换前缀即可：

XT_FS_ERR_ → XT_VFS_ERR_
XT_FS_INVALID_FD → XT_VFS_INVALID_FD
XT_FS_INVALID_DIR → 不再需要（目录句柄 NULL 即无效）

步骤 4：替换函数调用

xt_fs	xt_vfs	变化
xt_fs_init()	xt_vfs_init(&cfg)	需要配置参数
xt_fs_deinit()	xt_vfs_deinit()	相同
xt_fs_open(p, f)	xt_vfs_open(p, f)	fd 类型改为 xt_vfs_fd_t
xt_fs_close(fd)	xt_vfs_close(fd)	相同
xt_fs_read(fd,b,s)	xt_vfs_read(fd,b,s)	相同
xt_fs_write(fd,b,s)	xt_vfs_write(fd,b,s)	相同
xt_fs_seek(fd,o,w)	xt_vfs_seek(fd,o,w)	相同
xt_fs_tell(fd)	xt_vfs_tell(fd)	相同
xt_fs_flush(fd)	xt_vfs_fsync(fd)	**改名**（flush+sync 合并）
xt_fs_sync(fd)	xt_vfs_fsync(fd)	改名
xt_fs_remove(p)	xt_vfs_remove(p)	相同
xt_fs_rename(o,n)	xt_vfs_rename(o,n)	相同
xt_fs_utime(p,b)	xt_vfs_utime(p,b)	相同
xt_fs_stat(p,s)	xt_vfs_stat(p,s)	相同
xt_fs_fstat(f,s)	xt_vfs_fstat(f,s)	相同
xt_fs_mkdir(p)	xt_vfs_mkdir(p)	需 XT_VFS_ENABLE_DIR=1
xt_fs_rmdir(p)	xt_vfs_rmdir(p)	需 XT_VFS_ENABLE_DIR=1
xt_fs_opendir(p)	xt_vfs_opendir(p)	需 XT_VFS_ENABLE_DIR=1
xt_fs_closedir(d)	xt_vfs_closedir(d)	需 XT_VFS_ENABLE_DIR=1
xt_fs_readdir(d)	xt_vfs_readdir(d)	需 XT_VFS_ENABLE_DIR=1
xt_fs_telldir(d)	xt_vfs_telldir(d)	需 XT_VFS_ENABLE_DIR=1
xt_fs_seekdir(d,l)	xt_vfs_seekdir(d,l)	需 XT_VFS_ENABLE_DIR=1
xt_fs_rewinddir(d)	xt_vfs_rewinddir(d)	需 XT_VFS_ENABLE_DIR=1
xt_fs_access(p,m)	xt_vfs_access(p,m)	相同
xt_fs_truncate(p,l)	xt_vfs_truncate(p,l)	len 类型改为 xt_vfs_off_t
xt_fs_ftruncate(f,l)	xt_vfs_ftruncate(f,l)	同上
xt_fs_errno()	xt_vfs_errno()	相同
xt_fs_strerror(e)	xt_vfs_strerror(e)	相同

步骤 5：添加初始化配置和挂载

xt_fs 时期只需要 xt_fs_init()，xt_vfs 需要配置 + 挂载后端：

// 旧：xt_fs
xt_fs_init();
 
// 新：xt_vfs
xt_vfs_config_t cfg = {
    .max_mounts = 4,
    .max_files  = 16,
    .max_dirs   = 8,
    .max_threads = 4,
};
xt_vfs_init(&cfg);
xt_vfs_mount("/", &native_ops, native_ctx);  // 挂载到根目录

---

三、完整迁移示例

xt_fs 原始代码

#include "xt_fs.h"
 
void example(void) {
    xt_fs_err_t ret;
    int32_t fd;
    char buf[64];
    struct xt_fs_dir *dir;
    struct xt_fs_dirent *ent;
    struct xt_fs_stat st;
 
    ret = xt_fs_init();
    if (ret != XT_FS_ERR_OK) {
        xt_printf("init failed: %s\n", xt_fs_strerror(ret));
        return;
    }
 
    // 创建并写入文件
    fd = xt_fs_open("/data.txt", XT_FS_O_CREAT | XT_FS_O_RDWR | XT_FS_O_TRUNC);
    if (fd < 0) { goto cleanup; }
    xt_fs_write(fd, "hello", 5);
    xt_fs_flush(fd);
    xt_fs_close(fd);
 
    // 读取文件
    fd = xt_fs_open("/data.txt", XT_FS_O_RDONLY);
    xt_fs_read(fd, buf, sizeof(buf));
    xt_fs_close(fd);
 
    // 获取文件信息
    xt_fs_stat("/data.txt", &st);
    xt_printf("size: %u\n", (unsigned)st.st_size);
 
    // 目录操作
    xt_fs_mkdir("/logs");
    dir = xt_fs_opendir("/logs");
    while ((ent = xt_fs_readdir(dir)) != NULL) {
        xt_printf("%s\n", ent->d_name);
    }
    xt_fs_closedir(dir);
 
cleanup:
    xt_fs_deinit();
}

xt_vfs 迁移后代码

#include "xt_vfs.h"
#include "xt_vfs_native.h"  // Windows 原生后端
 
void example(void) {
    xt_vfs_err_t ret;
    xt_vfs_fd_t fd;
    char buf[64];
    xt_vfs_dir_t *dir;
    xt_vfs_dirent_t *ent;
    xt_vfs_stat_t st;
    void *ctx;
 
    // 初始化配置
    xt_vfs_config_t cfg = {
        .max_mounts  = 4,
        .max_files   = 16,
        .max_dirs    = 8,
        .max_threads = 4,
    };
 
    ret = xt_vfs_init(&cfg);
    if (ret != XT_VFS_ERR_OK) {
        xt_printf("init failed: %s\n", xt_vfs_strerror(ret));
        return;
    }
 
    // 挂载后端（这是新增步骤）
    ctx = xt_vfs_native_create("./root");
    xt_vfs_mount("/", xt_vfs_native_get_ops(), ctx);
 
    // 创建并写入文件
    fd = xt_vfs_open("/data.txt", XT_VFS_O_CREAT | XT_VFS_O_RDWR | XT_VFS_O_TRUNC);
    if (fd == XT_VFS_INVALID_FD) { goto cleanup; }
    xt_vfs_write(fd, "hello", 5);
    xt_vfs_fsync(fd);  // flush + sync 合并为 fsync
    xt_vfs_close(fd);
 
    // 读取文件
    fd = xt_vfs_open("/data.txt", XT_VFS_O_RDONLY);
    xt_vfs_read(fd, buf, sizeof(buf));
    xt_vfs_close(fd);
 
    // 获取文件信息（同前）
    xt_vfs_stat("/data.txt", &st);
    xt_printf("size: %u\n", (unsigned)st.st_size);
 
    // 目录操作（需 XT_VFS_ENABLE_DIR=1）
    xt_vfs_mkdir("/logs");
    dir = xt_vfs_opendir("/logs");
    while ((ent = xt_vfs_readdir(dir)) != NULL) {
        xt_printf("%s\n", ent->d_name);
    }
    xt_vfs_closedir(dir);
 
cleanup:
    xt_vfs_native_cleanup(ctx);
    xt_vfs_deinit();
}

---

四、宏映射

xt_fs	xt_vfs	说明
XT_FS_PATH_MAX	XT_VFS_PATH_MAX	默认 128（xt_fs 是 256）
XT_FS_FILENAME_MAX	XT_VFS_FILENAME_MAX	默认 64
XT_FS_MAX_FILES	XT_VFS_MAX_FILES	默认 8（xt_fs 是 16）
XT_FS_MAX_DIRS	XT_VFS_MAX_DIRS	默认 4（xt_fs 是 8）
XT_FS_O_RDONLY 等	XT_VFS_O_RDONLY 等	值不变
XT_FS_TYPE_REG/DIR	XT_VFS_TYPE_REG/DIR	值不变
XT_FS_F_OK/R_OK/W_OK/X_OK	XT_VFS_F_OK/R_OK/W_OK/X_OK	值不变
XT_FS_SEEK_SET/CUR/END	XT_VFS_SEEK_SET/CUR/END	值不变
XT_FS_INVALID_FD	XT_VFS_INVALID_FD
XT_FS_IS_VALID_FD/IS_VALID_DIR	无	不再需要（generation 自动校验）

---

五、注意事项

1. **权限位值已修正**：xt_fs 的组/其他人权限位存在值冲突 bug，xt_vfs 使用标准 POSIX 值。如果代码中硬编码了权限位数字（如 0x0008），需要对应修改。
2. **fd 是 xt_vfs_fd_t**：不再是 int32_t，建议用 XT_VFS_INVALID_FD 判无效而非 < 0（虽然两者等效）。
3. **flush + sync → fsync**：xt_fs_flush + xt_fs_sync 两个调用的地方，改为一个 xt_vfs_fsync。
4. **目录功能需开启宏**：XT_VFS_ENABLE_DIR=1（默认开启），关闭后目录 API 不可用。
5. **多后端需挂载**：xt_fs 时期隐式有一个后端，xt_vfs 需要显式 xt_vfs_mount 挂载。挂载到 / 即可恢复 xt_fs 时期的行为。
6. **config 必须传**：xt_vfs_init 必须传配置，不能像 xt_fs_init 那样无参数。
7. **堆/静态可切换**：XT_VFS_USE_HEAP=0 时使用静态数组（配合 xt_vfs_config_t 的 mem 字段或常量宏），适合裸机无堆环境。