Skip to content

Commit 074ffa3

Browse files
jfb8856606jfb8856606
committed
fix(docs): correct errors found in manual review
- 01/02/03 and all Layer docs: fix project path /data/workspace -> /projects/f-stack - Layer2: fix EVFILT_READ/WRITE/TIMER/SIGNAL constants (were wrong positive values, corrected to -1/-2/-7/-6) - Layer2: fix ff_run return type int -> void - Layer2: fix ff_route_ctl signature (enum types, remove ifname, correct param names) - Layer2: fix ff_log_open_set signature (was (const char*, int), is void) - Layer2: fix ff_log signature (add missing logtype param, uint32_t types) - Layer2: fix ff_log_set_level param types int -> uint32_t - Layer2: fix FF_LOG_* level values (start from 1U, not 0) - Layer2: fix kevent struct (data field __int64_t not intptr_t, add ext[4], filter is short not int16_t) - Layer3_Index: fix ff_run return type int -> void - Layer3_Index: fix ff_route_ctl signature (enum types) - Layer3_Index: fix ff_sysctl signature (const int* MIB array, not const char*) - Layer3_Index: fix ff_zc_mbuf_get/write/read signatures completely - Layer3_Index: fix ff_log_open_set/reset_stream/set_global_level/log/vlog/log_close signatures - Layer3_Index: fix kevent struct (data __int64_t, add ext[4], field offsets corrected) - Layer3_Functions: fix ff_init param (char * const argv[]) - Layer3_Functions: fix ff_kevent_do_each (4 params -> 7, void -> int) - Layer3_Functions: fix ff_route_ctl param count (2 -> 5) - Layer3_Functions: remove non-existent ff_msg_send function - Layer3_Functions: fix ff_config struct (correct field types, remove fake host substructure) - Layer3_Functions: fix ff_rss_tbl (remove non-existent ff_rss_tbl_lookup, correct structure) - Layer3_Functions: fix ff_msg_ring (replace with real ff_msg struct from ff_msg.h) - Layer3_Functions: fix ff_zc_mbuf struct and usage (correct fields and API) - Layer1/Layer1_Overview: clarify KNI now uses virtio_user not rte_kni.ko - Layer1_Overview: fix KNI description (not 'fully deprecated', implementation changed) - Knowledge_Base_Summary: fix FreeBSD version (11/13 -> 13.0)
1 parent 8f30868 commit 074ffa3

7 files changed

Lines changed: 172 additions & 141 deletions

‎docs/01-LAYER1-ARCHITECTURE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ NIC 驱动 (igb_uio / vfio-pci)
5050
### 2.1 核心目录布局
5151

5252
```
53-
/data/workspace/f-stack/
53+
/projects/f-stack/
5454
├── lib/ # F-Stack 核心库 (~21K 行 C 代码)
5555
│ ├── ff_dpdk_if.c (2855行) # DPDK 网卡接口层 - 最核心
5656
│ ├── ff_glue.c (1466行) # FreeBSD 粘合层
@@ -59,7 +59,7 @@ NIC 驱动 (igb_uio / vfio-pci)
5959
│ ├── ff_host_interface.c # 主机接口 (pthread/mmap/时间)
6060
│ ├── ff_init.c (69行) # 初始化协调
6161
│ ├── ff_epoll.c (159行) # epoll 接口转换
62-
│ ├── ff_dpdk_kni.c # 虚拟网卡支持
62+
│ ├── ff_dpdk_kni.c # 虚拟网卡支持（通过 virtio_user 实现，已不依赖 rte_kni.ko）
6363
│ ├── Makefile # 编译系统
6464
│ └── include/ # 头文件
6565
│
@@ -109,7 +109,7 @@ NIC 驱动 (igb_uio / vfio-pci)
109109
| **ff_init.c** | 69 | 初始化流程协调 | 上述所有模块 |
110110
| **ff_epoll.c** | 159 | Linux epoll→FreeBSD kqueue 转换 | FreeBSD kqueue |
111111
| **ff_host_interface.c** | -- | 主机 OS 接口 (mmap/pthread/rand) | 系统库 |
112-
| **ff_dpdk_kni.c** | -- | 虚拟网卡支持 (可选) | DPDK KNI |
112+
| **ff_dpdk_kni.c** | -- | 虚拟网卡支持（通过 virtio_user 实现，已不依赖 rte_kni.ko） | DPDK virtio_user |
113113

114114
## 3. FreeBSD TCP/IP 栈移植方式
115115

‎docs/02-LAYER2-INTERFACES.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ int ff_pthread_join(pthread_t thread, void **value_ptr);
123123
124124
### 2.1 配置文件格式 (INI)
125125
126-
文件位置: `/data/workspace/f-stack/config.ini`
126+
文件位置: `/projects/f-stack/config.ini`
127127
128128
```ini
129129
[dpdk]
@@ -416,7 +416,7 @@ rte_pktmbuf_free(m); // 多进程安全
416416
### 6.1 编译 F-Stack 库
417417

418418
```bash
419-
cd /data/workspace/f-stack/lib
419+
cd /projects/f-stack/lib
420420
make clean
421421
make
422422
make install PREFIX=/usr/local

‎docs/03-LAYER3-FUNCTIONS.md‎

Lines changed: 85 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
| 函数 | 签名 | 功能 | 线程安全 |
1616
|-----|------|------|--------|
17-
| `ff_init` | `int ff_init(int argc, char *argv[])` | 初始化 DPDK/FreeBSD/网卡 | 否 |
17+
| `ff_init` | `int ff_init(int argc, char * const argv[])` | 初始化 DPDK/FreeBSD/网卡 | 否 |
1818
| `ff_run` | `void ff_run(loop_func_t, void *arg)` | 启动主循环 (阻塞) | 否 |
1919
| `ff_stop_run` | `void ff_stop_run(void)` | 优雅停止循环 | 是 |
2020

@@ -52,7 +52,7 @@
5252
|-----|------|--------|--------|
5353
| `ff_kqueue` | BSD 事件队列 | 0 | int(kq_fd) |
5454
| `ff_kevent` | BSD 事件等待 | 6 | 事件数/-1 |
55-
| `ff_kevent_do_each` | BSD 遍历事件 | 4 | void |
55+
| `ff_kevent_do_each` | BSD 遍历事件 | 7 | int |
5656
| `ff_epoll_create` | Linux epoll | 1 | int(ep_fd) |
5757
| `ff_epoll_ctl` | epoll 控制 | 4 | 0/-1 |
5858
| `ff_epoll_wait` | epoll 等待 | 4 | 事件数/-1 |
@@ -73,7 +73,7 @@
7373
| 函数 | 参数 | 功能 |
7474
|-----|------|------|
7575
| `ff_sysctl` | 6 | 读写内核变量 |
76-
| `ff_route_ctl` | 2 | 路由表控制 |
76+
| `ff_route_ctl` | 5 | 路由表控制 |
7777
| `ff_rtioctl` | 2 | 路由 ioctl |
7878
| `ff_gettimeofday` | 2 | 获取系统时间 |
7979

@@ -95,7 +95,6 @@
9595
|-----|------|
9696
| `ff_pthread_create` | 创建 pthread |
9797
| `ff_pthread_join` | 等待 pthread |
98-
| `ff_msg_send` | 发送跨 lcore 消息 |
9998

10099
### 1.9 日志函数
101100

@@ -115,11 +114,12 @@
115114
```c
116115
struct kevent {
117116
uintptr_t ident; // 事件标识符 (fd 或定时器 ID)
118-
short filter; // 事件过滤器类型
119-
u_short flags; // 控制标志 (EV_ADD, EV_DELETE 等)
120-
u_int fflags; // 过滤器特定标志
121-
intptr_t data; // 事件数据 (就绪数、超时等)
117+
short filter; // 事件过滤器类型 (short，非 int16_t)
118+
unsigned short flags; // 控制标志 (EV_ADD, EV_DELETE 等)
119+
unsigned int fflags; // 过滤器特定标志
120+
__int64_t data; // 事件数据 (就绪数、超时等，固定 64 位)
122121
void *udata; // 用户定义数据指针
122+
__uint64_t ext[4]; // FreeBSD 13 新增扩展字段
123123
};
124124

125125
// 过滤器类型 (filter 值)
@@ -151,36 +151,31 @@ struct kevent {
151151
152152
### 2.2 ff_config 结构 (全局配置)
153153
154+
> **注意**: 以下为简化示意，非 `ff_config.h` 中的完整定义。实际结构中配置值均以字符串 (`char *`) 形式存储，由 `ff_load_config()` 解析 config.ini 后填充。关键字段类型如下：
155+
154156
```c
155157
struct ff_config {
156-
// DPDK 配置
158+
char *filename; // 配置文件路径
157159
struct {
158-
char portid_list[32]; // NIC 端口列表
159-
uint32_t nb_ports; // 端口数
160-
uint32_t lcore_mask; // CPU 核心掩码
161-
char proc_type; // 主/从进程
162-
uint32_t proc_id; // 进程 ID
163-
uint32_t nb_procs; // 进程总数
160+
char *lcore_mask; // CPU 核心掩码 (字符串，如 "0x01")
161+
char *proc_type; // 进程类型 (字符串 "primary"/"secondary")
162+
uint32_t proc_id; // 进程 ID
163+
uint32_t nb_procs; // 进程总数
164164
uint32_t pktmbuf_pool_size; // mbuf 池大小
165-
uint32_t numa_on; // NUMA 支持
165+
uint32_t numa_on; // NUMA 支持
166+
uint16_t *portid_list; // NIC 端口 ID 列表
167+
uint32_t nb_ports; // 端口数
166168
} dpdk;
167-
168-
// 主机配置
169-
struct {
170-
struct in_addr ipaddr; // IP 地址
171-
struct in_addr netmask; // 子网掩码
172-
struct in_addr gateway; // 网关
173-
char iface[IFNAMSIZ]; // 网卡名称
174-
} host;
175-
176-
// KNI 虚拟网卡配置
169+
170+
// 端口配置通过 dpdk.port_cfgs 访问 (struct ff_port_cfg 数组)
171+
// 每个 ff_port_cfg 包含 IP/mask/gw 等字段
172+
177173
struct {
178-
uint32_t enable; // 启用标志
179-
char name[IFNAMSIZ]; // 网卡名
180-
uint32_t core; // CPU 核心
174+
uint32_t enable; // KNI 启用标志
175+
char *kni_action; // KNI 转发策略
181176
} kni;
182-
183-
// 其他配置...
177+
178+
// ... 更多字段见 lib/ff_config.h
184179
} ff_global_cfg;
185180
```
186181

@@ -211,38 +206,55 @@ struct ff_port_cfg {
211206

212207
### 2.4 ff_rss_tbl 结构 (RSS 查表)
213208

214-
```c
215-
// RSS 表项：将源 IP/端口映射到目标队列
216-
struct ff_rss_tbl_entry {
217-
struct in_addr saddr; // 源 IP
218-
uint16_t sport; // 源端口
219-
220-
struct in_addr daddr; // 目标 IP 范围开始
221-
uint16_t dport_start; // 目标端口范围开始
222-
uint16_t dport_end;
223-
224-
uint16_t queue_id; // 目标 RX 队列
225-
uint16_t lcore_id; // 目标 CPU 核心
226-
};
209+
> **注意**: `ff_rss_tbl_lookup()` 函数不存在于公开 API 中，RSS 表仅供内部使用。实际结构体为 `ff_rss_tbl_type`（定义在 `lib/ff_dpdk_if.c`），外部无需直接访问。
227210
228-
// 查表函数
229-
uint16_t ff_rss_tbl_lookup(struct in_addr saddr, uint16_t sport,
230-
struct in_addr daddr, uint16_t dport);
211+
```c
212+
// 内部结构（仅供参考，不在公开头文件中）
213+
struct ff_rss_tbl_type {
214+
uint32_t saddr; // 源 IP
215+
uint16_t sport; // 源端口
216+
uint16_t num; // dip 表项数量
217+
struct ff_rss_tbl_dip_type dip_tbl[FF_RSS_TBL_MAX_DADDR];
218+
} __rte_cache_aligned;
219+
220+
// 公开初始化接口 (ff_host_interface.h)
221+
int ff_rss_tbl_init(void);
231222
```
232223
233224
### 2.5 ff_msg_ring 结构 (进程间通信)
234225
226+
> **注意**: `ff_msg_send()` 不是公开 API，在 `ff_api.h` 和 `ff_api.symlist` 中均不存在。进程间通信通过 `ff_msg` 消息队列（`lib/ff_msg.h`）实现，由 F-Stack 内部工具（knictl/sysctl 等）使用，应用层无需直接调用。
227+
235228
```c
236-
// 轻量级消息队列，用于跨 lcore 消息传递
237-
struct ff_msg_ring {
238-
void (*cb)(void *arg); // 回调函数指针
239-
void *arg; // 回调参数
229+
// 消息类型枚举 (lib/ff_msg.h)
230+
enum FF_MSG_TYPE {
231+
FF_UNKNOWN = 0,
232+
FF_SYSCTL,
233+
FF_IOCTL,
234+
FF_IOCTL6,
235+
FF_ROUTE,
236+
FF_TOP,
237+
FF_NGCTL,
238+
FF_IPFW_CTL,
239+
FF_TRAFFIC,
240+
FF_KNICTL,
241+
FF_MSG_NUM,
240242
};
241243
242-
// 发送消息到另一个 lcore
243-
int ff_msg_send(unsigned lcore_id,
244-
void (*cb)(void *),
245-
void *arg);
244+
// 消息结构体 (简化)
245+
struct ff_msg {
246+
enum FF_MSG_TYPE msg_type;
247+
int result;
248+
size_t buf_len;
249+
char *buf_addr;
250+
union {
251+
struct ff_sysctl_args sysctl;
252+
struct ff_route_args route;
253+
struct ff_traffic_args traffic;
254+
struct ff_knictl_args knictl;
255+
// ...
256+
};
257+
} __attribute__((packed)) __rte_cache_aligned;
246258
```
247259

248260
### 2.6 ff_tx_offload 结构 (发送卸载)
@@ -260,10 +272,25 @@ struct ff_tx_offload {
260272
### 2.7 ff_zc_mbuf 结构 (零拷贝)
261273

262274
```c
275+
// 定义于 lib/ff_api.h
263276
struct ff_zc_mbuf {
264-
struct rte_mbuf **m; // mbuf 指针数组
265-
uint16_t nb_mbufs; // 缓冲区数量
277+
void *bsd_mbuf; // 指向 mbuf 链头
278+
void *bsd_mbuf_off; // 指向当前偏移处的 mbuf
279+
int off; // 当前总偏移量 (APP 不应修改)
280+
int len; // mbuf 链总长度
266281
};
282+
283+
// 使用方法：
284+
// 1. 调用方分配 struct ff_zc_mbuf zm; (栈上或堆上均可)
285+
// 2. ff_zc_mbuf_get(&zm, len) — 分配 mbuf 链，填充 zm
286+
// 3. ff_zc_mbuf_write(&zm, data, len) — 写入数据到 mbuf 链
287+
// 4. ff_write(fd, zm.bsd_mbuf, len) — 以 bsd_mbuf 为 buf 发送
288+
//
289+
// 注意: ff_zc_mbuf_read() 暂未实现
290+
291+
int ff_zc_mbuf_get(struct ff_zc_mbuf *m, int len);
292+
int ff_zc_mbuf_write(struct ff_zc_mbuf *m, const char *data, int len);
293+
int ff_zc_mbuf_read(struct ff_zc_mbuf *m, const char *data, int len); // 暂未实现
267294
```
268295
269296
### 2.8 ff_dispatcher_context 结构 (包分发)
@@ -564,7 +591,7 @@ struct prison prison0; // 命名空间
564591
### 5.1 编译 F-Stack 库
565592

566593
```bash
567-
cd /data/workspace/f-stack/lib
594+
cd /projects/f-stack/lib
568595

569596
# 基础编译
570597
make clean

‎docs/F-Stack_Architecture_Layer1_System_Overview.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ F-Stack 模式 (用户态网络)
7676
### 2.1 源码树布局
7777

7878
```
79-
/data/workspace/f-stack/
79+
/projects/f-stack/
8080
│
8181
├── lib/ # F-Stack 核心库 (~21K 行C代码)
8282
│ ├── ff_dpdk_if.c (2855行) # ⭐ 最核心：DPDK/NIC驱动
@@ -675,7 +675,7 @@ F-Stack (用户态)
675675
676676
**kni和virtio选择：
677677
678-
- 当前版本已经全面弃用传统的kni模块，改用性能和linux源生兼容性更好的virtio
678+
- 当前版本 KNI 功能保留，但底层实现已从 `rte_kni.ko` 内核模块切换为 `virtio_user`（见 lib/Makefile:34），不再依赖内核 KNI 模块
679679
680680
---
681681

‎docs/F-Stack_Architecture_Layer2_Interface_Specification.md‎

Lines changed: 33 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ int ff_init(int argc, char * const argv[]);
7272
// 返回: 0 成功, -1 失败
7373
// 必须在主进程首先调用
7474

75-
int ff_run(loop_func_t loop, void *arg);
75+
void ff_run(loop_func_t loop, void *arg);
7676
// 启动主轮询循环
7777
// 参数: 用户回调函数、用户参数
7878
// 不返回 (除非 ff_stop_run() 调用)
@@ -218,11 +218,12 @@ struct hostent * ff_gethostbyname2(const char *name, int af);
218218

219219
**路由管理**：
220220
```c
221-
int ff_route_ctl(unsigned int cmd, const char *ifname,
222-
struct linux_sockaddr *dst, struct linux_sockaddr *gateway,
221+
int ff_route_ctl(enum FF_ROUTE_CTL req, enum FF_ROUTE_FLAG flag,
222+
struct linux_sockaddr *dst, struct linux_sockaddr *gw,
223223
struct linux_sockaddr *netmask);
224224
// 路由操作
225-
// cmd: ROUTE_CMD_ADD / ROUTE_CMD_DEL / ROUTE_CMD_CHANGE
225+
// req: FF_ROUTE_ADD / FF_ROUTE_DEL / FF_ROUTE_CHANGE
226+
// flag: FF_RTF_HOST / FF_RTF_GATEWAY
226227
```
227228
228229
**零拷贝 Mbuf**：
@@ -258,24 +259,25 @@ ssize_t ff_zc_mbuf_read(int fd, struct ff_zc_mbuf *zm);
258259
#define FF_LOGTYPE_USER1 20
259260
#define FF_LOGTYPE_USER8 27
260261

261-
int ff_log_open_set(const char *logfile, int level);
262-
// 设置日志文件和级别
262+
int ff_log_open_set(void);
263+
// 打开 F-Stack 日志文件（路径和级别均从 config.ini 读取）
264+
// 返回 0 成功，-1 失败
263265

264-
int ff_log_set_level(int logtype, int level);
266+
int ff_log_set_level(uint32_t logtype, uint32_t level);
265267
// 设置特定日志类型的级别
266268

267-
int ff_log(int level, const char *fmt, ...);
268-
// 输出日志
269-
270-
// 日志级别
271-
#define FF_LOG_EMERG 0
272-
#define FF_LOG_ALERT 1
273-
#define FF_LOG_CRIT 2
274-
#define FF_LOG_ERR 3
275-
#define FF_LOG_WARNING 4
276-
#define FF_LOG_NOTICE 5
277-
#define FF_LOG_INFO 6
278-
#define FF_LOG_DEBUG 7
269+
int ff_log(uint32_t level, uint32_t logtype, const char *format, ...);
270+
// 输出日志（level: FF_LOG_ERR 等；logtype: FF_LOGTYPE_USER1 等）
271+
272+
// 日志级别（值从 1 开始，0 为禁用）
273+
#define FF_LOG_EMERG 1U
274+
#define FF_LOG_ALERT 2U
275+
#define FF_LOG_CRIT 3U
276+
#define FF_LOG_ERR 4U
277+
#define FF_LOG_WARNING 5U
278+
#define FF_LOG_NOTICE 6U
279+
#define FF_LOG_INFO 7U
280+
#define FF_LOG_DEBUG 8U
279281
```
280282
281283
**多线程支持**：
@@ -407,21 +409,23 @@ struct ff_config {
407409
```c
408410
struct kevent {
409411
uintptr_t ident; // 事件 ID (socket fd)
410-
int16_t filter; // 事件过滤器
412+
int16_t filter; // 事件过滤器 (short，值为负数)
411413
uint16_t flags; // 事件标志
412414
uint32_t fflags; // 过滤器标志
413-
intptr_t data; // 数据 (就绪数/错误)
415+
__int64_t data; // 数据 (就绪数/错误，固定 64 位)
414416
void *udata; // 用户数据指针
417+
__uint64_t ext[4]; // FreeBSD 13 扩展字段
415418
};
416419

417-
// 支持的过滤器
418-
#define EVFILT_READ 1 // 套接字可读
419-
#define EVFILT_WRITE 2 // 套接字可写
420-
#define EVFILT_TIMER 7 // 定时器
421-
#define EVFILT_SIGNAL 10 // 信号
422-
#define EVFILT_VNODE 11 // 文件系统事件
423-
#define EVFILT_PROC 12 // 进程事件
424-
// ... 还有 7 种
420+
// 支持的过滤器 (值为负数！)
421+
#define EVFILT_READ (-1) // 套接字可读
422+
#define EVFILT_WRITE (-2) // 套接字可写
423+
#define EVFILT_AIO (-3) // 异步 I/O
424+
#define EVFILT_VNODE (-4) // 文件系统事件
425+
#define EVFILT_PROC (-5) // 进程事件
426+
#define EVFILT_SIGNAL (-6) // 信号
427+
#define EVFILT_TIMER (-7) // 定时器
428+
// ... 还有 6 种，见 freebsd/sys/event.h
425429

426430
// 事件标志
427431
#define EV_ADD 0x0001 // 添加事件

0 commit comments

Comments
 (0)