Translation pending. This page is currently available in Chinese.
A20OS VFS 边界语义设计¶
本文档规范 A20OS VFS 的 Linux 边界语义契约,定义各系统调用在特定标志与边界条件下的行为保证及当前实现的边界约束。
[!NOTE] 实现要点 A20OS VFS 支持现代 Linux 边界路径解析语义。解析器已完整支持
RESOLVE_NO_MAGICLINKS(拒绝穿越/proc/<pid>/fd/N类跳跃链接并返回-ELOOP)、RESOLVE_CACHED(基于 dentry cache 快速查找,未命中返回-EAGAIN)以及openat2/renameat2扩展,相关语义由smoke-vfs-edge自动化门禁保障。
1. 范围¶
覆盖的 syscall 和 VFS 边界领域:
openat2:已实现的resolve子集及 A20OS 扩展renameat2flag:RENAME_NOREPLACE、RENAME_EXCHANGE、RENAME_WHITEOUTstatx:mask 处理和 sync typefaccessat2/fchmodat2:AT_*flag 语义*xattr:namespace 校验和后端持久化- Symlink loop limit:提高到 Linux
MAX_SYMLINKS - Mount-point
..crossing:正确逃出 mount root chroot:让 path resolution 遵守task->fs.root_path
这里覆盖当前边界实现及其遗留差距;不覆盖运行时文件系统初始化移除或 page-cache/mmap coherence。
2. openat2:当前 resolve 子集¶
2.1 当前状态(设计时)¶
kernel/abi/linux/sys_proc.c 的 sys_openat2 曾从用户 struct open_how 复制 flags 和 mode,但忽略 resolve 和 syscall 的 size 参数,随后调用 sys_openat,因此 RESOLVE_* flag 没有任何效果。现已实现:size 被校验、未知 resolve bit 以 -EINVAL 拒绝,全部六个 RESOLVE_* flag(含 NO_MAGICLINKS)经 vfs_openat2 在 resolver 中生效(kernel/abi/linux/sys_proc.c、kernel/fs/vfs.c、kernel/fs/vfs/path_resolution.c)。
2.2 决策¶
当前实现的 flag 表如下;其中最后两项不是 Linux-compatible 编号:
| Flag | 语义 | 实现文件 |
|---|---|---|
RESOLVE_NO_SYMLINKS |
整个 walk 期间绝不跟随 symlink | kernel/fs/vfs/path_resolution.c |
RESOLVE_BENEATH |
拒绝 walk 到起始目录之上 | kernel/fs/vfs/path_resolution.c |
RESOLVE_IN_ROOT |
相对于起始目录解析绝对路径和 .. |
kernel/fs/vfs/path_resolution.c |
RESOLVE_NO_MAGICLINKS |
拒绝穿越 magic link(/proc/<pid>/fd/N 类 jump link),普通 symlink 仍可跟随;与 NO_SYMLINKS 同返回 -ELOOP |
kernel/fs/vfs/path_resolution.c;magic link 由 vnode VNODE_MAGICLINK 标记(procfs fd-symlink 创建时设置) |
RESOLVE_NO_XDEV |
拒绝跨越 mount point | kernel/fs/vfs/path_resolution.c |
RESOLVE_CACHED |
只使用缓存 lookup;任意组件未缓存则返回 -EAGAIN |
kernel/fs/vfs/path_resolution.c;dentry cache 是优化层,未缓存路径由调用方去 flag 重试 |
2.3 实现映射¶
kernel/abi/linux/sys_proc.c:接受 24 到 A20OSsizeof(struct open_how)(88)字节;用-EINVAL拒绝未知 resolve bit;将 resolve flag 传给vfs_openat2。函数中检查超长结构尾部是否为零的分支当前因前置size > sizeof(khow)拒绝而不可达。kernel/fs/vfs.c:vfs_openat2(dirfd, path, flags, mode, resolve)构造 resolution context 并调用 resolver。kernel/fs/vfs/path_resolution.c:让 openat2 resolver 接受起始路径、root path 和resolve_flags,并在 walk 中执行 beneath/root/mount 边界检查;RESOLVE_CACHED在 dentry cache 未命中时返回-EAGAIN(不回落真实 lookup)。kernel/fs/vfs/dcache.c:RESOLVE_CACHED通过vfs_dcache_lookup命中检查实现;dentry cache 仍是优化层而非权威 lookup 来源,未缓存路径返回-EAGAIN由调用方重试。kernel/include/fs/vfs.h:增加RESOLVE_*常量和open_howstruct layout。kernel/include/core/fcntl.h:当前常量表与 Linux 的 bit 分配一致(RESOLVE_CACHED == 0x20)。user/cmds/stress/vfs_edge.c:覆盖BENEATH、NO_SYMLINKS和CACHED的选定场景。
2.4 ABI 说明¶
- Linux 当前已知
struct open_how前缀是 24 字节的{ u64 flags; u64 mode; u64 resolve; },并通过 syscall 的size参数做尾部扩展;A20OS 内部结构额外声明了 64 字节 padding。 - A20OS 当前要求
24 <= size <= 88,并不接受 Linux 规则允许的更长全零扩展结构。 RESOLVE_CACHED与 Linux 一致为0x20;A20OS 自定义的RESOLVE_NO_TRAILING_SYMLINKS(曾占用0x20)已移除,不再与 Linux 冲突。- 未知 resolve bit 返回
-EINVAL;六个已知 flag 全部在 resolver 中有对应检查。
3. renameat2 flag¶
3.1 当前状态(设计时)¶
kernel/abi/linux/sys_path.c 的 sys_renameat2 曾用 -EINVAL 拒绝任何非零 flags。现已实现:RENAME_NOREPLACE 与 RENAME_EXCHANGE 被接受并经 vfs_rename_flags 分发到后端,RENAME_WHITEOUT 仍以 -EINVAL 拒绝。普通 same-path rename 由后端作为 no-op 成功;VFS 没有 same-path -EINVAL guard。
3.2 决策¶
实现 RENAME_NOREPLACE、RENAME_EXCHANGE;RENAME_WHITEOUT 在范围之外,因为 A20OS 没有 overlay/whiteout 文件系统支持。
不带冲突 flag 的 source 与 target 为同一路径时返回成功。RENAME_NOREPLACE 仍按“目标已存在”规则处理,不能把普通 same-path no-op 扩展成所有 flag 组合都成功。
| Flag | 支持 | 语义 | 实现文件 |
|---|---|---|---|
RENAME_NOREPLACE |
实现 | 如果目标已存在,以 -EEXIST 失败 |
kernel/fs/vfs.c、后端 rename ops |
RENAME_EXCHANGE |
实现 | 原子交换源和目标 | kernel/fs/vfs.c、后端 rename ops |
RENAME_WHITEOUT |
范围外 | 需要 overlayfs 语义 | 记录为不支持;返回 -EINVAL |
3.3 实现映射¶
kernel/abi/linux/sys_path.c:校验 flag;允许RENAME_NOREPLACE | RENAME_EXCHANGE;拒绝RENAME_WHITEOUT和不兼容组合。kernel/fs/vfs.c:由vfs_rename_flags校验并传递 flags;在委托给old_dir->ops->rename前检查 cross-mount(-EXDEV)和 permission/sticky-bit 规则。vfs_rename保留为 flags 为 0 的 wrapper;没有 same-target-EINVAL检查,普通 same-path no-op 由后端返回成功。kernel/fs/diskfs/ramfs.c:在ramfs_vnode_rename中实现RENAME_NOREPLACE(现有 lookup)和RENAME_EXCHANGE。kernel/fs/diskfs/ext4.c:扩展ext4_vn_rename,处理RENAME_NOREPLACE和RENAME_EXCHANGE。kernel/fs/diskfs/fat32.c/fat32_vn.c:已接入 rename,支持普通替换、跨目录移动与RENAME_NOREPLACE;不支持RENAME_EXCHANGE。- 后端 vnode ops 签名变更:
int (*rename)(vnode_t *old_dir, const char *old_name, vnode_t *new_dir, const char *new_name, unsigned int flags)。 kernel/include/fs/vfs.h:更新rename函数指针类型并增加RENAME_*常量。user/cmds/stress/vfs_edge.c:当前在 ramfs 上覆盖NOREPLACE与EXCHANGE。
4. statx¶
4.1 当前状态(设计时)¶
kernel/abi/linux/sys_path.c 的 sys_statx 曾默认 mask 为 STATX_BASIC_STATS 并填充固定字段集合,不遵守 sync type、不报告 STATX_BTIME、忽略大部分请求的 mask。当前实现不是 requested-only:它总把 STATX_BASIC_STATS 加入 stx_mask 并返回基础元数据,再按请求追加 STATX_BTIME 等可选字段;STATX_BTIME 的值与 ctime 相同。
4.2 决策¶
mask采用“基础字段始终提供、可选字段按请求追加”的策略:stx_mask总含STATX_BASIC_STATS,而不是只回报调用者请求的 bit。- 遵守
AT_STATX_SYNC_TYPE:FORCE_SYNC先执行 vnode page-cache writeback 再读取 metadata;DONT_SYNC不触发该 writeback。 - 将
STATX_BTIME报告为与ctime相同(A20OS 不跟踪 birth time)。 - 用
-EINVAL拒绝未知 flag。
4.3 实现映射¶
kernel/abi/linux/sys_path.c:将mask和 sync type 传给vfs_statx。kernel/fs/vfs_stat.c:vfs_statx/vfs_fstatx处理 sync hint,并复用vfs_vnode_stat读取 metadata。kernel/fs/vfs/stat_perm.c:vfs_vnode_stat提供基础 stat 与 RAM time-meta 回退。kernel/abi/linux/sys_path.c:组装struct statx,总是报告基础字段,并在请求STATX_BTIME时复制ctime。kernel/fs/page_cache.c:为FORCE_SYNC提供page_cache_writeback_vnode调用。kernel/include/abi/linux/stat.h:已经定义STATX_*和AT_STATX_*。user/cmds/stress/vfs_edge.c:覆盖FORCE_SYNC/DONT_SYNC与 size mask。
5. faccessat2 / fchmodat2¶
5.1 当前状态(设计时)¶
kernel/fs/vfs_stat.c中的vfs_faccessat2处理AT_EACCESS、AT_SYMLINK_NOFOLLOW和AT_EMPTY_PATH,并对未支持 bit 返回-EINVAL。kernel/abi/linux/sys_path.c中的sys_fchmodat处理AT_SYMLINK_NOFOLLOW和AT_EMPTY_PATH,但在 legacyfchmodat路径中忽略第四个参数。fchmodat2在kernel/abi/linux/syscall_table.def中连到带 flags 参数的sys_fchmodat。
5.2 决策¶
faccessat2:保留当前行为;增加严格校验,确保没有设置AT_EACCESS | AT_SYMLINK_NOFOLLOW | AT_EMPTY_PATH之外的 bit。fchmodat2:作为一等 syscall 处理,支持完整 flag(AT_SYMLINK_NOFOLLOW、AT_EMPTY_PATH)。用-EINVAL拒绝不支持的 bit。
5.3 实现映射¶
kernel/fs/vfs_stat.c:收紧vfs_faccessat2flag 校验。kernel/fs/vfs_stat.c:vfs_chmodat已检查 flag;确保带 flags 的fchmodat路径从 syscall table 暴露。kernel/abi/linux/sys_path.c:让sys_fchmodat成为规范实现,并确保fchmodat2共享同一路径。- 当前
vfs_edge.c没有专门的 faccessat2/fchmodat2 flag 场景;这是测试缺口。
6. xattr¶
6.1 当前状态¶
- xattr syscall 位于
kernel/abi/linux/sys_xattr.c。 - 存储是
kernel/fs/xattr.c中按(mnt, ino)索引的全局 RAM 表。 - 没有后端特定 xattr hook;FAT32/ext4 不持久化值。
xattr_check_namespace()只接受user.、trusted.、security.、system.;trusted./security.的 set/remove 要求CAP_SYS_ADMIN。- syscall 表面只接受 reg/dir/lnk vnode,其他类型返回
-EOPNOTSUPP。
6.2 已落地决策¶
P1 保留全局 RAM xattr 表,并收紧 ABI 表面:
- 用
-EINVAL拒绝没有 namespace 前缀(user.、trusted.、security.、system.)的名称。 - 如果调用者缺少
CAP_SYS_ADMIN,拒绝security.*和trusted.*。 - 用
-EOPNOTSUPP拒绝非 reg/dir/lnk vnode 上的 xattr(kernel/abi/linux/sys_xattr.c已这样做)。 - 保持值只存在于 RAM;记录块文件系统的持久化缺口。
6.3 实现映射¶
kernel/fs/xattr.c:xattr_check_namespacehelper 与 capability 检查。kernel/abi/linux/sys_xattr.c:通过 vnode xattr helper 执行 namespace 检查。kernel/include/fs/xattr.h:namespace 常量。kernel/fs/diskfs/fat32.c/kernel/fs/diskfs/ext4.c:暂不增加后端 xattr hook。user/cmds/stress/vfs_edge.c:覆盖 user/invalid/trusted namespace 的选定行为。
7. Symlink loop limit¶
7.1 当前状态(设计时)¶
vnode_lookup_path 曾把 symlink_depth 上限硬编码为 8(kernel/fs/vfs/path_resolution.c)。现已实现:使用 MAX_SYMLINKS(40,kernel/include/fs/vfs.h),深度超过时以 -ELOOP 失败。
7.2 决策¶
将限制提高到 Linux MAX_SYMLINKS(40)。计数器仍保留在 resolver context 中。
7.3 实现映射¶
kernel/fs/vfs/path_resolution.c:用MAX_SYMLINKS替换硬编码8。kernel/include/fs/vfs.h:增加#define MAX_SYMLINKS 40。user/cmds/stress/vfs_edge.c:构造超过 40 层的 symlink chain 并检查ELOOP。
8. Mount-point .. crossing¶
8.1 当前状态(设计时)¶
vnode_lookup_path 通过跟随 vnode->parent 处理 ..。此前 mount root 的 vnode->parent 要么指回自身,要么指向被挂载文件系统内部的 parent,因此 .. 无法逃出 mount。现已实现:在 mount root 处解析 .. 时切换到 mount point 的父目录(mount crossing),RESOLVE_NO_XDEV 阻止这种跨越。
8.2 决策¶
实现 Linux mount-point .. 语义:
- 在 mount root 处解析
..时,切换到底层文件系统中 mount point 的父目录。 - 与
openat2一起使用时,RESOLVE_NO_XDEV必须阻止这种跨越。 chroot与 mount crossing 组合时必须同时遵守两种边界。
8.3 实现映射¶
kernel/fs/vfs/mount.c:增加vfs_mount_parent(mount_t *mnt),返回覆盖mnt->path父路径的 mount。kernel/fs/vfs/path_resolution.c:在vnode_lookup_path中跟随vnode->parent前,先检查cur是否是 mount root;如果是,切换到 parent mount 的 vnode 并继续。kernel/include/fs/vfs.h:增加 mount-root 检测 helper。user/cmds/stress/vfs_edge.c:在/tmp挂载 ramfs,检查从 mount root 的..回到父 mount;当前没有 FAT32 嵌套 mount 专项。
9. chroot¶
9.1 当前状态(设计时)¶
kernel/abi/linux/sys_namespace.c 的 sys_chroot 曾校验目标为目录、检查 CAP_SYS_CHROOT、把路径存入 cur->fs.root_path 并重置 cwd,但 resolver 不读取 root_path。现已实现:vfs_path_normalize_absolute_with_root 在路径解析中约束 root_path(kernel/fs/vfs/path_resolution.c),chrooted 进程的绝对路径与 .. 都无法逃出 chroot。
9.2 决策¶
让 path resolution 遵守 task->fs.root_path:
- 绝对路径相对于
root_path解释。 ..解析不得逃出root_path。- chrooted 进程中的
openat(fd, "../../..", ...)必须留在 chroot 内部。 - 绝对路径
execve也必须使用root_path。
9.3 实现映射¶
kernel/fs/vfs/path_resolution.c:通过vfs_path_normalize_absolute_with_root和 resolver 的 root context 约束绝对路径与..。kernel/fs/vfs/path_resolution.c:让vfs_resolve和vfs_resolve_at使用当前 task 的root_path;kernel/fs/vfs.c中的vfs_resolve_no_follow_final使用相同 root 约束。kernel/proc/exec.c:proc_exec在构造绝对 executable path 时应用root_path,再调用vfs_path_normalize_absolute_with_root。kernel/abi/linux/sys_namespace.c:保留现有sys_chroot;该处无需改动。user/cmds/stress/vfs_edge.c:覆盖 chroot 后通过..访问外部 sibling 的拒绝行为。
9.4 pivot_root 与 mount 引用模型¶
模型¶
mount 现在同时以两种方式表达,二者一起维护、不会对同一个存活 mount 产生分歧:
- 树:
mnt_parent/mnt_mp/mnt_child说明 mount 挂在哪里、谁持有它。挂载点 vnode 由 mount 自己持有引用。 - 扁平前缀:
mount_t::path,路径解析按最长前缀匹配用它选择 mount。
树的用途:umount 的 busy 判定、pivot_root、/proc/self/mountinfo 的 parent id。前缀的用途:绝对路径落到哪个 mount。
/proc/<pid>/mountinfo 与 /proc/<pid>/mounts 使用目标进程的挂载命名空间和根目录;/proc/mounts 使用当前进程。表项在命名空间存活引用与挂载表锁保护下复制,格式化不继续持有裸 mount 指针。挂载点按完整路径组件判断是否位于根目录下,根外条目与已分离条目不输出;可见挂载点转换为根相对的绝对路径,并转义空格、制表符、换行和反斜杠。保留真实 mount/parent id,不因为父挂载不可见就重编号。当前设备号等其它 mountinfo 字段仍沿用既有兼容范围,不由此声明完整 Linux mountinfo 格式兼容。
2026-11-16 的 RV64 CLI 定向运行通过 tmpfs 挂载、写读、卸载,以及父进程读取私有 namespace/chroot 子进程的挂载视图;证据见应用契约。
进程位置同样是对象而不是字符串(proc_fs_context_t):
| 字段 | 含义 |
|---|---|
root_mnt / root_vn |
进程 root 所在的 (mount, vnode),各持一份引用 |
cwd_vn |
cwd 指向的目录对象,持有引用 |
cwd / root_path |
上述对象的扁平拼写,供路径拼接与显示使用 |
引用计数落在 mount 上:root_users 是「namespace 表自身 1 份 + 每个以该 mount 为 root 的进程 1 份」,cwd_users 同理记录站在该 mount 里的进程数。因此 busy 判定是常数时间比较,不需要遍历进程表。
fork 通过 vfs_task_fs_pins_copy() 复制指针并各取一份引用;fdtable_close_all()(所有 exit 路径都会经过的唯一 fs 钩子)调用 vfs_task_fs_pins_release() 释放。
pivot_root(2) 检查顺序¶
按 Linux 顺序,任一步失败都返回负 errno 且不改变进程状态:
CAP_SYS_ADMIN;new_root是目录、可搜索(X_OK),且不是当前 root;new_root所在 mount 不是当前 root 所在 mount(否则 pivot 什么也没改变;子 mount 合法——那正是容器的常规路径);put_old是目录;put_old位于**新** root 之下,且与new_root在同一 mount——这一条阻止进程借 pivot_root 保留一个本该被新 root 隐藏的旧树句柄;put_old的父目录可解析且是目录。
随后:把旧 root 的 mount 从树上摘下(vfs_mount_detach_root(),标记 VFS_MOUNT_DETACHED,保留对象供已有引用使用,procfs 不再列出该已分离挂载,任何路径都不再经过它),重设 root 为新 (mount, vnode) 对,cwd 移到 put_old 的父目录。
umount2 的 busy 规则¶
vfs_umount_flags() 实现三条 Linux 判定,任一成立返回 EBUSY:
root_users > 1:有进程以此为 root;mnt_child != NULL:其下还挂着 mount;cwd_users > 0:有进程正站在其中。
MNT_DETACH 越过全部三条。namespace root 本身返回 EINVAL。sys_umount2 现在转发 flags(此前完全丢弃),并对未知位返回 EINVAL。
门禁¶
smoke-pivot-root(user/cmds/stress/pivot_root_test.c)覆盖:mountinfo 的真实 parent id、busy umount、MNT_DETACH、put_old 越界被拒、pivot 后旧 root 不可按路径访问、pivot 前打开的 fd 仍能读到旧树、新 root 可写。
10. 变更 / 扩展文件汇总¶
| 文件 | 变更 |
|---|---|
kernel/abi/linux/sys_proc.c |
openat2 校验与分发 |
kernel/abi/linux/sys_path.c |
renameat2 flag、statx sync/mask、fchmodat2 flag |
kernel/abi/linux/sys_xattr.c |
namespace 和 capability 检查 |
kernel/fs/vfs.c |
vfs_rename_flags、rooted resolution hook |
kernel/fs/vfs_stat.c |
vfs_faccessat2 与 vfs_chmodat flag 校验 |
kernel/fs/vfs/path_resolution.c |
RESOLVE_*、MAX_SYMLINKS、mount .. crossing、chroot root |
kernel/fs/vfs/mount.c |
mount-parent lookup helper |
kernel/fs/vfs/dcache.c |
普通 lookup 优化缓存;RESOLVE_CACHED 通过 dcache 命中检查实现(未命中 -EAGAIN) |
kernel/fs/vfs/stat_perm.c |
vfs_vnode_stat、permission 与 RAM time-meta |
kernel/fs/xattr.c |
namespace validation helper |
kernel/fs/diskfs/ramfs.c |
RENAME_NOREPLACE / RENAME_EXCHANGE |
kernel/fs/diskfs/ext4.c |
RENAME_NOREPLACE / RENAME_EXCHANGE |
kernel/fs/diskfs/fat32.c、fat32_vn.c |
普通 rename 与 RENAME_NOREPLACE;不支持 exchange |
kernel/include/fs/vfs.h |
新常量和 vnode ops 签名 |
kernel/include/abi/linux/fcntl.h |
RESOLVE_* 和 RENAME_* ABI 值 |
kernel/include/abi/linux/stat.h |
已定义 STATX_* |
kernel/proc/exec.c |
executable 的 rooted path resolution |
user/cmds/stress/vfs_edge.c |
当前 RISC-V64 edge 场景 |
user/cmds/stress/vfs_stress.c |
较广 VFS 压力与基础行为场景 |
11. 测试门禁¶
必须增加或扩展以下 smoke / stress 门禁:
smoke-vfs-edge:当前 RISC-V64 单核目标,覆盖 openat2 的BENEATH/NO_SYMLINKS/NO_MAGICLINKS/CACHED、ramfs renameat2、statx、xattr、symlink loop、mount..crossing、chroot 等选定场景;不覆盖全部 resolve flag 组合、全部文件系统后端或其他架构。- 现有门禁(
smoke-abi-linux、check-vfs-abstraction)必须保持通过。
smoke-vfs-fs-specific(每后端 unsupported-op errno 矩阵)不属于 P1 范围;后端能力差异继续记录在 docs/zh/fs/fs-consistency-model.md。