feat(stack-coexist): auto dual-stack so one listen serves F-Stack and kernel (FF_KERNEL_COEXIST)

When FF_KERNEL_COEXIST is built and [stack] kernel_coexist=1, a plain ff_socket now creates an F-Stack socket plus a paired host kernel socket (native fd map in ff_host_interface.c); ff_bind/ff_listen/ff_close/ff_connect drive both stacks, ff_epoll_ctl registers a dual fd on both the kqueue and the host epoll, ff_epoll_wait merges them, and ff_accept returns a single-stack connection by source. SOCK_KERNEL/SOCK_FSTACK still force a single stack; macro-off or coexist-off stays byte-identical (nm: 0 coexist symbols). Adds native fd-map unit test, a dualstack demo mode, and revises kernel_event_support_spec to v6. Verified on hardware: one listen(80) answered 200 via both 9.134.214.176 (F-Stack/DPDK) and 127.0.0.1 (kernel).

Author: jfb8856606

docs/kernel_event_support_spec/00-overview.md

@@ -1,78 +1,85 @@
-# 00 Overview: F-Stack User-Space Stack + Local Kernel Stack COEXISTENCE (compile-macro gated + per-fd marker selection + unified events)
+# 00 Overview: F-Stack User-Space Stack + Local Kernel Stack AUTOMATIC DUAL-STACK COEXISTENCE (compile-macro gated + default dual-stack + marker single-stack override + unified events)
 
 > **Document ID**: SPEC-KE-00
-> **Version**: v5 (compile-macro gating: `FF_KERNEL_COEXIST` off by default + runtime `kernel_coexist` dual-layer switch)
+> **Version**: v6 (**native automatic dual-stack coexistence** paradigm: with no marker, one `ff_socket` builds BOTH the F-Stack and kernel stacks, dual-drives both, unified events; markers override to single-stack, compatible with v5; still gated by the `FF_KERNEL_COEXIST` compile macro + runtime `kernel_coexist` dual-layer switch)
 > **Date**: 2026-06-17
-> **Status**: Drafting
+> **Status**: Drafting (v6 design)
 > **Scope**: Navigation, terminology, and scope statement for the spec in this directory
 
 ---
 
-## 0. v5 Compile-Macro Gating Background (must read)
+## 0. v6 Background: from "per-fd either/or" to "automatic dual-stack" (must read)
 
-v4 already landed coexistence (app ON F-Stack + per-fd `SOCK_KERNEL` to the kernel stack + unified events). But all v4 coexistence code in `lib/` is **compiled unconditionally**, so even deployments not using coexistence link it in and cannot guarantee byte-for-byte zero regression vs. upstream F-Stack.
+v5 (commit ba148589d) already gated all `lib/` coexistence code under the compile macro `FF_KERNEL_COEXIST` (`lib/Makefile` off by default), forming a **compile-time + runtime dual-layer switch**, and measured byte-for-byte zero regression when off and per-fd coexistence usable when on (real-machine perf in `10`). The v5 semantics are **per-fd either/or**:
 
-**v5 new requirement**: gate ALL `lib/` coexistence code under a single compile macro `FF_KERNEL_COEXIST`, **commented off by default in `lib/Makefile`**, forming a **compile-time + runtime dual-layer switch**:
+- `ff_socket(type|SOCK_KERNEL)` → builds **only** a kernel fd, returns `ff_kernel_fd_encode(host_fd)` (≥`FF_KERNEL_FD_BASE`);
+- otherwise → builds **only** an F-Stack fd (raw fd).
 
-- **Compile-time (`FF_KERNEL_COEXIST`)**: undefined → all coexistence code (managed kernel-fd bridge, fd discrimination, `ff_epoll` merge, `ff_socket` kernel branch, per-`ff_*` routing, config `kernel_coexist`, `SOCK_FSTACK/SOCK_KERNEL` macros) is **not compiled**; `libfstack.a` is **byte-for-byte zero regression** vs. upstream. Defined (`make FF_KERNEL_COEXIST=1` or uncomment) → compiled in.
-- **Runtime (config `kernel_coexist`)**: **only when the macro is enabled**, `config.ini [stack] kernel_coexist=1` actually enables per-fd `SOCK_KERNEL` to use the kernel stack; default `=0` stays per-fd F-Stack.
-- **Opt-in impact**: `ff_api.h` `SOCK_FSTACK`/`SOCK_KERNEL` macros are also wrapped by `FF_KERNEL_COEXIST`, so a consumer (APP) must likewise define the macro to see these markers — the reasonable semantics of "off by default, explicitly enabled".
+**v6 upgrades the default semantics to "automatic dual-stack"**: when `FF_KERNEL_COEXIST` is compiled in **and** `config.ini [stack] kernel_coexist=1` —
 
-**The correct paradigm**: within **one F-Stack application process**, business connections use the **F-Stack user-space stack (DPDK + FreeBSD)**, while fds carrying the `SOCK_KERNEL` marker use the **host Linux kernel stack**, and the two **coexist in a single event loop**, gated by the compile macro `FF_KERNEL_COEXIST` (off by default). This is exactly what F-Stack's two existing implementations do:
-- the `FF_KERNEL_EVENT` compile mode of `adapter/syscall` (hook/LD_PRELOAD);
-- nginx's `kernel_network_stack` config switch.
+- **Default (no marker) = dual-stack**: one `ff_socket` builds BOTH an F-Stack fd and a kernel host fd, registers `ff_native_fd_map[fstack_fd]=host_fd`, and **returns the F-Stack raw fd**; `ff_bind/ff_listen/ff_close/ff_connect` etc. **dual-drive both stacks** on that dual-stack fd — **one `listen(80)` listens on both the F-Stack (DPDK) and Linux kernel stacks simultaneously**. Local `curl 127.0.0.1:80` and remote access to `:80` via the DPDK NIC are both reachable, with no marker required.
+- **Marker single-stack override (compatible with v5)**: `type|SOCK_KERNEL` = kernel only; `type|SOCK_FSTACK` = F-Stack only.
+- **Zero regression**: macro off **or** `kernel_coexist=0` **or** `SOCK_FSTACK` → byte-for-byte zero regression (the original F-Stack path).
 
-This feature = **solidify that coexistence capability as the primary baseline (hook mode)** + **add unified-event coexistence to the native `ff_api` mode**, gated by the `FF_KERNEL_COEXIST` compile macro, rather than building a side path that bypasses F-Stack.
+> **Implementation-status note (anti-speculation)**: v6's native map `ff_native_fd_map` and the default dual-build/dual-drive logic are **NOT yet landed in `lib/`** (grep confirms `lib/` has no `ff_native_fd_map`). This directory's v6 docs are the **upgraded design**; they explicitly distinguish "v5 already measured/landed" from "v6 to-be-implemented design" and must not present any v6 behavior as a fait accompli.
 
-> **v3 history**: v3 routed `ff_socket(SOCK_KERNEL)` to `ff_host_socket()` → a raw host `socket()`, completely bypassing the F-Stack user-space stack (a fundamental mistake), reverted in v4 and rewritten to the paradigm above.
+> **v3 historical mistake (reverted)**: v3 routed `ff_socket(SOCK_KERNEL)` to `ff_host_socket()` → raw host `socket()`, completely bypassing F-Stack — a fundamental mistake, reverted (commit 0748eff94). v6's "dual-stack" is never a bypass: F-Stack is always built and always present; the kernel stack is a **parallel additional** second stack.
+
+---
 
 ## 1. One-Sentence Goal
 
-Let an F-Stack application, **while running its business fast path on the F-Stack user-space stack**, route some sockets/listens/connects to the host kernel stack on a per-fd basis (so local `ping`/`curl`/`ssh` can directly reach its kernel-stack services, and the app as a client can `connect` via the kernel stack to local/external kernel services), with both stacks' fds sent/received in the **same epoll/event loop** — **F-Stack is always present and is never replaced by a side path**.
+Let an F-Stack application be **dual-stack by default**: the same socket/listen works on BOTH the F-Stack user-space stack (DPDK+FreeBSD, business fast path) and the host Linux kernel stack — local `ping`/`curl`/`ssh` reach the kernel-stack side, remote peers reach the F-Stack side via the DPDK NIC, and both stacks' events are sent/received in the **same epoll/event loop** — **F-Stack is always present, never replaced by a side path**; use `SOCK_KERNEL`/`SOCK_FSTACK` markers to override to single-stack when needed.
 
 ## 2. Scope Statement (Important)
 
-- **This feature = dual-stack coexistence**: F-Stack user-space stack (business, default) + host kernel stack (per-fd `SOCK_KERNEL`), in the same process and event loop.
-- **Selection method**: per-fd `SOCK_KERNEL`/`SOCK_FSTACK` markers (default F-Stack); one **coexistence-capability switch** in config.ini (whether to enable kernel-stack coexistence, without changing the default per-fd F-Stack semantics).
-- **Hook mode (primary baseline, already supported)**: directly reuse `FF_KERNEL_EVENT` — `ff_hook_socket` marker-based selection + `fstack_kernel_fd_map` dual-stack epoll merge; this round solidifies it and provides a correct coexistence demo.
-- **Native `ff_api` mode (new design)**: `ff_epoll_*` is currently a pure kqueue wrapper with no kernel-fd awareness; this round adds, inside lib, an fd-ownership table + a kernel-epoll mirror + an `ff_epoll_wait` merge of kqueue⊕epoll, so natively-linked applications can also coexist over both stacks in one process.
+- **This feature = automatic dual-stack coexistence**: with no marker, F-Stack + kernel dual-stack, dual-drive, unified events; markers override to single-stack.
+- **Compile-macro gating (outermost)**: all coexistence code is gated by `FF_KERNEL_COEXIST`, **commented off by default** in `lib/Makefile`; when off, coexistence code is not compiled and is byte-for-byte zero regression vs. upstream.
+- **Runtime switch**: `config.ini [stack] kernel_coexist` (effective only when the macro is on), `=1` enables automatic dual-stack, `=0` degrades to pure F-Stack (zero regression).
+- **Selection markers**: `SOCK_KERNEL` (kernel only) / `SOCK_FSTACK` (F-Stack only) override the default dual-stack.
+- **Hook mode (cross-reference baseline)**: `adapter/syscall`'s `FF_KERNEL_EVENT` already supports "app ON F-Stack + epoll dual-build merge + close linkage", **but socket/listen are NOT dual-built** (kernel listen requires explicit `SOCK_KERNEL`). The native v6 divergence = socket/bind/listen/connect **are also auto dual-built / dual-driven**.
 - **Explicitly excluded**:
-  - Do **not** create a side socket that bypasses F-Stack (the v3 `ff_host_socket` approach is deprecated).
-  - Do **not** add an anti-F-Stack "whole-process default-to-kernel" global switch (the v3 `default_stack=kernel` is deprecated).
-  - Do **not** create a new `ff_local_*` dual API / mTCP-like dual namespace.
-  - Do **not** do gazelle-style thread-level selection (the F-Stack multi-process model relies on different config files).
+  - Do **not** create a side socket that bypasses F-Stack (v3 `ff_host_socket` raw bypass deprecated).
+  - Do **not** add an anti-F-Stack "whole-process default-to-kernel" switch (v3 `default_stack=kernel` deprecated).
+  - Do **not** create an `ff_local_*` dual API / mTCP-like dual namespace.
+  - Do **not** do gazelle-style thread-level selection (F-Stack multi-process relies on different config files).
   - Do **not** adopt KNI/`rte_kni`/virtio-user packet reinjection (boundary clarification only).
 
 ## 3. Reading Path
 
 | Order | Document | Purpose |
 |---|---|---|
-| 1 | `plan.md` | Plan, team, gate, rework paradigm |
-| 2 | `01-requirements-spec.md` | Requirements and goals/non-goals (coexistence) |
-| 3 | `02-current-state-analysis.md` | Current state of hook FF_KERNEL_EVENT / nginx kernel_network_stack / native event layer (code is authoritative) |
-| 4 | `03-external-research.md` | External solution research (with URLs) |
-| 5 | `04-architecture-design.md` | Coexistence architecture, dual-stack unified events, bidirectional data flow |
-| 6 | `05-interface-design.md` | Marker/config contracts, hook and native dual-mode adaptation |
-| 7 | `06-milestones.md` | Milestones and coding work list |
-| 8 | `07-test-spec.md` | Test and performance-baseline plan |
-| 9 | `08-review-gate.md` | Review gate conclusion |
+| 1 | `01-requirements-spec.md` | Requirements and goals/non-goals (auto dual-stack + marker single-stack override) |
+| 2 | `02-current-state-analysis.md` | v5 measured state + native vs hook isomorphism/divergence table + v6 map gap |
+| 3 | `03-external-research.md` | External research (with URLs, low-trust corroboration) |
+| 4 | `04-architecture-design.md` | Dual-drive data flow + fd tri-state routing + dual-stack events + map |
+| 5 | `05-interface-design.md` | socket/bind/listen/connect/accept/close/epoll_* dual-stack contracts + marker semantics + connect draft + exception matrix |
+| 6 | `06-milestones.md` | R6→R7 automatic dual-stack milestones |
+| 7 | `07-test-spec.md` | cmocka dual-mode cases + real-machine dual-stack plan |
+| 8 | `08-review-gate.md` | Gate conclusion (v6 R7 "pending measurement") |
+| 9 | `09-impl-plan.md` | Per-file rework steps |
+| 10 | `10-perf-baseline-report.md` | No-regression criteria of dual-stack on the F-Stack fast path |
 
 ## 4. Glossary
 
 | Term | Meaning |
 |---|---|
-| F-Stack stack | DPDK PMD + user-space FreeBSD protocol stack (business fast path, **default stack**) |
-| Kernel stack | Host Linux kernel network protocol stack (local/management/client connecting to local or external kernel services) |
-| Coexistence | F-Stack fds and kernel fds present **in the same process and the same event loop**, each using its own stack |
-| Stack-selection marker | `SOCK_KERNEL`(0x02000000)/`SOCK_FSTACK`(0x01000000) on socket `type`, per-fd |
-| Coexistence-capability switch | A config.ini switch for whether to enable kernel-stack coexistence (does not change the default per-fd F-Stack semantics) |
-| fd ownership | The marker at creation fixes whether the fd belongs to F-Stack or the kernel; subsequent syscalls/events route by ownership (`is_fstack_fd`/`CHECK_FD_OWNERSHIP`) |
-| Unified events | External epoll style, internally merging F-Stack kqueue events + kernel epoll events |
-| Hook mode | LD_PRELOAD takes over the POSIX API (`ff_hook_*`) + `FF_KERNEL_EVENT`; coexistence already supported |
-| Native mode | The app directly calls `ff_*` (`ff_api.h`) + the `ff_run` main loop; this round adds unified-event coexistence |
+| F-Stack stack | DPDK PMD + user-space FreeBSD protocol stack (business fast path, **always present**) |
+| Kernel stack | Host Linux kernel network protocol stack (local/management/client to local or external kernel services) |
+| **Automatic dual-stack (v6)** | With no marker, one `ff_socket` builds both an F-Stack fd and a kernel host fd; each `ff_*` dual-drives both stacks |
+| **Dual-stack fd (v6)** | The F-Stack raw fd returned to the app, mapped to one kernel host fd in `ff_native_fd_map` |
+| **native map (v6, to-be-implemented)** | `ff_native_fd_map[fstack_fd]=host_fd` (`ff_host_interface.c`, 65536 entries), modeled on adapter `fstack_kernel_fd_map` |
+| Managed kernel fd (kernel-only) | `ff_kernel_fd_encode(host_fd)` (≥`FF_KERNEL_FD_BASE`=0x40000000), returned by `SOCK_KERNEL` or a kernel-side accepted connection; no map entry |
+| `FF_KERNEL_COEXIST` | **Compile macro** gating whether all coexistence code is compiled; off by default (commented) in `lib/Makefile` (compile-time switch) |
+| Selection marker | `SOCK_KERNEL`(0x02000000)/`SOCK_FSTACK`(0x01000000) on socket `type`, single-stack override of the default dual-stack (wrapped by `FF_KERNEL_COEXIST`, opt-in) |
+| Coexistence-capability switch | `config.ini [stack] kernel_coexist`, **runtime** enabling of automatic dual-stack (effective only when the macro is on) |
+| fd tri-state routing | `ff_is_kernel_fd(fd)`(≥BASE)=kernel only; else the F-Stack path, and if `ff_native_map_get(fd)>0` also dual-drive host_fd |
+| Unified events | External epoll style; internally merges F-Stack kqueue events + kernel epoll events (a dual-stack listen is registered once on each stack) |
+| Hook mode | LD_PRELOAD takes over the POSIX API (`ff_hook_*`) + `FF_KERNEL_EVENT`; epoll dual-build merge, socket/listen NOT dual-built |
+| Native mode | The app directly calls `ff_*` (`ff_api.h`) + the `ff_run` main loop; v6 implements automatic dual-stack |
 
 ## 5. Sources
 
-- F-Stack actual code (`adapter/syscall/`, `app/nginx-1.28.0/`, `lib/`) — **highest priority; on conflict, code is authoritative**.
+- F-Stack actual code (`lib/`, `adapter/syscall/`, `app/nginx-1.28.0/`) — **highest priority; on conflict, code is authoritative**.
 - F-Stack three-tier architecture docs and knowledge graph (`docs/`), `adapter/syscall/README.md`.
-- Public external materials (GitHub/technical blogs, etc.), all with accessible URLs in `03`.
+- Public external materials (GitHub/technical blogs, etc.), all with accessible URLs in `03`, **low-trust corroboration only**.

docs/kernel_event_support_spec/01-requirements-spec.md

@@ -1,16 +1,21 @@
-# 01 Requirements Spec: F-Stack User-Space Stack + Local Kernel Stack COEXISTENCE
+# 01 Requirements Spec: F-Stack User-Space Stack + Local Kernel Stack AUTOMATIC DUAL-STACK COEXISTENCE
 
 > **Document ID**: SPEC-KE-01
-> **Version**: v5 (compile-macro gating: `FF_KERNEL_COEXIST` off by default + runtime `kernel_coexist` dual-layer switch)
+> **Version**: v6 (native automatic dual-stack coexistence paradigm)
 > **Date**: 2026-06-17
-> **Status**: Drafting
+> **Status**: Drafting (v6 design)
 > **Scope**: Define the problem domain, goals/non-goals, functional and non-functional requirements, and success criteria of this feature.
-
-> **v5 sync (key points; see `zh_cn/01-requirements-spec.md` for full detail)**:
-> - **FR-10 (compile-macro gating, opt-in)**: all `lib/` coexistence code is wrapped by `FF_KERNEL_COEXIST`, commented off by default in `lib/Makefile:57-60` (`#FF_KERNEL_COEXIST=1`); macro block at `lib/Makefile:174-177` adds `-DFF_KERNEL_COEXIST` to both `HOST_CFLAGS` and `CFLAGS`. Macro off → `libfstack.a` byte-for-byte zero regression (`nm`/`objdump` shows no `ff_host_*`/`ff_epoll_pairs` symbols).
-> - **FR-11 (marker opt-in visibility)**: `SOCK_FSTACK`/`SOCK_KERNEL` (`ff_api.h:81-99`) are wrapped by the macro; an APP must also define `FF_KERNEL_COEXIST` to see them.
-> - **NFR-1 strengthened to a compile-time guarantee**: when the macro is undefined, coexistence code is not compiled at all.
-> - **G4** clarified: config `kernel_coexist` is a **runtime** switch effective only when the compile macro is on.
+> **Authoritative full text**: `zh_cn/01-requirements-spec.md` (Chinese is the maintained source of truth; this English file carries the v6 key points). On conflict, code is authoritative.
+
+> **v6 sync (key points; see `zh_cn/01-requirements-spec.md` for full detail)**:
+> - **Paradigm upgrade**: from v5 per-fd either/or to v6 **automatic dual-stack**. When `FF_KERNEL_COEXIST` is compiled in AND `kernel_coexist=1`, a default (no-marker) `ff_socket` builds BOTH an F-Stack fd and a kernel host fd, registers `ff_native_fd_map[fstack_fd]=host_fd`, returns the F-Stack raw fd; `ff_bind/ff_listen/ff_close/ff_connect` dual-drive both stacks. One `listen(80)` listens on both F-Stack (DPDK) and the Linux kernel stack.
+> - **FR-2/FR-3/FR-4 (auto dual-stack, v6 to-be-implemented)**: `ff_socket` dual-build; `ff_bind/ff_listen` dual-drive; one-listen-many-uses (remote `9.134.214.176:80` via DPDK NIC + local `curl 127.0.0.1:80` via kernel).
+> - **FR-6 (accept single-stack ownership, Q3=A)**: a dual-stack listen fd's accept returns a single-stack connection fd (F-Stack raw / kernel encode); subsequent recv/send/close route by `ff_is_kernel_fd`, NOT consulting the map (hot path, NFR-2).
+> - **FR-8/FR-9 (marker single-stack override)**: `SOCK_KERNEL` = kernel only (encode, no map); `SOCK_FSTACK` = F-Stack only (no map, zero regression). `SOCK_FSTACK` wins.
+> - **FR-10 / N7 (connect dual-stack, DRAFT, PENDING USER CONFIRMATION)**: a single client logical flow cannot truly duplex over both stacks; v6 contract = "F-Stack primary + kernel concurrent connect for dual-network reachability". Use `SOCK_KERNEL` for a pure-kernel client; kernel-primary/failover is future work. See `zh_cn/05 §6`.
+> - **FR-12 (compile-macro gating, opt-in)**: all `lib/` coexistence code (incl. the v6 `ff_native_fd_map`) is wrapped by `FF_KERNEL_COEXIST`, off by default (`lib/Makefile:57-60`/`:174-177`); macro off → byte-for-byte zero regression (`nm`/`objdump` shows no `ff_host_*`/`ff_epoll_pairs`/`ff_native_fd_map`).
+> - **NFR-1/NFR-2/NFR-3**: triple zero-regression guarantee (macro off / `kernel_coexist=0` / `SOCK_FSTACK`); hot path no regression (single-stack connection recv/send do not consult the map); F-Stack always present.
+> - **Implementation status (D9, anti-speculation)**: `ff_native_fd_map` and default dual-build/dual-drive are NOT yet landed (`zh_cn/02 §5.2` grep=0). v6 FR/NFR new items are to-be-implemented; acceptance pending R7.
 
 ---