mobile_comm/luatos/air780epm/docs/known_issues.md

VFS 统一测试 — 已知问题 / Bug 列表

本文件由 testcase/utest/fs/vfs_uniform/ 框架自动/手动追加, 汇总 vfs 统一接口在 6 个文件系统 (ram/posix/lfs2/fatfs/tfs/pgfs) 上的行为差异与已发现 bug.

格式

### <FS>::<test_name>  [severity]
- **Expected**: 一句话预期行为
- **Actual**: 一句话实际行为
- **Source**: 源文件:行号 (定位)
- **Repro**:
  1. 步骤 1
  2. 步骤 2
- **Tags**: fs=<fs>, mode=<mode>, feature=<area>

索引

• ram
• posix
• lfs2
• fatfs
• tfs
• pgfs

---

ram

(empty)

posix

posix::test_dir_nested_mkdir_auto_parent [med]

• Expected: io.mkdir("a/b/c") 在父目录 b 不存在时应自动创建 (与 ram 行为一致)
• Actual: io.mkdir 失败, 不创建父目录
• Source: luat/vfs/luat_fs_posix.c:200-208 (直接调原生 mkdir, 不会递归创建父目录)
• Repro:
  1. io.mkdir("vfs_dir_a/b/c") (b 不存在)
• Tags: fs=posix, mode=mkdir, feature=dir

posix::test_edge_deep_nesting [low]

• Expected: io.mkdir 应能创建 7 级嵌套目录 (a/b/c/d/e/f/g)
• Actual: io.mkdir 失败, 因为中间父目录 (a, a/b, …) 不存在
• Source: luat/vfs/luat_fs_posix.c:200-208 (同上, 单一 mkdir 调用)
• Repro:
  1. io.mkdir("vfs_edge_deep/a/b/c/d/e/f/g")
• Tags: fs=posix, mode=mkdir, feature=dir

posix::test_meta_rename_overwrite [low]

• Expected: os.rename 覆盖已存在目标文件应成功
• Actual: os.rename 失败, 源文件保持不变
• Source: luat/vfs/luat_fs_posix.c:105-112 (直接调原生 rename; Windows 不允许 overwrite existing target)
• Repro:
  1. mkdir d; io.open("d/from.txt","wb"); io.open("d/to.txt","wb")
  2. os.rename("d/from.txt", "d/to.txt")
• Tags: fs=posix, mode=rename, feature=meta, platform=windows

lfs2

lfs2 跑通 26/30 (跳过 1 个 C13 嵌套 mkdir). 真实 bug 4 个 (含 2 个 refcount 缺失).

lfs2::test_edge_long_filename [low]

• Expected: 60 字符文件名应可创建 (与 ram 一致)
• Actual: 60 字符文件名 open 失败
• Source: luat/vfs/luat_fs_lfs2.c (lfs2 默认 name_max=63, 但 PC 配置/驱动对长名更敏感)
• Repro:
  1. io.open("/lfs2/vfs_edge_<60 chars>.txt", "wb")
• Tags: fs=lfs2, mode=create, feature=long-name

lfs2::test_edge_deep_nesting [low]

• Expected: mkdir a/b/c/d/e/f/g 7 级嵌套应成功
• Actual: 失败
• Source: luat/vfs/luat_fs_lfs2.c:206-223 (mkdir 不自动创建父目录)
• Repro:
  1. io.mkdir("/lfs2/vfs_edge_deep/a/b/c/d/e/f/g")
• Tags: fs=lfs2, mode=mkdir, feature=deep-nesting

lfs2::test_refcount_remove_open_fails [med]

• Expected: 打开中的文件不应被 os.remove 删除
• Actual: os.remove 成功了
• Source: luat/vfs/luat_fs_lfs2.c:134 (直接调 lfs_remove, 不检查引用计数)
• Repro:
  1. 创文件 p
  2. f = io.open(p, "r")
  3. os.remove(p) -- 期望失败
  4. f:close()
• Tags: fs=lfs2, mode=read+remove, feature=refcount

lfs2::test_refcount_rename_open_fails [med]

• Expected: 打开中的源文件不应被 os.rename 重命名
• Actual: os.rename 成功了
• Source: luat/vfs/luat_fs_lfs2.c:134 (rename 路径同样不检查引用)
• Repro:
  1. 创文件 src
  2. f = io.open(src, "r")
  3. os.rename(src, dst) -- 期望失败
  4. f:close()
• Tags: fs=lfs2, mode=read+rename, feature=refcount

fatfs

fatfs::setup_module_not_found [high]

• Expected: 当 fatfs 模块在 PC BSP 中不可用时, mount_fatfs.setup() 应返回 false 让 main.lua 自跳过整个测试套
• Actual: mount_fatfs.lua:9 的 require("fatfs") 在 PC BSP 上直接抛出 "module 'fatfs' not found", VM 在 main.lua 检测 fs_ok 之前就崩溃退出, 测试套根本没有 self-skip 机会
• Source: testcase/utest/fs/vfs_uniform/scripts/mount_fatfs.lua:9
• Repro:
  1. 在 PC 模拟器上跑 vfs_uniform_fatfs
  2. mount_fatfs.setup() 里 require("fatfs") 失败, 抛错
  3. 错误沿着 require 链 vfs_uniform_mount.lua -> mount_fatfs.lua 一路冒泡, VM 退出
  4. main.lua 的 if not fs_ok then ... os.exit(0) end 永远不会执行
• Tags: fs=fatfs, mode=pc, feature=framework-bootstrap

fatfs::pc_build_fatfs_module_unavailable [high]

• Expected: PC BSP 应当能 require("fatfs") 加载内置 fatfs 模块 (因为 LUAT_USE_FATFS 已在 bsp/pc/include/luat_conf_bsp.h:145 定义, 且 luaopen_fatfs 在 bsp/pc/port/luat_base_mini.c:160 注册)
• Actual: 当前 PC 二进制 bsp/pc/build/out/luatos-lua.exe 对 require("fatfs") 返回 "module not found", 同样 require("uart")/require("json") 等内置模块也都失败; 只有 io/os/string/log/rtos 这类 globals 仍可用. 整个 fatfs 测试套无法在 PC 上执行
• Source: bsp/pc/port/luat_base_mini.c:159-161 (注册) vs PC BSP 实际加载行为
• Repro:
  1. 写 print(type(require("fatfs"))) 的最小 main.lua
  2. 用 bsp/pc/build/out/luatos-lua.exe ... /tmp/test/ 跑
  3. 输出 module 'fatfs' not found 然后 Lua VM exit!! reboot in 1000ms
• Tags: fs=fatfs, mode=pc, feature=module-registration

tfs

tfs::tfs_mount_format_name_marker [high]

• Expected: lf.mount(flash, "/tfs0", 0, 256*1024, {fs="tfs"}) 在 PC 模拟器空白 flash 上应返回 true, mount 后 VFS 即可在 /tfs0 上读写文件
• Actual: 第一次 lf.mount 返回 false, 日志显示 tfs: format ret=0 read_errors=0 (format 成功) 紧接着 tfs: open name marker failed 和 tfs: format mount failed, 之后才出现 tfs: anchor written chunk=0 seq=4096; 二次 mount 找到 anchor 但仍 tfs: open name marker failed 触发 tfs: probe failed, reformatting, 再次 tfs: open name marker failed 后 tfs: format or mount failed
• Source: components/little_flash/luat_little_flash_tfs.c:478 (lf_tfs_write_name_marker 中 tfs_open 失败) 与 :1226 (tfs: format mount failed)
• Repro:
  1. 在 PC 上跑 D:/github/LuatOS/bsp/pc/build/out/luatos-lua.exe 并加载 vfs_uniform_tfs/scripts
  2. mount_tfs.lua 调 spi.deviceSetup(1,255,...) + lf.init(spidev) + lf.mount(flash,"/tfs0",0,256*1024,{fs="tfs"})
  3. 观察: format ret=0 → open name marker failed → format mount failed, 紧接着 anchor 写入但 mount 仍失败
• Tags: fs=tfs, mode=mount, feature=format-name-marker

tfs::all_tests_skipped_mount_unavailable [high]

• Expected: 30 个共享用例应在 /tfs0 上运行, 大部分通过
• Actual: 30 个用例全部 0/0 跳过, 因为 tfs mount 失败直接 os.exit(0), 没有任何用例被执行
• Source: 测试 main.lua 在 mount.setup() 返回 false 时退出; 根因是 tfs mount bug
• Repro:
  1. 跑 vfs_uniform_tfs (与上面 tfs_mount_format_name_marker 同一触发条件)
  2. 日志最后两行: tfs mount 失败 + tfs FS 不可用, 退出
• Tags: fs=tfs, mode=run, feature=suite-execution

pgfs

pgfs mounted successfully on PC simulator (/pgfs0, 256KB partition, virtual NAND W25N01GVZEIG). However the FTL has very few free blocks at mount time (next=1, total=2, bad=0), and the GC allocator reports alloc_segment: no free blocks whenever a write triggers a new segment allocation. This causes most write/read roundtrip assertions to fail with 0-byte content. Each test below is a separate symptom of the same root cause (or, in two cases, an independent semantic bug).

pgfs::test_refcount_remove_open_fails [med]

• Expected: 打开中的文件不应被 os.remove 删除 (refcount 应阻止 remove)
• Actual: os.remove 成功了 (pgfs 直接删除了正在被读取的文件)
• Source: components/pgfs/luat_pgfs_posix.c (remove 路径未检查 refcount, 沿用 lfs2 的旧语义)
• Repro:
  1. io.open("/pgfs0/vfs_refcount_rm.txt", "wb") 然后 close
  2. f = io.open("/pgfs0/vfs_refcount_rm.txt", "r")
  3. os.remove("/pgfs0/vfs_refcount_rm.txt") -- 期望失败, 实际成功
  4. f:close()
• Tags: fs=pgfs, mode=read+remove, feature=refcount

pgfs::test_meta_rename_overwrite [low]

• Expected: rename 覆盖已存在的目标文件应成功 (POSIX 行为)
• Actual: rename 失败, 目标文件保持旧内容
• Source: components/pgfs/luat_pgfs_posix.c rename 实现 (未先 unlink 目标)
• Repro:
  1. io.mkdir("/pgfs0/d")
  2. 创 /pgfs0/d/from.txt (内容 "new") 和 /pgfs0/d/to.txt (内容 "old")
  3. os.rename("/pgfs0/d/from.txt", "/pgfs0/d/to.txt") -- 期望成功, 实际失败
• Tags: fs=pgfs, mode=rename, feature=metadata

pgfs::test_basic_write_read_roundtrip [high]

• Expected: 写入 "hello" 后读取应得到 "hello"
• Actual: 读出为空字符串 (write 静默失败, 文件大小为 0)
• Source: components/pgfs/pgfs_alloc_gc.c:78 alloc_segment: no free blocks
  • components/pgfs/luat_pgfs_posix.c (write 路径未检测 segment 分配失败)
• Repro:
  1. mount pgfs (256KB)
  2. f = io.open("/pgfs0/x.txt", "wb"); f:write("hello"); f:close()
  3. f = io.open("/pgfs0/x.txt", "rb"); f:read("*a") -- 期望 "hello", 实际 ""
• Tags: fs=pgfs, mode=wb/rb, feature=write-data-loss

pgfs::test_basic_write_read_large [high]

• Expected: 写入 64KB 数据后读回应得到 65536 字节
• Actual: 读出 0 字节 (write 静默失败, 因 segment 分配失败)
• Source: 同 test_basic_write_read_roundtrip (FTL 没有空闲块)
• Repro:
  1. f = io.open("/pgfs0/big.bin", "wb"); f:write(<64KB>); f:close()
  2. io.open("/pgfs0/big.bin", "rb"):read("*a") -- 期望 65536 字节, 实际 0
• Tags: fs=pgfs, mode=wb/rb, feature=large-write-data-loss

pgfs::test_edge_block_size_boundary [high]

• Expected: 4096 字节精确写入读回后, 大小和内容完全一致
• Actual: 读出 0 字节 (page-aligned 4KB 写入也静默失败)
• Source: 同 test_basic_write_read_roundtrip (FTL 没有空闲块)
• Repro:
  1. f = io.open("/pgfs0/block.bin", "wb"); f:write(<4096 bytes>); f:close()
  2. f = io.open("/pgfs0/block.bin", "rb"); f:read("*a") -- 期望 4096, 实际 0
• Tags: fs=pgfs, mode=wb/rb, feature=block-boundary

pgfs::test_basic_seek_tell [high]

• Expected: 写入 100 字节, seek('set', 50) 后 tell() 返回 50, 读出第 51 字节 = 50
• Actual: seek() 返回 0, read 返回空 (文件为 0 字节, write 静默失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.bin", "wb"); f:write(<100 bytes>); f:close()
  2. f = io.open("/pgfs0/x.bin", "rb"); f:seek("set", 50); print(f:seek()) -- 期望 50, 实际 0
• Tags: fs=pgfs, mode=rb, feature=seek-data-loss

pgfs::test_basic_seek_end [high]

• Expected: 写入 100 字节后 seek('end') 给出位置 100
• Actual: seek() 返回 0 (文件为空, write 失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.bin", "wb"); f:write("x"*100); f:close()
  2. f = io.open("/pgfs0/x.bin", "rb"); f:seek("end"); print(f:seek()) -- 期望 100, 实际 0
• Tags: fs=pgfs, mode=rb, feature=seek-end

pgfs::test_basic_seek_cur [high]

• Expected: seek('end') 后 seek('cur', -10) 给出位置 90
• Actual: seek() 返回 0 (文件为空, write 失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.bin", "wb"); f:write("x"*100); f:close()
  2. f = io.open("/pgfs0/x.bin", "rb"); f:seek("end"); f:seek("cur", -10); print(f:seek()) -- 期望 90, 实际 0
• Tags: fs=pgfs, mode=rb, feature=seek-cur

pgfs::test_meta_fsize [high]

• Expected: 写入 1234 字节, fs.fsize 应返回 1234
• Actual: fs.fsize 返回 0 (write 静默失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.bin", "wb"); f:write("Z"*1234); f:close()
  2. fs.fsize("/pgfs0/x.bin") -- 期望 1234, 实际 0
• Tags: fs=pgfs, mode=wb, feature=fsize

pgfs::test_meta_rename_file [high]

• Expected: rename a->b 应成功, 之后 b 存在且内容是 "data-a"
• Actual: rename 返回 err=2 (源文件不存在 / 写入失败, 链式失败)
• Source: 同 test_basic_write_read_roundtrip (写入失败导致源文件未创建, rename 报 ENOENT)
• Repro:
  1. f = io.open("/pgfs0/a.txt", "wb"); f:write("data-a"); f:close()
  2. os.rename("/pgfs0/a.txt", "/pgfs0/b.txt") -- 期望 true, 实际 err=2
• Tags: fs=pgfs, mode=rename, feature=metadata-chain-failure

pgfs::test_basic_append_mode [high]

• Expected: "foo" + append "bar" 后读出 "foobar"
• Actual: 读出空字符串 (write 静默失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.txt", "wb"); f:write("foo"); f:close()
  2. f = io.open("/pgfs0/x.txt", "ab"); f:write("bar"); f:close()
  3. io.open("/pgfs0/x.txt", "rb"):read("*a") -- 期望 "foobar", 实际 ""
• Tags: fs=pgfs, mode=ab, feature=append-data-loss

pgfs::test_posix_mode_w_plus [high]

• Expected: "w+" 打开后 write("xyz") 再 seek(0) read 应得到 "xyz"
• Actual: read 返回空字符串 (write 静默失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.txt", "w+"); f:write("xyz"); f:seek("set", 0); print(f:read("*a")) -- 期望 "xyz", 实际 ""
• Tags: fs=pgfs, mode=w+, feature=mode-flags

pgfs::test_posix_mode_r_plus [high]

• Expected: "r+" 打开已有文件后 write + seek + read 应得到原长度 (首字节被覆盖)
• Actual: read 返回 0 字节字符串 (写时静默失败, 文件被截断/清空)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败) + components/pgfs/luat_pgfs_posix.c (r+ 模式 open 后的截断/清空行为)
• Repro:
  1. f = io.open("/pgfs0/x.txt", "wb"); f:write("initial"); f:close()
  2. f = io.open("/pgfs0/x.txt", "r+"); f:write("X"); f:seek("set", 0); print(f:read("*a")) -- 期望 "Xniti..."(7 字节), 实际 ""
• Tags: fs=pgfs, mode=r+, feature=mode-flags

pgfs::test_posix_binary_text_same [high]

• Expected: 写入 0x0A 0x0D 0x00 0xFF 后 read(4) 读出 4 字节
• Actual: read(4) 返回 nil (文件为空, write 静默失败)
• Source: 同 test_basic_write_read_roundtrip (根因 = FTL 段分配失败)
• Repro:
  1. f = io.open("/pgfs0/x.bin", "wb"); f:write("\x0A\x0D\x00\xFF"); f:close()
  2. f = io.open("/pgfs0/x.bin", "rb"); f:read(4) -- 期望 4 字节, 实际 nil
• Tags: fs=pgfs, mode=rb, feature=binary-mode