imrcpan/erofs-freebsd-out-tree
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
imrcpan
2026-08-18 09:20:44 +02:00
commit b826cd721a
522 changed files with 93730 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
current/README.md
+13
View File
@@ -0,0 +1,13 @@
# repo22 当前状态报告索引
- [report-1](report-1/README.md)：第一次总体进度报告，保留
`573aaab7ee0b47cb6aed7f76c52c68dd4041326b` 创建时的原始内容。
- [report-2](report-2/README.md)：第二次总体进度报告，按
`381349b3847209a67d669264ac54a50a3599915c` 快照汇总正式批次、动态结果、
issue、风险和下一步。
- [report-3](report-3/README.md)：第三次总体进度报告，以
`12351cbb0a593474f4fcef68ffc5218d9c99dd46` 为最终验证快照，汇总完成项、
160 PASS/1 PARTIAL、独立审查结论、剩余搁置项和后续可选计划。
后续总体状态报告统一使用 `current/report-N/` 目录。逐项动态证据位于
`tests/results/manual/`，问题触发、分析和解决状态位于 `issues/`。
current/report-1/2026-08-09-overall-progress.md
+160
View File
@@ -0,0 +1,160 @@
# repo22 当前总体进度
更新时间：2026-08-09 UTC
状态报告代码基线：`cd0e985b5ac54a4b7acb7042422329ad1729fb3e`
本报告记录的是上述基线上的阶段性状态。测试结果、问题状态和统计会随后续
提交继续更新，不能将本文视为 TC001-TC156 已完成全量回归的声明。
## 目标与执行范围
repo22 的目标是在 FreeBSD 15 amd64 上提供只读 EROFS 内核模块，并以可复现
fixture、真实 KLD、真实 mount/read/errno 和完整清理证据验证声明的功能边界。
当前执行约束如下：
- 只修改和提交 `repo-community/repo22`，fixture、VM overlay、KLD 和原始日志仅
放在 `/work/build` 或 guest 临时目录。
- 不建设或使用 CI、runner、自动 PASS wrapper；每个 TC 必须逐份对照对应
Markdown 手工执行。
- host 侧 `mkfs.erofs`、`dump.erofs`、`fsck.erofs` 和静态源码审查只作为 fixture
或分析证据，不能替代 FreeBSD 内核动态结果。
- 每批测试形成独立 manual report，记录 commit、构建配置、KLD SHA256、guest
版本、命令、可观察输出或 errno、fixture hash 和清理状态。
- 每批完成后提交并 push 到 `xdm/main`；并行批次若使远端前进，则 fetch、rebase
自己的 test-only 提交后正常 push，禁止 force push。
## 已完成实现与审查
当前源码已覆盖 superblock、compact/extended inode、plain/inline/chunk 数据、
目录/namecache、xattr/ACL/metabox、LZ4/MicroLZMA/DEFLATE/ZSTD、fragment、
multi-device、NFS export、pager 和多项 fail-closed 边界检查。功能声明的准确边界
以 `docs/features.md` 为准。
主要 feature 批次包括：
- `29a215dd`：POSIX ACL 与完整 xattr namespace 集成。
- `545d35bd`：xattr、long prefix、shared xattr 和 metabox 边界加固。
- `96e22cc`：cold nested namei 与目录结构校验修复。
- `4ef680df`、`78182686`：真实 multi-device、slot mapping、flatdev 和 extent
映射审查修复。
- `2354b448`：NFS export、稳定句柄和相关 vnode 路径。
- `c208bf1f`：压缩映射 P0 收口，包括多算法、partial reference 和 extent 路径。
- `9a3604fb`：metadata/VFS 语义收口，包括 inline bounds、special `rdev`、pager、
namei、NFS generation 和真实压缩占用统计。
关键收尾与工程对齐提交：
| Commit | 已完成内容 |
|---|---|
| `c881f656` | 修复 48-bit superblock union、`OFF_MAX`、大 hole 内存和大目录索引等最终 metadata 边界；建立 TC150-TC153 与三份未决 issue。 |
| `4d51ca9e` | 停止跟踪 `build/obj`、生成头和架构 symlink，避免构建产物进入正式提交。 |
| `89594551` | 将 KLD 构建布局、源文件命名、架构门控和 `WITH_ZSTDIO` 方式与 FreeBSD/Linux 上游职责对齐。 |
| `2f2ac5a8` | 更新 README、architecture、refactoring plan/status，使构建、BSD API 差异和功能边界与源码一致。 |
| `077b37ab` | 删除会伪造覆盖或无条件 PASS 的旧 runner/wrapper，加入字段断言的 fixture transformer 与 FreeBSD probe，修订关键 TC 文档。 |
| `cd0e985b` | 完成最终 review finding：per-inode NFS generation、显式 extent 物理地址溢出检查、compact/extended timestamp 校验，并直接动态执行 TC154-TC156。 |
上述工作也包含多轮 code review 和 style review：源文件职责、函数顺序和磁盘 ABI
尽量贴近 Linux EROFS；FreeBSD vnode、pager、NFS、GEOM 和 `dev_t` 差异采用
FreeBSD 15 原生接口；磁盘长度、加法、移位和 signed/unsigned 转换按 fail-closed
原则处理。
## 已有动态验证
`tests/results/manual/` 中保留了各 feature 在对应历史 commit 上的真实 FreeBSD 15
动态证据。它们证明对应变更批次曾执行内核路径，但不能替代当前 final source 的
TC001-TC156 全量重跑。
| 批次 | 主要动态证据 | 当前解释 |
|---|---|---|
| 压缩 | compact/full LZ4、legacy full index、partial reference、MicroLZMA、DEFLATE、ZSTD、fragment、ztailpacking 和多种边界 source/hash compare | 历史 feature 证据存在；G5/G6 尚需在本轮 exact KLD 重跑。 |
| xattr/ACL/metabox | inline/shared/long-prefix xattr、ACL、metabox carrier 和 corruption errno | 历史 feature 证据存在；G4 尚未启动。 |
| directory/namei/pager | cold nested lookup、目录 padding、special `rdev`、真实 mmap/page fault 和 inline bounds | 历史 feature 证据存在；G1/G3 将按当前文档重跑。 |
| multi-device | 外部 provider、显式 slot、flatdev、unified address、fragment 和 orphan/error 路径 | 历史 feature 证据存在；G7 尚未启动。 |
| NFS | getfh/fhopen、同镜像重挂、同 md 替换、ESTALE、background/stress cleanup | 历史 feature 证据存在；G8 尚未启动。 |
| final review | TC150-TC152 动态 PASS；TC153 明确 SHELVED | 结果来自 `c881f656` 前后的 final-review 批次，不是 156 项全量 PASS。 |
当前 final source `cd0e985b` 的直接动态证据是
`tests/results/manual/2026-08-09T0557Z-review-fixes/manual-test-report.md`：
- FreeBSD 15.0-RELEASE-p8 amd64 上 `WITH_ZSTDIO=0` KLD SHA256 为
`d6e755c7a75dd5043b603d58215ae3e7c8f29318b31dc1885aa9bb070d6e57a5`。
- `WITH_ZSTDIO=1` KLD SHA256 为
`b442f9f05af1d1a76801690c83c9a40ec6fc739adb0663e7dacaf837eeb2ecf3`。
- TC154、TC155、TC156 均在该 final source 上直接动态 PASS，分别覆盖 per-inode
NFS generation、explicit extent `pa + plen` overflow 和 inode timestamp
validation。
- 该批结束时 EROFS mount、KLD 和 md provider 均已清理。
## 本轮八组全量回归
TC 编号范围为 TC001-TC156，共 156 项。以下集合经计数检查为总数 156、重复 0、
遗漏 0。
| 组 | 精确集合 | 数量 | 当前状态 |
|---|---|---:|---|
| G1 | TC001, TC007, TC009, TC011-TC014, TC019-TC040, TC147, TC150, TC151 | 32 | 已启动；正在修订文档和确定性 fixture，尚未形成 final-source 32 项结论。 |
| G2 | TC002, TC008, TC010, TC015-TC018, TC112-TC116, TC119 | 13 | 已启动；使用独立 worktree/VM，尚未形成 13 项结论。 |
| G3 | TC041-TC066, TC141, TC148, TC149, TC153 | 30 | 未启动。 |
| G4 | TC005, TC067-TC083, TC117, TC134-TC140, TC142 | 27 | 未启动。 |
| G5 | TC003, TC084-TC092 | 10 | 未启动。 |
| G6 | TC004, TC102-TC110, TC143-TC146, TC155 | 15 | 未启动。 |
| G7 | TC006, TC093-TC101, TC118 | 11 | 未启动。 |
| G8 | TC111, TC120-TC133, TC152, TC154, TC156 | 18 | 未启动。 |
G1/G2 的“已启动”只表示执行代理、工作目录和任务集合已经建立，不表示其中任何
TC 已在本轮计为 PASS。G8 中 TC154/TC156、G6 中 TC155 虽已有 `cd0e985b` 直接
证据，仍需由对应全量组在最终统计中明确引用或按组要求重跑，不能导致重复计数。
## 已完成与未完成
已完成：
- 核心 feature 实现、针对性 code review、FreeBSD 15 API 对齐和构建布局收口。
- 多个历史 feature 批次的真实 KLD 动态验证与清理记录。
- 当前 final source 的双配置构建和 TC154-TC156 直接动态验证。
- 移除旧 CI 风格 runner/wrapper，建立“逐 Markdown 手工执行”的验收规则。
- 三项已知验证缺口均有详细 issue，没有把未执行或环境受限结果标成 PASS。
未完成：
- TC001-TC156 在同一 final-source 基线族上的八组全量手工回归与最终汇总。
- G1/G2 的文档修订、fixture 固化、exact KLD 执行、逐 TC 报告和 push。
- G3-G8 的启动、独立环境分配、执行和结果提交。
- TC010 所需 16 TiB 级合格 provider、TC153 大目录内核路径、explicit extent
mapped compressed payload 的正向 fixture。
## Issue 索引
检查时 `issues/` 只有以下三份已跟踪文档，没有未提交 issue 文件或真实 issue
改动，因此本状态提交不修改 `issues/`。
| Issue | 状态 | 影响 feature | Shelved 原因 |
|---|---|---|---|
| `issues/TC010-48bit-statfs-large-provider.md` | SHELVED - environment unavailable | 48-bit block count、primary provider size validation、`statfs(2)`/`df` 总量和 root/block union 选择 | 非零 `blocks_hi` 在 4 KiB block 下至少要求 16 TiB GEOM provider；当前 vnode md 流程没有已验证、可安全清理的合格 provider。小 provider 拒绝和 TC150 fallback 都不能替代正向结果。 |
| `issues/TC153-large-directory-block-index-validation.md` | SHELVED - kernel validation incomplete | 超大目录二分索引、cold lookup、`EINTEGRITY` 传播和 negative namecache 正确性 | 已有可复现 FLAT_PLAIN fixture，但尚未在 FreeBSD fixed/pre-fix KLD 上完成冷查找对照；host 生成和静态审查不足以计 PASS。 |
| `issues/extent-metadata-fixture-unavailable.md` | SHELVED - positive fixture unavailable | explicit compressed extent parser、4/8/16/32-byte record、物理/逻辑高位、binary search、partial reference/fragment 映射 | erofs-utils 1.8.6 和已试 1.9.3 均不生成真实 mapped explicit-record payload。TC152 hole 与 TC155 overflow 只覆盖部分 header/negative 分支，不能替代正向压缩数据读取。 |
## 风险与依赖
- 并行组共享远端 `xdm/main`，每批 push 前必须重新 fetch/rebase 并确认没有覆盖其他
组的 TC、helper、report 或 issue。
- FreeBSD VM、SSH 端口、qcow overlay、md unit 和 mount point 必须按组隔离；任何
guest 残留都会污染后续动态证据。
- erofs-utils 的格式生成能力限制 explicit extent 等正向 fixture，必要时只能使用
字段自检、CRC32C-aware 的 structured transformer，不能手工猜偏移。
- 48-bit 大 provider、memory pressure、NFS stress 和性能 TC 对环境容量及稳定性要求
较高，环境不足时必须使用 `SHELVED/ISSUE` 或 `ENVIRONMENT-UNAVAILABLE`，不能
降低判据。
- 历史报告跨多个 commit。最终统计必须只接受对应 exact KLD 的本轮动态结果，或
明确标注尚未重跑，禁止把旧 HEAD 结果直接升级为全量 PASS。
## 下一步
1. 完成 G1/G2 文档和 fixture 修订，构建各自 exact KLD，逐 TC 手工执行并提交报告。
2. 每个先完成的组 fetch/rebase 最新 `xdm/main`，严格 pathspec 提交并正常 push。
3. 启动 G3/G4，随后按环境和依赖启动 G5-G8；压缩、multi-device、NFS 使用隔离 VM。
4. 对任何 kernel behavior failure 立即停止 PASS 计数，新增或更新有事实依据的 issue。
5. 八组结束后汇总 156 项，检查总数、重复、遗漏、KLD/image/source hash 和全部清理
证据，再发布 final-source 全量结论。
current/report-1/README.md
+8
View File
@@ -0,0 +1,8 @@
# repo22 当前状态索引
- [2026-08-09 总体进度](2026-08-09-overall-progress.md)：基线
`cd0e985b5ac54a4b7acb7042422329ad1729fb3e` 上的实现、历史动态证据、八组
全量回归分工、未决 issue、风险和下一步。
此目录记录阶段性状态；测试结果会随后续 commit 更新。正式逐项证据位于
`tests/results/manual/`，未决验证缺口位于 `issues/`。
current/report-2/2026-08-09-overall-progress.md
+123
View File
@@ -0,0 +1,123 @@
# repo22 第二次总体进度报告
更新时间：2026-08-09 UTC
权威统计快照：`381349b3847209a67d669264ac54a50a3599915c`
（该提交是当次 `xdm/main` 上完成 G3 报告后的快照）。
本报告只统计该快照已经提交的实现、正式批次和动态证据。TC060 源码修复与 G5
压缩回归正在并行进行，但在形成完整报告并提交前不提前计为 PASS，也不改变下述
冻结统计。
## 总体结论
- feature 实现、源码 code review、style review、FreeBSD 15 API 对齐和双配置构建
布局已经完成阶段性收口。
- 正式八组回归中，G1、G2、G3、G4 共执行 103 项：102 PASS，1 项
`TC060 KERNEL-FAIL` 正在修复。
- final review-fix 阶段还直接动态执行了 TC154-TC156，三项均 PASS。它们是三项
额外且不与前述 103 项重叠的 TC，因此当前共有 106 个不同 TC 具备动态结果，
其中 105 PASS、1 项待修。
- TC154-TC156 已分配给 G8，但先行 PASS 不能重复计入“已完成 G8”，也不能把 G8
标成已执行完毕。G8 尚有 TC111、TC131-TC133 未执行。
- TC010 与 TC153 已通过真实大 sparse provider 的 FreeBSD 内核路径验证并转为
RESOLVED。explicit extent 的 mapped compressed payload 正向 fixture 仍未获得，
对应 issue 尚未解决。
## 实现与审查
repo22 已完成以下阶段性工程工作：
- 实现并审查 superblock、compact/extended inode、plain/inline/chunk 数据、目录与
namecache、xattr/ACL/metabox、多算法压缩、fragment、multi-device、NFS export、
vnode pager 和 fail-closed 元数据边界。
- 对照 Linux EROFS 的磁盘 ABI、职责拆分和命名以降低长期维护偏差，同时保持
FreeBSD vnode、GEOM、pager、NFS、ACL 和 `dev_t` 语义为行为权威。
- 完成 overflow、长度、偏移、移位、signed/unsigned、目录大索引、48-bit union、
NFS generation、special vnode 和 timestamp 等多轮独立 code review 修复。
- 清理被跟踪的构建产物，统一 FreeBSD KLD 源文件布局、amd64 门控和
`WITH_ZSTDIO=0/1` 构建方式；当前构建仍以 kernel `-Werror` 为门槛。
- 删除会替代人工判定或无条件给出 PASS 的旧 CI 风格 runner/wrapper，保留可复现
fixture transformer 与原生 syscall/probe 工具。当前任务不实现 CI。
## 正式八组状态
八组精确集合总计 156 项，彼此无重复、无遗漏。
| 组 | 精确集合 | 数量 | 快照状态 |
|---|---|---:|---|
| G1 | TC001, TC007, TC009, TC011-TC014, TC019-TC040, TC147, TC150, TC151 | 32 | 32 PASS，正式批次完成。 |
| G2 | TC002, TC008, TC010, TC015-TC018, TC112-TC116, TC119 | 13 | 13 PASS，正式批次完成。 |
| G3 | TC041-TC066, TC141, TC148, TC149, TC152, TC153 | 31 | 31 已执行；30 PASS，TC060 KERNEL-FAIL。 |
| G4 | TC005, TC067-TC083, TC117, TC134-TC140, TC142 | 27 | 27 PASS，正式批次完成。 |
| G5 | TC003, TC004, TC084-TC092, TC102-TC110, TC143-TC146 | 24 | 压缩回归正在进行，尚无正式整组结论。 |
| G6 | TC006, TC093-TC101, TC118 | 11 | 尚未执行。 |
| G7 | TC120-TC130 | 11 | 尚未执行。 |
| G8 | TC111, TC131-TC133, TC154-TC156 | 7 | 正式整组未完成；TC154-TC156 已先行 PASS，TC111、TC131-TC133 尚未执行。 |
正式批次证据：
- [G1 报告](../../tests/results/manual/2026-08-09T0710Z-g1/manual-test-report.md)
- [G2 报告](../../tests/results/manual/2026-08-09T0710Z-g2/manual-test-report.md)
- [G3 报告](../../tests/results/manual/2026-08-09T1059Z-g3/manual-test-report.md)
- [G4 报告](../../tests/results/manual/2026-08-09T0839Z-g4/manual-test-report.md)
- [review-fix 报告](../../tests/results/manual/2026-08-09T0557Z-review-fixes/manual-test-report.md)
## 统计口径
正式批次已执行数为 `32 + 13 + 31 + 27 = 103`；PASS 数为
`32 + 13 + 30 + 27 = 102`，另有 TC060 一项 KERNEL-FAIL。
TC154-TC156 来自 review-fix 阶段的 exact-source FreeBSD 动态运行，并未包含在
G1-G4 的 103 项中。因此按“不同 TC 是否已有动态结果”计数，应增加三项，得到
106 个 TC 有动态结果、105 PASS、1 待修。按“正式组是否完成”计数时，三项仍属于
尚未完成的 G8，不能再次增加 PASS 数或宣称 G8 已完成。
## 大 Provider 验证
- TC010 使用逻辑长度 `17592193667072` 字节的 qualified sparse vnode provider，
动态挂载了 `blocks_hi=1` 的 48-bit EROFS，并验证 `df` 的 64-bit 总量无截断。
issue 已 RESOLVED。
- TC153 使用逻辑长度 `8796093091840` 字节的 sparse GEOM provider，令超大
FLAT_PLAIN 目录进入 `2147483648` 最终块索引的真实 kernel lookup 路径；固定 KLD
在 cold lookup 和 readdir 后均返回 `EINTEGRITY`，没有错误缓存为 `ENOENT`。
issue 已 RESOLVED。
- explicit extent 已动态覆盖 hole record、header 选择和部分负向分支，但仍缺少
mapped compressed payload 以及完整 record variant 的正向读取证据，不能关闭 issue。
## Issue 索引
| Issue | 当前状态 | 结论 |
|---|---|---|
| [TC060 standard pathconf](../../issues/TC060-pathconf-standard-values.md) | OPEN - KERNEL-FAIL | `_PC_NO_TRUNC` 与 `_PC_CHOWN_RESTRICTED` 返回 `EINVAL`；源码修复和复测正在进行。 |
| [TC010 48-bit statfs](../../issues/TC010-48bit-statfs-large-provider.md) | RESOLVED - qualified sparse vnode provider validated | qualified 16 TiB 级 sparse provider 已完成真实 mount/statfs/df 验证。 |
| [TC153 large directory index](../../issues/TC153-large-directory-block-index-validation.md) | RESOLVED - exact-source kernel validation passed | qualified 多 TiB sparse provider 已完成 exact-source 大索引 kernel lookup 验证。 |
| [Explicit extent fixture](../../issues/extent-metadata-fixture-unavailable.md) | SHELVED - positive fixture unavailable | issue 未解决；尚无使用 explicit-record parser 的 mapped compressed payload 正向 fixture。 |
## 当前风险
- TC060 是已确认的 FreeBSD kernel behavior failure，修复必须保持 NAME_MAX、PATH_MAX、
FILESIZEBITS、LINK_MAX、ACL 查询和未知键 errno 不回归，并完成 mount/md/KLD 清理。
- G5 同时覆盖 LZ4、MicroLZMA、DEFLATE、ZSTD、ztailpacking、partial reference、
explicit metadata 等多条压缩路径，fixture 资格和 `WITH_ZSTDIO` 配置差异仍是当前
最大执行风险。
- explicit extent 缺少上游工具可生成的 mapped positive fixture；静态 ABI 对照、
hole record 和 malformed case 不能替代真实压缩 payload 读取。
- G6 multi-device、G7 边界与压力类测试、G8 NFS/manual 页面仍需隔离 VM、精确 KLD、
direct syscall/数据比较和完整清理，历史 feature 报告不能自动升级为本轮结果。
- 并行 worktree 共享 `xdm/main`。每次 push 前必须 fetch/rebase，严格 pathspec，禁止
force push；guest mount、md、KLD 和临时 provider 残留必须清零。
## 下一步
1. 完成 TC060 根因修复，重跑全部 pathconf 键与基础 mount/read smoke，更新 issue
和 dated manual report。
2. 完成 G5 的 24 项压缩回归，提交 exact KLD、fixture hash、errno/数据比较与清理
证据。
3. 依次完成 G6 11 项、G7 11 项和 G8 剩余 TC111、TC131-TC133；在 G8 汇总中引用
或按要求复跑 TC154-TC156，但禁止重复计数。
4. 聚合 `TEST-COVERAGE-MATRIX`，审计 156 项总数、组间重复、遗漏、动态证据来源和
未解决 issue。
5. 完成最终独立 source review，检查 lock/resource/error path；执行
`WITH_ZSTDIO=0/1` 双配置 exact-source build，并做 `xdm/main`、remote/HEAD、
tracked clean 和 guest 清理的最终 audit。
current/report-2/README.md
+8
View File
@@ -0,0 +1,8 @@
# repo22 第二次状态报告索引
- [第二次总体进度报告](2026-08-09-overall-progress.md)：以
`381349b3847209a67d669264ac54a50a3599915c` 为统计快照，汇总实现与审查、
八组回归、动态结果计数、issue、风险和后续工作。
本目录只记录阶段性总体状态。各 TC 的命令、hash、errno、dmesg 和清理证据以
`tests/results/manual/` 中的对应报告为准。
current/report-3/2026-08-09-overall-progress.md
+124
View File
@@ -0,0 +1,124 @@
# repo22 第三次总体进度报告
更新时间：2026-08-09 UTC
权威验证快照：`12351cbb0a593474f4fcef68ffc5218d9c99dd46`
最终源码基线：`fcc85b93d5f8fd9671686bd68bf3b086c8bd25cf`
## 总体结论
本轮要求的 feature 全面验证、FreeBSD/Linux 行为差异审查、code review 和
style/可维护性优化已经完成。161 个可执行 Markdown 测试均已执行并形成受控
手工证据，最终为 160 PASS、1 PARTIAL、0 FAIL、0 KERNEL-FAIL、0 ENV。
唯一未完全关闭的是 TC146 的 explicit compressed extent mapped-payload 正向
fixture。该问题已按用户授权详细记录并搁置，不是已观察到的 kernel failure，
也不影响其他 160 个 TC 的结论。本轮目标因此完成，剩余工作属于已批准搁置项
或后续可选增强。
CI 和自动化 kernel-test harness 不在本轮范围内，未实现也未宣称完成。
## 已完成内容
- 完成 TC001-TC161 的规格、执行报告和覆盖矩阵机械审计；TC000 只作为模板。
- G1-G8 的 156 个表格行覆盖 TC001-TC156，恰好一次，无重复、无遗漏。
- 完成 TC157-TC161 独立回归，覆盖 explicit extent 全局顺序、48-bit compressed
block count、special vnode 组合 setattr、dot-omitted `OFF_MAX` cookie 和 `nm`
失败传播。
- TC010 的 16 TiB-plus statfs、TC060 的 FreeBSD pathconf、TC153 的超大目录索引
均已动态验证并转为 RESOLVED。
- 完成 superblock、inode、data、directory/namecache、xattr/ACL/metabox、压缩、
multi-device、NFS、pager、错误路径和边界算术的多轮独立 review。
- 保留 Linux EROFS 的磁盘 ABI、命名、函数顺序和职责拆分作为维护参照，同时以
FreeBSD vnode、GEOM、pager、NFS、ACL、`dev_t` 和 errno 语义为行为权威。
- 修正 README 的 NFS stale 承诺：generation 来自 superblock seed 和 inode
metadata；metadata-identical payload-only replacement 不保证 `ESTALE`。
- 清理 repo22 内全部 ignored build/object/image/repro/Python bytecode 产物；最终
guest 的 EROFS mount、md、EROFS KLD 和 DTrace KLD 计数均为零。
## 最终验证统计
| 状态 | 数量 | 说明 |
| --- | ---: | --- |
| PASS | 160 | 具备对应 dated manual report 的 FreeBSD 15 手工证据 |
| PARTIAL | 1 | TC146；HEAD2/interlaced PASS，explicit mapped payload 未完成 |
| FAIL / KERNEL-FAIL | 0 | 无开放 kernel 行为失败 |
| ENV | 0 | 无环境阻塞 |
| SHELVED test case | 0 | TC146 的子项不另计为 TC |
G1-G8 证据来自多个源码提交，不能表述为所有旧 TC 都运行在最终 KLD 上。最终
`fcc85b93d` 基线接受了 TC157-TC161、相关回归以及双配置 build/load/mount smoke。
## 最终构建
FreeBSD 15 kernel `-Werror` 双配置均成功：
| 配置 | KLD SHA256 |
| --- | --- |
| `WITH_ZSTDIO=0` | `15fda9d334132cd81769ce4dff4f8411a6e2b4cf7531c352530d0de85f42a2d2` |
| `WITH_ZSTDIO=1` | `23782dc0ce7da188807d35020bf2d8c6044b796c5c9a8746b398ba784cd6ad4e` |
TC161 的私有 `nm` shim 正确使构建失败且不发布新 KLD；移除 shim 后使用
`/usr/bin/nm` 的正常重建 exit 0。两个最终 KLD 均完成独立加载和只读挂载 smoke。
## Code Review 结论
最终独立复核未发现 P0/P1。已修复的最后一批问题包括：
- 16/32-byte explicit extent table 全局严格顺序验证；
- extended compressed inode 的完整 48-bit `blocks_hi` 解码；
- special vnode size 与其他 setattr 字段组合时的 false success；
- dot-omitted 目录在 `OFF_MAX` 的 cookie/offset overflow；
- `build.sh` 对 `nm` 自身失败的可靠传播；
- NFS generation 文档与真实实现边界不一致。
从社区第三方维护者视角，未发现仍需消除的非必要 Linux/FreeBSD 结构、命名或
职责差异。保留的差异均来自 FreeBSD kernel API、锁、provider、pager、NFS 或
权限模型要求。
## 未完成与搁置
唯一批准搁置项是
[explicit mapped extent payload](../../issues/extent-metadata-fixture-unavailable.md)：
- erofs-utils 1.8.6 不能生成或独立验证该新格式；
- 已尝试工具能力扫描、`--max-extent-bytes`、structured conversion、ABI/control
flow 对照以及多类负向 fixture；
- TC157 已证明 16/32-byte unordered table fail closed，但不能替代 mapped payload
的 source-identical 正向读取；
- 首个非零 `lstart` 和极大 extent-count 性能边界也保留为可选覆盖风险。
## 后续执行计划
1. 等待可生成并独立验证 explicit mapped-payload 的上游工具或可信 fixture。
2. 获得 fixture 后补充 4/8/16/32-byte 正向 record、partial reference、high words、
binary-search transition 和 final fragment 动态覆盖，使 TC146 从 PARTIAL 转 PASS。
3. 如后续项目另行启动 CI，再基于现有 Markdown 断言设计自动化；不得把当前手工
PASS 记录直接转换成无条件自动 PASS。
4. 后续源码变更继续执行受影响 TC、双配置 build、module smoke、scoped Git hygiene
和独立 review，不要求无差别重跑与改动无关的全部历史环境。
## 相关提交
正式八组手工验证：
- G1 `9ae22009f23a65320730072a780998e80aa9b728`
- G2 `aed7b68b79a5bd4115913f8361821c86fd58d2e2`
- G3 `381349b3847209a67d669264ac54a50a3599915c`
- G4 `f383bbbbff301a6bde18894f03ab88a8c0cc885a`
- G5 `c566d8ac6bf8e801082bbccf108451f6ee46ad40`
- G6 `f11fff5b8e8050e1017ed86f0bcf71042b2b45aa`
- G7 `f3ab2096fea3942317deb83fa051c84d3c124ec2`
- G8 `6f336d0a7387c8f110b19abad6e96f3ea17dba2e`
最终源码与验证收口：
- `f27b524a35b1c960be7e81884f9b928d9ac907e9`：metadata boundary 修复。
- `67d3c057fbcad5adc765ab9927da511e3221ac8f`：explicit extent header 解码修复。
- `fcc85b93d5f8fd9671686bd68bf3b086c8bd25cf`：TC157-TC161 规格与 helper。
- `12351cbb0a593474f4fcef68ffc5218d9c99dd46`：最终手工报告、覆盖、issue 和 README 汇总。
逐项证据见
`tests/results/manual/2026-08-09T1804Z-final-review-independent/manual-test-report.md`；
最终统计口径见 `docs/TEST_REPORT.md` 和 `tests/TEST-COVERAGE-MATRIX.md`。
current/report-3/README.md
+9
View File
@@ -0,0 +1,9 @@
# repo22 第三次状态报告索引
- [第三次总体进度报告](2026-08-09-overall-progress.md)：以
`12351cbb0a593474f4fcef68ffc5218d9c99dd46` 为最终验证快照，汇总已完成
feature 验证、code/style review、最终构建、剩余风险和后续计划。
本目录只记录本轮收尾状态。逐项命令、hash、errno 和清理证据以
`tests/results/manual/` 为准，issue 的触发、分析、尝试和验收条件以
`issues/` 为准。report-1 和 report-2 保留为历史快照，不因本报告改写。
current/report-4/2026-08-10-task2-code-review-style-assessment.md
+726
View File
@@ -0,0 +1,726 @@
# repo22 任务 2：全面代码审查与风格优化评估
日期：2026-08-10
性质：只读评估，不含源码修改、测试实现或 CI 变更
范围：原任务中的“2. 进行全面的 code review 和 style 优化”
## 1. 执行结论
本轮以第三方社区维护者视角，对 repo22 的 FreeBSD EROFS 实现进行了新的严格
静态审查。审查逐条回应原任务 2 的三个目标：
1. 判断实现是否合理复用 FreeBSD kernel 已有能力，是否存在不必要的重写，或
反过来存在不应强行引用内核实现的场景。
2. 判断 BSD 与 Linux 的行为差异是否被正确识别，避免把 Linux 共同缺陷误记为
BSD 移植差异，也避免为追求外观一致而破坏 FreeBSD VFS、GEOM 和 errno 契约。
3. 判断两个独立仓库在文件职责、函数和变量命名、定义顺序、磁盘 ABI、注释和
style 上是否已经消除非必要差异。
结论是：repo22 的 FreeBSD API 集成和核心算法映射已有良好基础，但任务 2 尚不
能认定为全面完成。本轮确认：
| 等级 | 数量 | 结论 |
| --- | ---: | --- |
| P0 | 0 | 未发现当前静态证据可确认的立即阻断问题 |
| P1 | 2 | vnode 生命周期 UAF；未压缩 physical run/chunk 大读的巨型分配与 `uiomove()` 长度截断 |
| P2 | 4 | 目录排序、根类型、compact 加法回绕、explicit extent 首次全表扫描 |
| P3 | 6 | errno、时间、symlink、48-bit 边界、setattr、FRAGMENTS 注释/死分支 |
这些新 finding 均未在本轮动态复现，也未修复。本报告给出的测试均是后续建议，
不是已执行结果。CI 明确不在本轮范围。
任务 1 已完成的 feature 验证和手工测试记录不在本报告中重写。静态审查发现的
新风险也不应被误读为已推翻全部既有功能证据；它们需要后续按优先级复现、修复
并回归。
## 2. 审计方法与限制
### 2.1 方法
本轮采用以下互相独立的证据层：
- **源码静态比对**：逐文件映射 repo22 与 Linux 7.1.0-rc1 `fs/erofs`，比较磁盘
ABI、核心算法、函数职责、函数顺序和命名。
- **FreeBSD 契约核对**：直接检查 FreeBSD 15.0-RELEASE-p9 中 vnode、VFS、GEOM、
`uio`、pager、ACL、extattr、XZ、ZSTD 和参考文件系统实现。
- **历史检查**：确认 repo22 最终源码提交、Linux 参考导入提交、tree hash、历史
测试入口和 UDF helper 的可追溯程度。
- **机械检查**：执行 FreeBSD `checkstyle9.pl`，检查文件树、共同编译单元顺序、
死声明、硬编码旧目录和许可证标识。
- **独立复核**：对高风险 vnode 生命周期、目录排序、根类型、只读 `setattr`、
许可证措辞、UDF 来源措辞、旧测试入口和 style 统计进行了二次静态复核。
### 2.2 限制
- 本轮没有启动新的 FreeBSD 动态测试批次。
- 新 finding 尚未通过 fault injection、损坏镜像、并发卸载或大 I/O 实测。
- 性能风险只根据分配和扫描路径分析，未给出吞吐、延迟或内存峰值数据。
- 许可证部分只陈述仓库可观察事实，不作法律结论。
- Linux 与 FreeBSD 是独立仓库；本报告只要求维护者可识别的相似性，不要求共享
Git 历史、构建系统或平台抽象。
- `checkstyle9.pl` 自身标记部分规则为 experimental，因此输出是审查输入，不能
自动等同为每一项都必须修改。
## 3. 可复现基线
### 3.1 BSD 目标
- repo22 HEAD：`76cfb553e0951b428f9d426933a10d1fe18d2a0e`
- 最终源码变更提交：`67d3c057fbcad5adc765ab9927da511e3221ac8f`
- 当前 `src/` tree：`a605af0f01f83d67c199005e775e1a47a1610036`
- 从 `67d3c057f` 到本报告基线 HEAD，`src/` tree 未再变化。
### 3.2 Linux 独立参考
- 精简参考：`/work/dev-src-linux/fs/erofs`
- 版本：Linux 7.1.0-rc1
- 本地导入提交：`8be2be573d2b191c83d760b65c554f78eb95893c`
- EROFS tree：`b79b9a8b62f633e887a8b99075ff9412fabd7f83`
- `/work/linux-src/fs/erofs` 与精简参考内容及 tree hash 相同。
该 Linux 树只作为独立源码参考，不要求与 repo22 共仓。当前 `/work` 开发环境内
可以用提交和 tree hash 验证其身份；只获得独立 repo22 的社区维护者，则无法从
现有 repo22 文档唯一重建该基线，详见第 10 节。
### 3.3 FreeBSD API 参考
- 路径：`/work/dev-freebsd-releng`
- 版本：FreeBSD 15.0-RELEASE-p9
- 重点契约：`insmntque()`、`uiomove()`、`vfs_read_dirent()`、GEOM VFS、vnode pager、
POSIX.1e ACL、extattr、XZ Embedded、ZSTDIO 和参考文件系统。
### 3.4 提交卫生
创建 report-4 前，repo22 scoped tracked、staged、untracked 状态均为 0，且
`HEAD == xdm/main`。本次提交范围限定为 `current/report-4/`，不会修改既有源码、
测试、文档、issues、report-1 至 report-3 或 `current/README.md`。
## 4. 文件职责映射
### 4.1 共同或语义对应文件
| repo22 | Linux `fs/erofs` | 维护者视角结论 |
| --- | --- | --- |
| `src/erofs_fs.h` | `erofs_fs.h` | 磁盘 ABI 应最严格对齐；字段布局正确性优先于平台风格 |
| `src/internal.h` | `internal.h`, `compress.h` | 内存结构和接口语义对应，FreeBSD 类型必然不同 |
| `src/super.c` | `super.c` | superblock、设备表、mount、statfs、生命周期 |
| `src/inode.c` | `inode.c` | inode 解码；Linux inode ops 由 BSD vnops 分担 |
| `src/data.c` | `data.c` | block/chunk mapping 对应；folio/iomap 改为 buffer/GEOM/uio |
| `src/dir.c` | `dir.c` | 目录结构解析对应；cookie 和 dirent 输出是 BSD 适配 |
| `src/namei.c` | `namei.c` | 两级二分搜索语义高度对应；namecache/锁为 BSD 适配 |
| `src/xattr.c` | `xattr.c` | 磁盘 xattr 解析对应；namespace、ACL、extattr API 不同 |
| `src/xattr.h` | `xattr.h` | 只应保留 FreeBSD 实际接口，当前仍有 Linux 残片 |
| `src/decompressor.c` | `decompressor.c` | dispatcher 对应；配置职责仍有非必要差异 |
| `src/decompressor_lzma.c` | `decompressor_lzma.c` | 算法对应；FreeBSD 侧私有嵌入 XZ Embedded |
| `src/decompressor_deflate.c` | `decompressor_deflate.c` | 直接调用 FreeBSD zlib，方向正确 |
| `src/decompressor_zstd.c` | `decompressor_zstd.c` | 使用内核 ZSTDIO，方向正确 |
| `src/zmap.c` | `zmap.c` | 压缩映射核心最接近 Linux，函数顺序对齐质量高 |
| `src/zdata.c` | `zdata.c` | 职责对应；同步读取与 Linux folio/pcluster pipeline 必然不同 |
| `src/Makefile` | `Makefile`, `Kconfig` | 只比较编译单元职责和顺序，不比较构建语法 |
### 4.2 Linux-only 文件，不应为了外观模拟
| Linux-only 文件 | 不在 repo22 创建空文件的理由 |
| --- | --- |
| `sysfs.c` | FreeBSD 无 Linux sysfs 模型，mount/sysctl 语义需独立设计 |
| `fileio.c` | Linux file-backed I/O 路径与当前 GEOM provider 模型不同 |
| `fscache.c` | Linux fscache/netfs 子系统在 FreeBSD 无直接对应 |
| `ishare.c` | Linux inode/xattr sharing 生命周期依赖其 VFS 内部模型 |
| `zutil.c` | Linux folio、bio、pcluster 工具层不适用于同步 BSD 读取路径 |
| `decompressor_crypto.c` | Linux Crypto API 后端在当前 FreeBSD 目标中无对应承诺 |
| `compress.h` | Linux 压缩调度、folio 和 stream 数据结构不能机械复制 |
缺少这些文件是必要平台差异，不是结构欠缺。为了目录看起来相同而新增空壳，会
制造虚假维护入口。
### 4.3 BSD-only 文件
| BSD-only 文件 | 必要性结论 |
| --- | --- |
| `src/erofs_vnops.c` | 必要。集中实现 VOP、pager、ACL、NFS file handle 和只读语义 |
| `src/lz4.c` | 必要。FreeBSD/OpenZFS LZ4 接口不匹配 EROFS raw block 和 partial 输出 |
| `src/erofs_defs.h` | 文件本身可存在，但当前含部分仅定义未使用的宏，必要性需缩减 |
## 5. Findings First
以下只列入已经过独立静态复核、或任务指定为已复核的结论。每项明确其类别，
避免把 Linux 共同问题写成 BSD 行为差异。
### 5.1 P0
无。
### 5.2 P1-1：`insmntque()` 失败后继续访问已回收 vnode
- **位置**：`src/inode.c:452` 调用 `insmntque()`；失败分支在
`src/inode.c:453-457` 释放 `en` 后又于 `src/inode.c:455` 写
`vp->v_data = NULL`。
- **FreeBSD 对照**：`sys/kern/vfs_subr.c:2303-2315` 在插入失败时清空
`v_data`、切换 dead ops、执行 `vgone()` 和 `vput()`；
`sys/kern/vfs_subr.c:2328-2341` 明确说明 `insmntque()` 会在失败时回收 vnode，
只有 `insmntque1()` 把清理留给调用者。
- **参考实现**：`sys/fs/cd9660/cd9660_vfsops.c:717-721` 失败后只释放私有
inode，不再解引用 vnode。
- **Linux 对照**：Linux `fs/erofs/inode.c` 使用 `iget5_locked()` /
`iget_failed()` 管理不同的 inode 生命周期，不能机械复制，但同样要求失败路径
不访问已交还对象。
- **触发与影响**：vnode 构造与强制或并发卸载竞争，进入
`MNTK_UNMOUNT`/`MNTK_UNMOUNTF` 失败路径。后续写可能成为释放后访问，并可能
清空已经复用 vnode 的 `v_data`，属于内核内存安全风险。
- **类别**：BSD 独有缺陷，源于 FreeBSD vnode 所有权契约。
- **修复方向**：采用 cd9660 所示所有权模式，失败后释放私有 `en`、清空输出并
返回，不再访问 `vp`。是否改用 `insmntque1()` 必须有明确的完整清理理由。
- **建议 Markdown 手工测试**：新增并发冷 lookup/getfh 与 `umount -f` 测试，
配合 vnode 分配压力；在 INVARIANTS/WITNESS 内核下记录 panic、WITNESS、引用
计数和清理状态。建议增加仅测试用故障注入以确定性触发插入失败。
- **状态**：已静态复核；未动态复现；未修复。
### 5.3 P1-2：一般未压缩 physical run/chunk 大读可触发巨型 `M_WAITOK` 分配和 `uiomove()` 长度截断
- **位置**：`src/data.c:493-500` 直接从 `uio_resid` 和映射 run 计算 `want`；
`src/data.c:514-518` 把该 `size_t` 长度传入读取路径；
`src/data.c:208-245` 的 `erofs_bread_device()` 使用
`malloc(len, M_EROFS, M_WAITOK)` 分配连续缓冲；`src/data.c:521` 再把 `size_t want`
传给 `uiomove()`。
- **FreeBSD 对照**：`sys/sys/uio.h:95` 声明
`int uiomove(void *cp, int n, struct uio *uio)`。因此大于等于 2 GiB 的 `size_t`
长度在传参时不能被该接口正确表达，可能截断为负值或零值并造成错误或无进展。
- **Linux 对照**：Linux `fs/erofs/data.c` 使用 folio/iomap 分页路径，不建立与
整个用户请求同尺寸的连续内核缓冲。该差异来自 I/O 模型，但当前无界分配不是
FreeBSD 所要求的必要差异。
- **触发与影响**：恶意或异常大 chunk/run，配合大 `VOP_READ`/`uio_resid`。影响
包括用户可控的巨型 `M_WAITOK` 连续内核分配、系统内存压力、长时间阻塞，以及
大于等于 2 GiB 时 `uiomove()` 截断或循环无进展。
- **类别**：BSD 独有缺陷，属于 I/O 分块和内核 API 宽度处理问题。
- **修复方向**：把读取固定分块到同时满足 buffer cache、`INT_MAX` 和合理内存
上限的尺寸；每轮验证 `uio_resid` 或 offset 必须前进；避免按整个 run 分配。
- **建议 Markdown 手工测试**：构造超大 chunk/run 的稀疏镜像，分别测试
`INT_MAX-1`、`INT_MAX`、`INT_MAX+1` 和大于 2 GiB 请求；记录 wired memory、
malloc failure、进度、信号中断、errno 和 mount/KLD 清理。测试必须设置资源
上限，避免把宿主机作为压力目标。
- **状态**：已静态复核；未动态复现；未修复。
### 5.4 P2-1：目录名称排序不变量未验证
- **位置**：`src/dir.c:72-109` 校验 dirent 数量、`nameoff` 单调、名称长度和非法
`/`，但不比较相邻名称；`src/namei.c:55-100` 执行块内二分，
`src/namei.c:103-125` 开始跨块二分选择。
- **Linux 对照**：Linux `fs/erofs/erofs_fs.h:280` 记录目录项按字典序排列；
Linux `fs/erofs/namei.c:45` 起的查找同样依赖该不变量，也未做全局排序验证。
- **触发与影响**：结构合法但名称降序、重复或跨块逆序的损坏镜像。实际存在的
名称可被静默返回为 `ENOENT`，随后建立负 namecache，使错误持续存在。
- **类别**：Linux 共同依赖的格式不变量；在 repo22“损坏结构返回
`EINTEGRITY`、不得静默 miss”的更严格政策下，是 BSD 当前一致性缺口，不应
描述成 BSD/Linux 行为差异。
- **修复方向**：对不可变目录执行一次全局严格递增验证，覆盖块内、跨块和重复
名称，并缓存结果；损坏统一返回 `EINTEGRITY`，不得写入负缓存。
- **建议 Markdown 手工测试**：构造块内降序、块内重复、跨块逆序、跨块重复四类
镜像；冷 lookup、重复 lookup、readdir 和 NFS lookup 均应返回
`EINTEGRITY`，并验证 namecache 无错误负项。
- **状态**：已静态复核；未动态复现；未修复。
### 5.5 P2-2：根 vnode 未验证为目录
- **位置**：`src/super.c:759-768` 的 `erofs_root()` 只调用 `erofs_vget()`；
`src/inode.c:471-475` 按 inode mode 设置 vnode 类型，并仅按 NID 设置 `VV_ROOT`。
- **Linux 对照**：Linux `fs/erofs/super.c:765-774` 加载 root inode 后明确执行
`S_ISDIR()`，非目录则释放并返回 `-EINVAL`。
- **FreeBSD 对照**：VFS mount 后续不会替 EROFS 强制验证其 `VFS_ROOT()` 返回
`VDIR`，文件系统必须自行维持该不变量。
- **触发与影响**：checksum-valid、但 root inode mode 被改为普通文件、symlink
或 FIFO 的镜像可能完成挂载；挂载点后续出现 `ENOTDIR` 或异常 vnode 语义。
- **类别**：BSD 独有缺口；Linux 已显式处理。
- **修复方向**：`erofs_vget()` 成功后验证 `(*vpp)->v_type == VDIR`，失败时正确
`vput()`。errno 可对齐 Linux 使用 `EINVAL`，或按 repo22 损坏政策使用
`EINTEGRITY`，但需统一文档。
- **建议 Markdown 手工测试**：分别生成 root inode 为 VREG、VLNK、VFIFO 的
checksum-valid 镜像，验证挂载失败、errno 稳定、无 mount/md/KLD 残留。
- **状态**：已静态复核；未动态复现；未修复。
### 5.6 P2-3：compact index 物理块号加法先发生 32-bit 回绕
- **位置**：`src/zmap.c:267`：
`m->pblk = le32dec(...) + nblk;`。`le32dec()` 和 `nblk` 均为 32-bit 范围，表达式
在赋给 64-bit `m->pblk` 前可能已经回绕。
- **Linux 对照**：Linux `fs/erofs/zmap.c:230-232` 使用同样的
`le32_to_cpu(...) + nblk` 结构，因此 Linux 参考也存在相同风险。
- **触发与影响**：基准物理块接近 `UINT32_MAX` 且 compact 索引累计 `nblk` 非零，
映射到错误的低地址，可能读到错误数据或触发后续一致性错误。
- **类别**：Linux 共同缺陷，绝不能为了源码相似而保留，也不能记成 BSD 差异。
- **修复方向**：在加法前显式提升到 64-bit，并使用 checked addition；随后按设备
块范围验证。
- **建议 Markdown 手工测试**：构造 base pblk 接近 `UINT32_MAX`、累计跨越边界的
compact 索引，验证映射不会回绕；同时测试恰好不溢出的边界和真实设备范围错误。
- **状态**：已静态复核；未动态复现；未修复。
### 5.7 P2-4：explicit extent 首次初始化执行有界 O(N) 全表扫描
- **位置**：`src/zmap.c:581-619` 的 `z_erofs_validate_extent_table()` 在首次初始化
时从 `index=0` 到 `en->z_extents-1` 逐项读取并验证严格递增；调用后才进入
二分映射路径。
- **Linux 对照**：Linux `fs/erofs/zmap.c:501-588` 映射 explicit extent 时按需
二分读取，没有 repo22 这一首次完整预扫描。
- **触发与影响**：超大 extent 表在首次访问时产生 O(N) 元数据 I/O 和延迟，攻击
者可用格式边界内的大计数制造明显可用性压力。
- **边界说明**：循环由 `en->z_extents` 严格限制，记录位置使用 checked arithmetic，
并验证 `lstart` 严格递增。当前证据不支持“无限循环”或“无边界访问”的说法。
- **类别**：BSD 独有的性能/可用性权衡，源于更严格的全表不变量验证，不是立即
correctness 失败。
- **修复方向**：先量化真实最坏情况。可评估分段验证、验证结果缓存、mount-time
预算或按二分访问范围逐步验证；任何优化都不能重新引入静默错误映射。
- **建议 Markdown 手工测试**：生成多档 extent count 的合法/末尾损坏表，测量
首次与重复 lookup/read 延迟、I/O 次数和内存；验证预算超限时 errno 和清理。
- **状态**：已静态复核；未做性能原型；未修复。
### 5.8 P3-1：DEFLATE 分配失败被统一映射为 `EIO`
- **位置**：`src/decompressor.c:246-257` 将所有后端非零返回统一转换为 `EIO`；
`src/decompressor_deflate.c` 的分配失败因而不能保留 `ENOMEM`。
- **Linux/FreeBSD 对照**：平台均区分资源耗尽和输入/设备错误；调用 FreeBSD
zlib 是正确的，但 wrapper 的返回契约过窄。
- **影响**：内存压力下诊断和上层重试策略失真。
- **类别**：BSD 独有 errno 映射问题。
- **修复方向**：后端返回正 errno，dispatcher 只做必要规范化。
- **建议测试**：故障注入 DEFLATE workspace/output 分配失败，要求 `ENOMEM`；损坏
流仍应为 `EIO` 或项目约定的完整性错误。
- **状态**：已静态复核；未动态复现；未修复。
### 5.9 P3-2：负 Unix 时间被拒绝，和 Linux 语义不一致
- **位置**：`src/inode.c:60-68` 以 `uint64_t seconds` 接收时间，并拒绝大于
`INT64_MAX` 的值。
- **Linux 对照**：Linux `fs/erofs/inode.c:108-109` 将磁盘 extended inode 的
64-bit 时间传给 inode time；Linux 时间模型允许 1970 年前的负时间语义。
- **影响**：使用补码表达负秒值的镜像在 BSD 被视为损坏，形成跨平台兼容差异。
- **类别**：BSD/Linux 行为差异，格式签名语义需先与上游规范确认。
- **修复方向**：确认磁盘字段的正式有符号语义，再采用显式 signed 解码和 FreeBSD
`timespec` 范围检查。
- **建议测试**：覆盖 `-1`、`INT64_MIN` 邻近值、epoch 和正最大值，在 Linux/BSD
上比较 stat 结果与 errno。
- **状态**：静态候选已复核；格式语义仍需上游确认；未修复。
### 5.10 P3-3：inline symlink 未拒绝声明长度内嵌 NUL
- **位置**：`src/data.c:529-533` 的 readlink 直接复用普通读取路径；
`src/data.c:493-525` 按 inode 声明长度移动字节，没有对 symlink payload 做 NUL
一致性检查。
- **Linux 对照**：Linux 同样主要依赖 inode size 和 VFS symlink 语义；本项不是
用于制造表面差异，而是要求 BSD 明确损坏镜像政策。
- **影响**：声明长度内部出现 NUL 时，不同调用者可能观察截断或不一致目标。
- **类别**：损坏输入处理缺口，是否需要拒绝应与 EROFS 格式语义统一。
- **修复方向**：确认格式是否禁止嵌入 NUL；若禁止，在 inode/readlink 验证中返回
`EINTEGRITY`，且不得影响合法非 NUL 目标。
- **建议测试**：inline 和非 inline symlink 分别构造中间 NUL、末尾 NUL、无 NUL
目标，比较 `readlink(2)`、namei 跟随和 NFS 行为。
- **状态**：静态候选已复核；格式语义待确认；未修复。
### 5.11 P3-4：48-bit end-exclusive 检查拒绝最后一个合法完整块
- **位置**：`src/zmap.c:895-898` 计算 `pend = m_pa + m_plen`，随后以
`(pend >> block_bits) >= (1ULL << 48)` 拒绝映射。
- **Linux 对照**：Linux 参考中的相关 48-bit 映射边界也存在同类 end-exclusive
处理风险。
- **触发与影响**：映射恰好结束在 48-bit 地址空间上界时，`pend` 是合法的
end-exclusive 值，但当前检查把最后一个完整合法块拒绝为 `EINTEGRITY`。
- **类别**：Linux 共同边界缺陷，不是 BSD 差异。
- **修复方向**：校验最后一个实际字节/块，或使用 `pend > limit` 的 byte limit
比较，并单独处理零长度。
- **建议测试**：覆盖最后合法块、越界一字节、越界一块和零长度映射。
- **状态**：已静态复核；未动态复现；未修复。
### 5.12 P3-5：birthtime-only `VOP_SETATTR()` 可假成功
- **位置**：`src/erofs_vnops.c:252-281` 检查 mode、uid、gid、atime、mtime、flags
和 size，但不检查 `va_birthtime`，最终可能返回 0。
- **FreeBSD 对照**：`VATTR_NULL()` 会把 birthtime 设为 `VNOVAL`，内核调用者可以
构造仅 birthtime 有效的请求。
- **触发与影响**：直接内核 VOP 调用可收到成功但属性未改变，违反只读 VOP 语义。
- **路径限定**：独立复核未确认普通用户态或 NFSv4 可绕过只读 mount 检查到达该
单属性路径，因此不能声称已有用户/NFS 可利用的假成功链。
- **类别**：BSD 独有 VOP 契约和未来维护问题，严重度降为 P3。
- **修复方向**：birthtime 变更返回 `EROFS`；对 type、nlink、fsid、fileid、
blocksize、rdev、bytes、generation 等结构字段明确返回 `EINVAL`。
- **建议测试**：扩展内核 probe，直接提交 birthtime-only 和各结构字段请求；本地
syscall 与 NFS 测试用于确认它们仍被只读层拒绝。
- **状态**：已静态复核；无已证实用户/NFS 路径；未修复。
### 5.13 P3-6：FRAGMENTS 特例分支不可达，注释与支持边界失配
- **位置**：`src/erofs_fs.h:56-64` 已把 `EROFS_FEATURE_INCOMPAT_FRAGMENTS` 放入
`EROFS_ALL_SUPPORTED_INCOMPAT`；`src/super.c:532` 因而从 `unsupported` 中清除该
bit，但 `src/super.c:533-549` 又试图在 `unsupported != 0` 时特例允许仅
FRAGMENTS 的组合。
- **Linux 对照**：Linux 通过实际 fragment/packed inode 路径表达支持，不需要
这种与 supported mask 自相矛盾的特例。
- **影响**：当前分支不可达，注释声称“窄允许”但真实代码已经把 FRAGMENTS 当作
一般 supported incompat bit，误导维护者判断支持边界。
- **类别**：BSD 独有死分支和文档一致性问题。
- **修复方向**：依据真实 feature 支持政策二选一：从 supported mask 移除后保留
严格特例，或删除死分支并准确文档化支持范围。
- **建议测试**：组合测试 FRAGMENTS、XATTR_PREFIXES、PLAIN_XATTR_PFX 和
`packed_nid`，记录 mount errno 和实际 fragment inode 访问结果。
- **状态**：已静态复核；未动态复现；未修复。
### 5.14 不列为 correctness finding：fragment `pstart_hi`
曾有候选认为 fragment extent 构造会丢失 `pstart_hi`。当前静态证据不足以确认该
字段在 fragment 记录格式中具有同样的高位语义，也不足以证明当前路径实际丢失
可用地址。因此本报告不把它列为 correctness finding，只保留为“与上游格式语义
确认”的待办。后续必须先取得格式规范或上游实现证据，再决定是否测试或修改。
## 6. FreeBSD 最佳实践与原生能力复用
| 领域 | 当前做法 | 评估与决策 |
| --- | --- | --- |
| DEFLATE | `src/decompressor_deflate.c:28` 起调用 FreeBSD zlib | 正确复用；应保留，修正 errno 契约即可 |
| ZSTD | `src/decompressor_zstd.c` 使用 ZSTDIO API | 正确复用；FreeBSD 无通用独立 zstd KLD，不应伪造依赖 |
| MicroLZMA | `src/decompressor_lzma.c:14-38` 私有重命名并编译 XZ Embedded | 应保留本地实现；stock `xz.ko` 未定义 `XZ_DEC_MICROLZMA`，不能强行链接 |
| LZ4 | `src/lz4.c:21` 起实现 raw/partial decoder | 应保留；FreeBSD/OpenZFS 接口含不同 framing，且不满足 EROFS partial 语义 |
| 目录输出 | `src/dir.c:160-178` 自有 cookie helper | 不能机械替换；它额外验证 cookie 严格递增和容量短读 |
| `vfs_read_dirent()` | FreeBSD `sys/kern/vfs_subr.c:6814-6830` | 可原型化为输出层 helper，但必须保留 EROFS cookie 约束并回归 NFS |
| GEOM/VFS I/O | `src/super.c:226` 建 consumer，`src/data.c:250` 用 `bread()` | 符合 FreeBSD 文件系统惯用路径，不应改为 GEOM class 私有读接口 |
| vnode cache | `src/inode.c:435-460` 用 `vfs_hash_get/insert` | 总体正确；仅 `insmntque()` 失败所有权需修复 |
| pager | `src/erofs_vnops.c:434` 复用 local pager | 正确，避免重写 VM pager |
| ACL/extattr | `src/erofs_vnops.c:68` 等调用 POSIX.1e ACL/extattr API | 正确保留 BSD namespace 和权限差异 |
| CRC32C | `src/super.c:307` 使用 `calculate_crc32c()` | 正确复用 FreeBSD kernel helper |
| endian | 磁盘字段使用 `leXXtoh`，非对齐流使用 `leXXdec` | 正确；不应直接复制 Linux unaligned 宏 |
| checked arithmetic | 多处使用 compiler overflow builtin | 合理；FreeBSD 15 无更优的通用非 LinuxKPI 替代 |
### 6.1 为什么不能强行依赖 `xz.ko`
FreeBSD `sys/modules/xz/Makefile:5-20` 会编译 `xz_dec_lzma2.c` 并导出符号，但没有
定义 `XZ_DEC_MICROLZMA`。MicroLZMA 入口受该宏控制，因此 stock `xz.ko` 不提供
repo22 所需的 `xz_dec_microlzma_*` ABI。简单添加 `MODULE_DEPEND(erofs, xz, ...)`
不能解决符号缺失。
只有在 FreeBSD 正式启用并导出 MicroLZMA KPI，同时更新模块 ABI/version 后，
repo22 才应重新评估直接依赖。当前强行引用反而违反“优先复用，但不强制引用一切”
的原任务要求。
### 6.2 LZMA per-call allocation 是性能原型事项
`src/decompressor_lzma.c:55-66` 每次解压分配并释放 decoder state。Linux 使用可
复用 stream pool。当前没有证据证明它造成 correctness 错误，但并发压缩读取会
产生约 30 KiB state 的反复 malloc/free 和锁竞争。
后续应单独做 per-CPU、mount-local 或受限 pool 原型，测量并发吞吐、内存峰值、
卸载清理和字典变化。没有数据前，不应把缓存重构混入 correctness 批次。
## 7. BSD/Linux 行为差异分类
### 7.1 必要的 BSD 差异
- 正 errno，而不是 Linux 内核负 errno。
- VOP/VFS operation table、vnode lock、namecache、`vn_vget_ino()` 和
`vfs_hash_*` 生命周期。
- GEOM consumer、设备 vnode 和 buffer cache I/O，而不是 folio/iomap/bio。
- FreeBSD extattr user/system namespace、`extattr_check_cred()` 和 POSIX.1e ACL。
- readdir 的 `a_cookies`/`a_ncookies` ABI、synthetic dot cookie 和 NFS 恢复语义。
- `fifo_specops`、FreeBSD FID 布局、generation 与 `ESTALE` 校验。
- pager 使用 `vnode_pager_local_getpages*`。
这些差异应保留，不应为了外观接近 Linux 而移除。
### 7.2 Linux 共同缺陷
- compact index 32-bit 加法回绕，见 `src/zmap.c:267` 与 Linux
`fs/erofs/zmap.c:231`。
- 48-bit end-exclusive 最后合法块边界。
- 目录二分依赖排序；Linux 也未全局验证。repo22 可选择更严格验证，但不能把
上游共同不变量说成 BSD 偏差。
源码相似不是保留共同缺陷的理由。修复时应尽量沿用上游命名和 checked arithmetic
结构，并把可上游化的发现单独记录。
### 7.3 BSD 独有缺陷
- `insmntque()` 失败后的 vnode 释放后访问。
- chunk 大读的整段 `M_WAITOK` 分配和 `size_t` 到 `int` 的 `uiomove()` 传参。
- root vnode 未检查 `VDIR`。
- DEFLATE errno 归一化过度。
- birthtime-only `VOP_SETATTR()` 假成功。
- FRAGMENTS supported mask 与特例注释矛盾。
### 7.4 非必要维护差异
- `erofs_fs.h` 定义顺序、常量命名和字段注释没有尽量保持 Linux 顺序。
- 压缩配置 loader 集中于 `decompressor.c`，而 Linux 分布在各 backend。
- backend 函数名使用 `lzma_decompress`、`deflate_decompress`、
`zstd_decompress`，没有采用 Linux `z_erofs_*` 体系。
- `xattr.h`、`internal.h`、`erofs_defs.h` 中仍有失效 Linux 声明或未使用抽象。
- xattr prefix helper 命名、部分函数定义位置和空包装与 Linux 无必要不同。
### 7.5 需要原型或格式确认后再判断
- fragment extent 的 `pstart_hi` 语义。
- LZMA decoder state 缓存。
- 保留 cookie 验证的 `vfs_read_dirent()` 输出适配器。
- explicit extent 全表验证的分段/缓存策略。
- negative timestamp 与 inline symlink NUL 的正式格式语义。
## 8. 结构、命名和 style 对齐
### 8.1 正向对齐结果
- repo22 与 Linux 有 15 个共同 C/H 文件名。
- `src/namei.c` 的核心名称查找函数名称和顺序高度对应 Linux。
- `src/zmap.c` 的 13 个共享核心算法函数保持相同相对顺序，是当前对齐质量最高的
文件之一。
- `src/Makefile` 中 12 个共同编译单元保持与 Linux Makefile 相同的相对顺序。
- `erofs_vnops.c` 集中 BSD VOP glue，避免把 FreeBSD 代码散入所有 Linux 对应
算法文件，这一文件级差异是必要且有利于维护的。
### 8.2 `erofs_fs.h` 的非必要差异
BSD 与 Linux 都包含同一组核心磁盘结构，但 repo22 的结构顺序、常量命名和注释
存在明显漂移。例如 repo22 从 `src/erofs_fs.h:104` 定义 superblock，而 Linux
先定义 deviceslot；dirent、chunk index、map header 和 lcluster index 的位置也有
移动。机械审查对 19 个核心 struct/union 记录到 31/171 个顺序逆序对，顺序相似度
约 81.9%。
字段 packing、offset、endian 和 `_Static_assert` 是 correctness 约束，应保留 BSD
表达；结构定义顺序、字段语义注释和非平台相关名称则应尽量恢复 Linux，以降低
未来磁盘格式同步成本。`EROFS_ALL_SUPPORTED_INCOMPAT` 与 Linux 名称不同，也应
先判断是否存在真实语义差异，再决定是否保留。
### 8.3 压缩职责和命名
repo22 把 LZMA、DEFLATE、ZSTD 配置解析集中在 `src/decompressor.c`，Linux 则分别
放在对应 backend。调用 ABI 必须因 FreeBSD 内核 API 而不同，但配置 loader 的
文件职责和 `z_erofs_*` 命名并无平台限制。
建议在 correctness 修复完成后，单独评估把配置解析移回各 backend，并统一内部
命名。该重排必须保持双配置构建和全部压缩 Markdown 测试，不应与 P1/P2 修复混在
同一提交。
### 8.4 死代码和残留抽象
- `src/xattr.h:11-42` 保留注释掉的 Linux `CONFIG_*` 分支、未实现的
`erofs_xattr_handlers`、`struct inode` 和 `struct posix_acl` 声明。
- `src/internal.h:50-71` 保留未使用的同步解压/cache 枚举和 `erofs_buf`；
`src/internal.h:243-247` 的 `erofs_is_fileio_mode()` 固定返回 false。
- `src/erofs_defs.h:5-19` 的 CRC polynomial、inode slot bits 和 range-coder 常量
多项仅定义未使用；`src/inode.c:137-139` 仍直接使用字面量 5。
- `src/super.c` 的部分空包装和函数顺序可进一步与 Linux/FreeBSD 惯例收敛，但应
放在纯维护提交中。
### 8.5 失效测试入口和 harness
- `test_all_decompress.sh:2-7` 仍标记 repo19；其 `SRCDIR` 当前未实际使用，但测试
内容不验证 repo22 KLD。
- `test_chunk_based.sh:2-17` 实际进入 repo17，后续会 clean、写镜像、卸载模块、
配置 md 和 mount，具有真实误操作其他目录和全局系统状态的风险。
- `tests/test_decompress.c` 与 `tests/test_decompress_standalone.c` 已无法通过当前语法
检查，并仍按旧参数数量调用后端接口；当前接口见 `src/internal.h:314-322`。
`docs/architecture.md:242-245` 已声明这两个根脚本不能作为验收入口，但只写文档
不足以消除可执行误入口。后续应删除、移入明确的 historical 目录，或改为立即失败
并指向 `tests/TC*.md`。
### 8.6 文档陈旧
- `docs/architecture.md:79` 的 `erofs_mount` 示例与当前
`src/internal.h` 结构不一致，字段如 `z_algorithmformat`、`fragmentoff` 已陈旧。
- `docs/architecture.md:273` 声称“零拷贝”，但 `src/data.c:244-261` 明确执行
`malloc` 和 `memcpy`。
- Linux 基线只记录绝对工作区路径和版本，没有独立仓库可获取的上游 provenance。
### 8.7 style(9) 机械结果
使用 FreeBSD `tools/build/checkstyle9.pl` 0.31 对 `src/*.[ch]` 连续检查，结果稳定：
- 18 个文件；
- 48 warnings；
- 1 error；
- 44 个超过 80 列；
- 4 个块注释格式告警；
- 唯一 error：`src/erofs_fs.h:265` 的 `return 0` 缺 FreeBSD 风格括号。
其他可见项包括 `src/internal.h:11-12` 的 `sys/param.h // MUST FIRST` 实际位于
`sys/types.h` 后，SPDX 注释形式混用，以及部分 Makefile 空白不统一。
这些结果不能机械全改。磁盘 ABI 宏、静态断言和与 Linux 保持一致的行，可能有
理由超过 80 列。建议先制定“FreeBSD style(9) 优先、磁盘 ABI/上游同步可例外”的
仓库规则，再逐批清理。
## 9. 正向成果与保留项
本轮不能只列问题。以下成果符合原任务 2 的目标，应在后续优化中保留：
- 使用 `bsd.kmod.mk`，而不是维持 Linux Kbuild 兼容层。
- GEOM consumer、设备 vnode、`bread()` 和 buffer cache 的组合符合 FreeBSD 文件
系统路径。
- `vfs_hash_*`、vnode pager、ACL、extattr、CRC32C、endian helper 和 checked
arithmetic 的总体选型正确。
- DEFLATE 和 ZSTD 直接复用可用的 FreeBSD 内核实现。
- 不强行依赖缺少 MicroLZMA ABI 的 `xz.ko`，不强行套用不兼容的 OpenZFS LZ4。
- `namei.c` 和 `zmap.c` 核心函数顺序与 Linux 高度对应。
- Linux-only 文件没有以空壳方式复制到 BSD 仓库。
- FreeBSD-only VOP glue 集中在 `erofs_vnops.c`，平台边界清晰。
- 既有动态测试已覆盖多设备、压缩映射、xattr/ACL、NFS、48-bit 和边界行为；
本报告不重写这些 task 1 证据。
## 10. 可追溯性与许可证边界
### 10.1 仓库许可证材料
repo22 的 18 个生产 `src/*.[ch]` 文件均带 SPDX 标识：13 个
`GPL-2.0-only`、4 个 `BSD-2-Clause`、1 个 `MIT`。`docs/erofs.5:1-23` 自身包含
完整的 BSD 两条款文本。
但 repo22 根目录没有集中式 `LICENSE`、`COPYING`、`NOTICE`、许可证构成表或来源
清单。SPDX 可以识别文件当前声明，不能单独让第三方重建整个 KLD 的来源、整体
分发边界和权利链。
建议后续增加集中式许可证和来源 manifest，明确 GPL 派生核心、MIT 磁盘 ABI、
BSD VOP wrapper、本地 LZ4 和嵌入 XZ 源的关系。本报告不作兼容性或法律结论。
### 10.2 UDF helper 来源
`src/dir.c:158-178` 明确写有“modelled after UDF”。历史版本的 `erofs_uiodir`
与 FreeBSD `sys/fs/udf/udf_vnops.c:614-639` 在结构、分支顺序和控制流上高度接近；
当前版本已增加严格 cookie 单调性、结果枚举、容量检查和不同错误传播。
现有 Git 历史不足以区分最初是直接复制、紧密改写还是参考实现，因此不得断言
侵权或具体来源类别。应由作者确认来源过程，并据此决定是否补充 FreeBSD UDF 的
版权归属或说明。
### 10.3 Linux 基线外部可复现性
在当前 `/work` 单仓环境内，Linux 参考可由导入提交
`8be2be573d2b191c83d760b65c554f78eb95893c` 和 tree
`b79b9a8b62f633e887a8b99075ff9412fabd7f83` 验证。
`docs/architecture.md:160-163` 目前只记录本地绝对路径和 Linux 7.1-rc1 字符串，
没有官方上游 URL、上游 Git commit/tag、获取命令和校验值。因此内部审查可复现，
独立社区仓库的外部复现材料仍不完整。
## 11. 第三方维护者相似度
以下评分来自文件树、共同符号顺序、磁盘 ABI 顺序、FreeBSD API、代码卫生和文档
可复现性的综合人工/机械评估。它不是客观度量，也不代表 feature 完整度：
| 维度 | 暂评分 | 说明 |
| --- | ---: | --- |
| 文件树与职责 | 8.0/10 | 共同文件清晰，Linux-only/BSD-only 边界总体合理 |
| 核心算法命名和顺序 | 8.5/10 | namei/zmap 较好，压缩后端仍有差异 |
| 磁盘 ABI 头文件可同步性 | 6.0/10 | 布局重视正确性，但顺序、命名、注释漂移明显 |
| FreeBSD API 与构建集成 | 9.0/10 | GEOM、VFS、pager、ACL、压缩库选型总体正确 |
| 代码卫生与 style(9) | 5.5/10 | 死声明、旧入口、48 warnings/1 error |
| 社区文档与基线可复现性 | 5.0/10 | 内部可验证，独立仓库 provenance 不完整 |
| **综合维护者相似度** | **7.2/10** | 带权主观评估，用于维护排序，不是兼容性结论 |
综合分采用带权主观评估：文件树与职责 15%，核心算法命名和顺序 20%，磁盘 ABI
头文件可同步性 20%，FreeBSD API 与构建集成 20%，代码卫生与 style(9) 15%，社区
文档与基线可复现性 10%。计算为
`8.0*0.15 + 8.5*0.20 + 6.0*0.20 + 9.0*0.20 + 5.5*0.15 + 5.0*0.10 = 7.225`，
按一位小数四舍五入为 `7.2/10`。权重反映本任务更重视算法、ABI 和平台集成，仍不
应视为客观兼容性指标。
从第三方维护者视角，当前更准确的描述是：核心算法和主要 FreeBSD 适配已对齐，
但仍存在明确的 correctness 风险、结构漂移、代码卫生和可追溯性工作。
## 12. 后续执行路线
本报告只给出路线，不执行任何修改。
### 第一批：先处理两个 P1
1. 修复 `insmntque()` 失败后的 vnode UAF。
2. 对 chunk/physical read 建立严格分块上限，修复 `uiomove(int)` 宽度问题。
3. 为两个问题分别新增 Markdown 手工测试和独立 FreeBSD 动态报告。
该批次必须最小化变更面，不能混入文件重排或 style 清理。
### 第二批：P2 correctness 与边界测试
1. 目录全局严格排序验证与 namecache 负项检查。
2. root vnode `VDIR` 验证。
3. compact pblk 64-bit checked addition。
4. 量化 explicit extent 首次 O(N) 扫描，并决定预算/缓存策略。
每项一份或一组明确 Markdown 测试，复用既有 fixture helper，但不实现 CI。
### 第三批：P3 correctness、compatibility 与 semantic/style
1. correctness/API 契约：保留原 P3 严重度，分别修正 DEFLATE 分配失败 errno、
48-bit end-exclusive 最后合法完整块边界，以及 birthtime-only `VOP_SETATTR()`
的只读语义。
2. compatibility/格式语义：确认并实现 Linux 负时间戳兼容语义；明确 inline symlink
内嵌 NUL 的格式政策并补充拒绝或兼容测试。
3. semantic/style：删除或改写不可达的 FRAGMENTS 特例分支，使注释、supported mask
和真实支持边界一致。
六项均需各自的 Markdown 手工测试或同类成组测试，不得因进入后续批次而改变本报告
中的 P3 严重度。
### 第四批：低风险卫生、文档和 provenance
1. 删除或隔离 repo17/repo19 历史脚本和失配 C harness。
2. 清理 `xattr.h`、`internal.h`、`erofs_defs.h` 的死声明和死宏。
3. 修正 architecture 文档、零拷贝表述和 Linux 基线复现信息。
4. 增加 LICENSE/COPYING、许可证构成和来源 manifest。
5. 确认 UDF helper 和本地实现的作者归属。
6. 在规则明确后处理 style(9) 的确定性问题。
### 第五批：结构重排和压缩职责对齐
1. 恢复 `erofs_fs.h` 非平台相关定义顺序、注释和名称。
2. 评估把压缩配置 loader 移回各 backend。
3. 统一内部 `z_erofs_*` 命名和函数定义顺序。
4. 删除无行为包装，调整非必要函数位置差异。
该批次风险高于普通 style，必须用双配置构建、模块加载和全部相关 Markdown 测试
证明无行为变化。
### 第六批：性能原型
1. LZMA decoder state pool/cache。
2. explicit extent 验证缓存或分段策略。
3. `vfs_read_dirent()` 输出适配器。
原型必须提供基线、压力方法、内存峰值、卸载清理和退化行为；没有数据不合并。
## 13. 原任务三个目标的覆盖矩阵
| 原任务目标 | 已确认正向证据 | 本轮发现 | 尚未验证/后续 |
| --- | --- | --- | --- |
| 1. 最佳实践与 BSD 原生能力复用 | GEOM/bread、vfs_hash、pager、ACL/extattr、CRC/endian、DEFLATE/ZSTD 复用正确；LZ4/MicroLZMA 本地实现有技术理由 | `insmntque()` 契约违反；chunk 大分配；dir helper 需保留但可原型化输出层；LZMA per-call allocation | 动态复现 P1；XZ KPI、dir adapter、LZMA pool 原型 |
| 2. 正确处理 BSD/Linux 行为差异 | 正 errno、VOP/VFS、GEOM、namecache、cookie、ACL namespace、FID/generation 等必要差异清晰 | root 类型、setattr、errno、负时间；compact/48-bit/排序属于 Linux 共同问题，未误记为 BSD 差异 | negative time、symlink NUL、fragment pstart_hi 格式语义确认 |
| 3. 第三方维护者相似性 | 15 个共同文件；namei/zmap 和 Makefile 顺序质量高；未伪造 Linux-only 空文件 | erofs_fs 顺序/注释、压缩职责/命名、死代码、旧脚本、陈旧文档、style、provenance、许可证清单 | 逐批结构重排、来源确认、外部可复现基线、回归验证 |
因此，三个目标都已有实质正向成果，但目标 3 明显未达到“没有任何非必要差异”
的完成标准；目标 1 和目标 2 也因两个 P1 和若干 P2/P3 finding 需要继续工作。
## 14. 与 report-3 的关系
`current/report-3` 是任务 1 收尾时的历史快照。它关于 161 项 feature 手工验证、
构建、清理和当时已知 issue 的证据继续有效，本报告不修改也不重写这些结论。
但 report-3 中“未发现仍需消除的非必要 Linux/FreeBSD 结构、命名或职责差异”是
一个超出当时证据范围的绝对表述。当时没有保存：
- 全部文件的函数、变量和定义顺序对照；
- FreeBSD 原生 API 复用清单；
- Linux-only/BSD-only 文件逐项必要性论证；
- 死代码、失效入口、style(9)、来源和许可证审计；
- 独立仓库可重建的 Linux 基线 provenance。
因此，对任务 2 应以本报告作更精确限定：
> repo22 的核心算法和主要 FreeBSD 适配已取得良好对齐，但尚不能认定全面完成
> code review 和 style 优化；仍存在两个 P1、四个 P2、六个 P3，以及明确的结构、
> 代码卫生、style 和可追溯性工作。
该限定不回写 report-3，以保持历史报告不可变和审计链清晰。
## 15. 最终状态
- 本轮只创建 `current/report-4/`。
- 未修改 `src/`、`tests/`、`docs/`、`issues/`、既有 report 或 CI。
- 未声称任何 finding 已修复。
- 未把静态候选误写成动态复现结果。
- 新问题进入后续计划前，应先创建对应 Markdown 手工测试规格，再由独立执行者在
FreeBSD 15 环境中复现、修复和回归。
current/report-4/README.md
+41
View File
@@ -0,0 +1,41 @@
# report-4：任务 2 代码审查与风格评估
本目录记录 2026-08-10 对 repo22 原任务中“任务 2：进行全面的 code review
和 style 优化”的只读调查结果。
本次工作只做静态评估、源码契约核对、Linux/FreeBSD 严格比对、历史检查和
机械 style 检查，不修改生产源码、测试、既有文档、issues 或 CI。报告中的新
finding 尚未在 FreeBSD 虚拟机中动态复现，也尚未修复。
## 审计基线
- BSD 目标：`repo-community/repo22`，提交
`76cfb553e0951b428f9d426933a10d1fe18d2a0e`
- 最终源码变更提交：`67d3c057fbcad5adc765ab9927da511e3221ac8f`
- repo22 `src/` tree：`a605af0f01f83d67c199005e775e1a47a1610036`
- Linux 独立参考：`/work/dev-src-linux/fs/erofs`，Linux 7.1.0-rc1
- Linux 本地导入提交：`8be2be573d2b191c83d760b65c554f78eb95893c`
- Linux EROFS tree：`b79b9a8b62f633e887a8b99075ff9412fabd7f83`
- FreeBSD API 参考：`/work/dev-freebsd-releng`，15.0-RELEASE-p9
## 结论摘要
- 任务 1 的 161 项 feature 验证结论不在本报告中重写，也不因本报告自动失效。
- 任务 2 尚不能认定已经全面完成。本轮确认 `P0=0`、`P1=2`、`P2=4`、
`P3=6`，另有若干非 correctness 的结构、style、来源与性能原型工作。
- FreeBSD 原生 API 和构建集成总体合理，强行复用并不适用于 LZ4、MicroLZMA
和目录 cookie helper。
- 核心算法映射质量较高，但磁盘 ABI 头文件顺序、压缩职责、死代码、历史测试
入口、文档、style(9) 和外部可复现性仍有明确维护债务。
- 综合维护者相似度暂评为 `7.2/10`。该分数仅用于排序维护工作，不是客观质量
或兼容性指标。
## 文档索引
- [任务 2 详细代码审查与风格评估](2026-08-10-task2-code-review-style-assessment.md)
## 与既有报告的关系
`current/report-1` 至 `current/report-3` 保持历史快照。本目录不修改它们。
report-3 的 feature 验证结果继续作为任务 1 证据；其中“没有非必要差异”的绝对
表述，由本次更完整的结构、style、来源和许可证审计作更精确的限定。