1- # F-Stack v1.25 Layer 1: Overall Architecture and Module Boundaries
1+ # F-Stack v1.26 Layer 1: Overall Architecture and Module Boundaries
22
33> ** Target Audience** : System architects, technical leads
44> ** Key Concepts** : Module partitioning, technology selection, data flow, process model
5- > ** Generation Date** : 2026-03-20
5+ > ** Generation Date** : 2026-03-20 (last sync: 2026-06-08, post FreeBSD 13.0 → 15.0 first-stage upgrade including M0 ~ M5 + runtime-fix + rib-fix + Phase-5b NFR-1 PASS)
66
77## 1. Top-Level Architecture Overview
88
@@ -33,7 +33,7 @@ NIC Hardware
3333| Pillar | Component | Purpose |
3434| --------| -----------| ---------|
3535| ** Kernel Bypass** | DPDK + PMD | Bypass Linux kernel network bottleneck |
36- | ** Mature Protocol Stack** | FreeBSD 13 .0 port | Reuse battle-tested TCP/IP implementation |
36+ | ** Mature Protocol Stack** | FreeBSD 15 .0 port (upgraded from 13.0 in 2025-2026) | Reuse battle-tested TCP/IP implementation |
3737| ** Multi-Core Parallelism** | Multi-process architecture + RSS | Fully utilize multi-core processing capability |
3838
3939### 1.3 Key Performance Metrics
@@ -51,27 +51,37 @@ NIC Hardware
5151
5252``` text
5353/data/workspace/f-stack/
54- ├── lib/ # F-Stack core library (~21K lines of C code )
55- │ ├── ff_dpdk_if.c (2855 lines) # DPDK NIC interface layer - most critical
56- │ ├── ff_glue.c (1466 lines) # FreeBSD glue layer
57- │ ├── ff_config.c (1379 lines) # Configuration parsing
58- │ ├── ff_syscall_wrapper.c # Linux→FreeBSD system call adaptation
54+ ├── lib/ # F-Stack core library (~22K lines, 33 .c files; full inventory in Layer3 §lib )
55+ │ ├── ff_dpdk_if.c (2856 lines) # DPDK NIC interface layer - most critical
56+ │ ├── ff_glue.c (1468 lines) # FreeBSD glue layer
57+ │ ├── ff_config.c (1381 lines) # Configuration parsing
58+ │ ├── ff_syscall_wrapper.c (1815 lines) # Linux→FreeBSD system call adaptation
5959│ ├── ff_host_interface.c # Host interface (pthread/mmap/time)
60- │ ├── ff_init.c (69 lines) # Initialization coordination
61- │ ├── ff_epoll.c (159 lines) # epoll interface conversion
60+ │ ├── ff_init.c (70 lines) # Initialization coordination
61+ │ ├── ff_epoll.c (~134 lines) # epoll → kqueue conversion
6262│ ├── ff_dpdk_kni.c # Virtual NIC support (via virtio_user, no longer depends on rte_kni.ko)
63- │ ├── Makefile # Build system
64- │ └── include/ # Header files
63+ │ ├── ff_route.c (1604 lines) # Route socket / RIB hooks (rtsock partial port)
64+ │ ├── ff_veth.c (1132 lines) # Virtual ethernet device (M4: full if_t accessor rewrite)
65+ │ ├── ff_kern_timeout.c (1266 lines) # callout subsystem (FreeBSD 13/14-compat _ff_callout_stop_safe)
66+ │ ├── ff_lock.c (448 lines) # sx/mutex/lockmgr userspace impl
67+ │ ├── ff_ng_base.c (3887 lines) # netgraph framework full port
68+ │ ├── ff_stub_14_extra.c (799 lines) # NEW: 14.0+ central stub bank + 5 runtime-fix landing point
69+ │ ├── ff_kern_*.c # Kernel emulation primitives (cv/intr/synch/subr/environment)
70+ │ ├── ff_subr_prf.c / ff_memory.c / ff_compat.c / ... # Other shims (≈ 13 more files)
71+ │ ├── Makefile # Build system (NET_SRCS now includes route_rtentry.c)
72+ │ └── include/ # Header files (ff_api.h, ff_memory.h, ...)
6573│
66- ├── freebsd/ # FreeBSD 13.0 kernel code port
67- │ ├── sys/
68- │ │ ├── netinet/ # IPv4 protocol stack
69- │ │ ├── netinet6/ # IPv6 protocol stack
70- │ │ ├── net/ # Generic network interfaces
71- │ │ ├── kern/ # Kernel services (malloc/locks/timers)
72- │ │ └── vm/ # Virtual memory
73- │ ├── amd64/ # x86 architecture-specific code
74- │ └── contrib/ck/ # ConcurrencyKit dependency
74+ ├── freebsd/ # FreeBSD 15.0 kernel code port (upgraded from 13.0; mips/ removed at M1)
75+ │ ├── sys/ # System headers
76+ │ ├── netinet/ # IPv4 protocol stack (incl. tcp_stacks/ subdir: rack, bbr, ...)
77+ │ ├── netinet6/ # IPv6 protocol stack
78+ │ ├── net/ # Generic network interfaces (incl. route/ subdir: nhop/fib_algo/route_ctl)
79+ │ ├── netlink/ # NEW (header-only): 14.0+ netlink headers, 0 .c, 0 SRCS — DP-2: no NETLINK port
80+ │ ├── netgraph/ # netgraph kernel surface (paired with lib/ff_ng_base.c)
81+ │ ├── kern/ # Kernel services (malloc/locks/timers)
82+ │ ├── vm/ # Virtual memory
83+ │ ├── amd64/ arm64/ i386/ arm/ # Supported architectures (mips/ removed in 14.0+)
84+ │ └── contrib/ck/ # ConcurrencyKit dependency (refreshed at M3 to support CK_LIST_FOREACH_FROM)
7585│
7686├── dpdk/ # DPDK 23.11.5 (submodule)
7787│ └── build/ # Build artifacts
@@ -106,33 +116,42 @@ NIC Hardware
106116
107117| Module | Lines | Responsibility | Dependencies |
108118| --------| -------| ---------------| --------------|
109- | ** ff_dpdk_if.c** | 2855 | NIC driver/DPDK operations/core TX/RX logic | DPDK, ff_glue |
110- | ** ff_glue.c** | 1466 | FreeBSD kernel emulation/memory/locks/interrupts | FreeBSD headers, DPDK |
111- | ** ff_config.c** | 1379 | INI configuration file parsing | ff_ini_parser |
112- | ** ff_syscall_wrapper.c** | 1825 | Linux system call → FreeBSD adaptation | FreeBSD sys |
113- | ** ff_init.c** | 69 | Initialization flow coordination | All above modules |
114- | ** ff_epoll.c** | 159 | Linux epoll → FreeBSD kqueue conversion | FreeBSD kqueue |
115- | ** ff_host_interface.c** | -- | Host OS interface (mmap/pthread/rand) | System libraries |
116- | ** ff_dpdk_kni.c** | -- | Virtual NIC support (via virtio_user, no longer depends on rte_kni.ko) | DPDK virtio_user |
119+ | ** ff_dpdk_if.c** | 2856 | NIC driver/DPDK operations/core TX/RX logic | DPDK, ff_glue |
120+ | ** ff_glue.c** | 1468 | FreeBSD kernel emulation/memory/locks/interrupts (8-category 14.0+ ABI fixes at M4) | FreeBSD headers, DPDK |
121+ | ** ff_config.c** | 1381 | INI configuration file parsing | ff_ini_parser |
122+ | ** ff_syscall_wrapper.c** | 1815 | Linux system call → FreeBSD adaptation (sockaddr calling-convention update at M4) | FreeBSD sys |
123+ | ** ff_init.c** | 70 | Initialization flow coordination | All above modules |
124+ | ** ff_epoll.c** | ~ 134 | Linux epoll → FreeBSD kqueue conversion | FreeBSD kqueue |
125+ | ** ff_host_interface.c** | ~ 285 | Host OS interface (mmap/pthread/rand) | System libraries |
126+ | ** ff_dpdk_kni.c** | ~ 441 | Virtual NIC support (via virtio_user, no longer depends on rte_kni.ko) | DPDK virtio_user |
127+ | ** ff_route.c** | 1604 | Route socket / RIB hooks (rtsock partial port; 5-category 14.0+ ABI fixes at M4) | FreeBSD net/route |
128+ | ** ff_veth.c** | 1132 | Virtual ethernet device (28 if_t accessor rewrites at M4) | FreeBSD net/if |
129+ | ** ff_kern_timeout.c** | 1266 | callout subsystem (` callout_init ` , ` _reset_tick_on ` , ` ff_timecounter ` ) | DPDK rte_timer |
130+ | ** ff_ng_base.c** | 3887 | netgraph framework full port (M5: ` node_p → node_cp ` correction) | FreeBSD netgraph headers |
131+ | ** ff_stub_14_extra.c** | 799 | NEW (M5 + runtime-fix): central 14.0+ stub bank (123 stubs, 661 undef resolutions) + 5 P0 SIGSEGV fixes + defensive ` vm_page_alloc_noobj ` panic | FreeBSD 14.0+ KBI |
117132
118133## 3. FreeBSD TCP/IP Stack Porting Approach
119134
120135### 3.1 Porting Strategy
121136
122137F-Stack adopted a ** complete porting** strategy:
123- - Extracted the full TCP/IP protocol stack code from FreeBSD 13.0
124- - Retained all network protocol code in ` freebsd/sys/ netinet/ `
125- - Implemented user-space emulation of kernel APIs through ` ff_glue.c `
126- - Supported optional features through conditional compilation (IPv6, KNI, TCPHPTS, etc.)
138+ - Originally extracted the full TCP/IP protocol stack code from FreeBSD 13.0; ** upgraded to FreeBSD 15.0 in 2025-2026 ** (M0 ~ M5; full evidence in ` docs/freebsd_13_to_15_upgrade_spec/ ` )
139+ - Retained all network protocol code in ` freebsd/netinet/ ` (incl. ` netinet/tcp_stacks/ ` for RACK/BBR), ` freebsd/netinet6/ ` , ` freebsd/net/ ` (incl. ` net/route/ ` FIB rework subdir)
140+ - Implemented user-space emulation of kernel APIs through ` ff_glue.c ` and the supplemental 14.0+ stub bank ` ff_stub_14_extra.c `
141+ - Supported optional features through conditional compilation (IPv6, KNI, TCPHPTS, FF_NETGRAPH, etc.); 15.0-introduced subsystems (NETLINK protocol, KTLS) are ** not ** ported per DP-2 / out-of-scope
127142
128143### 3.2 Ported FreeBSD Subsystems
129144
130145``` text
131- freebsd/sys/
146+ freebsd/
132147├── netinet/ # IPv4: tcp_*.c, udp_*.c, ip_*.c, if_arp.c
148+ │ └── tcp_stacks/ # Modular TCP stacks: rack.c (~759 KB), bbr.c (~444 KB), tailq_hash.* (-DMODNAME=tcp_rack)
133149├── netinet6/ # IPv6: ip6_*.c, tcp6_*.c
134150├── net/ # Generic network: if.c, route.c, netisr.c
135- ├── kern/ # Kernel services: malloc, mutex, synch, callout
151+ │ └── route/ # FIB rework subdir (14.0+): nhop, fib_algo, route_ctl (22 files)
152+ ├── netlink/ # 14.0+ NETLINK headers (header-only, 0 .c) — DP-2: protocol not ported
153+ ├── netgraph/ # netgraph kernel surface (paired with lib/ff_ng_base.c)
154+ ├── kern/ # Kernel services: malloc, mutex, synch, callout (incl. kern_descrip.c with 5475-boundary fix)
136155├── vm/ # Virtual memory: vm_page.c (mbuf mapping)
137156└── sys/ # System definitions: socket.h, mbuf.h, etc.
138157```
@@ -152,7 +171,7 @@ freebsd/sys/
152171
153172### 4.1 ff_dpdk_if.c Core Responsibilities
154173
155- This is the most critical module (2855 lines), responsible for the entire data link:
174+ This is the most critical module (2856 lines), responsible for the entire data link:
156175
157176** Initialization Flow** :
158177``` text
0 commit comments