Skip to content

Commit d25ba1e

Browse files
author
dpdk-spec-leader
committed
docs(spec): DPDK 23.11.5 -> 24.11.6 LTS upgrade — spec generation phase
Phase one (spec) of the F-Stack embedded DPDK upgrade from 23.11.5 LTS to 24.11.6 LTS. This commit lands the 6 deliverable spec documents (per the plan.md §0.2 7-doc deliverable list, of which plan.md itself is .gitignored as a local-only AI planning artifact per ea8aac1). Phase two (M1~M6 implementation: tree replace + 3-patch port + glue fix + tests + docs sync) will follow in subsequent commits. Spec generation flow (harness + spec-driven + 5 sub-agent team): - dpdk-23-patch-scout : F-Stack local DPDK patch inventory - dpdk-24-analyzer : 24.11.6 vs 23.11.5 key change analysis - diff-comparator : rte-layer file-level diff + symbol intersection - spec-author : 5 spec docs authored - gate-keeper : independent review (99-review-report.md PASS) Documents (6 files, 1708 lines total): 00-overview-and-glossary.md (142 lines) Project overview + glossary + scope; 4 core decisions table. 01-requirements-spec.md (154 lines) FR-D-1..11 + NFR-D-1..6; R-D1..D12 risks; DP-A1..A8 decided + DP-B1..B7 closed at spec phase + DP-C1..C3 deferred to phase two; gate matrix G1..G7. 02-current-and-target.md (299 lines) F-Stack's 3 historical patches inventory (5f3768c + 62f1c34 + 9271817 — diff with upstream 23.11.5 has empty differential beyond these 3 commits) + key 24.11.6 changes: - VERSION 23.11.5 -> 24.11.6 - ABI_VERSION 24.0 -> 25.0 - lib/ count 57 -> 59 (+argparse +ptr_compress, both opt-in, F-Stack 0 ref) - lib/eal +2962 lines (largest delta; eal_bus_cleanup() still unconditional in 24.11.6 stable -> 9271817 patch must rebase) - lib/timer 0 line delta (only __rte_cache_aligned macro position adjustment) - lib/net rte_ip.h 21.6KB -> 210B (split into rte_ip4.h + rte_ip6.h; F-Stack uses 10 struct rte_ipv{4,6}_hdr but only includes rte_ip.h — stub-include forwarding will make M4 compile pass) - KNI completely removed in 24.11.6 (R-D2 escalated P2->P1) - igb_uio not in upstream (F-Stack maintains own version since DPDK 21.05 removed it) - meson minimum 0.53.2 -> 0.57 04-port-and-impl.md (490 lines) M1..M6 milestones with full executable bash command lists; two-commit semantic layering ('replace:' + 'port:' merged per plan.md §4.4 / DP-A8) plus optional 'fix:' if glue layer needs source-level adaptation; 14-24 turn estimate. 06-test-and-acceptance-spec.md (385 lines) Single-doc test spec covering TC-A..G: - TC-A helloworld functional - TC-B helloworld perf (curl-bench 100/1000, phase-5b methodology reused, +-5% trade-off threshold) - TC-C nginx single-proc functional - TC-D nginx single-proc perf - TC-E nginx multi-proc functional + 9271817 worker-exit & 62f1c34 reload validations - TC-F nginx multi-proc wrk functional only (no horizontal scaling perf — user runs that on physical machines later) - TC-G F-Stack phase-2 + vlan-test historical features single-pass smoke 99-review-report.md (238 lines) gate-keeper review: PASS, no P0/P1 blocking. Closed 4 DP-Bx items at spec phase via direct measurement. One must-fix-before- M2: KNI A/B decision (FF_KNI=0 or preserve KNI subtree). Spec backed up to /data/workspace/dpdk-stable-24.11.6/f-stack-lib/test-configs/ dpdk-23-24-upgrade/ (matches the freebsd-15.0/f-stack-lib model). Workspace mandate: 0 direct rm/kill/chmod throughout. Local commit only; no push (per project standing convention).
1 parent 4e3cfc1 commit d25ba1e

6 files changed

Lines changed: 1708 additions & 0 deletions

File tree

‎docs/dpdk_23_24_upgrade_spec/zh_cn/00-overview-and-glossary.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# 00 — 项目概览与术语表
2+
3+
> 文档语言：中文（首版）
4+
> 系列文档根目录：`/data/workspace/f-stack/docs/dpdk_23_24_upgrade_spec/zh_cn/`
5+
> 文档版本：v0.1（2026-06-09）
6+
> Parent plan：`plan.md`
7+
8+
---
9+
10+
## 1. 项目一句话定义
11+
12+
把 **F-Stack** 当前内嵌的 **DPDK 23.11.5 LTS** 升级到 **DPDK 24.11.6 LTS**，并产出可被工程团队与后续 AI 代理直接执行的中文 Spec 文档集。
13+
14+
> 本 Spec 阶段只产文档，不动代码；真正的整树替换、3 patch 重打、测试由 `04-port-and-impl.md` 定义的阶段二执行。
15+
16+
---
17+
18+
## 2. 项目背景
19+
20+
### 2.1 F-Stack 与 DPDK 的依赖关系
21+
22+
F-Stack 是把 FreeBSD 内核协议栈剥离出来跑在 DPDK 用户态的工程：DPDK 提供 NIC I/O、lcore 多线程、mbuf 池、ring 队列等基础设施，F-Stack 在其上承载 FreeBSD 的 TCP/IP/IPFW/NETGRAPH。F-Stack 与 DPDK 的接口集中在 `lib/ff_dpdk_if.c`（主胶水）+ `lib/ff_dpdk_pcap.c` + `lib/ff_dpdk_kni.c` + `lib/ff_memory.c`（page-array）四个文件。
23+
24+
### 2.2 F-Stack 内嵌 DPDK 模式
25+
26+
- F-Stack 仓库 `dpdk/` 子目录是完整 DPDK 23.11.5 镜像（57 lib、含 `build/` 编译产物，与 upstream 23.11.5 顶层结构一致，仅缺 `.ci/.editorconfig/.github/.mailmap` 4 个 dotfile）。
27+
- F-Stack `lib/libfstack.a` 默认以 static lib 形式链接 DPDK，不依赖系统包管理。
28+
- F-Stack 在 `dpdk/` 内累积了 3 个本地 patch（详见 §5.1）。
29+
30+
### 2.3 升级驱动力
31+
32+
- **23.11 LTS 与 24.11 LTS 的对齐**：DPDK LTS 周期约 1 年，24.11.6（2026-06）是当前最新 stable LTS。停在 23.11 远离上游驱动 / PMD / 性能优化。
33+
- **`92718178b` patch 在上游的状态**：F-Stack 的 secondary 进程 cleanup fix 已等待 25.07 上游 fix 才能彻底消除（实测 24.11.6 stable 未合）。本次升级仅消除 23 vs 24 的 API 表面差异，但 `92718178b` 仍需 backport（24.11.6 内 `eal_bus_cleanup()` 仍是 PRIMARY/SECONDARY 不分的无条件调用）。
34+
- **新 lib 评估**：24.07 引入 `argparse` + `ptr_compress`（HiSilicon / Arm 提交），F-Stack 完全不引用，零成本。
35+
36+
---
37+
38+
## 3. 范围边界
39+
40+
### 3.1 IN-SCOPE（本 Spec 系列覆盖）
41+
42+
| 范围 | 实测规模 |
43+
|---|---|
44+
| `f-stack/dpdk/`（升级目标，整树替换 23.11.5 → 24.11.6） | 整树（与 dpdk-stable-24.11.6 完全对齐 + 重打 3 个 F-Stack 历史 patch）|
45+
| F-Stack 在 `dpdk/` 的本地 patch（3 commit） | 5f3768c63 + 62f1c34df + 92718178b |
46+
| F-Stack 胶水文件 | `lib/ff_dpdk_if.c` + `lib/ff_dpdk_pcap.c` + `lib/ff_dpdk_kni.c` + `lib/ff_memory.c`（行级核查 24.11.6 ABI 兼容）|
47+
| 测试 | helloworld 单进程功能+性能；nginx 单进程功能+性能；nginx 多进程 curl + wrk **功能** |
48+
49+
### 3.2 OUT-OF-SCOPE（本 Spec 系列**不**覆盖）
50+
51+
| 范围 | 不覆盖原因 |
52+
|---|---|
53+
| 实际整树替换与 3 patch 重打 | 仅 Spec 阶段；阶段二独立执行 |
54+
| 性能基线物理机重测 | CVM ssh round-trip ~6 ms 决定单进程吞吐上限；多进程水平扩展由 user 后续物理机环境完成 |
55+
| 24.11 KNI 子系统重启用 | 与本次升级解耦；如上游 KNI 在 24.11.6 仍存在，FF_KNI=1 维持现状 |
56+
| argparse / ptr_compress 启用 | 24.07 新引入，F-Stack 0 引用，零成本不启用 |
57+
| Git push | 仅本地 commit；push 时机由用户决定 |
58+
| 英文版 Spec | 待中文版人工审计后再考虑（与 freebsd_13_to_15_upgrade_spec 同款约定）|
59+
| 与 phase-2 启用的 7 个 FF_* flag 的回归矩阵 | 仅在 06-test 中作 single-pass smoke 验证，不做完整 5×3 矩阵 |
60+
61+
---
62+
63+
## 4. 三个源码根目录（实测）
64+
65+
| 路径 | 角色 | 版本 |
66+
|---|---|---|
67+
| `/data/workspace/dpdk-stable-23.11.5/` | DPDK 23.11.5 upstream 原版 | VERSION=23.11.5, ABI_VERSION=24.0 |
68+
| `/data/workspace/dpdk-stable-24.11.6/` | DPDK 24.11.6 upstream 原版（升级目标）| VERSION=24.11.6, ABI_VERSION=25.0 |
69+
| `/data/workspace/f-stack/dpdk/` | F-Stack 内嵌当前 DPDK | VERSION=23.11.5, ABI_VERSION=24.0（与 upstream 一致 + 3 个本地 patch）|
70+
71+
---
72+
73+
## 5. F-Stack 当前 DPDK 修改清单（实测）
74+
75+
### 5.1 3 个历史 patch 完整覆盖
76+
77+
经 dpdk-23-patch-scout 实测：F-Stack 在 `dpdk/` 内的本地修改 = 3 个 commit 完全覆盖（差集空集，无遗漏）。
78+
79+
| commit | 时间 | 内容分类 | 文件 | 升级时是否需迁移 |
80+
|---|---|---|---|---|
81+
| `5f3768c63` | 2025-10-31 | igb_uio 内核模块 + FreeBSD 13.1+ 适配 | `dpdk/kernel/linux/{igb_uio/{igb_uio.c, compat.h, Kbuild, Makefile, meson.build}, meson.build}` + `dpdk/lib/eal/freebsd/include/rte_os.h` | **必须重打** — 24.11.6 上游不会自带 igb_uio（DPDK 在 ≥21.05 已移除），且 FreeBSD 13.1+ CPU_AND/CPU_OR 适配是 F-Stack 独有 |
82+
| `62f1c34df` | 2026-01-16 | secondary 进程 restart 死循环 fix | `dpdk/lib/timer/rte_timer.c` + `rte_timer.h`（新增 `rte_timer_meta_init()`）+ `f-stack/lib/ff_dpdk_if.c:910`（调用点）| **必须重打** — lib/timer 在 24.11.6 上游零行变化；F-Stack 独有需求 |
83+
| `92718178b` | 2026-03-18 | secondary 进程调用 eal_bus_cleanup() 守护 | `dpdk/lib/eal/linux/eal.c`（rte_eal_cleanup 内 `eal_bus_cleanup()` 调用前加 `if (rte_eal_process_type() == RTE_PROC_PRIMARY)` 守护）| **必须重打** — 24.11.6 stable 未含等效 fix；上游真正 fix 在 25.07 commit `4bc53f8f0d64`，未 backport 到 24.11.6 |
84+
85+
### 5.2 F-Stack 不引用的新 lib
86+
87+
`lib/argparse/` + `lib/ptr_compress/` 在 F-Stack 0 引用（实测 grep `rte_argparse|rte_ptr_compress|argparse\.h|ptr_compress\.h` 在 `f-stack/lib/` 与 `f-stack/example/` 下均 0 命中）。
88+
89+
---
90+
91+
## 6. 术语表（Glossary）
92+
93+
| 术语 | 含义 |
94+
|---|---|
95+
| **DPDK** | Data Plane Development Kit；Intel 开源的用户态网络驱动框架 |
96+
| **DPDK LTS** | Long-Term Support 分支；每 12 个月发布，stable 维护 ~2 年 |
97+
| **`f-stack/dpdk/`** | F-Stack 仓库内嵌的 DPDK 镜像（当前 23.11.5）|
98+
| **`dpdk-stable-23.11.5/24.11.6`** | DPDK 官方 stable 分支的 release tarball / git checkout |
99+
| **VERSION / ABI_VERSION** | DPDK 顶层两个版本文件；前者是用户可见版本，后者是 SONAME 编号（24.0 = 23.x 兼容族；25.0 = 24.11+ 兼容族）|
100+
| **rte 层** | DPDK 公开 API 名空间（lib/<X>/rte_*.h）；F-Stack 通过 rte_* 与 DPDK 交互 |
101+
| **整树替换** | `cp -a /data/workspace/dpdk-stable-24.11.6/* f-stack/dpdk/` 一次性把 24.11.6 上游树替换 23.11.5；适合 LTS-to-LTS 升级 |
102+
| **3 patch 重打** | 把 F-Stack 历史 commit `5f3768c63 + 62f1c34df + 92718178b` 中的修改重新应用到 24.11.6 树上 |
103+
| **Primary / Secondary process** | DPDK 多进程模式；primary 持有 NIC，secondary 通过共享 hugepage 与之通信（F-Stack 的 nginx 多 worker、`tools/sbin/ipfw` 等都是 secondary）|
104+
| **EAL** | Environment Abstraction Layer；DPDK 启动 / lcore / hugepage / 设备扫描的核心子系统 |
105+
| **`rte_timer_meta_init()`** | F-Stack 在 lib/timer/ 中新增的内部函数（commit `62f1c34df`）；声明 "For f-stack internal use only"，不导出 ABI |
106+
| **`eal_bus_cleanup()` PRIMARY 守护** | F-Stack commit `92718178b` 在 `rte_eal_cleanup()` 内对 `eal_bus_cleanup()` 调用加 `if (rte_eal_process_type() == RTE_PROC_PRIMARY)` 包裹，避免 secondary 进程退出时去 reset 共享设备 |
107+
| **`igb_uio`** | Intel 1Gb UIO kernel module；DPDK 21.05 已从 upstream 移除，F-Stack 沿用 ≤20.11 的版本作为 vfio-pci 的备选 |
108+
| **rte_ip.h 陷阱** | 24.11 把 `rte_ip.h` 内容（21.6 KB）拆分到 `rte_ip4.h` + `rte_ip6.h`，仅保留 210B stub include；F-Stack 包含 `<rte_ip.h>` 仍能编译，但若依赖具体 IPv4/IPv6 结构需要补 include |
109+
| **argparse / ptr_compress** | DPDK 24.07 新增的两个 opt-in lib（命令行参数解析 / 32-16 位指针压缩）；F-Stack 0 引用 |
110+
| **phase-5b 方法学** | F-Stack 既有性能基线方法学（`tools/sbin/p5b_perf_matrix.sh` + curl-bench + 3 trials + 跨配置 delta + ssh round-trip ~6 ms 上限说明）|
111+
112+
---
113+
114+
## 7. 4 项核心决策（已落定，由 plan.md 多轮 q&a 确认）
115+
116+
| # | 决策 | 决定 | 来源 |
117+
|---|---|---|---|
118+
| 1 | Agent team 拓扑 | Leader + 5 子 agent | plan.md §2 |
119+
| 2 | DPDK 替换策略 | 整树替换（备份 + cp -a + 3 patch 重打）| plan.md §4，DP-A2 |
120+
| 3 | 测试矩阵组织 | 单 spec doc `06-test-and-acceptance-spec.md` | plan.md §0.2，q3=A |
121+
| 4 | spec 文档体系规模 | 7 篇精简（合并 02+03 + 合并 04+05）| plan.md §0.2，q4=B |
122+
| 5 | 3 patch 重打 commit 形态 | 合并到一个 `port:` commit，独立于 `replace:` commit | plan.md §4.4，DP-A8 |
123+
124+
---
125+
126+
## 8. 阅读顺序建议
127+
128+
| 角色 | 顺序 |
129+
|---|---|
130+
| 项目经理 / 架构 reviewer | 00 → 01 → 06 → 99 |
131+
| 实施工程师 | 00 → 02 → 04 → 06 |
132+
| 后续 AI 代理（拾取阶段二任务） | 04 → 02 → 06 |
133+
134+
---
135+
136+
## 9. 文档元信息
137+
138+
- **作者**：Leader（主对话内执行）
139+
- **协作输入**：dpdk-23-patch-scout / dpdk-24-analyzer / diff-comparator 三路并行调研（已完成）
140+
- **审查**：gate-keeper（待 Phase 4 出具 `99-review-report.md`）
141+
- **校验**：所有数字均来自实测命令输出；非实测的推断在术语表与本节注明来源
142+
- **下一步**：阅读 `01-requirements-spec.md` 了解本次升级要解决/不解决的具体问题

0 commit comments

Comments
 (0)