perf(stack-select): wrk loopback baseline for kernel-access path

jfb8856606 · jfb8856606 · commit d61df357d2de · 2026-06-16T11:15:38.000+08:00
- helloworld_stacksel: add single-thread epoll keep-alive bench mode
- Makefile: A/B targets _ffk (ff_socket SOCK_KERNEL) vs _libc (raw socket)
- docs: 10-perf-baseline-report — A/B delta within noise (no data-path
  regression), with freebsd_13_to_15 CVM data as background reference
diff --git a/docs/kernel_event_support_spec/zh_cn/10-perf-baseline-report.md b/docs/kernel_event_support_spec/zh_cn/10-perf-baseline-report.md
@@ -0,0 +1,122 @@
+# 10 性能基线报告：内核访问路径（ff_socket(SOCK_KERNEL)）wrk 自压基线
+
+> **文档编号**：SPEC-KE-10
+> **日期**：2026-06-16
+> **状态**：COMPLETE
+> **作用域**：在**本机 loopback** 用 wrk 对"本地 socket/fd/event 访问"特性（`ff_socket(SOCK_KERNEL)` 内核栈路径）做性能基线，并以同源原生 `libc socket()` 版本做 A/B 对压求开销 Δ%，以 `freebsd_13_to_15_upgrade_spec/` 既有 CVM 数据作背景对照。
+> **实证铁律**：所有数字来自实际 wrk 运行（原始输出 `/tmp/keperf/{A,B}_T{1,2,3}_trial{1,2,3}.txt`），禁止臆造。
+
+---
+
+## 1. 测试目的
+
+量化"内核访问特性"在**数据面**是否引入吞吐/延迟开销。本特性核心是 socket 创建时按标记选栈（`ff_socket(...,SOCK_KERNEL)` → `ff_host_socket` → 宿主 `socket()`），后续 `bind/listen/accept/recv/send/epoll` 走相同的内核 fd 路径。因此理论上 A/B 的差异**仅为每连接建连时一次 `ff_socket→ff_host_socket` 函数跳转**，对 keep-alive 长连接的数据面应为零额外开销。本测试用实测验证该判断。
+
+---
+
+## 2. 环境
+
+| 项 | 值 |
+|---|---|
+| 主机 | 单台 CVM，16 vCPU，31 GiB |
+| 压测器 | wrk **4.2.0 [epoll]**（GitHub `wg/wrk` 源码本机构建，`/tmp/wrk-build/wrk`；系统源无 wrk 包） |
+| 被测端 | `example/helloworld_stacksel`，**单线程 epoll keep-alive HTTP server**（`bench <port>` 模式） |
+| 协议 | HTTP/1.1，`Connection: keep-alive`，固定 15B 响应体（对标 freebsd 升级 CVM helloworld 场景） |
+| 链路 | **loopback 127.0.0.1**（server 与 wrk 同机；server 绑 CPU0，wrk 绑 CPU2-15，`taskset` 降争用） |
+| 编译 | A/B 同 `-O2 -g`，同源 `main.c`，均链接 `lib/libfstack.a` |
+
+### 2.1 A/B 两版本（同源，仅 `ksock()` 不同）
+| 版本 | 构建 | socket 创建 | 含义 |
+|---|---|---|---|
+| **A** `helloworld_stacksel_ffk` | `-DUSE_FF_KERNEL=1` | `ff_socket(AF_INET, SOCK_STREAM\|SOCK_KERNEL, 0)` | 本特性内核访问路径 |
+| **B** `helloworld_stacksel_libc` | `-DUSE_FF_KERNEL=0` | `socket(AF_INET, SOCK_STREAM, 0)` | 纯内核栈参照 |
+
+---
+
+## 3. 方法（对齐既有 CVM 方法学档位）
+
+| 档位 | wrk 参数 | 时长 | 用途 |
+|---|---|---|---|
+| T1 | `-t2 -c10  --latency` | 5s | 轻载 + 预热剔除 |
+| T2 | `-t4 -c100 --latency` | 30s | 中负载主回归 |
+| T3 | `-t8 -c500 --latency` | 30s | 高并发尾延迟 |
+
+- 每档 **3 trial 取 median**；每版本前置一次 3s warmup（丢弃）。
+- 命令模板：`taskset -c 2-15 /tmp/wrk-build/wrk -t4 -c100 -d30s --latency http://127.0.0.1:<port>/`
+- server 启停经 `/data/workspace/kill_process.sh`；脚本 `/tmp/keperf/runbench.sh`。
+
+---
+
+## 4. 实测结果（median of 3 trials；原始见 `/tmp/keperf/`）
+
+### 4.1 吞吐 req/s
+
+| 档位 | A `SOCK_KERNEL` | B `libc socket` | Δ (A vs B) | 三次 trial（A / B） |
+|---|---:|---:|---:|---|
+| T1 (-t2 -c10 5s)   | 120,949 | 136,199 | **−11.2%** | A 119822/132566/120949 · B 137667/136199/118075 |
+| T2 (-t4 -c100 30s) | 125,169 | 119,498 | **+4.7%**  | A 125169/113753/135646 · B 119498/135067/118084 |
+| T3 (-t8 -c500 30s) | 107,298 | 112,728 | **−4.8%**  | A 102829/115724/107298 · B 114646/105920/112728 |
+
+### 4.2 延迟（median of 3 trials）
+
+| 档位 | A p50 | B p50 | A p99 | B p99 |
+|---|---:|---:|---:|---:|
+| T1 | 67us  | 60us  | 151us  | 133us  |
+| T2 | 767us | 814us | 1.04ms | 1.15ms |
+| T3 | 4.58ms| 4.37ms| 5.25ms | 5.11ms |
+
+- **Socket errors：0**（所有 18 个 trial 均无 connect/read/write/timeout 错误）。
+
+### 4.3 结论（A/B）
+
+**A 与 B 的吞吐/延迟差异在 ±11% 的 trial 间噪声范围内、无系统性方向**（A 在 T2 略快、T1/T3 略慢，各 trial 区间高度重叠）。这与理论一致：`ff_socket(SOCK_KERNEL)` 仅在**建连时**比 `libc socket()` 多一次 `ff_host_socket` 函数跳转，对 keep-alive 数据面零额外开销。
+
+→ **内核访问特性不引入可测量的数据面性能回归**（佐证 NFR-1 零开销 / NFR-2 业务快路径无回归）。波动主因：loopback 自压下 server 与 wrk 同机 CPU/软中断争用（实测 `sys` 时间占比极高），属测量噪声而非特性开销。
+
+---
+
+## 5. 背景对照：freebsd_13_to_15 既有 CVM 数据（口径不同，仅作参考）
+
+来源 `docs/freebsd_13_to_15_upgrade_spec/zh_cn/13.0-baseline-cvm-bench-report.md`（**双 CVM、server 跑 DPDK + F-Stack 用户态栈、相同 wrk 三档**）：
+
+| 档位 | 13.0 baseline req/s | 15.0 rfix req/s | 本报告 A（内核栈 loopback）|
+|---|---:|---:|---:|
+| T1 | 24,414 | 23,757 | 120,949 |
+| T2 | 220,691 | 203,933 | 125,169 |
+| T3 | 239,555 | 217,100 | 107,298 |
+
+**口径差异（不可直接等价，务必注意）**：
+1. **栈不同**：CVM 数据是 **F-Stack 用户态栈经 DPDK 网卡**的数据面吞吐；本报告是 **Linux 内核栈 + loopback** 的吞吐——二者测的是不同协议栈的不同路径。
+2. **拓扑不同**：CVM 为**双机网卡间**真实收发；本报告为**单机 loopback 自压**（server 与 wrk 争用同一组 CPU）。
+3. **并发模型不同**：CVM helloworld 为 F-Stack `lcore=4`；本报告为**单线程 epoll**（用户已确认"单线程数字仅反映串行下限"）。
+4. T1 在两边都波动较大（5s 短窗），仅作链路探活，不用于结论。
+
+**用途说明**：本特性是在 F-Stack 之外**新增**一条"内核栈可访问"通道（供本机 ping/curl 与客户端连本机/外部内核服务），**不替代** F-Stack 业务数据面。CVM 数据用于说明 F-Stack 业务面的吞吐量级背景；本特性的开销由 §4 的 A/B 同环境对压给出（≈噪声、无回归）。
+
+---
+
+## 6. 局限与后续
+
+- 本基线为**本机 loopback 单线程**自压，反映"串行/单 loop 下限"，**非** server 真实极限，也非双 CVM DPDK 数据面；绝对值仅在同口径内可比。
+- 真实物理机/双 CVM 下的 hook 模式端到端与 F-Stack 业务面+内核管理面共存吞吐，待具备 DPDK 绑定物理 NIC 环境后按 `cvm-bench-methodology.md` 补跑（沿用 `freebsd_13_to_15` F-A3/F-A4 路径）。
+- 如需更高单机吞吐基线，可启用多线程 `SO_REUSEPORT`（本轮按用户要求保持单线程）。
+
+---
+
+## 7. 复现实步
+
+```bash
+# 1) 构建 wrk（系统无包时源码构建）
+git clone --depth 1 https://github.com/wg/wrk.git /tmp/wrk-build && make -C /tmp/wrk-build -j4
+
+# 2) 构建 A/B 被测二进制
+cd /data/workspace/f-stack/example/helloworld_stacksel && make bench
+#   -> helloworld_stacksel_ffk (SOCK_KERNEL) / helloworld_stacksel_libc (libc)
+
+# 3) 三档自压（server 绑 CPU0，wrk 绑 CPU2-15，各 3 trial）
+bash /tmp/keperf/runbench.sh A helloworld_stacksel_ffk  18211
+bash /tmp/keperf/runbench.sh B helloworld_stacksel_libc 18212
+#   原始输出：/tmp/keperf/{A,B}_T{1,2,3}_trial{1,2,3}.txt
+```
+
+> 合规：wrk 进程经 `kill_process.sh` 停止、临时文件经 `rm_tmp_file.sh` 清理；无直接 rm/kill/chmod。
diff --git a/example/helloworld_stacksel/Makefile b/example/helloworld_stacksel/Makefile
@@ -17,10 +17,28 @@ LIBS+= -L${FF_PATH}/lib -Wl,--whole-archive,-lfstack,--no-whole-archive
 LIBS+= -Wl,--no-whole-archive -lrt -lm -ldl -lcrypto -lz -pthread -lnuma
 
 TARGET=helloworld_stacksel
+TARGET_FFK=helloworld_stacksel_ffk
+TARGET_LIBC=helloworld_stacksel_libc
+
+# Perf-baseline binaries are built at -O2 (same flags for A and B so the
+# measured A/B delta isolates only the ksock() difference).
+BENCH_CFLAGS=-O2 -g -I${FF_PATH}/lib $(shell $(PKGCONF) --cflags libdpdk)
 
 all:
 	cc ${CFLAGS} -o ${TARGET} main.c ${LIBS}
 
+# A/B perf-baseline targets from the SAME main.c (only ksock() differs):
+#   _ffk  : USE_FF_KERNEL=1 -> ff_socket(SOCK_KERNEL)  (feature path A)
+#   _libc : USE_FF_KERNEL=0 -> libc socket()           (pure-kernel ref B)
+.PHONY: bench
+bench: ${TARGET_FFK} ${TARGET_LIBC}
+
+${TARGET_FFK}:
+	cc ${BENCH_CFLAGS} -DUSE_FF_KERNEL=1 -o ${TARGET_FFK} main.c ${LIBS}
+
+${TARGET_LIBC}:
+	cc ${BENCH_CFLAGS} -DUSE_FF_KERNEL=0 -o ${TARGET_LIBC} main.c ${LIBS}
+
 .PHONY: clean
 clean:
-	/data/workspace/rm_tmp_file.sh $(CURDIR)/${TARGET} $(CURDIR)/main.o
+	/data/workspace/rm_tmp_file.sh $(CURDIR)/${TARGET} $(CURDIR)/${TARGET_FFK} $(CURDIR)/${TARGET_LIBC} $(CURDIR)/main.o
diff --git a/example/helloworld_stacksel/main.c b/example/helloworld_stacksel/main.c
@@ -16,28 +16,46 @@
  *   (no args)            self-test: in-process kernel-stack server+client
  *   server <port>        one-shot HTTP/1.1 server on the kernel stack
  *   client <ip> <port>   connect to a kernel-stack service and print reply
+ *   bench <port>         single-thread epoll keep-alive HTTP server (wrk target)
+ *
+ * A/B build switch (perf baseline):
+ *   USE_FF_KERNEL=1 (default)  ksock() -> ff_socket(SOCK_KERNEL)  [feature path A]
+ *   USE_FF_KERNEL=0            ksock() -> libc socket()           [pure-kernel ref B]
  */
 
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <unistd.h>
 #include <errno.h>
+#include <fcntl.h>
 #include <sys/types.h>
 #include <sys/socket.h>
+#include <sys/epoll.h>
 #include <sys/wait.h>
 #include <netinet/in.h>
 #include <arpa/inet.h>
 
 #include "ff_api.h"   /* ff_socket + SOCK_KERNEL / SOCK_FSTACK markers */
 
+#ifndef USE_FF_KERNEL
+#define USE_FF_KERNEL 1
+#endif
+
 static int
 ksock(void)
 {
-    /* Single API + marker: this socket belongs to the host kernel stack. */
+#if USE_FF_KERNEL
+    /* A (feature path): connection-level stack selection via marker. */
     int fd = ff_socket(AF_INET, SOCK_STREAM | SOCK_KERNEL, 0);
     if (fd < 0)
         perror("ff_socket(SOCK_KERNEL)");
+#else
+    /* B (pure-kernel reference): raw libc kernel socket. */
+    int fd = socket(AF_INET, SOCK_STREAM, 0);
+    if (fd < 0)
+        perror("socket()");
+#endif
     return fd;
 }
 
@@ -211,6 +229,109 @@ do_selftest(void)
     return 1;
 }
 
+static int
+set_nonblock(int fd)
+{
+    int fl = fcntl(fd, F_GETFL, 0);
+    return (fl < 0) ? -1 : fcntl(fd, F_SETFL, fl | O_NONBLOCK);
+}
+
+/*
+ * Single-threaded epoll keep-alive HTTP server (mode "bench <port>") — the wrk
+ * performance-baseline target. One thread, one epoll loop multiplexing the
+ * listen fd and all accepted keep-alive connections (same single-loop
+ * event-driven model as the F-Stack helloworld_epoll baseline). All fds come
+ * from ksock(): SOCK_KERNEL host fds (A) or raw libc fds (B); the rest of the
+ * path (bind/listen/accept/epoll/recv/send) is identical, so the A/B delta
+ * isolates only the per-connection ff_socket->ff_host_socket indirection.
+ */
+static int
+do_bench(int port)
+{
+    static const char resp[] =
+        "HTTP/1.1 200 OK\r\nContent-Length: 15\r\n"
+        "Connection: keep-alive\r\n\r\nhello-stacksel\n";
+    const size_t resp_len = sizeof(resp) - 1;
+
+    int sfd = ksock();
+    if (sfd < 0)
+        return 1;
+    int on = 1;
+    setsockopt(sfd, SOL_SOCKET, SO_REUSEADDR, &on, sizeof(on));
+
+    struct sockaddr_in sa;
+    memset(&sa, 0, sizeof(sa));
+    sa.sin_family = AF_INET;
+    sa.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
+    sa.sin_port = htons((unsigned short)port);
+    if (bind(sfd, (struct sockaddr *)&sa, sizeof(sa)) < 0) {
+        perror("bind");
+        return 1;
+    }
+    if (listen(sfd, 1024) < 0) {
+        perror("listen");
+        return 1;
+    }
+    set_nonblock(sfd);
+
+    int ep = epoll_create1(0);
+    if (ep < 0) {
+        perror("epoll_create1");
+        return 1;
+    }
+    struct epoll_event ev, evs[1024];
+    ev.events = EPOLLIN;
+    ev.data.fd = sfd;
+    epoll_ctl(ep, EPOLL_CTL_ADD, sfd, &ev);
+
+    printf("[bench] %s keep-alive server on 127.0.0.1:%d (single-thread epoll)\n",
+           (USE_FF_KERNEL ? "ff_socket(SOCK_KERNEL)" : "libc socket()"), port);
+    fflush(stdout);
+
+    for (;;) {
+        int n = epoll_wait(ep, evs, 1024, -1);
+        if (n < 0) {
+            if (errno == EINTR)
+                continue;
+            perror("epoll_wait");
+            break;
+        }
+        for (int i = 0; i < n; i++) {
+            int fd = evs[i].data.fd;
+            if (fd == sfd) {
+                for (;;) {
+                    int cfd = accept(sfd, NULL, NULL);
+                    if (cfd < 0)
+                        break;  /* EAGAIN: backlog drained */
+                    set_nonblock(cfd);
+                    ev.events = EPOLLIN;
+                    ev.data.fd = cfd;
+                    epoll_ctl(ep, EPOLL_CTL_ADD, cfd, &ev);
+                }
+            } else {
+                char buf[2048];
+                ssize_t r = recv(fd, buf, sizeof(buf), 0);
+                if (r > 0) {
+                    ssize_t off = 0;
+                    while (off < (ssize_t)resp_len) {
+                        ssize_t w = send(fd, resp + off, resp_len - off, 0);
+                        if (w <= 0)
+                            break;
+                        off += w;
+                    }
+                } else if (r == 0 ||
+                           (r < 0 && errno != EAGAIN && errno != EWOULDBLOCK)) {
+                    epoll_ctl(ep, EPOLL_CTL_DEL, fd, NULL);
+                    close(fd);
+                }
+            }
+        }
+    }
+    close(ep);
+    close(sfd);
+    return 0;
+}
+
 int
 main(int argc, char **argv)
 {
@@ -220,5 +341,7 @@ main(int argc, char **argv)
         return do_server(atoi(argv[2]), /*oneshot*/atoi(argv[3])) == 0 ? 0 : 1;
     if (argc >= 4 && strcmp(argv[1], "client") == 0)
         return do_client(argv[2], atoi(argv[3])) == 0 ? 0 : 1;
+    if (argc >= 3 && strcmp(argv[1], "bench") == 0)
+        return do_bench(atoi(argv[2]));
     return do_selftest();
 }
