Update three-layer architecture docs and knowledge graph for recent changes

Add post-index delta sections to KNOWLEDGE_GRAPH_WIKI.md for:
- MTU/jumbo-frame configuration support (2D)
- native-mt SMP-aware pcpu/SMR slot isolation + global lock removal (2E)

Update Layer1 (multi-thread mode section), Layer2 (thread safety +
multi-thread interface), Layer3 (recent code delta), Summary, README,
and concise 01/02-LAYER docs to reflect thread_mode=1, -DSMP, per-thread
curcpu, uma_crit_lock removal, and MTU config support.

Author: jfb8856606

docs/01-LAYER1-ARCHITECTURE.md

@@ -304,6 +304,10 @@ Shared Resources:
 **Advantages**: Fault isolation, flexible scaling  
 **Disadvantages**: Complex inter-process synchronization
 
+### 6.2.1 Native Multi-Thread Mode (`thread_mode=1`, v1.26+)
+
+An alternative to multi-process: each worker thread runs its own FreeBSD stack instance (`vnet_i`, `thread0_i`) within one process. The kernel view is SMP-aware (`-DSMP`): each thread gets a dense pcpu slot `[0, nb_threads-1]` with per-thread `curcpu`, disjoint UMA/SMR per-CPU cache slots, and its own callout callwheel. The `uma_crit_lock` global spinlock has been removed (slot isolation is the sole protection). `thread_mode=0` preserves the original single-thread/multi-process behavior with zero regression. See `docs/native_mt_spec/`.
+
 ### 6.3 Kernel-Stack Coexistence (`FF_KERNEL_COEXIST`, optional, default off)
 
 An optional mode (compile-time macro `FF_KERNEL_COEXIST` + runtime `config.ini [stack] kernel_coexist`, both default off) lets one process serve traffic over **both** the F-Stack stack and the host Linux kernel stack from the **same `ff_epoll_wait` loop**:

docs/02-LAYER2-INTERFACES.md

@@ -410,6 +410,10 @@ void worker_main(int worker_id) {
 - Registering new callbacks after ff_run()
 - Cross-lcore socket operations
 
+### 5.1.1 Native Multi-Thread Mode (`thread_mode=1`, v1.26+)
+
+In `thread_mode=1`, each worker thread gets its own dense pcpu slot with per-thread `curcpu`, disjoint UMA/SMR per-CPU cache slots, and its own callout callwheel (`timeout_cpu` is `__thread`). The `uma_crit_lock` global spinlock has been removed (slot isolation is the sole protection). `ff_pthread_create()`-created application threads do **not** get a pcpu slot and must not call `ff_*` stack APIs (fail-fast by design). See `docs/native_mt_spec/`.
+
 ### 5.2 DPDK Atomic Operations
 
 ```c

docs/F-Stack_Architecture_Layer1_System_Overview.md

@@ -475,6 +475,17 @@ Core features:
 ✓ One process crash does not affect other processes
 ```
 
+#### Native Multi-Thread Mode (`thread_mode=1`, v1.26+)
+
+Since v1.26, F-Stack supports an optional **single-process multi-thread** mode (`thread_mode=1` in `config.ini`), where each worker thread runs its own FreeBSD stack instance (independent `vnet_i`, `thread0_i`) within one process. This complements the multi-process model for use cases where shared address space is needed.
+
+Key design points (spec: `docs/native_mt_spec/`):
+- **SMP-aware kernel view** (`-DSMP`, `lib/Makefile:221`): `MAXCPU=1024`, `UMA_ZONE_PCPU` preserved, each thread gets a dense pcpu slot `[0, nb_threads-1]` with per-thread `curcpu` (`lib/include/sys/pcpu.h:34`).
+- **Per-thread UMA/SMR slot isolation**: `mp_ncpus`/`mp_maxid`/`all_cpus` set from `nb_threads` before `uma_startup1()`; each thread exclusively owns its `uz_cpu[curcpu]` and SMR `c_seq` slot.
+- **Global `uma_crit_lock` removed** (commit `57b612d16`): the band-aid spinlock that serialized UMA per-CPU cache access is now a no-op, since slot isolation is the sole protection.
+- **Per-thread callwheel** (`ff_kern_timeout.c:190` `static __thread int timeout_cpu`).
+- **`thread_mode=0` zero regression**: all paths gated by `thread_mode ?` ternary; values identical to pre-change.
+
 ### 4.2 Multi-Process Deployment Model
 
 ```

docs/F-Stack_Architecture_Layer2_Interface_Specification.md

@@ -806,6 +806,12 @@ int ret = ff_pthread_create(&thread, NULL, thread_func, arg);
 // ✗ Cannot create new threads after ff_run()
 ```
 
+**Native Multi-Thread Mode (`thread_mode=1`, v1.26+)**:
+
+Since v1.26, F-Stack supports `thread_mode=1` in `config.ini` for single-process multi-thread operation. Each worker thread gets its own dense pcpu slot with per-thread `curcpu`, UMA/SMR per-CPU cache slot, and callout callwheel. The `uma_crit_lock` global spinlock that previously serialized UMA access has been removed (slot isolation is the sole protection). See `docs/native_mt_spec/` for the full design and runtime test data.
+
+> **Note**: `ff_pthread_create()`-created application threads do **not** get a pcpu slot (they have `pcpup == NULL`). Calling any `ff_*` stack API from such threads is unsupported and will crash (fail-fast by design). Only threads created via the `ff_stack_thread_init()` path (i.e., `main_loop` workers in `thread_mode=1`) have valid pcpu slots.
+
 **Example - Multi-Threaded Application**:
 
 ```c

docs/F-Stack_Architecture_Layer3_Function_Index.md

@@ -1206,6 +1206,35 @@ bash start.sh -c config.ini -b ./app
 
 ---
 
+## Recent Code Delta (2026-07~08, MTU jumbo-frame support + native-mt SMP-aware pcpu/SMR slot isolation)
+
+> 与 `01/02/03-LAYER*` 文档同步；权威细节见 `docs/mtu_change_spec/` 和 `docs/native_mt_spec/`。
+
+### MTU / jumbo-frame configuration support
+
+- **MTU capability query**：`lib/ff_dpdk_if.c` `ff_mtu_capability()` 查询 `rte_eth_dev_info` 的 `max_mtu`/`min_mtu`；jumbo-capable 标志用 `uint8_t`（非 `bool`，因 `-nostdinc` 下 `stdbool.h` 不可用）。魔数替换为命名宏 `FF_MTU_DEFAULT` / `FF_MTU_JUMBO_THRESHOLD` 等。
+- **SIOCSIFMTU ioctl 去重**：`lib/ff_veth.c` 通过 fall-through 使 v4/v6 共用一条 MTU 设置路径；校验硬件能力后调 `rte_eth_dev_set_mtu`。
+- **KNI/MTU 互斥解除**：`mtu_enable` 与 `kni.enable` 的互斥检查已移除（commit `989f1d2da`），二者可同时启用。
+- **IPv6 nd_ifinfo maxmtu 同步**：`lib/ff_veth.c` 在 MTU 变更时调 `if_notifymtu` 传播到 `nd_ifinfo.maxmtu`（commit `0f25ac495`），使 IPv6 路径 MTU 发现与邻居发现跟踪配置的 MTU。
+- **config.ini `[portN]`**：新增每端口 `mtu` 配置项（默认 1500）。
+- Traceability: `docs/mtu_change_spec/` (00-09, zh_cn/). Key commits: `0f8f6991e`, `332abf997`, `4c30d118f`, `989f1d2da`, `0f25ac495`.
+
+### native-mt SMP-aware pcpu/SMR slot isolation + global lock removal
+
+- **`-DSMP` 构建标志**（`lib/Makefile:221-223`）：激活 `MAXCPU=1024`、`UMA_ZONE_PCPU` 不再被剥离、per-cpu `M_ZERO` 全槽清零、`tcp_hpts.c` 的 `smp_topo()` 调用点。
+- **三元组 `mp_ncpus`/`mp_maxid`/`all_cpus`**（`lib/ff_freebsd_init.c:314-317`）：`thread_mode ? nb_threads : 1`，在 `uma_startup1()` 和 `mi_startup()` 之前设置且此后不变。
+- **`uma_page_slab_hash` 提前初始化**（`lib/ff_freebsd_init.c:379-387`）：移到 `uma_startup1()` 之前，修复 `mp_maxid ≥ 2` 时 zone-of-zones 多页导致的启动崩溃。
+- **`ff_pcpu_thread_init(cpuid)` 恢复使用形参**（`lib/ff_freebsd_init.c:106-112`）：`pcpu_init(pcpup, cpuid, ...)`（原为硬编码 `0`）；新增 `cpuid > mp_maxid` 的 `panic` 上界检查（因 `subr_pcpu.c:88 KASSERT` 在无 `INVARIANTS` 时被编译掉）。
+- **稠密 pcpu id**：主线程 `ff_pcpu_thread_init(thread_mode ? ff_cur_proc_id() : 0)`；worker `ff_stack_thread_init(thread_mode ? qconf->proc_id : 0)`；`ff_cur_proc_id()` = `ff_cur_lcore_conf()->proc_id`（稠密 `[0, nb_threads-1]`）。
+- **`curcpu` per-thread 化**（`lib/include/sys/pcpu.h:34`）：`#define curcpu PCPU_GET(cpuid)` = `pcpup->pc_cpuid`（原为字面量 `0`）；保留 `#undef curcpu` 避免与上游重定义。
+- **`timeout_cpu` 改 `__thread`**（`lib/ff_kern_timeout.c:190`）：`static __thread int timeout_cpu`（原为 `static int`，全局被每线程写）。
+- **`pause_wchan` 引导窗口兜底**（`lib/ff_kern_synch.c:105`）：`&pause_wchan[pcpup != NULL ? curcpu : 0]`——`malloc()` OOM 重试在 pcpu 建立前可达。
+- **`uma_crit_lock` 全局锁移除**（G2，commit `57b612d16`）：`lib/include/vm/uma_int.h:44-50` 的 `critical_enter/exit` 改为 `do {} while(0)` 空操作 + 3 行注释；`lib/ff_glue.c` 删除 `volatile int uma_crit_lock;` 定义。安全前提：`curcpu` 已绑线程（抢占/迁核不改变槽位归属），SMR 读侧的 `critical_enter` 在非 UMA TU 中本就是空操作。
+- **`thread_mode=0` 零回归**：所有路径由 `thread_mode ?` 三元运算门控；逻辑值等价（`mp_ncpus=1`/`mp_maxid=0`/`all_cpus={0}`/`curcpu=0`），4 项非等价差异已记录（`UMA_ZONE_PCPU` 不再剥离、CK `lock` 前缀恢复、`MAXCPU` BSS 增长、`curcpu` 内存载入）。
+- Traceability: `docs/native_mt_spec/zh_cn/` (00-17 + `_m17_*`), English in `docs/native_mt_spec/` root. Key commits: `c7996a94f` (G1), `57b612d16` (G2).
+
+---
+
 **Related Documents**:
 - [Layer 1: System Architecture Overview](./F-Stack_Architecture_Layer1_System_Overview.md)
 - [Layer 2: Interface Definition and Specification](./F-Stack_Architecture_Layer2_Interface_Specification.md)

docs/F-Stack_Knowledge_Base_Summary.md

@@ -2,7 +2,8 @@
 
 **Document Version**: 1.0  
 **Generation Date**: 2026-03-20  
-**Content Scope**: F-Stack v1.26 (FreeBSD 15.0 port; upgraded from 13.0 in 2025-2026 — M0~M5 + runtime-fix + rib-fix + Phase-5b NFR-1 PASS; **Phase-2 M6 NETGRAPH+IPFW + M7 PAGE_ARRAY + M8 ZC_SEND + M9 PA+ZC + M10 FLOW_IPIP + M11 FLOW_ISOLATE + M12 FDIR + M13 LOOPBACK + Phase-5b perf baseline matrix + F-A1 fix (PA-only now production-ready), 2026-06-08**) + DPDK 24.11.6 LTS (upgraded from 23.11.5 LTS on 2026-06-09 — tree replace + 4 patches re-applied; helloworld + nginx single/multi-worker + ipfw + vlan smoke all PASS) Complete Three-Layer Architecture Knowledge Base  
+**Last Updated**: 2026-08-05 (adds native-mt SMP-aware pcpu/SMR slot isolation + global lock removal, MTU/jumbo-frame configuration support)  
+**Content Scope**: F-Stack v1.26 (FreeBSD 15.0 port; upgraded from 13.0 in 2025-2026 — M0~M5 + runtime-fix + rib-fix + Phase-5b NFR-1 PASS; **Phase-2 M6 NETGRAPH+IPFW + M7 PAGE_ARRAY + M8 ZC_SEND + M9 PA+ZC + M10 FLOW_IPIP + M11 FLOW_ISOLATE + M12 FDIR + M13 LOOPBACK + Phase-5b perf baseline matrix + F-A1 fix (PA-only now production-ready), 2026-06-08**) + DPDK 24.11.6 LTS (upgraded from 23.11.5 LTS on 2026-06-09 — tree replace + 4 patches re-applied; helloworld + nginx single/multi-worker + ipfw + vlan smoke all PASS) + **native-mt SMP-aware pcpu/SMR slot isolation** (2026-08, commits `c7996a94f` G1 + `57b612d16` G2; spec: `docs/native_mt_spec/`) + **MTU/jumbo-frame configuration support** (2026-07; spec: `docs/mtu_change_spec/`) Complete Three-Layer Architecture Knowledge Base  
 **Document Location**: `/data/workspace/f-stack/docs/`  
 **Purpose**: Pre-requisite architecture documentation for Spec-Driven Development
 

docs/KNOWLEDGE_GRAPH_WIKI.md

@@ -94,6 +94,49 @@ Traceability: `docs/ff_rss_check_opt_spec/zh_cn/` (00-11), esp. `05-接口设计
 - **Fix**: intercept `IPPROTO_IP + LINUX_IP_BIND_ADDRESS_NO_PORT` in `ff_setsockopt`/`ff_getsockopt` before `linux2freebsd_opt`, return success no-op. FreeBSD already defers ephemeral port selection to connect; F-Stack RSS reverse path (`ff_rss_adjust_sport/6`) picks the source port at connect. Covers both v4 and v6 (nginx calls setsockopt at IPPROTO_IP level for both).
 - **Complements R-E (§6 of ff_rss 10)**: R-E fixed the kernel-side bind gate (`in_pcb.c`/`in6_pcb.c`); this patch fixes the setsockopt option wiring so nginx can actually request the delayed-port behavior without EINVAL.
 
+---
+
+## 2D. Post-index code delta: MTU/jumbo-frame configuration support
+
+> **Manual addendum (not yet re-indexed)**: documented against current source (2026-07). Covers the MTU change feature set (`mtu_change_spec/`): jumbo-frame enablement, KNI/MTU mutual-exclusion removal, IPv6 `nd_ifinfo.maxmtu` sync, and SIOCSIFMTU ioctl dedup. Re-index with `npx gitnexus analyze` to fold into the graph.
+
+The feature allows runtime MTU changes on DPDK-backed veth interfaces, including jumbo frames up to the NIC's hardware limit. The KNI/MTU mutual exclusion that previously blocked `mtu_enable` when KNI was enabled has been removed; IPv6 `nd_ifinfo.maxmtu` is now synced via `if_notifymtu` so IPv6 path MTU discovery tracks the configured MTU.
+
+| Area | Where in source |
+|------|-----------------|
+| MTU capability query | `lib/ff_dpdk_if.c`: `ff_mtu_capability()` queries `rte_eth_dev_info` for `max_mtu`/`min_mtu`; uses `uint8_t` (not `bool`) for the jumbo-capable flag (commit `4c30d118f` clean-build fix). Magic numbers replaced with named macros `FF_MTU_DEFAULT`, `FF_MTU_JUMBO_THRESHOLD` etc. (commit `0f8f6991e`). |
+| SIOCSIFMTU ioctl handler | `lib/ff_veth.c`: dedup'd via fall-through so v4 and v6 share one code path (commit `332abf997`); validates against `if_getmtu` + hw capability, calls `rte_eth_dev_set_mtu` for DPDK-backed NICs. |
+| KNI/MTU mutex removal | `lib/ff_dpdk_if.c` / `lib/ff_config.c`: removed the `mtu_enable`/`kni.enable` mutual-exclusion check (commit `989f1d2da`); both can now be enabled simultaneously. |
+| IPv6 nd_ifinfo maxmtu sync | `lib/ff_veth.c`: `if_notifymtu` called on MTU change to propagate to `nd_ifinfo.maxmtu` (commit `0f25ac495`), ensuring IPv6 path MTU discovery and neighbor discovery use the updated MTU. |
+| config.ini `[portN]` | New per-port `mtu` configuration item (default 1500); parsed in `ff_config.c`. |
+| IPv6 fragmentation | `freebsd/netinet6/`: IPv6 fragment reassembly respects the updated `maxmtu` (FreeBSD 15.0 `ip6_input` path). |
+
+Traceability: `docs/mtu_change_spec/` (00-09, zh_cn/), esp. `06-solution-and-conclusion.md` (jumbo validation complete), `09-implementation-and-code-change-design.md`. Key commits: `0f8f6991e`, `332abf997`, `4c30d118f`, `989f1d2da`, `0f25ac495`, `1336077d0`.
+
+---
+
+## 2E. Post-index code delta: native-mt SMP-aware pcpu/SMR slot isolation + global lock removal
+
+> **Manual addendum (not yet re-indexed)**: documented against current source (2026-08). Covers the `native_mt_spec/` spec 17 work: making the FreeBSD kernel view SMP-aware for `thread_mode=1`, giving each stack thread a dense pcpu slot with per-thread `curcpu`, and removing the `uma_crit_lock` global spinlock that was serializing the UMA per-CPU cache fast path. Re-index with `npx gitnexus analyze` to fold into the graph.
+
+Before this change, all stack threads shared pcpu slot 0 (because `ff_pcpu_thread_init` ignored its `cpuid` parameter, `mp_ncpus=1`, `mp_maxid=0`, `MAXCPU=1`, and `curcpu` was hardcoded to 0). This caused SMR read-side sequence numbers to be overwritten across threads, creating a UAF window. A global spinlock `uma_crit_lock` was introduced as a band-aid to serialize UMA per-CPU cache access, but it was a dataplane bottleneck. This work (G1+G2) makes each thread own a distinct dense pcpu slot and removes the lock.
+
+| Area | Where in source |
+|------|-----------------|
+| `-DSMP` build flag | `lib/Makefile:221-223`: `CFLAGS+= -DSMP` — activates `MAXCPU=1024`, `UMA_ZONE_PCPU` not stripped, per-cpu `M_ZERO` full-slot zeroing, `smp_topo()` call site in `tcp_hpts.c`. |
+| `smp_topo()` stub | `lib/ff_glue.c:171-177`: returns `NULL` (safe: `tcp_hpts.c:1890 if (cpu_top == NULL) grp_cnt = 1`; `grps[]` never `malloc`'d). |
+| Triple `mp_ncpus`/`mp_maxid`/`all_cpus` | `lib/ff_freebsd_init.c:314-317`: `nb_cpus = thread_mode ? nb_threads : 1; mp_ncpus = nb_cpus; mp_maxid = nb_cpus - 1; for (i...) CPU_SET(i, &all_cpus);` — set **before** `uma_startup1()` (`:331`) and `mi_startup()` (`:339`); never modified after. |
+| `uma_page_slab_hash` advance | `lib/ff_freebsd_init.c:379-387`: moved hash init **before** `uma_startup1()` — when `mp_maxid ≥ 2`, zone-of-zones item size exceeds 1 page → `UMA_ZFLAG_VTOSLAB` set → `keg_alloc_slab()` calls `vsetzoneslab()` during `uma_startup1()` → NULL deref crash without this fix. |
+| `ff_pcpu_thread_init(cpuid)` uses parameter | `lib/ff_freebsd_init.c:106-112`: now `pcpu_init(pcpup, cpuid, ...)` (was hardcoded `0`); upper-bound `panic` if `cpuid > mp_maxid` (because `subr_pcpu.c:88 KASSERT` is compiled out without `INVARIANTS`). |
+| Dense pcpu id for main/worker | `lib/ff_freebsd_init.c:317`: `ff_pcpu_thread_init(thread_mode ? ff_cur_proc_id() : 0)`; `lib/ff_dpdk_if.c:2652`: `ff_stack_thread_init(thread_mode ? qconf->proc_id : 0)`. `ff_cur_proc_id()` = `ff_cur_lcore_conf()->proc_id` (dense `[0, nb_threads-1]`). |
+| `curcpu` per-thread | `lib/include/sys/pcpu.h:34`: `#define curcpu PCPU_GET(cpuid)` = `pcpup->pc_cpuid` (was `0`); `#undef curcpu` retained to avoid redefinition with upstream `freebsd/sys/pcpu.h:218`. |
+| `timeout_cpu` per-thread | `lib/ff_kern_timeout.c:190`: `static __thread int timeout_cpu` (was `static int`); `CC_CPU(cpu)` ignores arg and returns calling thread's own `__thread cc_cpu`. |
+| `pause_wchan` bootstrap fallback | `lib/ff_kern_synch.c:105`: `&pause_wchan[pcpup != NULL ? curcpu : 0]` — reachable from `malloc()` OOM retry before pcpu is built. |
+| `uma_crit_lock` removal (G2) | `lib/include/vm/uma_int.h:44-50`: `critical_enter/exit` → `do {} while(0)` + 3-line comment; `lib/ff_glue.c`: deleted `volatile int uma_crit_lock;` definition. Safe because `curcpu` is per-thread (preemption/migration doesn't change slot), and SMR read-side `critical_enter` was already a no-op in non-UMA TUs. |
+| `thread_mode=0` zero regression | All paths gated by `thread_mode ?` ternary; `mp_ncpus=1`, `mp_maxid=0`, `all_cpus={0}`, `curcpu=0`, `ff_pcpu_thread_init(0)` — value-identical to pre-change (4 known non-equivalent differences: `UMA_ZONE_PCPU` no longer stripped, CK `lock` prefix restored, `MAXCPU`-sized BSS growth, `curcpu` memory load). |
+
+Traceability: `docs/native_mt_spec/zh_cn/` (00-17 + `_m17_*` + `plan-17-*`), esp. `17-SMP-aware-pcpu视图与去全局锁.md` (main spec), `_m17_F_runtime.md` (runtime test report), `_m17_gate_code_g1.md`/`_m17_gate_code_g2.md` (gate reviews). English translation in `docs/native_mt_spec/` root. Key commits: `c7996a94f` (G1), `57b612d16` (G2).
+
 ## 3. Directory Structure
 
 ```

docs/README.md

@@ -251,7 +251,7 @@ Recommended path:
 ### Version Information
 
 ```
-Knowledge base version: 1.5 (adds R10: ff_readv/ff_writev/ff_ioctl/ff_dup/ff_dup2 kernel-fd routing + select/poll documented limits, 2026-06-18; on top of 1.4 R9 ff_kqueue/ff_kevent coexistence + IPv6 IPV6_V6ONLY + 1.3 FF_KERNEL_COEXIST kernel-stack coexistence + 1.2 FreeBSD 13.0 → 15.0 first-stage + Phase-2 M6-M13 + Phase-5b + F-A1 fix + vlan-vip-ipfw test)
+Knowledge base version: 1.6 (adds native-mt SMP-aware pcpu/SMR slot isolation + global uma_crit_lock removal, 2026-08-05, commits c7996a94f+57b612d16, spec: docs/native_mt_spec/; and MTU/jumbo-frame configuration support, 2026-07, spec: docs/mtu_change_spec/; on top of 1.5 R10 ff_readv/ff_writev/ff_ioctl/ff_dup/ff_dup2 kernel-fd routing + select/poll documented limits, 2026-06-18; on top of 1.4 R9 ff_kqueue/ff_kevent coexistence + IPv6 IPV6_V6ONLY + 1.3 FF_KERNEL_COEXIST kernel-stack coexistence + 1.2 FreeBSD 13.0 → 15.0 first-stage + Phase-2 M6-M13 + Phase-5b + F-A1 fix + vlan-vip-ipfw test)
 F-Stack version: v1.26 (branch feature/1.26)
 FreeBSD port base: 15.0 (was 13.0 in v1.25)
 DPDK version: 24.11.6 LTS (upgraded from 23.11.5 LTS on 2026-06-09 via tree replace + 4 patches re-applied; see dpdk_23_24_upgrade_spec/zh_cn/)