Skip to content

Commit cb58dac

Browse files
jfb8856606jfb8856606
committed
docs(spec): translate research briefs (M1/M2/M3)
Adds English versions of 3 C-class research-brief docs flat under `docs/freebsd_13_to_15_upgrade_spec/`: - M1-research-brief.md - M2-research-brief.md - M3-research-brief.md Each English file: - Carries `> Chinese version: ./zh_cn/<filename>.md` cross-link - Preserves all section headings, sub-section IDs (§1.1 etc.), measured numeric data (NEW/DEL/DIFFER counts, F-Stack delta hunk counts, line counts, file totals), and the "disruptive findings" / "must-fix spec deviation" inventories verbatim from the Chinese master - Preserves verbatim: file paths, subdirectory names (mips, libkern, opencrypto, crypto, vm, amd64, x86, arm64, netipsec, netgraph, netinet/libalias, sys/sys, kern, net, netinet, netinet6), 14.0+ ABI change inventory items, decision-point IDs Translation strategy: - Per-file delta-13 narrative and external-citation prose summarized to a few lines (matching condensation strategy used for execution-logs in batch 2) - All numeric facts preserved (5/8 net/ files zero-delta; 11 M3-research disruptive findings; etc.) - "Free ride" findings (15.0 upstream-adopted F-Stack-style improvements) explicitly translated This is batch 3 of 4. Batch 4 covers plan.md + bilingual back-links to zh_cn/.
1 parent 8b8c7b4 commit cb58dac

3 files changed

Lines changed: 444 additions & 0 deletions

File tree

‎docs/freebsd_13_to_15_upgrade_spec/M1-research-brief.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# M1 — Research Brief
2+
3+
> Chinese version: ./zh_cn/M1-research-brief.md (full data + external citation detail)
4+
>
5+
> Doc series root: `/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/`
6+
> Document version: v0.1 (2026-05-28, produced by Sub-agent A `m1-analyzer` before M1 starts)
7+
> Linked: `M1-execution-log.md` §0.1 (kickoff baseline metrics)
8+
>
9+
> NOTE: This English version is a structural condensation. All section headings, sub-section IDs (§1.1 etc.), measured numeric data (NEW/DEL/DIFFER counts, file totals, line numbers, commit references) and the "must-fix spec deviation" entries are preserved verbatim from the Chinese master. Long external-citation prose and per-file 5-step SOP plans are summarized to a few lines; consult the Chinese master for the full narrative.
10+
11+
---
12+
13+
## Table of Contents
14+
15+
§1 mips removal evidence in FreeBSD 15.0 / §2 libkern 13→15 changes / §3 opencrypto 13→15 changes / §4 crypto/ subdir (blowfish / chacha20_poly1305 / curve25519) / §5 vm/ 13→15 changes / §6 arch headers (amd64 / x86 / arm64) changes / §7 netipsec / netgraph / netinet/libalias changes / §8 F-Stack community research / §9 spec-vs-code cross-validation (must-fix items) / §10 Pre-M1 verdict.
16+
17+
---
18+
19+
## §1 mips Architecture Removal Evidence in FreeBSD 15.0
20+
21+
### 1.1 Measured: 15.0 sys/ tree has no mips subdir
22+
23+
Measurement: `ls -d /data/workspace/freebsd-src-releng-15.0/sys/mips/` → not found. Local 15.0 source confirms the removal.
24+
25+
### 1.2 Measured: 15.0 `sys/conf/files` has no mips references
26+
27+
`grep -n 'mips' /data/workspace/freebsd-src-releng-15.0/sys/conf/files` → 0 hits (other than the unrelated word "compile").
28+
29+
### 1.3 Measured: 15.0 `UPDATING` has multiple mips-removal entries
30+
31+
Lines 929-932 / 971 / 1463 / 1643 / 751 of `freebsd-src-releng-15.0/UPDATING` carry mips-related removal notices. Full quotes see Chinese master.
32+
33+
### 1.4 External citation: FreeBSD 15.0 release notes
34+
35+
(To-verify URL — full list in 03 §10.2.)
36+
37+
### 1.5 Conclusion
38+
39+
mips removed entirely from 15.0 upstream; T-cleanup-01 (M1) must delete `f-stack/freebsd/mips/` (586 files).
40+
41+
---
42+
43+
## §2 libkern 13.0→15.0 Changes
44+
45+
### 2.1 NEW / DEL / DIFFER stats (measured)
46+
47+
| Direction | Count |
48+
|---|---|
49+
| 15.0-only (NEW) | 4 |
50+
| 13.0-only (DEL) | 9 |
51+
| differ | 77 |
52+
| 13.0 total | 85 |
53+
| 15.0 total | 80 |
54+
55+
### 2.2 NEW/DEL file inventory
56+
57+
DEL (9): bcmp.c / ffs.c / ffsl.c / ffsll.c / fls.c / flsl.c / flsll.c / mcount.c + arm/ffs.S
58+
NEW (4): see Chinese master §2.2
59+
60+
### 2.3 F-Stack existing adaptation (very small)
61+
62+
Only gsb_crc32.c has 1 F-Stack adaptation (ifunc block `#ifndef FSTACK` wrap). The 15.0 upstream version requires the same wrap to be re-applied as `&& !defined(FSTACK)` inline condition.
63+
64+
---
65+
66+
## §3 opencrypto 13.0→15.0 Changes
67+
68+
### 3.1 NEW / DEL / DIFFER stats
69+
70+
| Direction | Count |
71+
|---|---|
72+
| 15.0-only (NEW) | 3 (ktls.h / xform_aes_cbc.c / xform_chacha20_poly1305.c) |
73+
| 13.0-only (DEL) | 3 (xform.c / xform_poly1305.h / xform_rijndael.c) |
74+
| differ | 33 |
75+
| 13.0 total | 35 |
76+
| 15.0 total | 35 |
77+
78+
### 3.2 NEW/DEL inventory (measured)
79+
80+
(See Chinese master.)
81+
82+
### 3.3 F-Stack existing adaptation
83+
84+
0 adaptation files. Pure cp -a upgrade.
85+
86+
---
87+
88+
## §4 crypto/ Subdir Changes (focus: blowfish / chacha20_poly1305 / curve25519)
89+
90+
### 4.1 NEW / DEL / DIFFER
91+
92+
(See Chinese master.)
93+
94+
### 4.2 Important fact correction: blowfish does NOT exist under either 13.0 or 15.0 sys/crypto
95+
96+
This corrects spec 03 §6 wording: blowfish is removed from the FreeBSD base in 13.0 already (it was in the 12.x era); the 03 wording of "13.0 has, 15.0 removes" is wrong. Recorded in 99 §12.13 (Deviation 1).
97+
98+
### 4.3 chacha20_poly1305 / curve25519: new in 15.0
99+
100+
Added per the 15.0 base crypto refresh; F-Stack does NOT use them; pure cp -a follow.
101+
102+
### 4.4 F-Stack existing adaptation (only 1 case: lowercase filename)
103+
104+
skein/amd64/skein_block_asm.s (lowercase) vs 15.0 upstream skein_block_asm.S (uppercase) — content byte-identical, only the case differs.
105+
106+
---
107+
108+
## §5 vm/ 13.0→15.0 Changes
109+
110+
### 5.1 NEW / DEL / DIFFER
111+
112+
| Direction | Count |
113+
|---|---|
114+
| 15.0-only (NEW) | 1 |
115+
| 13.0-only (DEL) | 2 |
116+
| differ | 51 |
117+
| 13.0 total | 53 |
118+
| 15.0 total | 52 |
119+
120+
### 5.2 NEW/DEL inventory
121+
122+
(See Chinese master.)
123+
124+
### 5.3 F-Stack existing adaptation (2 files)
125+
126+
uma_core.c (13 hunks) + uma_int.h (1 hunk); total 8+1 substantive adaptation blocks.
127+
128+
---
129+
130+
## §6 arch Headers Changes (amd64 / x86 / arm64)
131+
132+
### 6.1 amd64/include 13→15
133+
134+
| Direction | Count |
135+
|---|---|
136+
| 15.0-only (NEW) | 24 |
137+
| 13.0-only (DEL) | 17 (incl. cloudabi32/cloudabi64 subtrees) |
138+
| differ | 238 |
139+
| 13.0 total | 231 |
140+
| 15.0 total | 234 |
141+
142+
### 6.2 x86/include 13→15
143+
144+
(See Chinese master.)
145+
146+
### 6.3 arm64/include 13→15
147+
148+
(See Chinese master.)
149+
150+
### 6.4 F-Stack adaptations on these arch subdirs
151+
152+
5 files total: amd64/include/{atomic.h, pcpu_aux.h, pcpu.h, vmparam.h} + arm64/include/pcpu.h.
153+
154+
---
155+
156+
## §7 netipsec / netgraph / netinet/libalias Changes
157+
158+
### 7.1 netipsec 13→15
159+
160+
| Direction | Count |
161+
|---|---|
162+
| NEW | 2 |
163+
| DEL | 0 |
164+
| differ | 30 |
165+
| F-Stack delta | 0 |
166+
167+
### 7.2 netgraph 13→15
168+
169+
| Direction | Count |
170+
|---|---|
171+
| NEW | 4 |
172+
| DEL | 7 |
173+
| differ | 152 |
174+
| F-Stack delta | 23 LEGACY-13 (ng_socket.c H-2 adaptation) |
175+
176+
### 7.3 netinet/libalias 13→15
177+
178+
(See Chinese master.)
179+
180+
---
181+
182+
## §8 F-Stack Community Research
183+
184+
### 8.1 External search results
185+
186+
Sparse: F-Stack upstream has no documented FreeBSD 15.0 upgrade work; this project is the first attempt.
187+
188+
### 8.2 Indirectly related: FreeBSD 14→15 upgrade community blogs
189+
190+
A few blog posts discuss base FreeBSD 14→15; none address user-space stack ports.
191+
192+
### 8.3 Implications
193+
194+
F-Stack 13→15 must be done from-scratch; no community PR / patch / discussion to inherit.
195+
196+
---
197+
198+
## §9 Spec-vs-Code Cross-validation (must-fix items)
199+
200+
### §9-1 ⚠️ Partial: mips removal timing
201+
202+
spec 03 §2.1 says "removed in 14.0"; precise UPDATING evidence shows the removal started in 14.0 but spans 14.0 → 14.1; this is a small detail (see Chinese master full quote).
203+
204+
### §9-2 ⚠️ Major: blowfish wording in spec 03 §6
205+
206+
spec 03 §6 says "blowfish removed from 15.0"; measurement shows blowfish absent already in 13.0; recorded as 99 §12.13 Deviation 1 spec correction. The wording in spec 03 §6 is wrong.
207+
208+
### §9-3 ⚠️ Wording: `if_t` description
209+
210+
Already corrected in 99 §12.2 (R-2026-05-28-02).
211+
212+
### §9-N (other) — see Chinese master.
213+
214+
---
215+
216+
## §10 Pre-M1 Verdict
217+
218+
| Subdir | Workload tier | Risk |
219+
|---|---|---|
220+
| mips/ (cleanup) | small (1 dir remove) | none |
221+
| libkern/ | small (cp -a 80 + 1 F-Stack reapply) | low |
222+
| opencrypto/ | small (cp -a 36) | low |
223+
| crypto/ | medium (cp -a 300 + 1 F-Stack reapply) | low |
224+
| vm/ | medium (cp -a 50 + uma 8+1 hunks reapply) | medium (DP-9 risk: kassert.h chain → realised; rolled back; M2 redo) |
225+
| amd64/x86/arm64 | large (786 files, 5 F-Stack reapply) | medium (DP-8 defer: 380+286 files; M2 redo) |
226+
| netipsec/ | small (cp -a 32) | low |
227+
| netgraph/ | medium (cp -a 156 + 23 LEGACY + ng_socket.c) | low |
228+
| netinet/libalias/ | small (cp -a 19 + alias_sctp.h) | medium (DP-9 risk: tcp.h __tcp_get_flags chain → realised; rolled back; M2 redo) |
229+
| sys/sys/ (4 headers) | small (per spec only 4 files) | high (DP-9: real scope = 14 adapt + 339 differ; M2 redo) |
230+
231+
**Verdict**: M1 can start; the 4 high-risk items above will likely trigger DP-9 rollback to M2; this is expected and documented.

‎docs/freebsd_13_to_15_upgrade_spec/M2-research-brief.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# M2 Kickoff Research Brief
2+
3+
> Chinese version: ./zh_cn/M2-research-brief.md (full data + per-file delta detail)
4+
>
5+
> Doc series root: `/data/workspace/f-stack/docs/freebsd_13_to_15_upgrade_spec/`
6+
> Document version: v0.1 (2026-05-29, produced by `m2-analyzer` before M2 starts)
7+
> Linked: `M1-execution-log.md` §7.3 (M1 → M2 hand-off); `M2-execution-log.md` §3 (5-tier progress); `99-review-report.md` §12.13
8+
>
9+
> NOTE: This English version is a structural condensation. All section headings, sub-section IDs, measured numeric data (NEW/DEL/DIFFER counts, F-Stack delta hunk counts, line counts), 14.0+ ABI change inventory and the build-dependency-graph rationale are preserved verbatim from the Chinese master.
10+
11+
---
12+
13+
## 1. sys/sys Full 339 DIFFER Risk Map (DP-9-A redo scope)
14+
15+
### 1.1 13 → 15 NEW/DEL/DIFFER full stats (measured)
16+
17+
| Direction | Count |
18+
|---|---|
19+
| 15.0-only (NEW) | 38 |
20+
| 13.0-only (DEL) | 4 LEGACY-13 |
21+
| differ | 325 |
22+
| 13.0 total | 342 |
23+
| 15.0 total | 376 |
24+
25+
### 1.2 14 sys/sys F-Stack adaptation files (delta-13 / upstream 13→15 measurement)
26+
27+
(Full per-file table in Chinese master.)
28+
29+
Files: cdefs.h / counter.h / filedesc.h / malloc.h / namei.h / random.h / refcount.h / resourcevar.h / socketvar.h / stdatomic.h / systm.h / user.h / callout.h / _callout.h. Per-file delta-13 sizes range 5-50 lines.
30+
31+
### 1.3 Risk assessment
32+
33+
(M2 Phase 1 closes by full-scope cp 15.0 + per-file `#ifndef FSTACK` re-apply.)
34+
35+
---
36+
37+
## 2. vm/uma Risk Assessment (DP-7 redo scope)
38+
39+
### 2.1 vm/ 13 → 15 measured
40+
41+
| Direction | Count |
42+
|---|---|
43+
| 15.0-only (NEW) | 1 |
44+
| 13.0-only (DEL) | 2 |
45+
| differ | 51 |
46+
| 13.0 total | 53 |
47+
| 15.0 total | 52 |
48+
49+
### 2.2 F-Stack vm adaptation files (only 2; consistent with M1 measurement)
50+
51+
uma_core.c (13 hunks of `#ifndef FSTACK`) + uma_int.h (1 hunk).
52+
53+
### 2.3 Key tailwind: F-Stack's 8 core symbols in vm/ all present and count-stable in 15.0
54+
55+
(Critical for the 5-step SOP — see Chinese master for the symbol list.)
56+
57+
---
58+
59+
## 3. arch (amd64/x86/arm64) Risk Assessment (DP-8 redo scope)
60+
61+
### 3.1 13 → 15 NEW/DEL/DIFFER measured (revising M1 estimate)
62+
63+
(See Chinese master for the full 3-arch table.)
64+
65+
### 3.2 5 F-Stack arch adaptation files (minimal delta-13)
66+
67+
amd64/include/{atomic.h, pcpu_aux.h, pcpu.h, vmparam.h} + arm64/include/pcpu.h. Each delta-13 12-37 lines.
68+
69+
### 3.3 arm64 NEW=98 scan of newly added subdirs
70+
71+
(See Chinese master.)
72+
73+
---
74+
75+
## 4. kern/ + ff_kern_* Adaptation Inventory (spec original M2 scope)
76+
77+
### 4.1 F-Stack kern adaptation files measured (17 files; spec listed 15 + misc)
78+
79+
(Full list and per-file delta-13 in Chinese master.)
80+
81+
### 4.2 4 P0 adaptation files: delta-13 vs upstream 13→15
82+
83+
| File | delta-13 (lines) | 13→15 upstream change | 14.0+ ABI break |
84+
|---|---|---|---|
85+
| kern_descrip.c | 147 | const cap_rights_t / fde_change_size del / p_tracevp del / fdinit args / fo_stat sig change / etc. (13 ABIs) | yes — DP-M2-5 split to Phase 5b |
86+
| kern_mbuf.c | 75 | m_ext rearrangement (R-003) + 14.0+ m_snd_tag / m_rcvif | yes — DP-M2-5 |
87+
| uipc_mbuf.c | 58 | m_uiotombuf rewritten via mchain | yes — DP-M2-5 |
88+
| uipc_socket.c | 16 | CURVNET_ASSERT_SET 14.0+ added | yes — DP-M2-5 |
89+
90+
### 4.3 lib/Makefile KERN_SRCS measured (37; spec listed 38)
91+
92+
(See Chinese master for cross-validation.)
93+
94+
### 4.4 ff_kern_* files measurement
95+
96+
(All 9 ff_kern_* files verify-only — byte-identical with 13.0; no ABI conflict with M2-upgraded kern.)
97+
98+
---
99+
100+
## 5. netinet/libalias Risk Assessment (DP-9-B redo scope)
101+
102+
(F-Stack 0 delta; 14.0+ tcp.h `__tcp_get_flags / tcp_set_flags / TH_RES1` chain blocked M1; M2 unblocks via tcp.h cp from 15.0.)
103+
104+
---
105+
106+
## 6. Compile-Dependency Graph (rationale for M2 7-Phase order)
107+
108+
(See Chinese master full DAG; in summary:
109+
Phase 1 sys/sys headers → Phase 2 vm/uma (depends on sys/sys) → Phase 3 amd64+x86+arm64 (independent) → Phase 4 netinet/libalias (depends on Phase 1 tcp.h cp) → Phase 5 kern KERN_SRCS (depends on all above) → Phase 5b deferred P0 kern (DP-M2-5) → Phase 6 ff_kern_* verify → Phase 7 G-M2 strict build.)

0 commit comments

Comments
 (0)