Skip to content

Commit 9c9889c

Browse files
jfb8856606jfb8856606
committed
【manual】Perform a rough manual review of the documents in the docs/ directory and correct some obvious errors.
1 parent d023cdf commit 9c9889c

7 files changed

Lines changed: 75 additions & 104 deletions

‎docs/01-LAYER1-ARCHITECTURE.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,6 @@ NIC 驱动 (igb_uio / vfio-pci)
4343
- **连接建立**: 100 万+ CPS (Connection Per Second)
4444
- **延迟**: 微秒级 (vs 毫秒级内核栈)
4545

46-
<!-- 注: 此补充基于 2/3 评审意见一致 (GPT-5.4 + Claude) -->
4746
> **注意**: 以上性能数据为参考值，实际结果取决于硬件配置 (CPU/网卡)、测试场景和报文大小等条件。
4847
4948
## 2. 目录结构与模块边界
@@ -298,7 +297,7 @@ Worker-N (CPU-N) ┘
298297
| 维护成本 | ★★★ | ★★★★★ |
299298
300299
**历史背景**:
301-
- 初期自研简单栈 → 性能不足
300+
- 初期自研简单栈 → 稳定性不足
302301
- 2017 年参考 libplebnet/libuinet → 完整移植 FreeBSD 栈
303302
- 这决定了今天的架构
304303
@@ -332,6 +331,4 @@ F-Stack 的架构设计围绕三个核心支柱：
332331
1. **Kernel Bypass**: 规避 Linux 内核瓶颈
333332
2. **成熟协议栈**: 复用 FreeBSD 久经考验的实现
334333
3. **多核并行**: 充分利用现代多核 CPU 和 NIC 硬件能力
335-
336-
<!-- 注: 此修改基于 2/3 评审意见一致 (GPT-5.4 + Claude)，原文“10 亿+”为笔误，与全文其他位置“1000 万+”不一致 -->
337-
这使得 F-Stack 能够达到 500 万+ RPS、1000 万+ 并发连接的性能水平，是云计算核心网络设施的理想选择。
334+
这使得 F-Stack 能够达到 500 万+ RPS、1000 万+ 并发连接的性能水平，是云计算核心网络设施的理想选择。

‎docs/02-LAYER2-INTERFACES.md‎

Lines changed: 4 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
77
## 1. F-Stack API 完整列表 (80+ 导出函数)
88

9-
<!-- 注: 此补充基于 2/3 评审意见一致 (GPT-5.4 + Claude) -->
109
> **API 层次说明**: F-Stack 的接口体系分为三个层级：
1110
> 1. **`ff_api.h` 主接口** — 包含 ff_init/ff_run/ff_stop_run 等生命周期函数及所有 socket/kqueue/sysctl 等函数声明
1211
> 2. **`ff_epoll.h` 补充接口** — epoll 兼容层 (ff_epoll_create/ff_epoll_ctl/ff_epoll_wait)，独立于 ff_api.h
@@ -135,13 +134,9 @@ nb_ports = 1 # 端口数量
135134
# CPU 核心配置
136135
lcore_mask = 0x1 # 使用的 CPU 核心 (十六进制位掩码)
137136
# 0x1 = CPU-0, 0x3 = CPU-0,1, 0x7 = CPU-0,1,2
138-
proc_type = primary # primary(主进程) 或 secondary(从进程)
139-
proc_id = 0 # 进程 ID (多进程模式)
140-
nb_procs = 1 # 总进程数
141137
142138
# 内存配置
143-
pktmbuf_pool_size = 512000 # 报文内存池大小 (mbuf 数量)
144-
numa_on = 0 # NUMA 支持 (0=关闭, 1=开启)
139+
numa_on = 1 # NUMA 支持 (0=关闭, 1=开启)
145140
146141
[host]
147142
# 网络地址配置
@@ -155,8 +150,6 @@ iface = eth0 # 物理网卡名称
155150
[kni]
156151
# 虚拟网卡支持 (可选)
157152
enable = 0 # 启用虚拟网卡 (0=禁用, 1=启用)
158-
name = veth0 # 虚拟网卡名称
159-
core = 0 # 处理虚拟网卡的 CPU 核心
160153
```
161154

162155
### 2.2 编程方式配置
@@ -286,7 +279,8 @@ int loop_func(void *arg) {
286279
int nevents = ff_epoll_wait(epfd, events, MAX_EVENTS, -1);
287280

288281
for (int i = 0; i < nevents; i++) {
289-
// 处理事件...
282+
// 循环处理事件...
283+
// 特别注意，ff_accept时需要循环调用，直到失败
290284
}
291285

292286
return 0;
@@ -338,10 +332,7 @@ if (m) {
338332
```
339333

340334
**3. CPU 亲和性**
341-
在启动参数中指定 CPU 核心:
342-
```bash
343-
./app --lcores=0@0,1@1 # lcore 0 运行在 CPU-0, lcore 1 运行在 CPU-1
344-
```
335+
通过配置文件指定 CPU 核心的亲和性绑定:
345336

346337
## 4. 多进程开发规范
347338

‎docs/03-LAYER3-FUNCTIONS.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@
66
77
## 1. 导出函数完整索引 (80+ 函数)
88

9-
<!-- 注: 此补充基于 2/3 评审意见一致 (GPT-5.4 + Claude) -->
109
> **符号导出层次**: 以下函数索引包含 `ff_api.h` 和 `ff_epoll.h` 中声明的全部接口。实际通过 `ff_api.symlist` 动态导出的符号是其子集。
1110
> - ff_init / ff_run / ff_stop_run 在 `ff_api.h` 中声明但**不在** `ff_api.symlist` 中，仅通过静态链接可用
1211
> - ff_epoll_* 系列函数声明在 `ff_epoll.h` 中，不在 `ff_api.h` 中

‎docs/F-Stack_Architecture_Layer1_System_Overview.md‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -589,7 +589,7 @@ bash start.sh (启动脚本)
589589
选项 A：移植 FreeBSD 协议栈（F-Stack 采用）
590590
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
591591
优点：
592-
✓ 代码成熟 (20+ 年优化)
592+
✓ 代码成熟 (20+ 年优化)且清晰度较好
593593
✓ 功能完整 (TCP/UDP/ICMP/IGMP/IPv6)
594594
✓ RFC 兼容性高
595595
✓ 已有 BBR/RACK/DCTCP 等算法
@@ -617,15 +617,23 @@ bash start.sh (启动脚本)
617617
选项 C：使用 Linux 内核栈 (Kernel Bypass)
618618
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
619619
✗ 不满足需求 (核心目标就是绕过内核)
620+
621+
移植到用户态优点：
622+
✓ 版本迭代快，新功能支持早
623+
✓ 性能一般略高于FreeBSD
624+
625+
移植到用户态缺点：
626+
✗ 代码更复杂，清晰度不如FreeBSD
627+
✗ 版本迭代快，跟进社区新版本工作量大
620628
```
621629
622630
**历史背景**：
623-
- F-Stack 初期（2015-2016）自研了简单 TCP/IP 栈
631+
- F-Stack 初期（2013-2016）自研了简单 TCP/IP 栈
624632
- 发现协议功能缺陷、性能优化空间有限
625633
- 2017 年参考 libuinet/libplebnet，完整移植 FreeBSD 11.0
626634
- 2021 年升级到 FreeBSD 13.0（支持 BBR 等算法）
627635
628-
### 5.3 KNI (Kernel Network Interface) 的设计决策
636+
### 5.3 KNI (Kernel Network Interface) 和virtio的设计决策
629637
630638
**KNI 的用途**：与 Linux 内核通信的虚拟网卡
631639
@@ -650,9 +658,14 @@ F-Stack (用户态)
650658
- KNI 会增加数据拷贝，影响吞吐 (2-3%)
651659
652660
**性能特性**：
653-
- 速率限制：1K QPS 数据、9K QPS 控制、10K QPS 总体
661+
662+
- 默认速率限制：1K QPS 数据、9K QPS 控制、10K QPS 总体
654663
- 可选的报文分发回调：应用自定义哪些流进入 KNI
655664
665+
**kni和virtio选择：
666+
667+
- 当前版本已经全面弃用传统的kni模块，改用性能和linux源生兼容性更好的virtio
668+
656669
---
657670
658671
## 6. 性能特性与硬件加速
@@ -678,7 +691,7 @@ F-Stack 充分利用现代 NIC 的硬件加速：
678691
NIC → kernel 缓冲 → 应用缓冲 (2 次拷贝)
679692

680693
F-Stack 方式：
681-
NIC → DPDK mbuf → 应用 (0 次拷贝，仅指针传递)
694+
NIC → DPDK mbuf → FreeBSD mbuf(0 次拷贝，仅指针传递) → 应用 # 【注】当前mbuf到应用使用的socket接口，零拷贝暂未支持，后续考虑将单独的零拷贝API ff_zc_mbuf_read()做实际实现支持
682695
```
683696
684697
**2. 批处理 (Batch Processing)**
@@ -759,16 +772,6 @@ LD_PRELOAD=libff_syscall.so nginx
759772
...
760773
```
761774

762-
**方式 3：配置文件启用 (如 Redis)**
763-
```bash
764-
# redis.conf
765-
port 6379
766-
...
767-
768-
# Redis 在启动时调用 ff_init()
769-
# 自动拦截所有网络操作
770-
```
771-
772775
### 7.2 工具支持
773776

774777
运维工具通过 IPC 与 F-Stack 进程通信：

‎docs/F-Stack_Architecture_Layer2_Interface_Specification.md‎

Lines changed: 38 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -568,22 +568,21 @@ F-Stack 使用 INI 格式配置文件，通过 `ff_load_config()` 加载：
568568
lcore_mask = 0xf # 使用核心 0-3 (十六进制)
569569
channel = 4 # 内存通道数
570570
memory = 4096 # 预留内存 (MB)
571-
promiscuous = 0 # 混杂模式
572-
numa_on = 0 # NUMA 支持
571+
promiscuous = 1 # 混杂模式
572+
numa_on = 1 # NUMA 支持
573573
574574
# 网卡配置
575575
port_list = 0,1 # 使用网卡 0 和 1
576576
nb_vdev = 0 # 虚拟设备数
577-
nb_bond = 0 # 网卡绑定数
577+
nb_bond = 0 # bondding网卡数
578578
579579
# 性能调优
580580
tso = 1 # 启用 TSO (硬件分段)
581-
lro = 1 # 启用 LRO (硬件合并)
582581
vlan_strip = 1 # VLAN 硬件标签剥离
583582
symmetric_rss = 0 # 双向 RSS 对称性
584583
idle_sleep = 0 # 空闲时 sleep (微秒)
585-
pkt_tx_delay = 0 # 包发送延迟 (关闭立即发)
586-
enable_kni = 0 # 启用虚拟网卡
584+
pkt_tx_delay = 100 # 包发送延迟 (关闭立即发)
585+
enable_kni = 1 # 启用虚拟网卡
587586
588587
[port0]
589588
# 网卡 0 的配置
@@ -592,16 +591,16 @@ netmask = 255.255.255.0
592591
gateway = 10.0.0.254
593592
broadcast = 10.0.0.255
594593
595-
# VIP (虚拟 IP，用于负载均衡)
594+
# VIP (虚拟 IP，用于单机支持多IP)
596595
vip_addr = 10.0.0.100; 10.0.0.101; 10.0.0.102
597596
598597
# IPv6 支持
599598
addr6 = 2001:db8::1
600599
prefix_len = 64
601600
gateway6 = 2001:db8::ff
602601
603-
# 策略路由
604-
ipfw_pr = /etc/ipfw_rules.txt
602+
# 用于支持多网段IP时设置简单的策略路由
603+
ipfw_pr = 10.0.0.100 255.255.255.0;192.168.0.0 255.255.255.0
605604
606605
# lcore 绑定 (可选)
607606
lcore_list = 0,1
@@ -612,50 +611,54 @@ addr = 192.168.1.1
612611
netmask = 255.255.255.0
613612
gateway = 192.168.1.254
614613
615-
[vlan0]
614+
[vlan<vlan id>]
616615
# VLAN 配置 (优先级高于 [portN])
617616
portid = 0
618617
addr = 172.16.0.1
619618
netmask = 255.255.0.0
620-
vid = 100 # VLAN ID
621-
priority = 3 # 优先级
619+
gateway = 172.16.0.1
620+
broadcast = 172.16.255.255
622621
623-
[kni0]
622+
[kni]
624623
# 虚拟网卡配置
625-
portid = 0
626-
lcore = 0
627-
type = tap # 虚拟网卡类型
624+
enable=1
625+
method=reject
626+
# The format is same as port_list
627+
tcp_port=80,443
628+
udp_port=53
629+
# KNI ratelimit value, default: 0, means disable ratelimit.
630+
# example:
631+
# The total speed limit for a single process entering the kni ring is 10,000 QPS,
632+
# 1000 QPS for general packets, 9000 QPS for console packets (ospf/arp, etc.)
633+
# The total speed limit for kni forwarding to the kernel is 20,000 QPS.
634+
#console_packets_ratelimit=0
635+
#general_packets_ratelimit=0
636+
#kernel_packets_ratelimit=0
628637
629638
[freebsd.boot]
630639
# FreeBSD 启动时配置
631-
hz = 1000 # 时钟频率 (Hz)
632-
fd_reserve = 100 # 预留文件描述符
640+
hz = 100 # 时钟频率 (Hz)
641+
fd_reserve = 1204 # 预留文件描述符
633642
kern.ipc.maxsockets = 1000000 # 最大 socket 数
634643
635644
[freebsd.sysctl]
636645
# FreeBSD 运行时 sysctl 配置
637-
kern.ipc.somaxconn = 1024 # socket 监听队列
638-
net.inet.tcp.syncache.hashsize = 512
639-
net.inet.tcp.syncache.bucketlimit = 30
646+
kern.ipc.somaxconn = 32768 # socket 监听队列
647+
net.inet.tcp.syncache.hashsize = 4096
648+
net.inet.tcp.syncache.bucketlimit = 100
640649
641650
# TCP 算法
642651
net.inet.tcp.cc.algorithm = cubic
643652
net.inet.tcp.functions_default=freebsd # freebsd/rack/bbr
644653
645654
# socket 缓冲 (关键性能参数)
646-
net.inet.tcp.sendspace = 32768 # 发送缓冲 (字节)
647-
net.inet.tcp.recvspace = 32768 # 接收缓冲
655+
net.inet.tcp.sendspace = 16384 # 发送缓冲 (字节)
656+
net.inet.tcp.recvspace = 8192 # 接收缓冲
648657
649658
# TCP 特性
650659
net.inet.tcp.sack.enable = 1 # SACK 选择性确认
651660
net.inet.tcp.rfc1323 = 1 # 时间戳选项
652-
net.inet.tcp.delayed_ack = 1 # 延迟确认
653-
654-
# 性能相关
655-
net.inet.tcp.inflight.enable = 1 # 输入流量控制
656-
net.inet.tcp.inflight.debug = 0
657-
net.inet.tcp.inflight.min = 6144
658-
net.inet.tcp.inflight.max = 2097152
661+
net.inet.tcp.delayed_ack = 1 # 延迟确认高吞吐， 0则低延迟
659662
```
660663

661664
### 3.2 配置优先级规则
@@ -700,9 +703,8 @@ F-Stack 采用 DPDK 的 Primary-Secondary 进程模型：
700703
#### **主进程 (Primary Process)**
701704

702705
```c
703-
// 启动时设置
704-
export proc_type=primary
705-
export proc_id=0
706+
// 启动时命令行设置
707+
proc_type=primary proc_id=0
706708

707709
ff_init(argc, argv)
708710
├─ 初始化 DPDK EAL (rte_eal_init)
@@ -720,9 +722,8 @@ ff_init(argc, argv)
720722
#### **从进程 (Secondary Process)**
721723
722724
```c
723-
// 启动时设置
724-
export proc_type=secondary
725-
export proc_id=1 # 不同从进程使用不同 ID
725+
// 启动时命令行设置
726+
proc_type=secondary proc_id=1 # 不同从进程使用不同 ID
726727
727728
ff_init(argc, argv)
728729
├─ 连接到 DPDK 共享内存 (由主进程创建)
@@ -1021,30 +1022,6 @@ int main(int argc, char *argv[]) {
10211022
}
10221023
```
10231024
1024-
#### **模式 3: Select/Poll (传统)**
1025-
1026-
```c
1027-
int main_loop(void *arg) {
1028-
fd_set readfds, writefds;
1029-
struct timeval tv = {0, 0}; // 非阻塞
1030-
1031-
FD_ZERO(&readfds);
1032-
FD_ZERO(&writefds);
1033-
1034-
// 添加你关注的 fd
1035-
FD_SET(sockfd1, &readfds);
1036-
FD_SET(sockfd2, &writefds);
1037-
1038-
int nfds = ff_select(64, &readfds, &writefds, NULL, &tv);
1039-
1040-
if (FD_ISSET(sockfd1, &readfds)) {
1041-
// sockfd1 可读
1042-
}
1043-
1044-
return 0;
1045-
}
1046-
```
1047-
10481025
### 5.2 关键开发规范
10491026
10501027
**规则 1: 强制非阻塞**
@@ -1054,6 +1031,7 @@ ff_ioctl(sockfd, FIONBIO, &flags); // 必须设置!
10541031
```
10551032

10561033
**规则 2: Main Loop 时间限制**
1034+
10571035
```c
10581036
// ✗ 错误: 阻塞太长
10591037
int main_loop(void *arg) {

0 commit comments

Comments
 (0)