Add English translation of MTU change spec documents

Translate all 16 Chinese spec documents (00-15) under
docs/mtu_change_spec/zh_cn/ to English, placed alongside zh_cn/ in
docs/mtu_change_spec/. Cross-references updated to English filenames.

Author: jfb8856606

docs/mtu_change_spec/00-overview-index.md

@@ -0,0 +1,47 @@
+# F-Stack MTU Modification After DPDK NIC Takeover — Investigation Overview
+
+> Conclusion-first document. All conclusions are cross-validated against **actual code** (`lib/` + `freebsd/`) + **runtime testing** + **external authoritative sources**; conflicts resolved in favor of code and runtime results.
+> Investigation target: `/data/workspace/f-stack/`, DPDK 24.11.6, runtime environment is the local DPDK-exclusive NIC (virtio, `0000:00:09.0`, IP `9.134.214.176`).
+
+## One-Line Conclusion
+
+**Partial support**: After f-stack's DPDK takes over the NIC, **decreasing MTU (≤1500) works**; **increasing MTU (>1500, i.e., jumbo frame) is unsupported** — `ff_ioctl(SIOCSIFMTU)` returns `EINVAL(22)` directly for >1500.
+
+## Per-Scenario Conclusions
+
+| Scenario | Supported | Direct Evidence |
+|---|---|---|
+| **Decrease MTU** (e.g., 1500→1400) | ✅ **Supported** | Runtime test `mtu 1400` succeeded (exit=0); code-wise `ether_ioctl` writes `ifp->if_mtu` directly for values ≤ETHERMTU (`if_ethersubr.c:1181`) |
+| **Increase MTU to jumbo** (e.g., 9000) | ❌ **Unsupported** | Runtime test returns `ioctl SIOCSIFMTU (set mtu): Invalid argument`; code-wise `ether_ioctl` returns `EINVAL` for `ifr_mtu > ETHERMTU` (`if_ethersubr.c:1178-1179`) |
+| **Increase MTU to 2000** (slightly over standard frame) | ❌ **Unsupported** | Same as above, same EINVAL; upper bound locked at `ETHERMTU=1500` |
+
+## Root Cause (Software/Hardware Gap)
+
+1. **Protocol-stack layer hardcodes 1500 upper bound**: f-stack's `ff_veth_ioctl` (`lib/ff_veth.c:235`) delegates `SIOCSIFMTU` to FreeBSD `ether_ioctl` (L248). `ether_ioctl` (`freebsd/net/if_ethersubr.c:1174-1181`) hardcodes `EINVAL` for `ifr_mtu > ETHERMTU(1500)`. Also `ether_ifattach` (`if_ethersubr.c:985`) statically sets `if_mtu` to `ETHERMTU=1500` on NIC attach.
+2. **DPDK hardware layer has no MTU wiring at all**: `lib/ff_dpdk_if.c` port init/config flow has **no** `rte_eth_dev_set_mtu` call; `rxmode` has no `mtu`/`max_rx_pkt_len`/jumbo settings; mbuf pool created with `RTE_MBUF_DEFAULT_BUF_SIZE`(=2048), not enlarged by large MTU. Even bypassing the protocol-stack 1500 limit, DPDK hardware cannot send/receive jumbo frames.
+3. **No software/hardware linkage**: Even if `if_mtu` (software value) is changed, it is never propagated to the DPDK hardware port. For ≤1500 this is harmless (hardware default 2048 buf suffices for standard frames); for jumbo it guarantees failure.
+
+## Three-Source Evidence Consistency
+
+| Evidence Source | Conclusion |
+|---|---|
+| **Code** (`ff_veth.c`/`if_ethersubr.c`/`ff_dpdk_if.c`) | ether_ioctl hardcodes 1500 upper bound; DPDK has no set_mtu/jumbo/large mbuf |
+| **Runtime test** (`tools/sbin/ifconfig`) | 1400 succeeds; 9000/2000 both EINVAL; upper bound 1500 |
+| **External** (F-Stack official issues #239 / #720) | Maintainer confirms "mtu cannot exceed 1500"; jumbo support issue remains OPEN (enhancement, unimplemented) |
+
+## Modification Points for Full Jumbo Support (Increasing MTU)
+
+See `06-solution-and-conclusion.md` for details. Core four points (all required):
+1. `ff_dpdk_if.c`: port config calls `rte_eth_dev_set_mtu` + enables jumbo `rxmode` (`RTE_ETH_RX_OFFLOAD_SCATTER` or enlarged `mtu`).
+2. `ff_dpdk_if.c`: mbuf pool `data_room_size` enlarged by max MTU (or multi-pool/scatter receive).
+3. `ff_veth.c` / `ether_ifattach` path: make `if_mtu` upper bound configurable (bypass `ether_ioctl`'s ETHERMTU hard check, typically by intercepting `SIOCSIFMTU` in `ff_veth_ioctl` to handle it and propagate to DPDK).
+4. `config.ini`: add `mtu` config item for `ff_veth_setup_interface` to read and initialize.
+
+## Document Index
+
+- `01-protocol-stack-analysis.md` — SIOCSIFMTU ioctl conversion and ether_ioctl 1500 upper-bound chain
+- `02-dpdk-hardware-analysis.md` — port/mbuf/rxmode config gaps
+- `03-software-hardware-gap-analysis.md` — different consequences of decreasing vs. increasing MTU
+- `04-external-research.md` — F-Stack official issues, DPDK docs, tech blogs
+- `05-runtime-test-report.md` — runtime evidence chain (tools/sbin/ifconfig)
+- `06-solution-and-conclusion.md` — full jumbo modification plan + final conclusion

docs/mtu_change_spec/01-protocol-stack-analysis.md

@@ -0,0 +1,101 @@
+# Protocol-Stack Layer Analysis: SIOCSIFMTU Full Path
+
+> This document analyzes f-stack's user-space FreeBSD protocol stack handling of MTU modification (`SIOCSIFMTU`/`SIOCGIFMTU`). All references are actual code `file:line`.
+
+## 1. Application Layer → f-stack ioctl Conversion
+
+f-stack exposes Linux-semantics `ff_ioctl`, which must convert Linux `SIOCSIFMTU`/`SIOCGIFMTU` to FreeBSD equivalents.
+
+`lib/ff_syscall_wrapper.c`:
+```c
+177: #define LINUX_SIOCGIFMTU      0x8921
+178: #define LINUX_SIOCSIFMTU      0x8922
+...
+518:        case LINUX_SIOCGIFMTU:
+519:            return SIOCGIFMTU;
+520:        case LINUX_SIOCSIFMTU:
+521:            return SIOCSIFMTU;
+```
+
+- Read MTU: `LINUX_SIOCGIFMTU(0x8921)` → FreeBSD `SIOCGIFMTU`
+- Set MTU: `LINUX_SIOCSIFMTU(0x8922)` → FreeBSD `SIOCSIFMTU`
+
+The protocol-stack layer **does have** the conversion path to receive MTU modification requests; `tools/sbin/ifconfig` also changes MTU through this path.
+
+## 2. Generic ifioctl Layer (if.c)
+
+The converted `SIOCSIFMTU` enters FreeBSD's generic interface ioctl dispatch.
+
+`freebsd/net/if.c`:
+```c
+2729:  case SIOCSIFMTU:
+2733:      error = priv_check(td, PRIV_NET_SETIFMTU);   // permission check
+2736:      if (ifr->ifr_mtu < IF_MINMTU || ifr->ifr_mtu > IF_MAXMTU)  // broad bounds
+              ... (out-of-range EINVAL)
+          // call driver's if_ioctl callback
+2755:          if_notifymtu(ifp);   // notify MTU change on success and change
+```
+Read MTU:
+```c
+2515:      ifr->ifr_mtu = ifp->if_mtu;   // SIOCGIFMTU returns software value
+```
+
+- The `if.c` layer only does `priv_check` and **broad** bounds checking (`IF_MINMTU`~`IF_MAXMTU`, `IF_MAXMTU` up to 65535) — not the source of the 1500 limit.
+- After passing `priv_check`/bounds, it calls the driver's `if_ioctl` callback (i.e., `ff_veth_ioctl`).
+
+## 3. Driver Layer ff_veth_ioctl (Key Delegation Point)
+
+`lib/ff_veth.c`:
+```c
+234: static int
+235: ff_veth_ioctl(if_t ifp, u_long cmd, caddr_t data)
+236: {
+238:     struct ff_veth_softc *sc = if_getsoftc(ifp);
+240:     switch (cmd) {
+241:     case SIOCSIFFLAGS:            // only explicitly handles UP/DOWN
+242:         if (if_getflags(ifp) & IFF_UP) { ff_veth_init(sc); }
+244:         else if (...) ff_veth_stop(sc);
+246:         break;
+247:     default:
+248:         error = ether_ioctl(ifp, cmd, data);   // SIOCSIFMTU falls here
+249:         break;
+250:     }
+252:     return (error);
+253: }
+```
+
+Callback registration (`ff_veth_setup_interface`):
+```c
+923:     if_setioctlfn(ifp, ff_veth_ioctl);
+```
+
+- `ff_veth_ioctl` **does not handle `SIOCSIFMTU` separately**; it delegates entirely to FreeBSD's generic Ethernet handler `ether_ioctl`.
+- This means: **f-stack has no DPDK hardware propagation hook for MTU modification at the driver layer** (no `rte_eth_dev_set_mtu` call).
+
+## 4. ether_ioctl's 1500 Hard Upper Bound (True Source of EINVAL)
+
+`freebsd/net/if_ethersubr.c`:
+```c
+1174:  case SIOCSIFMTU:
+1178:      if (ifr->ifr_mtu > ETHERMTU) {
+1179:          error = EINVAL;              // >1500 rejected directly
+1181:      } else ifp->if_mtu = ifr->ifr_mtu;   // ≤1500 writes software value
+```
+
+- `ETHERMTU = 1500`. This is the **true upper bound source for MTU modification**:
+  - `ifr_mtu ≤ 1500`: accepted, writes `ifp->if_mtu` (software value).
+  - `ifr_mtu > 1500`: returns `EINVAL`, `if_mtu` unchanged.
+
+## 5. MTU Initial Value
+
+`ether_ifattach` statically initializes MTU to 1500 on NIC attach:
+```c
+985:      ifp->if_mtu = ETHERMTU;
+```
+`ff_veth_setup_interface` (`ff_veth.c:927`) calls `ether_ifattach(ifp, sc->mac)`, so the f-stack NIC defaults to MTU=1500.
+
+## Summary (Protocol-Stack Layer)
+
+- **Can change**: The protocol-stack layer supports modifying `if_mtu` software value via `ff_ioctl(SIOCSIFMTU)`, provided it is **≤1500**.
+- **Cannot increase**: `ether_ioctl` hardcodes `> ETHERMTU(1500)` → `EINVAL`; f-stack does not intercept/override in `ff_veth_ioctl`, so jumbo is rejected at the protocol-stack layer.
+- **No hardware propagation**: Regardless of success, the `if_mtu` software value is never propagated to the DPDK port via `rte_eth_dev_set_mtu` (see `02-dpdk-hardware-analysis.md`).

docs/mtu_change_spec/02-dpdk-hardware-analysis.md

@@ -0,0 +1,71 @@
+# DPDK Hardware Layer Analysis: Port / mbuf / rxmode Config Gaps
+
+> This document analyzes f-stack's current MTU/jumbo-related implementation at the DPDK port init/config stage. All references are actual code `file:line` (`lib/ff_dpdk_if.c`, DPDK 24.11.6).
+
+## 1. No rte_eth_dev_set_mtu Call
+
+Full-text search of `lib/ff_dpdk_if.c` for `mtu` / `rte_eth_dev_set_mtu` / `max_rx_pkt_len` / `jumbo` / `RTE_ETHER_MTU`: **0 matches** (only matches `rte_pktmbuf_pool_create`, `rte_eth_dev_configure`, `rxmode.offloads` and other MTU-unrelated items).
+
+Conclusion: **f-stack never calls `rte_eth_dev_set_mtu`**; port MTU is always the PMD default (standard Ethernet 1500), and the protocol-stack `if_mtu` software value has **no linkage** to the hardware MTU.
+
+## 2. mbuf Pool Created at Standard Frame Size
+
+`lib/ff_dpdk_if.c`:
+```c
+425:        if (rte_eal_process_type() == RTE_PROC_PRIMARY) {
+426:            snprintf(s, sizeof(s), "mbuf_pool_%d", socketid);
+427:            pktmbuf_pool[socketid] =
+428:                rte_pktmbuf_pool_create(s, nb_mbuf,
+429:                    MEMPOOL_CACHE_SIZE, 0,
+430:                    RTE_MBUF_DEFAULT_BUF_SIZE, socketid);   // 2048B per mbuf data area
+431:        } else {
+432:            ... rte_mempool_lookup(s);   // secondary reuses
+433:        }
+```
+
+- `RTE_MBUF_DEFAULT_BUF_SIZE = 2048` (DPDK definition = `RTE_PKTMBUF_HEADROOM(128) + 1920`, actual usable data area ~1920B).
+- Sufficient for standard Ethernet frames (1500 + 14 header + FCS/overhead), but **far insufficient for jumbo frames (9000+)**.
+- No `data_room_size` enlargement by large MTU, no scatter receive enabled, so a single mbuf cannot hold a jumbo frame.
+
+## 3. Port rxmode Has No jumbo / max_rx_pkt_len Config
+
+`lib/ff_dpdk_if.c` port config section (around L700-923), `port_conf.rxmode` settings:
+```c
+733:      port_conf.rxmode.mq_mode = RTE_ETH_MQ_RX_RSS;          // RSS
+781-782:  ... RTE_ETH_RX_OFFLOAD_VLAN_STRIP                       // VLAN strip
+787:      port_conf.rxmode.offloads &= ~RTE_ETH_RX_OFFLOAD_KEEP_CRC;
+791-793:  ... DEV_RX_OFFLOAD_TCP_LRO                              // LRO (conditional)
+799-803:  ... RTE_ETH_RX_OFFLOAD_CHECKSUM                        // checksum
+807-809:  ... RTE_ETH_RX_OFFLOAD_TIMESTAMP                       // timestamp
+```
+```c
+856:      ret = rte_eth_dev_configure(port_id, nb_queues, nb_queues, &port_conf);
+...
+885:          rxq_conf.offloads = port_conf.rxmode.offloads;
+886:          ret = rte_eth_rx_queue_setup(port_id, q, nb_rxd, ...);
+```
+
+- `rxmode` has **no** `mtu` field set (in DPDK 24.x `rte_eth_dev_configure` uses `port_conf.rxmode.mtu`; f-stack leaves it unset → defaults to `RTE_ETHER_MTU=1500`).
+- **No** jumbo-related offload (e.g., `RTE_ETH_RX_OFFLOAD_SCATTER`) for receiving large frame segments.
+- Therefore the DPDK port initializes with standard 1500 MTU; the PMD's jumbo send/receive capability is never enabled.
+
+> Note: The local DPDK NIC is virtio; its jumbo/scatter capability is limited by the PMD. Even if f-stack code adds the above config, the PMD and underlying NIC/vSwitch must jointly support jumbo to truly enable it (see `04-external-research.md`).
+
+## 4. External API Has No MTU Item
+
+- `lib/ff_api.h`: search `mtu` = 0 matches, **no external MTU get/set interface**.
+- `config.ini`: search `mtu`/`jumbo` = 0 matches, **no MTU config item**.
+
+f-stack neither reads any MTU config at init nor exposes a programming interface for upper layers to set hardware MTU.
+
+## Summary (DPDK Hardware Layer)
+
+| Check Item | Status | Impact |
+|---|---|---|
+| `rte_eth_dev_set_mtu` | Never called | Software `if_mtu` not propagated to hardware |
+| mbuf `data_room_size` | Fixed 2048 (`RTE_MBUF_DEFAULT_BUF_SIZE`) | Cannot hold >~1920B jumbo frames |
+| `rxmode.mtu` / jumbo offload | Unset (defaults to 1500) | Port initializes at standard frame |
+| scatter (segmented receive) | Not enabled | Single mbuf cannot assemble jumbo frame |
+| `config.ini` MTU item / `ff_api` MTU interface | None | No config/programming entry point |
+
+**Conclusion**: The DPDK hardware layer has no MTU wiring or jumbo support whatsoever. Combined with the protocol-stack 1500 upper bound, this forms the "decrease MTU works, increase MTU unsupported" software/hardware gap (see `03-software-hardware-gap-analysis.md`).

docs/mtu_change_spec/03-software-hardware-gap-analysis.md

@@ -0,0 +1,68 @@
+# Software/Hardware Gap and Difference Analysis
+
+> Synthesizing `01-protocol-stack-analysis.md` (software layer) and `02-dpdk-hardware-analysis.md` (hardware layer), this document analyzes the different consequences and the nature of the gap for "decreasing MTU" vs. "increasing MTU".
+
+## 1. Nature of the Gap
+
+f-stack's MTU handling has two independent stages, neither of which is wired through to hardware:
+
+```
+Application ff_ioctl(SIOCSIFMTU)
+   │  ff_syscall_wrapper.c:520 (LINUX_SIOCSIFMTU→SIOCSIFMTU)
+   ▼
+if.c:2729 (priv_check + IF_MINMTU/IF_MAXMTU broad check)
+   │
+   ▼
+ff_veth_ioctl (ff_veth.c:248 default branch)
+   │
+   ▼
+ether_ioctl (if_ethersubr.c:1178)
+   ├── ifr_mtu ≤ 1500 → write ifp->if_mtu (software value) ✅
+   └── ifr_mtu > 1500 → EINVAL ❌ (hard upper bound)
+   │
+   ✗ Gap: no path calls rte_eth_dev_set_mtu
+   ▼
+DPDK port hardware MTU stays at PMD default (1500), mbuf buf=2048
+```
+
+**Gap point**: The `if_mtu` modified at the protocol-stack layer is a **pure software value**, never propagated to the DPDK hardware port. f-stack lacks the bridge from "software MTU change → `rte_eth_dev_set_mtu` hardware propagation".
+
+## 2. Decreasing MTU (≤1500): Works
+
+**Protocol-stack layer**: `ether_ioctl` accepts, writes `if_mtu` (`if_ethersubr.c:1181`). The protocol stack then uses the smaller `if_mtu` for TCP MSS negotiation and IP fragmentation decisions — i.e., outbound data is organized by the new smaller MTU.
+
+**Hardware layer**: DPDK port MTU remains 1500, mbuf buf=2048. Since the new MTU (e.g., 1400) is **smaller** than hardware capacity, send/receive is unaffected:
+- Send: protocol stack already organizes packets ≤1400; frames are smaller; hardware sends normally.
+- Receive: hardware still receives ≤1500 frames; protocol stack processes per `if_mtu`.
+
+**Conclusion**: Decreasing MTU **works**. The software/hardware gap is harmless in the "decrease" direction — because hardware capacity (1500/2048) is already ≥ the new software MTU. Runtime test confirmed 1400 succeeds with normal connectivity (see `05-runtime-test-report.md`).
+
+> Note: Decreasing MTU only changes the local protocol stack's fragmentation/MSS behavior, not hardware; this is distinct from "physical link MTU". No side effects for the decrease scenario.
+
+## 3. Increasing MTU (>1500, jumbo): Unsupported
+
+**Protocol-stack layer**: `ether_ioctl` returns `EINVAL` for `ifr_mtu > ETHERMTU(1500)` (`if_ethersubr.c:1178-1179`). The request is **rejected at the protocol-stack layer**; `if_mtu` unchanged. Runtime test confirmed 9000 and 2000 both return `Invalid argument`.
+
+**Even bypassing the protocol-stack upper bound** (e.g., directly changing `ether_ifattach`'s `if_mtu`, as in issue #720's hacky approach), the hardware layer still fails:
+- mbuf `data_room_size` is fixed 2048, cannot hold a 9000B frame (`ff_dpdk_if.c:430`).
+- Port `rxmode` has no jumbo/scatter config, no `rte_eth_dev_set_mtu` call; PMD initializes at 1500.
+- RX: >1500 frames are dropped or truncated by the PMD; TX: single mbuf cannot hold jumbo and scatter is not enabled.
+
+**Conclusion**: Increasing MTU is **unsupported**, and it is a dual block of "protocol-stack upper bound + hardware gap"; both must be modified to support it (see `06-solution-and-conclusion.md`).
+
+## 4. Consistency Check with Three-Layer Architecture Docs / Knowledge Graph
+
+- The three-layer architecture docs (`docs/03-LAYER3-FUNCTIONS.md` etc.) describe `ff_veth_ioctl`/`ff_syscall_wrapper`'s ioctl conversion responsibilities, consistent with this investigation; the docs do not list MTU capability separately — this investigation supplements the explicit conclusion "MTU modification is software-layer only, ≤1500".
+- The knowledge graph (`KNOWLEDGE_GRAPH_WIKI.md`) does not record MTU/jumbo-related symbols; this investigation's conclusions can serve as incremental supplements (if needed later).
+- **Consistency principle**: where docs and code differ, the actual code `file:line` referenced in this investigation prevails.
+
+## 5. Difference Summary Table
+
+| Dimension | Decrease MTU (≤1500) | Increase MTU (>1500 jumbo) |
+|---|---|---|
+| Protocol-stack `ether_ioctl` | Accepts, writes `if_mtu` | `EINVAL` rejection |
+| Propagated to DPDK hardware | No (but harmless) | No (and harmful) |
+| mbuf 2048 can hold | Yes (new MTU smaller) | No |
+| PMD port default 1500 | Compatible | Incompatible |
+| Runtime test | Success | Failure (EINVAL) |
+| Overall conclusion | ✅ Supported | ❌ Unsupported |