packerlschupfer/octeon-flowtable

# octeon-flowtable 一个纯净的 **nftables flow-offload 后端**，专为 Cavium **Octeon+ (CN50xx)** 数据包处理组件设计 —— 即 Ubiquiti EdgeRouter Lite 3 (ERLite-3) 中的 SoC。它能为 运行主流 OpenWrt 的 ERLite-3 提供硬件加速的 NAT/路由，其性能**媲美 专有的 EdgeOS offload**，且仅使用 GPL 内核源代码和公开的 OCTEON 硬件参考手册 —— **无需 Ubiquiti 二进制文件，无需 Cavium SDK**。 WQE 级别的 RX 钩子会在构建任何 skb *之前*拦截转发的数据包， 在 FPA 数据包缓冲区中重写 L2/L3/L4 层（NAT、下一跳 MAC、TTL/hop-limit、VLAN 标签）并计算增量校验和，然后通过 PKO 传输 —— 无需 skb，不经过 Linux 协议栈。 未命中则正常向下穿透至常规转发流程。 ## 测试结果（基于真实的 ERLite-3，CN5020，2×500 MHz） | 指标 | OpenWrt 软件 | **本驱动** | EdgeOS 厂商 | |---|---|---|---| | 单流 TCP NAT | 764 Mbps | **932 Mbps** | 940 Mbps | | 多流 TCP NAT | 941 Mbps | **935 Mbps** | 563 Mbps | | UDP-64 NAT (pps) | 73k | **431k** | 247–431k | | 负载下的 RTT | 6.1 ms | **2.1 ms** | 2.6 ms | 在小包 pps 上达到软件基准的 5.9 倍，延迟改善了 3 倍 —— 媲美 其逆向工程的厂商实现。 ## 加速范围 IPv4 + IPv6、NAT + 路由、untagged + **802.1Q VLAN**（retag / pop / push）+ **QinQ**（双标签）—— 均已通过硬件验证。此外还包含一个全局硬件 FAU 计数器 以及一个 **PKO tail-drop AQM**，在相同吞吐量下可将 bufferbloat 从 54 ms 降低至 4 ms。 请参阅 [`docs/PROJECT-OUTCOME.md`](docs/PROJECT-OUTCOME.md) 和 [`docs/FUTURE-WORK.md`](docs/FUTURE-WORK.md) 获取完整的支持矩阵。 ## 目录布局 ``` docs/ design RFC, hardware model, behavioural spec, build + install guides, outcome src/octeon_flowtable/ the kernel module src/octeon_flowtable/tests/ regression suite + nft/topology rigs (see Testing) src/staging-patches/ the octeon_ethernet hook patch (adds the exported hooks) package/octeon-flowtable/ OpenWrt kmod package (init script + UCI config) prompts/ reproducible runbooks (build / deploy / EdgeOS→OpenWrt config migration) ``` ## 快速入门 1. 将 `src/staging-patches/120-octeon-flowtable-hooks.patch` 补丁应用到您的 OpenWrt octeon 内核（`target/linux/octeon/patches-6.18/`）并重新编译。 2. 编译模块：`cd src/octeon_flowtable && make octeon OWRT=/path/to/openwrt` （或在 menuconfig 中从 `package/` 选择 **kmod-octeon-flowtable**）。 3. 在 `/etc/config/firewall` 中启用硬件 offload： `option flow_offloading '1'` + `option flow_offloading_hw '1'`，然后执行 `fw4 reload`。 4. 验证：`conntrack -L | grep HW_OFFLOAD`。 从源码编译：[`docs/BUILDING.md`](docs/BUILDING.md)。安装、 启用与调优：[`docs/INSTALLING.md`](docs/INSTALLING.md)。可复现的操作手册： [`prompts/`](prompts/)。 ## 预编译镜像 不想自己编译工具链？打标签的发布版本会在 [Releases](../../releases) 页面提供可直接刷入的 EdgeRouter Lite 镜像，由 CI 直接从本仓库构建（GitHub Actions → [`build-image.yml`](.github/workflows/build-image.yml)）。 内核已包含暂存的钩子补丁和 offload 调优参数 (CVMSEG=2, `receive_group_order=1`)；`kmod-octeon-flowtable` 已预装。 目前发布了两个变体（资源文件名以 `lean-` / `router-` 为前缀）： - **lean** —— offload + `conntrack`/`tcpdump`；一个纯净的基础底座，方便您添加自己的包。 - **router** —— lean + LuCI Web UI + WireGuard，适合开箱即用的家用路由器。 构建版本已完全锁定（OpenWrt main @ `84f4f77`，kernel 6.18.34，锁定了 `packages`/`luci` feeds），因此特定标签可以逐字节复现 —— 参见 [`ci/`](ci/)。 发布新版本：推送一个 `v*` 标签（`git tag v0.1.0 && git push origin v0.1.0`）。 `workflow_dispatch` 可仅构建镜像而不发布（仅生成构建产物）。 ## 测试 [`src/octeon_flowtable/tests/regression.sh`](src/octeon_flowtable/tests/regression.sh) 是一个包含 14 项检查的回归测试套件，需从测试主机上针对 DUT 路由器运行 （约 8 分钟，退出码即失败次数）。它涵盖了 flowtable 的两种 VLAN 编码方式 （子接口隐式和具有显式 `VLAN_PUSH`/VLAN 不可知匹配的桥接 LAN 底层设备）， 双向的 TCP **和** UDP 线速测试，使用 kill-`-9` 结合陈旧条目驱逐进行流表复用，fw4 reload 风暴测试 （重复条目泄漏检查），孤儿 GC、链路抖动恢复以及空闲稳定状态。 其中一项检查值得推荐给所有 offload 驱动：它通过**驱动中 `tx_ok` 数据包计数器的差值来证明 fast-path 已生效**，而不是 通过吞吐量来推断 —— 因为在空闲的路由器上，软件路径也能达到 线速，这会悄无声息地将一次 offload 测试变成无效操作（no-op）。每次部署前以及 更改模块或 staging 补丁后都应运行此测试。 该套件的预检机制会自动修复其拓扑结构（一个 `wan` netns 端点和一个 带 tag 的客户端子接口）。其余的 `tests/*.nft` 文件和 `*-rig.sh` 脚本 是在进行 VLAN/QinQ/IPv6 调试期间使用的独立拓扑测试环境。 ## 状态与注意事项 已在 [ERLite-3](https://openwrt.org/toh/ubiquiti/edgerouter_lite) / CN5020 上针对 OpenWrt 的 kernel 6.18.34 进行了测试（相关设备的硬件规格、 串口控制台引脚分布以及原厂 OpenWrt 安装/恢复流程请参见该页面）。 CN50xx 是一款约 2008 年时代的 Octeon Plus 组件，早已停产；这个项目的存在 是因为它是廉价芯片上一个易于处理的硬件 fast-path 目标，而不是因为 这个世界还需要另一个路由器协议栈。硬件性能瓶颈（PIP 最多解析 2 个 VLAN 标签；flowtable 仅 offload TCP/UDP/GRE；v6 扩展 头部走 slow-path）已记录在 `docs/FUTURE-WORK.md` 中。VPN：传输态的 WireGuard/IPsec-NAT-T 已被 offload（因为是 UDP）；但 VPN *终结*属于加密问题， 是一个单独的挑战 —— 请参阅 `docs/COP2-CRYPTO-SCOPING.md`。 ## 许可证 GPL-2.0（本项目是一个 Linux 内核模块）。请参阅 [`LICENSE`](LICENSE)。

标签：NAT, nftables, OpenWrt, 内核模块, 安全资源, 客户端加密, 硬件加速, 网络性能优化, 网络路由