xt_vfs_native - 原生文件系统后端

版本：0.1 | 日期：2026-06-16 | 路径： components/xt_vfs_native/

---

一、概述

xt_vfs_native 是 xt_vfs 虚拟文件系统的原生后端实现，将 VFS ops 接口映射到宿主操作系统的标准 C 库文件 API（ fopen / fread / opendir 等）。它主要用于 Windows/Linux 模拟器环境和宿主侧测试，让上层应用代码在不接触真实嵌入式文件系统的情况下完成功能验证。

1.1 设计原则

• **全量实现**：实现 xt_vfs_ops_t 全部 26 个函数指针，不是最小子集
• **槽位管理**：文件和目录句柄通过固定大小槽位表管理，不直接暴露 FILE* 给 Core
• **路径隔离**：所有操作限定在 base_path 根目录下，子路径前导 / 被剥离后拼接
• **errno 映射**：系统错误码统一转换为 XT_VFS_ERR_* 系列，对上层透明
• **跨平台**：通过 XT_SDK_PLATFORM_WINDOWS 宏区分 Windows 与 POSIX 的 mkdir / statfs 差异

1.2 与 xt_vfs 的关系

xt_vfs 定义了虚拟文件系统框架和 ops 接口（ xt_vfs_ops_t ），xt_vfs_native 是该接口的一个具体后端实现。其他后端如 LittleFS、FatFS 各自实现同一份 ops 表，通过 xt_vfs_mount 挂载后对上层提供统一的文件操作 API。

应用层  →  xt_vfs（Core：路由 / 锁 / 句柄管理）
               ├── xt_vfs_native   ← 本组件（宿主 OS 文件系统）
               ├── LittleFS 后端   （Flash 文件系统）
               └── FatFS 后端      （SD 卡文件系统）

1.3 依赖

依赖	用途
xt_vfs（虚拟文件系统）	VFS 框架： xt_vfs_ops_t 接口定义、类型定义、 XT_VFS_MAX_FILES 等宏
xt_sdk_version（SDK 版本号）	XT_SDK_PLATFORM_WINDOWS 平台宏
C 标准库	stdio.h 、 stdlib.h 、 string.h 、 errno.h
POSIX	sys/stat.h 、 dirent.h 、 unistd.h 、 utime.h 、 sys/statvfs.h
Windows SDK	windows.h （ GetDiskFreeSpaceExA ）

---

二、核心概念

2.1 槽位表模型

后端上下文 native_ctx_t 内部维护两张固定大小的槽位表：

槽位表	大小	内容	分配方式
files[XT_VFS_MAX_FILES]	VFS 配置	native_file_t （ FILE* + flags ）	线性扫描找 fp==NULL
dirs[XT_VFS_MAX_DIRS]	VFS 配置	native_dir_t （ DIR* + telldir_pos + path ）	线性扫描找 dir==NULL

文件句柄 fh 直接指向槽位地址（ &ctx->files[slot] ），close 时通过指针运算反推槽位索引。目录句柄 dh 则是独立分配的 native_dir_handle_t （仅含 index ），因为 VFS 的 xt_vfs_dir_t 是 opaque 指针。

2.2 路径映射

_make_fullpath 将 VFS 子路径映射到宿主文件系统：

VFS 挂载点: /c
base_path:  ./vfs_root
 
xt_vfs_open("/c/log.txt", ...) 
  → Core 路由剥离 /c → subpath = "log.txt"
  → native_open: _make_fullpath(ctx, "log.txt", ...)
  → 宿主路径: "./vfs_root/log.txt"

子路径前导 / 被跳过后与 base_path 以 / 拼接。

2.3 标志映射

VFS 打开标志到 CRT fopen 模式字符串的映射遵循 ANSI C 语义：

VFS 标志组合	fopen 模式
O_RDONLY	"rb"
O_WRONLY + O_CREAT + O_TRUNC	"wb"
O_WRONLY + O_APPEND	"ab"
O_RDWR + O_CREAT + O_TRUNC	"wb+"
O_RDWR + O_APPEND	"ab+"
O_RDWR （无 CREAT）	"rb+"

特殊回退：以 "r" 模式打开失败且带 O_CREAT 标志时，回退以 "wb+" 重新打开。

2.4 平台差异处理

功能	Windows	POSIX
创建目录	mkdir(path)	mkdir(path, 0755)
文件系统空间	GetDiskFreeSpaceExA	statvfs
块大小	固定 512 字节	statvfs.f_bsize

2.5 readdir 的静态 dirent

native_readdir 使用模块级静态变量 s_dirent 返回目录项。这意味着：

• 同一时刻只能有一个有效的 readdir 结果
• 两次连续 readdir 之间不能穿插其他 readdir 调用
• 实际使用中由 VFS Core 的后端锁保证同一挂载点操作串行化

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_vfs_native（原生文件系统） 。

3.1 生命周期管理

函数签名	说明
const xt_vfs_ops_t * xt_vfs_native_get_ops(void)	获取原生 FS 的 ops 表（惰性初始化，永不返回 NULL）
void * xt_vfs_native_create(const char *base_path)	创建原生 FS 后端实例，设置根目录
void xt_vfs_native_cleanup(void *ctx)	递归清空后端根目录下所有文件及子目录
void xt_vfs_native_destroy(void *ctx)	销毁后端实例，释放内存（允许传 NULL）

公开接口共 4 个：获取 ops 表、创建实例、清理目录、销毁实例。ops 表内部 26 个函数由 VFS Core 调用。

---

四、编译配置

宏	默认值	说明
XT_VFS_NATIVE_ROOT	"./vfs_root"	后端默认根目录路径

通过 xmake 选项 xt_vfs_native_root 可在配置时覆盖：

xmake f --xt_vfs_native_root=/tmp/my_vfs

文件/目录槽位数量由 xt_vfs（虚拟文件系统） 的 XT_VFS_MAX_FILES 和 XT_VFS_MAX_DIRS 决定，详见 xt_vfs（虚拟文件系统） 编译配置。

---

五、常见模式

5.1 挂载原生后端到 VFS

#include "xt_vfs.h"
#include "xt_vfs_native.h"
 
void app_init(void)
{
    xt_vfs_config_t cfg = {
        .max_mounts  = 2,
        .max_files   = 8,
        .max_dirs    = 4,
        .max_threads = 4,
    };
    xt_vfs_init(&cfg);
 
    /* 创建后端实例并挂载到 /c */
    void *ctx = xt_vfs_native_create("./my_root");
    if (ctx == NULL) {
        /* 内存分配失败 */
        return;
    }
 
    const xt_vfs_ops_t *ops = xt_vfs_native_get_ops();
    xt_vfs_mount("/c", ops, ctx);
 
    /* 之后通过 xt_vfs API 操作 /c 路径 */
    xt_vfs_fd_t fd = xt_vfs_open("/c/test.txt", XT_VFS_O_CREAT | XT_VFS_O_RDWR);
    /* ... */
    xt_vfs_close(fd);
}

5.2 多后端混合挂载

/* 模拟器环境：native 用于持久化，ramfs 用于临时数据 */
void *native_ctx = xt_vfs_native_create("./vfs_root");
xt_vfs_mount("/disk", xt_vfs_native_get_ops(), native_ctx);
 
xt_vfs_mount("/tmp", &ramfs_ops, &ramfs_ctx);
 
/* 两者完全隔离，通过路径前缀路由 */

5.3 测试后清理

/* 测试结束后递归清空后端目录 */
xt_vfs_unmount("/c");
xt_vfs_native_cleanup(native_ctx);  /* 递归删除 ./vfs_root 下所有文件 */
xt_vfs_native_destroy(native_ctx);

---

六、反模式

反模式	问题	正确做法
销毁前未关闭所有文件	FILE* 泄漏，槽位残留	先 close 所有 fd，再 unmount
base_path 设为宿主根目录	误操作系统关键文件	使用独立子目录如 ./vfs_root
依赖 sync_all 刷盘	实现为空操作（直接返回 OK）	用 fsync 单文件同步
并发 readdir 依赖返回指针有效性	静态 s_dirent 被覆盖	同一挂载点操作已由 Core 后端锁串行化，不同挂载点互不影响
XT_VFS_MAX_FILES 设过小	打开文件数超限返回 XT_VFS_ERR_NFILE	根据实际需求调整 VFS 配置

---

七、注意事项

• native_unmount 内部调用 xt_vfs_native_destroy 释放上下文内存，因此 unmount 后不应再使用该 ctx
• xt_vfs_native_get_ops 返回的 ops 表是静态常量，可多次调用返回同一指针
• native_mount 会检查 base_path 是否存在，不存在则自动创建目录
• readdir 自动跳过 . 和 .. 目录项
• statfs 在 Windows 上块大小固定为 512 字节， f_files 和 f_ffree 始终为 0