Skip to content

Commit 61885f0

Browse files
committed
docs(spec): add source citations and unverified-URL list for external facts in 03
Audit P1-005 fix. 03 v0.1 referenced many upstream facts (mips removal, clang/llvm 19, pkgbase, pr_usrreqs merge, inpcb SMR, if_t opaqueness, netlink, RACK default, KTLS, routing/rib/nexthop, 14.4/15.1 timeline) but contained zero URLs and zero retrieval dates. This commit adds a new section 10 to 03 with two layers: - 10.1 Locally-verifiable sources (path:line + quotation), sourced primarily from the in-tree freebsd-src-releng-15.0 / 13.0 trees (RELNOTES, UPDATING, sys/conf/newvers.sh, sys/sys/param.h, sys/conf/files, sys/sys/protosw.h, sys/netinet/in_pcb.h, sys/net/if.h, sys/net/if_var.h, sys/netlink/). - 10.2 Unverified external URL queue, listing 8 facts that still need network access (clang 19 import date, pkgbase status, netlink intro year, RACK default knob, KTLS commit, routing rewrite design doc, 14.x release timeline, 15.1 placeholder), each with candidate URL(s) and a turning-into-verified condition. - 10.3 Verification protocol: when to verify (before M1 kickoff), how to record (URL + retrieval date + quote), fallback when URL unreachable, and the future Phase 4 reviewer check. Files: - 03-freebsd-15-changes.md: append section 10 (47 new lines). - 98-independent-audit-report.md: P1-005 and sec 6.1 item 6 marked 'fixed 2026-05-28, see 99 sec 12.6'. - 99-review-report.md: append sec 12.6 revision record. Why not a separate 03-appendix-sources.md (one of the audit's two suggested approaches): keeping the citations inline in 03 sec 10 avoids cross-file maintenance cost while still meeting the 'every external fact has a verifiable source or an explicit unverified label' requirement. Verification: grep -cE 'sys/conf/newvers\.sh|sys/sys/param\.h|UPDATING:|RELNOTES:\ |sys/sys/protosw\.h|sys/netinet/in_pcb\.h|sys/net/if\.h\ |sys/net/if_var\.h|sys/conf/files|sys/netlink' \ zh_cn/03-freebsd-15-changes.md # -> 13 hits, all in section 10.1. The 8 unverified URL items are non-blocking for the Spec stage (Go/No-Go decision 'as Spec draft = GO' stays unchanged); the human reviewer should resolve them during M1 preparation. Lint: 0 diagnostics across zh_cn/.
1 parent d198466 commit 61885f0

3 files changed

Lines changed: 64 additions & 2 deletions

File tree

docs/freebsd_13_to_15_upgrade_spec/zh_cn/03-freebsd-15-changes.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,3 +319,50 @@ F-Stack 不启用,P3。
319319
| 升级里程碑(§8) | `05-implementation-plan.md` 引用作为 baseline 时间线参考 |
320320

321321
> 下一步:`04-diff-and-port-strategy.md` 把本节风险与 02 改造点交叉,产出最终 port 任务清单。
322+
323+
## 10. 外部资料引用与待核验清单(2026-05-28 增补)
324+
325+
> 本节响应独立审计 §P1-005:本文档大量引用上游事实(mips 移除、clang/llvm 19、pkgbase、`pr_usrreqs` 合并、inpcb SMR、`if_t` 不透明化、netlink、RACK 默认化、KTLS、routing/rib/nexthop、14.4/15.1 时间线等),但在 v0.1 中没有逐条给出 URL / 引文片段 / 抓取日期。本节按"§10.1 本地权威源(可立即复核)"与"§10.2 外部 URL 待核验清单"两类,把每条事实的来源补上;§10.3 给出"待核验"条目的转正条件。
326+
> 全部引文均为 2026-05-28 实测;本地路径均位于 `/data/workspace/freebsd-src-releng-15.0/`(除非另注)。
327+
328+
### 10.1 本地权威源(可立即复核)
329+
330+
下表中每条引文的形式为「文件路径 + 行号 + 简短引文」,读者可直接 `sed -n '<line>p' <path>` 复核。
331+
332+
| 03 章节 | 事实 | 本地权威源(路径:行号 + 引文) |
333+
|---|---|---|
334+
| §1 / §2.1 | 13.0 = `RELEASE-p2`,15.0 = `RELEASE-p9` | `freebsd-src-releng-13.0/sys/conf/newvers.sh``REVISION="13.0" / BRANCH="RELEASE-p2"``freebsd-src-releng-15.0/sys/conf/newvers.sh``REVISION="15.0" / BRANCH="RELEASE-p9"` |
335+
| §1 / §6 | `__FreeBSD_version`:13.0=`1300139`,15.0=`1500068` | `freebsd-src-releng-13.0/sys/sys/param.h``#define __FreeBSD_version 1300139``freebsd-src-releng-15.0/sys/sys/param.h:#define __FreeBSD_version 1500068` |
336+
| §2.1 | mips 整体移除(始于 14.0,commit 2021-12-09) | `freebsd-src-releng-15.0/UPDATING:929-932``20211209: Remove mips as a recognized target. This starts the decommissioning of mips support in FreeBSD. mips related items will be removed wholesale in the coming days and weeks.`;行 971:`Mips has been removed from universe builds`;行 1463:`mips, powerpc, and sparc64 are no longer built as part of universe`;行 1643:`mips GXEMUL support has been removed`;行 751:`Following the general removal of MIPS support, the ath(4) AHB bus-…` |
337+
| §2.2 | clang/llvm 18 阶梯升级(→ 19 待 14.x→15 RELNOTES 校核) | `freebsd-src-releng-15.0/UPDATING:621-628``20240406: Clang, llvm, lld, lldb, compiler-rt, libc++, libunwind and openmp have been upgraded to 18.1.6.`;clang 19 升级条目留待 §10.2 待核验(UPDATING 文本未在本仓库版本中检出 19.x 升级行) |
338+
| §2.3 | pkgbase 在 15.0 阶段密集落地 | `freebsd-src-releng-15.0/UPDATING` 行 80/90/157/159/166/184/188/211/227/243/265/358/373/381/386/458/463/527/556/613/618/622/712/716/717/718(共 40+ 处),代表性引文:行 157:`release engineering builds on pkgbase.freebsd.org`;行 527:`different transport - netlink(4) socket instead of unix(4). Users of …`(同时关联 netlink) |
339+
| §2.4 | 13→15 syscall 表实测(22 项新增 + 3 项删除) | `grep '^#define[[:space:]]\+SYS_' freebsd-src-releng-{13.0,15.0}/sys/sys/syscall.h \| awk '{print $2}' \| sort \| comm`(详见 99 §12.1) |
340+
| §3.1 | `pr_usrreqs` 在 15.0 已被合并入 `protosw` | `freebsd-src-releng-13.0/sys/sys/protosw.h:95``struct pr_usrreqs *pr_usrreqs;``freebsd-src-releng-13.0/sys/sys/protosw.h:188``struct pr_usrreqs {`;15.0 同名头文件中已无 `pr_usrreqs` 字段(grep 0 行) |
341+
| §3.2 | `inpcb` 转 SMR | `freebsd-src-releng-15.0/sys/netinet/in_pcb.h:141-142``are be performed inside SMR section. Once desired PCB is found its own lock is to be obtained and SMR section exited.`;行 192:`smr_seq_t inp_smr; /* (i) sequence number at disconnect */`;行 342:`The pcbs are protected with SMR section…` |
342+
| §3.3 | `if_t` typedef(详见 99 §12.2) | `freebsd-src-releng-13.0/sys/net/if_var.h:127``typedef struct ifnet * if_t;``freebsd-src-releng-15.0/sys/net/if.h:667``typedef struct ifnet *if_t;` |
343+
| §3.5 | netlink 子系统 15.0 引入 | `freebsd-src-releng-15.0/sys/netlink/`(目录存在,3907 行 `.c`,13.0 该目录不存在);`freebsd-src-releng-15.0/UPDATING:851-853``As of commit 7c40e2d5f685, the dependency on netlink(4) has been added … to compile netlink(4) module if it is not present in their kernel.` |
344+
| §3.6 | RACK / BBR / extra TCP stacks 模块化 | `freebsd-src-releng-15.0/sys/conf/files:4451-4456``netinet/tcp_stacks/rack.c optional inet tcphpts tcp_rack \| inet6 tcphpts tcp_rack \\``compile-with "${NORMAL_C} -DMODNAME=tcp_rack -DSTACKNAME=rack"`;同时 `rack_bbr_common.c` / `sack_filter.c` / `tailq_hash.c` / `rack_pcm.c` 也在该处声明 |
345+
| §3.7 | KTLS 在 GENERIC 默认开启 | `freebsd-src-releng-15.0/RELNOTES:227-228``Kernel TLS is now enabled by default in kernels including KTLS support. KTLS is included in GENERIC kernels for aarch64, …` |
346+
| §3.8 | routing / rib / nexthop 安全相关 | `freebsd-src-releng-15.0/UPDATING:107-109``15.0-RELEASE-p4 SA-26:05.route … Local DoS and possible privilege escalation via routing sockets.`(侧证 routing 子系统在 15.0 仍处活跃维护) |
347+
348+
### 10.2 外部 URL 待核验清单
349+
350+
下表中的事实需要外部网络访问才能补全 URL / 抓取日期;按本审计回合的范围,这些条目暂以"待核验"留存,由 M1 启动前的人工 review 阶段补完。
351+
352+
| 03 章节 | 事实 | 候选 URL(待核验) | 转正条件 |
353+
|---|---|---|---|
354+
| §2.2 | clang/llvm 19 升级时间点(v0.1 写"clang/llvm 19") | `https://www.freebsd.org/releases/15.0R/relnotes/`(FreeBSD 15.0 官方 release notes);`https://lists.freebsd.org/archives/freebsd-current/`(搜索 "Clang 19 import") | 在线打开 → 截取关键句 → 记入本节 + 99 §12.6 |
355+
| §2.3 | pkgbase 在 15.0 状态(v0.1 写"P3 / EXPERIMENTAL knob") | `https://wiki.freebsd.org/PkgBase``https://docs.freebsd.org/en/articles/explaining-bsd/`(pkgbase 章节) | 同上 |
356+
| §3.5 | netlink 引入年份(v0.1 写"实际 14.0 引入")的官方说明 | `https://www.freebsd.org/releases/14.0R/relnotes/``man.freebsd.org/cgi/man.cgi?netlink(4)` | 同上 |
357+
| §3.6 | RACK 在 15.0 base 的 default knob 状态 | `https://www.freebsd.org/releases/15.0R/relnotes/``https://lists.freebsd.org/archives/freebsd-net/`(搜索 "RACK default") | 同上 |
358+
| §3.7 | KTLS API 14→15 变化的具体 commit / phabricator review | `https://reviews.freebsd.org/``https://cgit.freebsd.org/src/log/sys/sys/ktls.h` | 同上 |
359+
| §3.8 | routing/rib/nexthop 重写设计文档 | `https://reviews.freebsd.org/D26577`(route_ctl 引入);FreeBSD wiki "FIB / NHOP" 词条 | 同上 |
360+
| §6 | 14.0R 至 14.4R 时间线表 | `https://www.freebsd.org/releases/`(每个 14.x 版本主页) | 同上 |
361+
| §6 | 15.1R 时间线占位 | `https://www.freebsd.org/releases/15.1R/`(暂未发布) | 发布后回填 |
362+
363+
### 10.3 待核验条目的转正条件与流程
364+
365+
1. **触发时机**:本批"待核验"条目应在 M1 实施阶段启动前,由人工 review 补 URL,**不阻塞** Spec 阶段交付(§7 Go/No-Go 判断中"作为 Spec 草案 = GO")
366+
2. **核验方式**:访问 §10.2 列出的候选 URL → 截取与本文档事实相关的不超过 3 句原文 → 在本节追加「URL + 抓取日期 + 引文片段」 → 把对应行的"候选 URL(待核验)"改为"已核验 URL"
367+
3. **不可用回退**:若 URL 失效或与文档事实不一致,应在本节记录"已尝试核验,结论与 v0.1 不符 / 无法访问"并联动订正主体章节
368+
4. **Phase 4 reviewer 责任**:未来再次评审本文档时,若发现 §10.2 列表为空(表示已全部核验完),应在 99 §3 / §7 增加一条"外部事实 100% 可复核"的质量指标

docs/freebsd_13_to_15_upgrade_spec/zh_cn/98-independent-audit-report.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@
114114
| 审计判断 | 本地源码事实较充分,但外部 release notes 证据链不足;尤其是 14.3/14.4/15.1 时间线、工具链版本、pkgbase 等非本地源码事实,不宜仅靠记忆写入 |
115115
| 影响 | 03 的"外部资料调研"达不到可审计标准;后续人工 review 难以复核来源 |
116116
| 建议 | 增加 `03-appendix-sources.md` 或在 03 每条外部事实后追加 URL + 引文片段 + 抓取日期;无法验证的条目标为"待核验" |
117-
| 严重度 | **P1** |
117+
| 严重度 | **P1**【已修订 2026-05-28,详见 `99-review-report.md` §12.6】 |
118118

119119
### P1-006:文档状态过期,当前交付状态与内容不一致
120120

@@ -206,7 +206,7 @@
206206
3. 重新生成真实 `diff -rq` / checksum 的 `04` 统计,或把现有统计全部降级为估算。【已完成 2026-05-28,详见 `99-review-report.md` §12.3】
207207
4.`f-stack/lib/Makefile` 重新抽取全量 `*_SRCS` 表,替换 04 的省略号版本。【已完成 2026-05-28,详见 `99-review-report.md` §12.4】
208208
5. 清理文档状态:plan/01/99 中所有"待完成/下一步等待 Phase 1.4"的过期表述。【已完成 2026-05-28,详见 `99-review-report.md` §12.5】
209-
6. 给 03 外部事实补 URL + 引文 + 抓取日期,或将不可核验条目标为"待核验"。
209+
6. 给 03 外部事实补 URL + 引文 + 抓取日期,或将不可核验条目标为"待核验"。【已完成 2026-05-28,详见 `99-review-report.md` §12.6】
210210

211211
### 6.2 推荐修订
212212

docs/freebsd_13_to_15_upgrade_spec/zh_cn/99-review-report.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -444,3 +444,18 @@ q2 决定的范围(来自 plan.md §1.5):
444444
| 修订后状态 | `98 P1-006` 闭合;`spec 阶段交付`整体结论保持 **✅ 通过** 不变。 |
445445
| 校验 | `read_lints` 在 zh_cn/ 目录返回 0 diagnostics;`grep -nE '当前不存在\|2 份已交付,6 份待出\|待 Phase 3\\.\|待 Phase 4 出报告\|待 Leader 下回合' zh_cn/{plan,01,99,00}.md` 应无残留(合法历史引文如 98 审计报告原文与本节修订记录除外)。 |
446446

447+
### 12.6 修订 R-2026-05-28-06:03 外部资料引用与待核验清单
448+
449+
|| 内容 |
450+
|---|---|
451+
| 修订日期 | 2026-05-28 |
452+
| 关联审计条目 | `98-independent-audit-report.md` §3 P1-005,§6.1 第 6 项 |
453+
| 错误根因 | 03 v0.1 大量引用上游事实(mips 移除、clang/llvm 19、pkgbase、`pr_usrreqs` 合并、inpcb SMR、`if_t` 不透明化、netlink、RACK 默认化、KTLS、routing/rib/nexthop、14.4/15.1 时间线等),但全文仅 1 处出现"Release Notes"字样、零 URL、零抓取日期。Phase 2 Sub-Agent B(Analyzer-15)原计划应跑 `web_search` / `web_fetch`,实际未执行;Phase 4 reviewer 未把"外部事实是否可复核"列为审查维度。 |
454+
| 实测基线 | 本次改用"本地权威源"补充:`/data/workspace/freebsd-src-releng-15.0/` 本身就是 15.0-RELEASE-p9 的完整源代码 + RELNOTES + UPDATING + sys/sys/param.h + sys/conf/newvers.sh + sys/conf/files + 各子系统头文件,绝大多数事实可以在本仓库内部找到逐字引文。本节列入 13 条本地可复核事实 + 8 条待核验外部 URL。 |
455+
| 修订动作 1 | `03-freebsd-15-changes.md` 末尾新增 §10「外部资料引用与待核验清单(2026-05-28 增补)」,分三个小节:§10.1 本地权威源(13 条事实,每条给 `路径:行号 + 引文`,读者可直接 `sed -n '<line>p'` 复核);§10.2 外部 URL 待核验清单(8 条,覆盖 clang 19、pkgbase、netlink 引入年份、RACK 默认 knob、KTLS commit、routing 重写设计、14.x 时间线、15.1);§10.3 待核验条目的转正条件与流程。 |
456+
| 修订动作 2 | 不新建独立的 `03-appendix-sources.md`(审计 P1-005 建议的两种方案之一),而是把外部资料章节内嵌到 03 自身 §10,避免额外的跨文件维护成本;与审计建议的等效性体现在:每条事实仍能定位到来源 + 待核验项明确列出转正路径。 |
457+
| 修订动作 3 | `98-independent-audit-report.md` §3 P1-005 与 §6.1 第 6 项追加"已修订 2026-05-28,详见 99 §12.6"标记,闭合审计条目。 |
458+
| 影响范围 | 03 中所有外部事实从"无可复核证据"升级为"本地可复核(§10.1)"或"明确待核验(§10.2)"。**Spec 阶段 Go/No-Go 维度的"作为 Spec 草案 = GO"结论保持不变;新增的外部 URL 核验工作不阻塞 M1 实施阶段,可在 M1 准备阶段并行完成**(详见 §10.3)。 |
459+
| 修订后状态 | `98 P1-005` 闭合;`spec 阶段交付`整体结论保持 **✅ 通过** 不变。 |
460+
| 校验 | `read_lints` 在 zh_cn/ 目录返回 0 diagnostics;`grep -nE 'sys/conf/newvers\\.sh\|sys/sys/param\\.h\|UPDATING:\|RELNOTES:\|sys/sys/protosw\\.h\|sys/netinet/in_pcb\\.h\|sys/net/if\\.h\|sys/net/if_var\\.h\|sys/conf/files' zh_cn/03-*.md` 应有 ≥10 处命中(即本地引文路径)。 |
461+

0 commit comments

Comments
 (0)