docs: multi-agent review and fix for architecture docs and specs

Architecture docs (simplified + full versions):
- Fix API signatures: ff_kevent_do_each (3→7 params), ff_route_ctl (2→5 params),
  ff_rtioctl, ff_zc_mbuf_get, ff_sysctl, ff_log/ff_vlog (add level+logtype)
- Fix Socket API: struct sockaddr → struct linux_sockaddr throughout
- Fix ff_openlog_stream → ff_log_reset_stream / ff_log_open_set
- Fix global vars: enable_kni (static→non-static), nb_dev_ports (uint32_t→int),
  idle_sleep (uint32_t→unsigned, remove default), pktmbuf_pool (MAX_LCORE→NB_SOCKETS)
- Fix struct ff_tx_offload and ff_dispatcher_context fields per source
- Fix main_loop pseudocode: TX drain before RX, add idle sleep step
- Fix code block language markers (8 blocks)
- Fix markdown syntax (unclosed bold, list spacing)
- Fix typo: unctions_default → functions_default

Specs documents:
- P0: Unify eventfd design (single evfd → dual eventfd_req/eventfd_rsp) across SPEC-002/003
- P0: Unify function naming (ff_create_ring_zone → ff_create_sc_ring_zone) across SPEC-002/003
- P0: Reconcile throughput targets (1.5x→1.2x micro, ≥10% Nginx) across SPEC-001/004
- P1: Fix ring entries count (32→64) in SPEC-001 NFR-004
- P1: Fix ff_thread_handle offset (68→72, 8-byte alignment) in SPEC-003
- P1: Add clarifying comment for ACQUIRE_ZONE_LOCK macro in Ring mode
- P1: Fix operator precedence bug (++spin_count & 0xFF == 0) in SPEC-003
- P1: Annotate 72h stability test vs 24h acceptance criteria

Stats: Update SUMMARY.txt line counts to match modified files

Author: jfb8856606

docs/01-LAYER1-ARCHITECTURE.md

@@ -10,7 +10,7 @@
 
 F-Stack 采用了"用户态网络栈"架构，解决 Linux 内核网络处理的性能瓶颈：
 
-```
+```text
 应用层 (Applications)
   ↓ (ff_socket/ff_read/ff_write 等 Linux-like API)
 F-Stack 库 (libfstack.a)
@@ -49,7 +49,7 @@ NIC 驱动 (igb_uio / vfio-pci)
 
 ### 2.1 核心目录布局
 
-```
+```text
 /data/workspace/f-stack/
 ├── lib/                          # F-Stack 核心库 (~21K 行 C 代码)
 │   ├── ff_dpdk_if.c   (2855行) # DPDK 网卡接口层 - 最核心
@@ -123,7 +123,7 @@ F-Stack 采用了**完整移植**策略：
 
 ### 3.2 FreeBSD 移植的子系统
 
-```
+```text
 freebsd/sys/
 ├── netinet/        # IPv4: tcp_*.c, udp_*.c, ip_*.c, if_arp.c
 ├── netinet6/       # IPv6: ip6_*.c, tcp6_*.c
@@ -151,7 +151,7 @@ freebsd/sys/
 这是最核心的模块 (2855 行)，负责整个数据链路：
 
 **初始化流程**:
-```
+```text
 ff_dpdk_init()
   ├─ rte_eal_init()              // DPDK 环境初始化
   ├─ init_lcore_conf()           // CPU 核心/端口映射
@@ -164,7 +164,7 @@ ff_dpdk_init()
 
 ### 4.2 收包流程 (Ingress)
 
-```
+```text
 NIC 硬件 (RSS 处理器分发)
   ↓
 多个 RX 队列 (per-CPU-core)
@@ -179,7 +179,7 @@ process_packets() 函数
 
 ### 4.3 发包流程 (Egress)
 
-```
+```text
 应用 (ff_write/ff_send/ff_sendto/ff_sendmsg)
   ↓
 FreeBSD TCP/UDP 栈
@@ -241,7 +241,7 @@ int main_loop(void *arg) {
 
 ### 6.1 单进程模式 (推荐)
 
-```
+```text
 F-Stack 进程 (1 个)
   └─ 单个 lcore (1 个 CPU 核心)
     ├─ NIC RX/TX 队列映射
@@ -253,7 +253,7 @@ F-Stack 进程 (1 个)
 
 ### 6.2 多进程模式
 
-```
+```text
 主进程 (Primary)
   ├─ DPDK EAL 初始化
   └─ 启动 N 个 Worker 进程
@@ -335,4 +335,5 @@ F-Stack 的架构设计围绕三个核心支柱：
 1. **Kernel Bypass**: 规避 Linux 内核瓶颈
 2. **成熟协议栈**: 复用 FreeBSD 久经考验的实现
 3. **多核并行**: 充分利用现代多核 CPU 和 NIC 硬件能力
-   这使得 F-Stack 能够达到 500 万+ RPS、1000 万+ 并发连接的性能水平，是云计算核心网络设施的理想选择。
+
+这使得 F-Stack 能够达到 500 万+ RPS、1000 万+ 并发连接的性能水平，是云计算核心网络设施的理想选择。

docs/02-LAYER2-INTERFACES.md

@@ -27,25 +27,25 @@ void ff_stop_run(void);                          // 优雅停止循环
 ```c
 // Socket 创建和管理
 int ff_socket(int domain, int type, int protocol);
-int ff_bind(int s, const struct sockaddr *addr, socklen_t addrlen);
+int ff_bind(int s, const struct linux_sockaddr *addr, socklen_t addrlen);
 int ff_listen(int s, int backlog);
-int ff_accept(int s, struct sockaddr *addr, socklen_t *addrlen);
-int ff_accept4(int s, struct sockaddr *addr, socklen_t *addrlen, int flags);
-int ff_connect(int s, const struct sockaddr *addr, socklen_t addrlen);
-int ff_close(int s);
+int ff_accept(int s, struct linux_sockaddr *addr, socklen_t *addrlen);
+int ff_accept4(int s, struct linux_sockaddr *addr, socklen_t *addrlen, int flags);
+int ff_connect(int s, const struct linux_sockaddr *name, socklen_t namelen);
+int ff_close(int fd);
 
 // 数据 I/O
-ssize_t ff_read(int s, void *buf, size_t len);
-ssize_t ff_readv(int s, const struct iovec *iov, int iovcnt);
-ssize_t ff_write(int s, const void *buf, size_t len);
-ssize_t ff_writev(int s, const struct iovec *iov, int iovcnt);
+ssize_t ff_read(int d, void *buf, size_t nbytes);
+ssize_t ff_readv(int fd, const struct iovec *iov, int iovcnt);
+ssize_t ff_write(int fd, const void *buf, size_t nbytes);
+ssize_t ff_writev(int fd, const struct iovec *iov, int iovcnt);
 ssize_t ff_send(int s, const void *buf, size_t len, int flags);
 ssize_t ff_sendto(int s, const void *buf, size_t len, int flags,
-                  const struct sockaddr *to, socklen_t tolen);
+                  const struct linux_sockaddr *to, socklen_t tolen);
 ssize_t ff_sendmsg(int s, const struct msghdr *msg, int flags);
 ssize_t ff_recv(int s, void *buf, size_t len, int flags);
 ssize_t ff_recvfrom(int s, void *buf, size_t len, int flags,
-                    struct sockaddr *from, socklen_t *fromlen);
+                    struct linux_sockaddr *from, socklen_t *fromlen);
 ssize_t ff_recvmsg(int s, struct msghdr *msg, int flags);
 
 // Socket 选项
@@ -63,8 +63,9 @@ int ff_kqueue(void);
 int ff_kevent(int kq, const struct kevent *changelist, int nchanges,
               struct kevent *eventlist, int nevents,
               const struct timespec *timeout);
-void ff_kevent_do_each(int kq, void *arg, 
-                       void (*cb)(int fd, short, void *));
+int ff_kevent_do_each(int kq, const struct kevent *changelist, int nchanges,
+                      void *eventlist, int nevents, const struct timespec *timeout,
+                      void (*do_each)(void **, struct kevent *));
 
 // Linux epoll (兼容)
 int ff_epoll_create(int size);
@@ -86,31 +87,33 @@ int ff_fcntl(int s, int cmd, ...);
 int ff_ioctl(int s, unsigned long request, ...);
 
 // 系统配置
-int ff_sysctl(int *name, u_int namelen, void *oldp,
-              size_t *oldlenp, void *newp, size_t newlen);
+int ff_sysctl(const int *name, u_int namelen, void *oldp,
+              size_t *oldlenp, const void *newp, size_t newlen);
 ```
 
 ### 1.5 特殊功能 API
 
 ```c
-// 原始包发送
-int ff_route_ctl(int cmd, struct rtentry *rt);
-int ff_rtioctl(int req, struct rt_addrinfo *info);
+// 路由控制
+int ff_route_ctl(enum FF_ROUTE_CTL req, enum FF_ROUTE_FLAG flag,
+                 struct linux_sockaddr *dst, struct linux_sockaddr *gw,
+                 struct linux_sockaddr *netmask);
+int ff_rtioctl(int fib, void *data, unsigned *plen, unsigned maxlen);
 
 // 零拷贝 mbuf 操作
-struct rte_mbuf *ff_zc_mbuf_get(int s);
-int ff_zc_mbuf_write(int s, struct rte_mbuf *m);
-int ff_zc_mbuf_read(int s, struct rte_mbuf **m);  // 【注】暂未实现，后续考虑支持
+int ff_zc_mbuf_get(struct ff_zc_mbuf *m, int len);
+int ff_zc_mbuf_write(struct ff_zc_mbuf *m, const char *data, int len);
+int ff_zc_mbuf_read(struct ff_zc_mbuf *m, const char *data, int len);  // 【注】暂未实现
 
 // 时间相关
 int ff_gettimeofday(struct timeval *tv, struct timezone *tz);
 
 // 日志
-void ff_log(const char *format, ...);
-void ff_vlog(const char *format, va_list ap);
-void ff_openlog_stream(FILE *fp);
-void ff_log_set_global_level(unsigned int level);
-void ff_log_set_level(unsigned int level);
+int ff_log(uint32_t level, uint32_t logtype, const char *format, ...);
+int ff_vlog(uint32_t level, uint32_t logtype, const char *format, va_list ap);
+int ff_log_reset_stream(void *f);
+void ff_log_set_global_level(uint32_t level);
+int ff_log_set_level(uint32_t logtype, uint32_t level);
 void ff_log_close(void);
 
 // 多线程支持
@@ -379,15 +382,7 @@ void worker_main(int worker_id) {
 
 ### 4.3 进程间通信
 
-```c
-// 发送消息到其他 lcore
-int ff_msg_send(unsigned lcore_id, void (*cb)(void *), void *arg);
-
-// 在另一个 lcore 接收消息
-void msg_handler(void *arg) {
-    // 在消息接收的 lcore 中执行
-}
-```
+> **注意**: `ff_msg_send()` 不是公开 API，在 `ff_api.h` 和 `ff_api.symlist` 中均不存在。进程间通信通过 `ff_msg` 消息队列（`lib/ff_msg.h`）实现，由 F-Stack 内部工具（knictl/sysctl 等）使用，应用层无需直接调用。
 
 ## 5. 线程安全性
 

docs/03-LAYER3-FUNCTIONS.md

@@ -74,7 +74,7 @@
 |-----|------|------|
 | `ff_sysctl` | 6 | 读写内核变量 |
 | `ff_route_ctl` | 5 | 路由表控制 |
-| `ff_rtioctl` | 2 | 路由 ioctl |
+| `ff_rtioctl` | 4 | 路由 ioctl |
 | `ff_gettimeofday` | 2 | 获取系统时间 |
 
 ### 1.7 特殊功能函数
@@ -98,14 +98,14 @@
 
 ### 1.9 日志函数
 
-| 函数 | 功能 |
-|-----|------|
-| `ff_log` | 格式化日志 |
-| `ff_vlog` | va_list 日志 |
-| `ff_openlog_stream` | 打开日志流 |
-| `ff_log_set_global_level` | 设置全局日志级别 |
-| `ff_log_set_level` | 设置模块日志级别 |
-| `ff_log_close` | 关闭日志 |
+| 函数 | 签名 | 功能 |
+|-----|------|------|
+| `ff_log` | `int ff_log(uint32_t level, uint32_t logtype, const char *format, ...)` | 格式化日志 |
+| `ff_vlog` | `int ff_vlog(uint32_t level, uint32_t logtype, const char *format, va_list ap)` | va_list 日志 |
+| `ff_log_reset_stream` | `int ff_log_reset_stream(void *f)` | 重设日志输出流 |
+| `ff_log_set_global_level` | `void ff_log_set_global_level(uint32_t level)` | 设置全局日志级别 |
+| `ff_log_set_level` | `int ff_log_set_level(uint32_t logtype, uint32_t level)` | 设置模块日志级别 |
+| `ff_log_close` | `void ff_log_close(void)` | 关闭日志 |
 
 ## 2. 核心数据结构
 
@@ -261,11 +261,11 @@ struct ff_msg {
 
 ```c
 struct ff_tx_offload {
+    uint8_t ip_csum;               // IP 校验和卸载
+    uint8_t tcp_csum;              // TCP 校验和卸载
+    uint8_t udp_csum;              // UDP 校验和卸载
+    uint8_t sctp_csum;             // SCTP 校验和卸载
     uint16_t tso_seg_size;         // TSO 分段大小 (0 = 禁用)
-    uint8_t tx_csum_ip;            // IP 校验和卸载
-    uint8_t tx_csum_l4;            // L4 校验和卸载
-    uint8_t vlan_insert;           // VLAN 插入标志
-    uint16_t vlan_id;              // VLAN ID
 };
 ```
 
@@ -295,21 +295,14 @@ int ff_zc_mbuf_read(struct ff_zc_mbuf *m, const char *data, int len);  // 暂未
 
 ### 2.8 ff_dispatcher_context 结构 (包分发)
 
+> **注意**: 以下为 `ff_api.h` 中的实际定义。此结构作为 `dispatch_func_context_t` 回调的额外上下文参数传入，仅包含 VLAN 相关信息。报文数据、长度、队列等信息通过回调函数的其他参数传递。
+
 ```c
 struct ff_dispatcher_context {
-    uint16_t port_id;              // 入口网卡
-    uint16_t queue_id;             // 入口队列
-    
-    uint8_t *data;                 // 报文数据
-    uint16_t len;                  // 报文长度
-    
-    // 解析结果
-    uint16_t vlan_id;              // VLAN ID
-    uint8_t *l3_data;              // L3 头指针
-    uint8_t *l4_data;              // L4 头指针
-    
-    // 控制信息
-    uint32_t flags;                // 标志位
+    struct {
+        uint8_t stripped;          // VLAN 是否已剥离
+        uint16_t vlan_tci;         // Priority (3) + CFI (1) + Identifier Code (12)
+    } vlan;
 };
 ```
 
@@ -405,10 +398,10 @@ ff_dpdk_if.c
 **关键全局变量**:
 
 ```c
-static uint32_t enable_kni = 0;              // KNI 启用标志
-static uint16_t nb_dev_ports = 0;            // NIC 数量
-static uint32_t idle_sleep = 100;            // 空闲睡眠微秒数
-static struct rte_mempool *pktmbuf_pool[RTE_MAX_LCORE];  // 每核 mbuf 池
+int enable_kni = 0;                                   // KNI 启用标志（非 static）
+int nb_dev_ports = 0;                                  // NIC 数量（非 static，非 uint16_t）
+static unsigned idle_sleep;                            // 空闲睡眠微秒数（由配置赋值，无硬编码默认值）
+struct rte_mempool *pktmbuf_pool[NB_SOCKETS];          // 按 NUMA socket 索引的 mbuf 池
 ```
 
 **初始化函数调用链**:
@@ -446,42 +439,42 @@ int main_loop(void *arg) {
     uint64_t drain_tsc = (rte_get_tsc_hz() + US_PER_S - 1) / US_PER_S * BURST_TX_DRAIN_US;
     uint64_t cur_tsc, prev_tsc = 0;
 
-    while (!stop_loop) {
+    while (1) {
+        if (unlikely(stop_loop)) break;
+        
         cur_tsc = rte_rdtsc();
 
         // === 1. 驱动 FreeBSD 定时器 ===
         if (unlikely(freebsd_clock.expire < cur_tsc)) {
             rte_timer_manage();        // 触发 TCP timers 等
-            freebsd_clock.expire = cur_tsc + FREEBSD_CLOCK_TICK;
         }
 
-        // === 2. 接收报文 ===
-        for (each_port in lr->ports) {
-            for (each_queue) {
-                uint16_t nb_rx = rte_eth_rx_burst(
-                    port_id, queue_id, 
-                    pkts_burst, MAX_PKT_BURST
-                );
-                process_packets(pkts_burst, nb_rx);
+        // === 2. TX burst queue drain (先于 RX) ===
+        diff_tsc = cur_tsc - prev_tsc;
+        if (unlikely(diff_tsc >= drain_tsc)) {
+            for (each_port in qconf->tx_ports) {
+                send_burst(qconf, ...);
             }
+            prev_tsc = cur_tsc;
         }
 
-        // === 3. 发送报文 (定时刷新) ===
-        if (drain_tsc && (cur_tsc - prev_tsc) > drain_tsc) {
-            for (each_port in lr->ports) {
-                uint16_t nb_tx = rte_eth_tx_buffer_flush(
-                    port_id, queue_id, tx_buffer
-                );
-            }
-            prev_tsc = cur_tsc;
+        // === 3. 接收报文 (RX) ===
+        for (each_rx_queue in qconf->rx_queues) {
+            uint16_t nb_rx = rte_eth_rx_burst(
+                port_id, queue_id, 
+                pkts_burst, MAX_PKT_BURST
+            );
+            process_packets(pkts_burst, nb_rx);
         }
 
         // === 4. 执行用户回调 ===
         if (lr->loop) {
-            int ret = lr->loop(lr->arg);  // 应用业务逻辑
-            if (ret < 0) {
-                ff_stop_run();
-            }
+            lr->loop(lr->arg);         // 应用业务逻辑
+        }
+        
+        // === 5. 空闲睡眠 ===
+        if (likely(idle && idle_sleep)) {
+            rte_delay_us_sleep(idle_sleep);
         }
     }
 

docs/F-Stack_Architecture_Layer1_System_Overview.md

@@ -673,7 +673,7 @@ F-Stack (用户态)
 - 默认速率限制：1K QPS 数据、9K QPS 控制、10K QPS 总体
 - 可选的报文分发回调：应用自定义哪些流进入 KNI
 
-**kni和virtio选择：
+**KNI 和 virtio 选择**：
 
 - 当前版本 KNI 功能保留，但底层实现已从 `rte_kni.ko` 内核模块切换为 `virtio_user`（见 lib/Makefile:34），不再依赖内核 KNI 模块