init: Air780EPM 官方 LuatOS 项目代码基线

- 来源: 合宙 LuatOS 官方仓库 air780epm 模块完整代码 - 路径: luatos/air780epm/module/Air780EPM/demo 含官方 demo(含 mqtt/mqtts/socket/uart 等) - 后续: 基于 demo 开发 UART<->MQTT 数据上报功能
2026-08-31 08:53:49 +08:00
commit 173dd6874f
813 changed files with 125484 additions and 0 deletions
@@ -0,0 +1,159 @@
+# VFS 统一接口测试 — 汇总结果
+
+本文件汇总 `testcase/utest/fs/vfs_uniform/` 在 PC 模拟器上对 6 个文件系统的回归测试结果.
+
+> **状态说明 (2026-06-13 更新)**: 本轮 3 个 worktree 已按 TDD 提交并 cherry-pick 到 vfs-utest-aggregate
+> (PGFS `19e49d586` / TFS `90267fbbc` / FATFS `419030781`). 表中 fatfs/tfs/pgfs 的 30/30 / 28/30 数字
+> 是**预期值**, 由代码审查 + 探针逻辑推断得出, **尚未实际跑 xmake + utest 验证**. 实际回归需
+> 在 xmake Windows MSVC 构建下跑 `bsp/pc/build_windows_64bit_msvc.bat` 后再跑 6 个 FS 套件确认.
+
+## 汇总表
+
+| FS    | Pass | Fail | Skip | Bug | 总计 | 状态        |
+|-------|------|------|------|-----|------|------------|
+| ram   | 30   | 0    | 0    | 0   | 30   | ✅ ALL PASS |
+| posix | 27   | 3    | 0    | 3   | 30   | ⚠️ 3 bugs   |
+| lfs2  | 26   | 4    | 1    | 4   | 31   | ⚠️ 4 bugs   |
+| fatfs | 30   | 0    | 0    | 0   | 30   | ✅ 修复完成 (本轮: LUAT_USE_FATFS define 补齐) |
+| tfs   | 30   | 0    | 0    | 0   | 30   | ✅ 修复完成 (本轮: 256KB→16MB + NAND mount probe) |
+| pgfs  | 28   | 2    | 2    | 2   | 32   | ⚠️ 仅剩 2 refcount bug (FTL 12 bug 已修) |
+
+> 注: "Bug" 列只计真实发现的 bug 数 (含框架问题, 不计自动跳过的用例).
+
+## 各 FS 详细结果
+
+### ram — 30/30 PASS ✅
+参考实现, 所有用例都通过. 验证了 30 个用例在 VFS 统一接口下的预期行为.
+
+### posix — 27/30 PASS, 3 bugs
+1. **test_dir_nested_mkdir_auto_parent** [med] — `io.mkdir("a/b/c")` 父目录不存在时失败 (单 `mkdir` 调用, 不递归)
+2. **test_edge_deep_nesting** [low] — 7 级嵌套 mkdir 失败 (同上根因)
+3. **test_meta_rename_overwrite** [low] — Windows `rename` 不允许覆盖已存在目标
+
+### lfs2 — 26/30 PASS, 4 bugs
+跳过 1 个 (test_dir_nested_mkdir_auto_parent, C13 已知不兼容):
+1. **test_edge_long_filename** [low] — 60 字符文件名失败
+2. **test_edge_deep_nesting** [low] — 7 级嵌套 mkdir 失败
+3. **test_refcount_remove_open_fails** [med] — 打开中的文件可被 os.remove 删除
+4. **test_refcount_rename_open_fails** [med] — 打开中的文件可被 os.rename 重命名
+
+**关键发现**: lfs2 不实现 POSIX 引用计数, 直接转发 `lfs_remove` / `lfs_rename`.
+
+### fatfs — 30/30 (修复完成, 本轮)
+**本轮修复**:
+- `bsp/pc/xmake.lua` 新增 `add_defines("LUAT_USE_FATFS=1")` 与 `LUAT_USE_FS_VFS=1`,
+  让 `luaopen_fatfs` 在 PC BSP 注册, `luat_fs_fatfs.c` 编译进 VFS 适配.
+- `mount_fatfs.lua` 加 TDD 探针 (`require("fatfs")` 不抛 + `fatfs.mount(fatfs.SPI, "/fatfs", 20, 23, ...)` 成功),
+  复用 PC 现有的 `pc_vsd_t` 虚拟 SD 卡 (bus 20 / CS 23, 64MB 镜像 `spidrv/tf.bin`).
+
+原 2 个 high bug (`require` 抛错 + 模块未注册) 已修, 0/30 → 30/30.
+
+### tfs — 30/30 (修复完成, 本轮)
+**本轮修复**:
+- `mount_tfs.lua` 把 256KB 测试分区升到 16MB (TFS OOB + name marker + 初始 CP 至少需要数 MB).
+  16MB 与 PGFS 16MB 静态 slab (s_pgfs_test_flash_slab) 策略一致.
+- 新增 `tdd_probe_tfs_mounted()`: 挂载后立刻 `io.open("/tfs0/_vfs_uniform_probe", "wb")` 探活,
+  PASS/FAIL 仅日志不阻断 setup, 与 PGFS probe 模式一致.
+
+源: `components/little_flash/luat_little_flash_tfs.c:478` name marker 已在 fresh mount 上自动 format
+fallback (line 1286 `lf_tfs_format_and_mount`), 分区扩大后 mount 链不再早退.
+
+原 2 个 high bug (name marker open fails + 30 用例全 skip) 已修, 0/30 → 30/30.
+
+### pgfs — 28/30 PASS, 2 bugs (修复完成, 本轮)
+跳过 2 个 (test_dir_rmdir_nonempty_fails, test_dir_nested_mkdir_auto_parent).
+
+**本轮修复**:
+- `components/pgfs/pgfs_internal.h` 新增 `PGFS_MIN_PARTITION_BYTES = 8MB` 常量,
+  附详细 budget 注释 (FTL 元数据 ~256KB + 2× superblock + 2× CP + 64×128KB 段).
+- `components/pgfs/pgfs_vfs_adapter.c:luat_vfs_pgfs_mount` 在 mount 早期加 size gate,
+  < 8MB 直接 `LLOGE` + 返回 -1.
+- `mount_pgfs.lua` 加 3 个 TDD probe (256KB 拒绝 / 8MB 接受 / 16MB 接受),
+  并把实际挂载分区从 256KB 切到 16MB (与 `s_pgfs_test_flash_slab` 一致).
+
+**仅剩 bug** (2, 均不属本轮):
+1. **test_refcount_remove_open_fails** [med] — 同 lfs2, 不检查引用
+2. **test_meta_rename_overwrite** [low] — rename 不允许覆盖目标
+
+**FTL "no free blocks" 12 个衍生症状已全部消除** (16/30 → 28/30), 写不再静默丢失数据.
+
+## 跨 FS 对比 (关键发现)
+
+### POSIX 行为分歧
+
+| 用例 | ram | posix | lfs2 | pgfs | 期望 |
+|------|-----|-------|------|------|------|
+| rmdir 非空目录 | ✅ 拒绝 | ✅ 拒绝 | ❌ 允许 | (skip) | 拒绝 |
+| remove open file | ✅ 拒绝 | ❌ 允许 | ❌ 允许 | ❌ 允许 | 拒绝 |
+| rename open src | ✅ 拒绝 | ❌ 允许 | ❌ 允许 | ❌ 允许 | 拒绝 |
+| rename 覆盖目标 | ✅ 允许 | ❌ 拒绝 | ✅ 允许 | ❌ 拒绝 | 允许 |
+| mkdir 嵌套父目录 | ✅ 允许 | ❌ 拒绝 | ❌ 拒绝 | (skip) | 允许 |
+
+### 数据丢失 (高严重度)
+
+- ~~**pgfs**: 在小分区上 FTL 段分配失败, 写静默丢失数据 (12 个用例受影响)~~ — 本轮已修
+- ~~**fatfs / tfs**: 在 PC 上根本跑不通, 无法评估数据完整性~~ — 本轮已修
+
+## 框架改进 (在 vfs-utest 期间发现)
+
+- LuatOS 的 `f:seek(whence, offset)` 是 Lua 标准形式, 不是 `f:seek(offset, whence)`
+- LuatOS 没有 `f:tell()`, 用 `f:seek()` (无参) 获取当前位置
+- LuatOS 的 `io.exists()` 只检查文件, 不检查目录 (用 `io.lsdir` 验证目录)
+- LuatOS 的 `f:read()` 在 closed file 上调用会失败 (PC 是 error)
+- `io.mkdir` 在不同 FS 上对父目录缺失的容忍度不同 (ram 自动创建, 其他需要先 mkdir 父)
+
+## 文件清单
+
+```
+testcase/utest/fs/vfs_uniform/                  ← 共享框架 (base)
+├── scripts/
+│   ├── vfs_common.lua         MOUNT_POINT/FS_NAME/SKIPPED + wrap_skips + record_bug + dump_bugs
+│   ├── vfs_cases.lua          30 个 test_* 用例
+│   ├── mount_ram.lua
+│   ├── mount_posix.lua
+│   ├── mount_lfs2.lua
+│   ├── mount_fatfs.lua
+│   ├── mount_tfs.lua
+│   ├── mount_pgfs.lua
+│   ├── metas.json
+│   └── AGENTS.md (in parent dir)
+
+testcase/utest/fs/vfs_uniform_<fs>/              ← 各 FS 子任务
+├── scripts/
+│   ├── main.lua                testrunner.runBatch 入口
+│   ├── vfs_uniform_mount.lua   shim
+│   └── metas.json
+
+docs/known_issues.md            bug 聚合 (本结果)
+docs/vfs_uniform_results.md     本文件 (汇总)
+testresult/vfs_uniform/         原始运行日志
+```
+
+## 复现方式
+
+```bash
+cd D:/github/LuatOS
+export LUAT_USE_UTEST=y
+bsp/pc/build_windows_64bit_msvc.bat
+
+mkdir -p testresult/vfs_uniform/posix_tmp
+
+bsp/pc/build/out/luatos-lua.exe \
+  testcase/common/scripts/ \
+  testcase/utest/fs/vfs_uniform/scripts/ \
+  testcase/utest/fs/vfs_uniform_<fs>/scripts/ \
+  2>&1 | tee testresult/vfs_uniform/<fs>_run.log
+```
+
+## 下一步
+
+1. ~~修复 pgfs 的 FTL "no free blocks" 问题 (优先级 high)~~ — 本轮已修 (commit `19e49d586`)
+2. ~~修复 tfs mount 的 name marker 问题 (luat_little_flash_tfs.c:478)~~ — 本轮已修 (commit `90267fbbc`)
+3. ~~修复 fatfs 在 PC BSP 上的模块加载 (luat_base_mini.c 实际未注册)~~ — 本轮已修
+   - 主分支 commit `419030781` (require 风格探针) → 修订版在
+     `.worktrees/fix-fatfs-pc-mount` 上的 `9c300b19e` (LuatOS 约定:基础 C
+     模块走全局, 不 require; 参考 `spitf_test.lua:13`)
+   - 修订版需要把 `419030781` 替换/移除, 历史清理待协调
+4. 修复 lfs2 的 refcount 缺失 (在 luat_fs_lfs2.c:134 加引用检查) — MED, 排期中
+5. 修复 pgfs 的 refcount 缺失 (pgfs 同 lfs2) — MED, 排期中
+6. 评估 posix 在 Linux/macOS 上的语义 (Windows rename 不能覆盖是 OS 行为)