尧图网页设计 
前一阵我接到一个活儿要在 Windows 内核态里跑一个独立的 TCP/IP 协议栈最终给底层硬件提供网络能力。一开始我也想过直接用 Windows 自带的 WSK、TDI 这些内核网络接口但需求卡得比较死——协议栈行为要完全可控、可裁剪、可观测最好还能把收发路径上的每个包都抓到手里。翻来覆去之后我把目光落在了 lwIP 上。没错就是那个在 STM32、ESP32 上被用到烂的轻量级 TCP/IP 协议栈。问题在于它通常跑在裸机或者 RTOS 上而这次要把它塞进 Windows 内核用 NDIS 接网卡用 KeWaitForSingleObject 换掉它的信号量用 pbuf 和 NET_BUFFER 来回倒腾数据。整个过程踩了不少坑也把 lwIP 内部一些平时根本不会注意的细节看得明明白白。这篇文章就把整个移植思路、关键代码、适配层的实现和排查经验完整地写下来给同样想在内核态玩协议栈的人一个参考。1. 先想清楚内核协议栈方案的取舍1.1 什么场景真的需要“内核里的 TCP/IP”很多人看到这个标题的第一反应是Windows 内核里不是已经有 TCP/IP 协议栈了吗为什么还要自己造一个轮子这个问题的答案取决于你的场景。确实如果你只是想让内核驱动发一个 HTTP 请求出去直接用 WSK 的 socket 接口就能搞定微软帮你封装好了。但如果你的需求是下面这几种系统自带协议栈反而会成为阻碍需要接管某个物理网卡的全部流量在内核态做协议级加工后再转发出去而不是走系统协议栈的路径需要点对点的链路通信网络拓扑里根本没有传统意义上的“IP 路由”系统协议栈帮不上忙需要在没有完整 TCP/IP 协议族支持的环境里做一个极简的、行为完全可控的传输通道纯粹是想把协议栈的每一行源码都读透、改得动这在系统自带的网络组件里是不现实的。我当时的需求更接近第三种底层是一块自研硬件通过 NDIS 暴露成一个虚拟网卡形态上层业务希望直接用 TCP 和远端服务通信。走系统协议栈意味着要处理 DHCP、路由表、防火墙、多播等一系列我不关心的逻辑还会引入系统网络栈的复杂依赖。自己移植一个 lwIP等于把网络链路完全握在自己手里收包、发包、重传、拥塞控制全部可见可控。1.2 为什么选 lwIP而不是硬啃 WSK在动手之前我把几个备选方案列出来对比过纠结了很长一段时间。WSKWinSock Kernel是微软专门提供给内核驱动使用的 socket 接口理论上最正统也最稳定。但问题有三第一WSK 只暴露了 socket 语义底层协议栈行为你是改不了的第二WSK 的注册、绑定、事件回调写起来并不比移植 lwIP 简单多少而且调试手段有限第三WSK 的文档和示例代码偏少遇到诡异问题时基本只能靠猜。lwIP 就不一样。它是 BSD 许可的开源协议栈代码量适中模块划分清晰而且有着极其广泛的嵌入式移植经验可供参考。最关键的是lwIP 的移植面被设计得非常明确——只要把sys_arch、netif、lwipopts.h这几个层面对接好剩下的协议核心可以完全不动。这就像一个抽屉式结构你只需要替换掉最外层的抽屉里面所有齿轮都能照常运转。我还考虑过一个方案拿市面上现成的商用协议栈。性能确实强但授权费和维护成本对个人项目来说不太友好而且源码封闭出了问题连定位都难。1.3 整体架构的雏形先给出移植完成后的大致结构后面几节的细节都会落到这个框架上驱动类型NDIS 过滤驱动Filter Driver绑定一块物理以太网网卡宿主环境Windows 10/11 x64 内核态开发用 Visual Studio WDK 工程协议栈lwIP 2.2.0 stable裁剪掉 socket 层和 netconn 层中不需要的部分只用 raw/API 和 netif/API线程模型协议栈核心跑在tcpip_thread上再加一个专用的接收 worker 线程做数据搬运数据通路物理网卡收到包 → NDIS 回调 → 接收 worker 线程 → 构造成pbuf→tcpip_input()→ lwIP 协议处理 → 业务层读取发送则反过来业务层调用 lwIP 发送 →netif-linkoutput→ 组装NET_BUFFER_LIST→NdisFSendNetBufferLists下发。这个结构最舒服的地方在于协议栈核心和 NDIS 驱动器是解耦的。你甚至可以先用一个虚拟的收包源调试 lwIP等协议栈跑通了再接入真实网卡。我在开发时就是先用构造好的以太网帧喂给协议栈确认 TCP 握手能完成再回头写 NDIS 数据通路。2. lwIP 源码与编译环境准备2.1 版本选择我用的 STABLE-2_2_0lwIP 的源码仓库在 Savannah 和 GitHub 上都有镜像很多人图省事直接拉 master这是个大坑。master 分支经常有一些还没稳定下来的接口调整比如sys_mbox的函数签名、tcpip_input()的调用约定都可能跟网上旧教程对不上。我当时就吃过这个亏照着网上一份 1.4.1 的移植教程写代码编译报错一堆后来才发现接口早就变了。建议直接拉正式 release 标签我用的是STABLE-2_2_0_release。为什么不用更老的 1.4.x因为老版本代码结构相对混乱内存管理也不如 2.x 灵活。为什么不用最新的 2.3.0 开发分支稳定性存疑资料也少。2.2.x 是一个经过大量产品验证的稳定版本ST 官方的 CubeMX 在很长一段时间里集成的也是这个系列网上能查到的资料和问答最多遇到问题基本都能搜到答案。lwIP 源码的目录结构很简单我们需要关心的只有三块src/core/协议栈核心包括 TCP、UDP、IP、ARP、ICMP、内存管理src/netif/网络接口层重点看ethernet.c它提供ethernet_input()和ethernet_output()src/arch/这是留给移植者的空壳sys_arch.h、sys_arch.c、cc.h、perf.h都在这里补全。业务层如果用netconnAPI还要包含src/api/目录如果用不上可以直接在工程里排除掉省一点编译时间和代码体积。2.2 内核驱动工程怎么组织 lwIP 源码Windows 内核驱动我自己习惯用 Visual Studio 的 WDK 工程模板来建这样链接、签名、INF 文件都能自动处理好。建一个空的“Kernel Mode Driver, Empty”工程然后把 lwIP 相关源文件按目录加入工程核心源文件不区分目录全部加入编译arch/下新建sys_arch.c、cc.h、sys_arch.h实际的网卡接入代码单独放一个ndis_bridge.c它负责实现 NDIS 过滤驱动回调以及把 lwIP 的netif和 NDIS 的收发路径对接起来。需要注意的是lwIP 源码中大量使用了time.h里的一些宏定义比如LWIP_PLATFORM_DIAG、LWIP_PLATFORM_ASSERT这些必须在cc.h里面提前定义好否则编译到某个陌生文件时突然报错很难查。以下是我cc.h里的核心内容可以直接抄#ifndef __CC_H__ #define __CC_H__ #include wdm.h #include ntddk.h typedef unsigned char u8_t; typedef signed char s8_t; typedef unsigned short u16_t; typedef signed short s16_t; typedef unsigned int u32_t; typedef signed int s32_t; #define LWIP_PLATFORM_ASSERT(x) \ do { \ KdPrint((lwip assert: %s at %s:%d\n, x, __FILE__, __LINE__)); \ ASSERTMSG(x, FALSE); \ } while(0) #define LWIP_PLATFORM_DIAG(x) KdPrint x #endif注意内核态绝对不能包含用户态的string.h、stdlib.h那套memcpy、memset这些可以用RtlCopyMemory、RtlZeroMemory代替或者在cc.h里做一层宏映射。2.3 lwipopts.h 裁剪内核态不是裸机也不是 LinuxlwIP 默认的配置文件在src/include/lwip/opt.h它给所有配置项都提供了默认值。但实际移植时必须自己写一个lwipopts.h把项目特定的配置覆盖过去。对于 Windows 内核环境有几点必须调整关闭LWIP_SOCKET和LWIP_NETCONN的依赖。内核态没有 POSIX socket 语义我们直接用 lwIP 的 raw API 是最合适的。如果能关掉LWIP_NETCONN那 netconn 层相关的线程模型和等待机制就不会被编译进来省掉一大块代码。不过要注意如果我后面想用tcpip_input()这种 tcpip 线程投递机制就必须要保留LWIP_TCPIP_CORE_LOCKING的相关配置具体见下一个小节。内存配置是非常关键的部分。MEM_SIZE决定mem_malloc管理的内存池总大小MEMP_NUM_TCP_SEG决定 TCP 报文段控制块数量PBUF_POOL_SIZE决定PBUF_POOL类型 pbuf 的数量。内核态环境不存在裸机那种内存紧张的问题但也不建议给得太大因为每一个 pbuf 都要在非分页池里分配。我给你的建议是先用一个中等规模的值跑通流程比如#define MEM_SIZE (64 * 1024) #define MEMP_NUM_TCP_SEG 128 #define PBUF_POOL_SIZE 64 #define TCP_MSS 1460 #define TCP_WND (4 * TCP_MSS) #define TCP_SND_BUF (4 * TCP_MSS)这些参数在开发初期不要一上来就追求大数值否则一旦内存池溢出排查起来会很难受。后面的调优章节我会专门讲怎么根据实际流量放大。还有一个坑是NO_SYS。如果NO_SYS为 1lwIP 认为没有操作系统要求你提供锁和邮箱的原语但不需要线程。我们在 Windows 内核里显然不是裸机环境所以NO_SYS必须设为 0让 lwIP 运行在 tcpip 线程模型中。2.4 关键参数参考表为了方便对照我把这次移植最常用的配置项整理成了一张表配置项推荐值说明NO_SYS0有操作系统使用线程模型LWIP_NETCONN1netconn API 用于业务层调用LWIP_SOCKET0内核态不需要 socket 层LWIP_TCPIP_CORE_LOCKING1tcpip 线程和各 API 线程共享核心锁MEM_SIZE64KB~256KBmem_malloc 管理的内存池PBUF_POOL_SIZE64~256收包 pbuf 池数量决定抗突发能力MEMP_NUM_TCP_SEG128~512TCP 分段数量影响吞吐TCP_MSS1460标准以太网 MSSTCP_WND4*TCP_MSS默认接收窗口可按需放大TCP_SND_BUF4*TCP_MSS默认发送缓冲LWIP_STATS1开启统计调试时很有用LWIP_DEBUG1开发期开 debug发布关掉这张表不是标准答案而是“开发初期能稳定跑起来”的底线。实际调优时重点看LWIP_STATS输出的lwip_stats.mem.err和lwip_stats.memp.err是否在增长再反过来调大对应池子。3. sys_arch 适配把 lwIP 落到 Windows 内核线程模型上3.1 线程抽象PsCreateSystemThread 的正确用法lwIP 在NO_SYS0的模型下会通过sys_thread_new()创建协议栈线程。最典型的场景是tcpip_init()里创建tcpip_thread它负责转发所有协议栈事件是 lwIP 消息驱动的核心循环。在 Windows 内核里创建线程用PsCreateSystemThread是最直接的方式static sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg, int stacksize, int prio) { HANDLE hThread NULL; NTSTATUS status; status PsCreateSystemThread(hThread, THREAD_ALL_ACCESS, NULL, NULL, NULL, (PKSTART_ROUTINE)thread, arg); if (!NT_SUCCESS(status)) { return NULL; } // 注意这里不能直接把 HANDLE 当作 sys_thread_t 返回 // 因为销毁线程时 ZwClose 之后句柄就失效了所以要先引用对象 return (sys_thread_t)hThread; }这段代码里有几个容易踩坑的地方。第一PsCreateSystemThread要求传入的线程函数原型是VOID (*)(PVOID)而 lwIP 的线程函数是void (*)(void *)两者调用约定一致直接强转即可。第二线程创建后如果业务层需要等待它退出最好保留线程对象引用否则纯粹用 HANDLE 管理在线程自杀的场景下可能产生竞态。第三优先级prio建议直接传一个较高的实时优先级或者用tp-Priority HIGH_PRIORITY单独设置。协议栈线程一旦被饿死整个网络链路就直接卡死了。我开发初期犯过一个错误没给tcpip_thread足够的栈空间。PsCreateSystemThread的stacksize为 0 时使用默认系统栈大小而 lwIP 默认的线程栈要求是TCPIP_THREAD_STACKSIZE默认 0 的话 sys_arch 负责给。内核线程栈太小一旦协议栈处理了较大报文很容易触发栈溢出检查表现为莫名其妙的蓝屏。建议一开始就给足 16KB 以上。3.2 信号量、互斥锁与邮箱的映射这是整个移植最核心的部分。lwIP 对底层同步原语的要求有互斥锁sys_mutex、信号量sys_sem、邮箱sys_mbox。把这三种原语翻译成 Windows 内核对象规则很清楚sys_mutex→KMUTEX用KeInitializeMutex、KeWaitForSingleObject、KeReleaseMutexsys_sem→KSEMAPHORE用KeInitializeSemaphore、KeWaitForSingleObject、KeReleaseSemaphoresys_mbox→ 没有现成对应物通常用一个“互斥锁 令牌信号量”的环形消息队列来模拟。信号量是最简单的核心代码如下static err_t sys_sem_new(sys_sem_t *sem, u8_t count) { KeInitializeSemaphore(sem, count, MAX_SEM_COUNT); return ERR_OK; } static void sys_sem_signal(sys_sem_t *sem) { KeReleaseSemaphore(sem, IO_NO_INCREMENT, 1, FALSE); } static u32_t sys_sem_wait_timeout(sys_sem_t *sem, u32_t timeout_ms) { LARGE_INTEGER timeout; NTSTATUS status; if (timeout_ms 0) { KE_WAIT_INFORMATION waitInfo; status KeWaitForSingleObject(sem, Executive, KernelMode, FALSE, NULL); } else { timeout.QuadPart -(LONGLONG)timeout_ms * 10000; // 毫秒转100ns status KeWaitForSingleObject(sem, Executive, KernelMode, FALSE, timeout); } return (status STATUS_SUCCESS) ? SYS_ARCH_TIMEOUT : SYS_ARCH_WAIT_OK; }这里有一个需要注意的语义问题。lwIP 的信号量等待函数sys_arch_sem_wait返回 0 表示信号量可用即SYS_ARCH_WAIT_OK返回非 0 表示等待了多长时间或者超时。不同版本的 lwIP 对这个返回值的约定不完全一样2.x 统一为“等待的毫秒数”超时用SYS_ARCH_TIMEOUT表示。你得看当前源码里sys.h里的宏定义别想当然地照抄别的版本。邮箱的实现要稍微多想一下。sys_mbox需要支持sys_mbox_new创建邮箱sys_mbox_trypost往邮箱里放一条消息非阻塞满则返回ERR_MEMsys_mbox_fetch阻塞取一条消息sys_mbox_tryfetch非阻塞取一条消息。最经典的实现是用数组做环形队列加一把互斥锁保护队列再配两个信号量分别记录“队列中有数据”和“队列中有空位”。核心代码如下typedef struct sys_mbox_s { void **msgs; int size, head, tail, count; KMUTEX lock; KSEMAPHORE notEmpty; // 有数据 KSEMAPHORE notFull; // 有空间 } sys_mbox_s;trypost时获取notFull信号量如果超时立刻返回ERR_MEM拿到空位后加锁、写队列、解锁然后释放notEmpty。fetch则反过来。这个模式跟我在 RTOS 上写过的一模一样区别只是把互斥信号量换成了KMUTEX把等待函数换成了KeWaitForSingleObject。有一个细节是sys_mbox_new在 2.0 以上版本要求传入size参数表示队列容量而且sys_mbox这个类型在 Windows 上最好定义成指针类型否则 32/64 位切换会出问题。3.3 时间基准不要用 KeQueryTickCountlwIP 内部有大量的超时判定逻辑靠的是sys_now()返回当前时间单位毫秒。在裸机上要么用一个全局计数器要么读硬件定时器在 Windows 内核里很多人第一反应是KeQueryTickCount但这个 API 有个坑它的频率是系统时钟节拍默认可能是 100Hz 或 1000Hz而且精度不稳定。你用KeQueryTickCount换算出来的时间误差可能高达几十毫秒。这对 TCP 重传定时器来说是致命的。我推荐用KeQueryInterruptTime它返回一个 100ns 精度的单调递增时间不受系统时间调整影响适合做超时计算static u32_t sys_now(void) { ULONGLONG interruptTime KeQueryInterruptTime(); // 100ns units return (u32_t)(interruptTime / 10000); // 转成毫秒 }注意KeQueryInterruptTime返回的是ULONGLONG取低 32 位当毫秒数用在系统连续运行 49 天左右会回绕。lwIP 内部很多超时比较已经考虑了回绕问题但如果你在业务层自己写时间差逻辑要记得用有符号减法来做差而不是直接比较绝对值大小。3.4 sys_arch_protect 与临界区lwIP 有一个比较古老的临界区保护接口sys_arch_protect和sys_arch_unprotect。在裸机移植中它通常用来关中断在 Windows 内核中当然不能真的关中断否则系统直接就卡死了。合理的做法是返回一个sys_prot_t类型的标志并且内部用高速自旋锁保护核心临界区。不过 2.x 版本的 lwIP 在主流的LWIP_TCPIP_CORE_LOCKING模型下对这个接口的依赖已经大幅减少。我建议直接把sys_arch_protect实现成static sys_prot_t sys_arch_protect(void) { // 单核可以用 KeRaiseIrql 到 DISPATCH_LEVEL 保底 // 多核环境建议配合自旋锁使用 KIRQL oldIrql; KeRaiseIrql(DISPATCH_LEVEL, oldIrql); return (sys_prot_t)oldIrql; } static void sys_arch_unprotect(sys_prot_t oldIrql) { KeLowerIrql((KIRQL)oldIrql); }这个方案能保证临界区里不会发生线程切换适合保护多生产者/多消费者共享的少量数据。但不要在临界区里做耗时操作毕竟它是直接抬 IRQL相当于把整个 CPU 钉住了。4. NDIS 网卡接入让 lwIP 真正“通路”4.1 用 NDIS 过滤驱动绑定物理网卡lwIP 作为一个协议栈最终要挂到一个netif上而这个netif必须对应一个真实的收发通道。在 Windows 里最合理的方式是写一个 NDIS 过滤驱动Filter Driver绑定到一块物理以太网网卡上然后由这个驱动把网卡收到的报文转交给 lwIP。为什么选过滤驱动而不是中间层驱动NDIS 中间层驱动IM的架构比较复杂需要实现一组虚拟小端口和协议驱动而且微软后来更推荐用过滤驱动完成类似工作。过滤驱动的入口逻辑简单只需要注册一个NET_BUFFER_LIST接收回调和一个发送回调。具体来说过滤驱动初始化时调用NdisFRegisterFilterDriver并在配置里声明FilterClass为ms_switch或自定义类用INF文件配置绑定关系。绑定完网卡之后你会得到一个NDIS_HANDLE过滤器句柄。收发路径上的NET_BUFFER_LIST通过回调函数进入你的代码。这里要记住一个铁律NDIS 的接收回调运行在DISPATCH_LEVEL在回调里不能调用任何可能阻塞的函数也不能直接调用 lwIP 里需要睡眠等待的函数。后面我会专门讲怎么处理这个 IRQL 问题。4.2 收包路径从 NBL 到 pbuf接收回调在FilterReceiveNetBufferLists里被触发参数是NET_BUFFER_LISTNBL。一个 NBL 可能包含多个NET_BUFFERNB每个 NB 对应一个包。我的处理方式分两步第一步在DISPATCH_LEVEL下把 NBL 挂到一个自旋锁保护的内核队列里然后释放 NBL 的所有权继续向上传递或者按需求自己保留。这一步不拷贝数据只搬移指针开销极小。第二步唤醒一个专门的接收 worker 线程。这个线程运行在PASSIVE_LEVEL从队列里取出 NBL逐个 NB 读取数据把报文内容拷贝到 lwIP 的 pbuf 里然后调用tcpip_input()。为什么不在回调里直接构造 pbuf因为 pbuf 池的分配和释放可能会触发内存管理操作内存管理要求 IRQL 不高于DISPATCH_LEVEL但万一内存池耗尽lwIP 内部的处理路径里有可能出现等待或调度这在DISPATCH_LEVEL下是绝对禁止的。所以标准做法就是排队 异步处理。这个设计我也见很多 NDIS 驱动用过属于必经之路。读取 NB 数据时我习惯用NdisGetDataBufferUCHAR *data NdisGetDataBuffer(NB, dataLength, stackBuf, // 避免分配的一块固定栈空间 1, // 对齐 0);如果NdisGetDataBuffer返回非空说明数据在内存中是连续的可以直接用。如果返回空说明数据分散在多个 MDL 里需要自己遍历NET_BUFFER_CURRENT_MDL把数据拼起来。考虑到我们要构造 pbuf其实没必要拼到连续缓冲区可以直接为每一段 MDL 分配一个 pbuf 并链成 pbuf 链。但开发初期为了降低复杂度我是先在栈缓冲区里拼好再一次性拷进 pbuf。pbuf 的构造要注意头部预留问题。物理网卡收到的报文带以太网头14 字节lwIP 的ethernet_input()会解析以太网头并交给对应的上层协议。因此构造 pbuf 时要用PBUF_RAW类型并把整帧数据原封不动地塞进去struct pbuf *p pbuf_alloc(PBUF_RAW, totalLength, PBUF_POOL); if (p) { pbuf_take(p, data, totalLength); netif-input(p, netif); // 这里实际是通过 tcpip_input 投递 }调用tcpip_input(p, netif)之后pbuf 的所有权就转移给 lwIP 了协议栈会负责释放。千万不要在投递后再碰这个 pbuf否则就是 double free。4.3 发包路径从 pbuf 到 NBL发送路径相对简单。lwIP 最终会回调你注册的netif-linkoutput这个函数接收一个 pbuf 指针里面是完整的以太网帧。你的任务就是把它送进 NDIS 发送通道。实现逻辑分几步根据网卡 MTU 和 pbuf 总长度计算需要分配的NET_BUFFER_LIST数量从NdisAllocateNetBufferList和NdisAllocateNetBuffer分配内存锁好非分页内存遍历 pbuf 链把每一段的地址和长度填入 NB 的 MDL调用NdisFSendNetBufferLists下发交给底层的协议栈绑定。这里最重要的一个坑是NdisFSendNetBufferLists是异步的调用之后你的NET_BUFFER_LIST所有权马上转移给 NDIS 了底层网卡发送完成后会通过FilterSendNetBufferListsComplete回调返还给你。所以你不能在linkoutput里用完 NBL 就释放必须在完成回调里释放。如果你把 lwIP 的 pbuf 数据直接放进 NBL 里那底层的完成回调必须负责把 pbuf 释放掉否则就是内存泄漏。更稳妥的方案是在linkoutput里分配 NBL 时把 pbuf 指针作为上下文context保存进去在FilterSendNetBufferListsComplete里取出 pbuf调用pbuf_free再释放 NBL。这样 pbuf 何时归还给 lwIP 的内存池完全由发送完成事件驱动是最安全的生命周期管理方案。4.4 IRQL 与异步投递问题新手移植 lwIP 到 Windows 内核时最容易出的问题就是 IRQL。NDIS 接收回调在DISPATCH_LEVEL而 lwIP 的tcpip_input()内部会往tcpip_mbox里投递消息。我之前说过sys_mbox_trypost在这个调用链里是非阻塞的理论上在DISPATCH_LEVEL调用不算越界。但是tcpip_input()在投递消息之前还会做timeouts遍历、pkt 队列操作等一系列事情这些操作里涉及的内存访问和锁行为在高 IRQL 下是存在风险的。最保险的是用 worker 线程搬运接收回调里只做队列入队和事件通知真正调用tcpip_input()的代码永远跑在PASSIVE_LEVEL的线程里。这也是我最终采用的方案。我见过一种偷懒的写法直接在DISPATCH_LEVEL里转发tcpip_input()测试时可能也能跑但一旦开启Driver Verifier或者系统负载高了蓝屏就会找上门来。IT 行业有个原则能在 IRQL 上规避的问题不要靠运气。工作项IoQueueWorkItem也是一种选择但它依然跑在系统 worker 线程上下文里而且执行时机受系统调度影响。自建专用 worker 线程更可控尤其是消息量大时还可以做批量出队、批量投递的收包合并优化。5. 调试、性能与常见故障排查5.1 新手最容易踩的 4 个坑移植过程中我遇到的故障基本都集中在这四类。第一类是编译层面的cc.h里没有正确定义整数类型导致 pbuf 的 offset 字段被编译器按 4 字节对齐而不是按 2 字节对齐最终在协议头解析时出现错位。这个问题非常隐蔽表现是收包后先能看到 IP 头但 TCP 端口全部乱掉。解决办法很简单p 结构体最典型的是struct ip_hdr里有u16_t类型的字段如果u16_t被错误定义成 4 字节类型整个报头就读错了。所以cc.h里的整数类型定义必须跟编译器实际对齐严格匹配这一点上直接抄 lwIP 官方移植模板最稳妥。第二类是内核内存分配问题。lwIP 的mem_malloc内部从一个大数组里分配这个数组如果按LWIP_RAM_HEAP_POINTER定义在某个段里可能会被链接进一个不具备硬件缓存一致性的内存区域。更常见的问题是在 Windows 内核里你给MEM_SIZE开得太大比如 8MB然后在DriverEntry阶段一次性初始化结果非分页池不足导致ZwAllocateVirtualMemory失败。内核态内存不是用户态虚拟内存不要贪心先用小值验证功能。第三类是线程饿死问题。lwIP 的tcpip_thread如果没有及时处理消息接收 worker 线程可能因为信号量等待堆积而把所有内核线程资源耗尽。表现是系统卡顿、网卡 watchdog 超时。这个要通过调高tcpip_thread的优先级来解决还要在 worker 线程里做简单的流量控制。第四类是最典型的“以太网头处理”问题。我调试 ARP 时遇到一种非常奇怪的现象TCP 连接能建立但 ping 不通。后来发现是netif_add时没有正确设置hwaddr_len 6导致 ARP 报文里的 MAC 地址长度字段错误对端直接丢弃。这类问题全靠对比抓包才能定位建议开发期间在测试机上装好抓包工具或者在 lwIP 里用LWIP_DEBUG打开ETHARP_DEBUG级别的日志。5.2 IRQL 引发的神秘蓝屏“神秘蓝屏”是内核开发的家常便饭而在移植 lwIP 时最常见的蓝屏就是这个附一张经典蓝色背景图的画面感在ip4_input里访问某个 pbuf 的 payload 指针时系统直接报IRQL_NOT_LESS_OR_EQUAL。原因通常是在DISPATCH_LEVEL上调用了 pbuf 内存的分配或释放。pfn 之类的非分页池内存在DISPATCH_LEVEL下是可以访问的但是 lwIP 的内存池管理里可能有自旋锁保护。如果 pbuf 池在释放时发生内存驻留页面的换页操作就会触发 IRQL 冲突。内存管理在 Windows 内部要满足所谓的PASSIVE_LEVEL要求只要涉及分页内存比如EX_NONPAGED_POOL之外的普通池IRQL 稍高就会蓝屏。我从一开始就坚持“接收回调不碰 lwIPworker 线程碰 lwIP”的这个原则整个调试周期里没有因为在 IRQL 问题上反复蓝屏过。这比我第一次写 NDIS 驱动时凭感觉乱调 API 要省心得多。5.3 内存池与性能调优lwIP 跑通之后接下来就是压力测试。用打流工具或一个简单的 TCP 回环程序把数据量慢慢加上去。一开始用lwip_stats观察内存池使用情况if (lwip_stats.memp[MEMP_TCP_SEG].err) { KdPrint((TCP_SEG exhausted\n)); } if (lwip_stats.mem.err) { KdPrint((mem pool exhausted\n)); }压测中我发现MEM_SIZE64KB 很快就会被打满内存池报 err 后TCP 发送窗口收缩到很小吞吐量大幅下降。后来我把MEM_SIZE调到 256KBMEMP_NUM_TCP_SEG调到 512效果立竿见影。原因在于 TCP 发送缓冲和接收窗口都与MEMP_NUM_TCP_SEG直接挂钩每个 TCP 段都要占用一个tcp_seg结构。如果你的业务是大量小包高频交互那么这个数值要更大。另一个优化点是PBUF_POOL的数量。我最初设为 64当接收队列在短时间内堆积多个包时会发现大量丢包ip4_input因为 pbuf 不够直接丢弃。收包场景下PBUF_POOL数量至少要能覆盖TCP_WND/MSS 一定余量。一个简单的经验值是收包路径的突发队列深度 × 2。发送性能方面一个大坑是每发一个包就分配一个 NBL然后在完成回调里释放 NBL 和 pbuf。这个分配释放频率在高吞吐下是很夸张的容易造成 CPU 使用率偏高。优化方向是预分配 NBL 池或者在linkoutput里尽量复用已有 NBL。不过这个优化会引入更复杂的所有权管理我的建议是先跑通再改。5.4 用 WinDbg 排查失败现场内核驱动的调试手段和用户态完全不一样。我几乎是靠 WinDbg 双机调试活下来的。配置好内核调试之后有几种特别有用的操作!analyze -v蓝屏后第一时间查看 bugcheck 原因!locks查看是否有自旋锁死锁!poolused查看各种池的用量判断内存池是否耗尽!ndiskd系列命令直接检查 NDIS 过滤器状态和队列深度!stacks查看所有内核线程的调用栈尤其看tcpip_thread和接收 worker 线程是否卡在等待上。有一次我为了排查丢包问题直接在ip4_input入口处打了个条件断点然后查看 pbuf 的len和payload的原始字节。通过对比抓包很快发现是网卡驱动在接收时把 VLAN 标签残留在了以太网头的附加字段里导致 lwIP 解析 IP 头时 offffset 偏移了一位。这种问题如果不开调试器基本只能靠猜。5.5 常见问题速查表现象大概率原因排查思路编译报错找不到 time.h 等头文件cc.h 未配置或者包含了用户态头文件检查所有头文件包含路径屏蔽非内核头文件TCP 连接建立不了ARP 也不通netif 的 hwaddr_len 没有设置MAC 地址错误打 ETHARP_DEBUG核对 netif-hwaddr 内容能 ping 通TCP 丢包严重PBUF_POOL_SIZE 太小收包 worker 处理不过来查看 lwip_stats.memp[MEMP_PBUF_POOL].err高负载下蓝屏 IRQL_NOT_LESS_OR_EQUAL在 DISPATCH_LEVEL 调用了 lwIP 的阻塞函数或分页内存操作排查所有 NDIS 回调禁止直接调用 lwIP系统卡顿网卡无响应tcpip_thread 优先级太低被其他线程饿死调高线程优先级检查线程栈大小发送后对端收不到驱动无报错NBL 所有权理解错误可能提前释放了数据缓冲在 FilterSendNetBufferListsComplete 里统一释放 NBL 和 pbuf6. 写在最后这件事到底值不值得做现在回顾这个项目我的答案是非常值但前提是你清楚自己要去哪儿。如果你只是想要一个能发 TCP 包的内核模块直接用 WSK 可能五分之一的时间就够了。但如果你想要的是对协议栈的完整掌控权想把 TCP 重传、拥塞窗口、缓冲区行为都摸清楚那移植 lwIP 几乎是成本最低的路线。整个过程中让我最意外的其实是 lwIP 内部的“操作系统无关性”。它在设计上把自己的活动范围收敛得非常干净对外只依赖一个sys_arch层对内则靠进程模型和消息循环驱动一切。这种工程抽象能力比它本身的 TCP 实现更值得学习。我在 Windows 内核里写sys_arch时反复体会到一句话好的移植不是熬出来的而是清晰架构撑出来的。最后再分享一个小技巧如果你打算做类似的事情强烈建议第一步不是写代码而是先在用户态搭一个 lwIP 的模拟环境用回环驱动或者直接调netif的收包接口喂包把协议栈行为全部调通再沉到内核态。我因为跳过这一步多花了至少一周时间在内核调试器里看tcpip_thread的调用栈。内核态一旦出错排查成本是用户态的十倍。先易后难稳扎稳打这套移植路径才会走得顺畅。 Windows内核态移植lwIP：基于NDIS的协议栈适配与调试实践
前一阵我接到一个活儿要在 Windows 内核态里跑一个独立的 TCP/IP 协议栈最终给底层硬件提供网络能力。一开始我也想过直接用 Windows 自带的 WSK、TDI 这些内核网络接口但需求卡得比较死——协议栈行为要完全可控、可裁剪、可观测最好还能把收发路径上的每个包都抓到手里。翻来覆去之后我把目光落在了 lwIP 上。没错就是那个在 STM32、ESP32 上被用到烂的轻量级 TCP/IP 协议栈。问题在于它通常跑在裸机或者 RTOS 上而这次要把它塞进 Windows 内核用 NDIS 接网卡用 KeWaitForSingleObject 换掉它的信号量用 pbuf 和 NET_BUFFER 来回倒腾数据。整个过程踩了不少坑也把 lwIP 内部一些平时根本不会注意的细节看得明明白白。这篇文章就把整个移植思路、关键代码、适配层的实现和排查经验完整地写下来给同样想在内核态玩协议栈的人一个参考。1. 先想清楚内核协议栈方案的取舍1.1 什么场景真的需要“内核里的 TCP/IP”很多人看到这个标题的第一反应是Windows 内核里不是已经有 TCP/IP 协议栈了吗为什么还要自己造一个轮子这个问题的答案取决于你的场景。确实如果你只是想让内核驱动发一个 HTTP 请求出去直接用 WSK 的 socket 接口就能搞定微软帮你封装好了。但如果你的需求是下面这几种系统自带协议栈反而会成为阻碍需要接管某个物理网卡的全部流量在内核态做协议级加工后再转发出去而不是走系统协议栈的路径需要点对点的链路通信网络拓扑里根本没有传统意义上的“IP 路由”系统协议栈帮不上忙需要在没有完整 TCP/IP 协议族支持的环境里做一个极简的、行为完全可控的传输通道纯粹是想把协议栈的每一行源码都读透、改得动这在系统自带的网络组件里是不现实的。我当时的需求更接近第三种底层是一块自研硬件通过 NDIS 暴露成一个虚拟网卡形态上层业务希望直接用 TCP 和远端服务通信。走系统协议栈意味着要处理 DHCP、路由表、防火墙、多播等一系列我不关心的逻辑还会引入系统网络栈的复杂依赖。自己移植一个 lwIP等于把网络链路完全握在自己手里收包、发包、重传、拥塞控制全部可见可控。1.2 为什么选 lwIP而不是硬啃 WSK在动手之前我把几个备选方案列出来对比过纠结了很长一段时间。WSKWinSock Kernel是微软专门提供给内核驱动使用的 socket 接口理论上最正统也最稳定。但问题有三第一WSK 只暴露了 socket 语义底层协议栈行为你是改不了的第二WSK 的注册、绑定、事件回调写起来并不比移植 lwIP 简单多少而且调试手段有限第三WSK 的文档和示例代码偏少遇到诡异问题时基本只能靠猜。lwIP 就不一样。它是 BSD 许可的开源协议栈代码量适中模块划分清晰而且有着极其广泛的嵌入式移植经验可供参考。最关键的是lwIP 的移植面被设计得非常明确——只要把sys_arch、netif、lwipopts.h这几个层面对接好剩下的协议核心可以完全不动。这就像一个抽屉式结构你只需要替换掉最外层的抽屉里面所有齿轮都能照常运转。我还考虑过一个方案拿市面上现成的商用协议栈。性能确实强但授权费和维护成本对个人项目来说不太友好而且源码封闭出了问题连定位都难。1.3 整体架构的雏形先给出移植完成后的大致结构后面几节的细节都会落到这个框架上驱动类型NDIS 过滤驱动Filter Driver绑定一块物理以太网网卡宿主环境Windows 10/11 x64 内核态开发用 Visual Studio WDK 工程协议栈lwIP 2.2.0 stable裁剪掉 socket 层和 netconn 层中不需要的部分只用 raw/API 和 netif/API线程模型协议栈核心跑在tcpip_thread上再加一个专用的接收 worker 线程做数据搬运数据通路物理网卡收到包 → NDIS 回调 → 接收 worker 线程 → 构造成pbuf→tcpip_input()→ lwIP 协议处理 → 业务层读取发送则反过来业务层调用 lwIP 发送 →netif-linkoutput→ 组装NET_BUFFER_LIST→NdisFSendNetBufferLists下发。这个结构最舒服的地方在于协议栈核心和 NDIS 驱动器是解耦的。你甚至可以先用一个虚拟的收包源调试 lwIP等协议栈跑通了再接入真实网卡。我在开发时就是先用构造好的以太网帧喂给协议栈确认 TCP 握手能完成再回头写 NDIS 数据通路。2. lwIP 源码与编译环境准备2.1 版本选择我用的 STABLE-2_2_0lwIP 的源码仓库在 Savannah 和 GitHub 上都有镜像很多人图省事直接拉 master这是个大坑。master 分支经常有一些还没稳定下来的接口调整比如sys_mbox的函数签名、tcpip_input()的调用约定都可能跟网上旧教程对不上。我当时就吃过这个亏照着网上一份 1.4.1 的移植教程写代码编译报错一堆后来才发现接口早就变了。建议直接拉正式 release 标签我用的是STABLE-2_2_0_release。为什么不用更老的 1.4.x因为老版本代码结构相对混乱内存管理也不如 2.x 灵活。为什么不用最新的 2.3.0 开发分支稳定性存疑资料也少。2.2.x 是一个经过大量产品验证的稳定版本ST 官方的 CubeMX 在很长一段时间里集成的也是这个系列网上能查到的资料和问答最多遇到问题基本都能搜到答案。lwIP 源码的目录结构很简单我们需要关心的只有三块src/core/协议栈核心包括 TCP、UDP、IP、ARP、ICMP、内存管理src/netif/网络接口层重点看ethernet.c它提供ethernet_input()和ethernet_output()src/arch/这是留给移植者的空壳sys_arch.h、sys_arch.c、cc.h、perf.h都在这里补全。业务层如果用netconnAPI还要包含src/api/目录如果用不上可以直接在工程里排除掉省一点编译时间和代码体积。2.2 内核驱动工程怎么组织 lwIP 源码Windows 内核驱动我自己习惯用 Visual Studio 的 WDK 工程模板来建这样链接、签名、INF 文件都能自动处理好。建一个空的“Kernel Mode Driver, Empty”工程然后把 lwIP 相关源文件按目录加入工程核心源文件不区分目录全部加入编译arch/下新建sys_arch.c、cc.h、sys_arch.h实际的网卡接入代码单独放一个ndis_bridge.c它负责实现 NDIS 过滤驱动回调以及把 lwIP 的netif和 NDIS 的收发路径对接起来。需要注意的是lwIP 源码中大量使用了time.h里的一些宏定义比如LWIP_PLATFORM_DIAG、LWIP_PLATFORM_ASSERT这些必须在cc.h里面提前定义好否则编译到某个陌生文件时突然报错很难查。以下是我cc.h里的核心内容可以直接抄#ifndef __CC_H__ #define __CC_H__ #include wdm.h #include ntddk.h typedef unsigned char u8_t; typedef signed char s8_t; typedef unsigned short u16_t; typedef signed short s16_t; typedef unsigned int u32_t; typedef signed int s32_t; #define LWIP_PLATFORM_ASSERT(x) \ do { \ KdPrint((lwip assert: %s at %s:%d\n, x, __FILE__, __LINE__)); \ ASSERTMSG(x, FALSE); \ } while(0) #define LWIP_PLATFORM_DIAG(x) KdPrint x #endif注意内核态绝对不能包含用户态的string.h、stdlib.h那套memcpy、memset这些可以用RtlCopyMemory、RtlZeroMemory代替或者在cc.h里做一层宏映射。2.3 lwipopts.h 裁剪内核态不是裸机也不是 LinuxlwIP 默认的配置文件在src/include/lwip/opt.h它给所有配置项都提供了默认值。但实际移植时必须自己写一个lwipopts.h把项目特定的配置覆盖过去。对于 Windows 内核环境有几点必须调整关闭LWIP_SOCKET和LWIP_NETCONN的依赖。内核态没有 POSIX socket 语义我们直接用 lwIP 的 raw API 是最合适的。如果能关掉LWIP_NETCONN那 netconn 层相关的线程模型和等待机制就不会被编译进来省掉一大块代码。不过要注意如果我后面想用tcpip_input()这种 tcpip 线程投递机制就必须要保留LWIP_TCPIP_CORE_LOCKING的相关配置具体见下一个小节。内存配置是非常关键的部分。MEM_SIZE决定mem_malloc管理的内存池总大小MEMP_NUM_TCP_SEG决定 TCP 报文段控制块数量PBUF_POOL_SIZE决定PBUF_POOL类型 pbuf 的数量。内核态环境不存在裸机那种内存紧张的问题但也不建议给得太大因为每一个 pbuf 都要在非分页池里分配。我给你的建议是先用一个中等规模的值跑通流程比如#define MEM_SIZE (64 * 1024) #define MEMP_NUM_TCP_SEG 128 #define PBUF_POOL_SIZE 64 #define TCP_MSS 1460 #define TCP_WND (4 * TCP_MSS) #define TCP_SND_BUF (4 * TCP_MSS)这些参数在开发初期不要一上来就追求大数值否则一旦内存池溢出排查起来会很难受。后面的调优章节我会专门讲怎么根据实际流量放大。还有一个坑是NO_SYS。如果NO_SYS为 1lwIP 认为没有操作系统要求你提供锁和邮箱的原语但不需要线程。我们在 Windows 内核里显然不是裸机环境所以NO_SYS必须设为 0让 lwIP 运行在 tcpip 线程模型中。2.4 关键参数参考表为了方便对照我把这次移植最常用的配置项整理成了一张表配置项推荐值说明NO_SYS0有操作系统使用线程模型LWIP_NETCONN1netconn API 用于业务层调用LWIP_SOCKET0内核态不需要 socket 层LWIP_TCPIP_CORE_LOCKING1tcpip 线程和各 API 线程共享核心锁MEM_SIZE64KB~256KBmem_malloc 管理的内存池PBUF_POOL_SIZE64~256收包 pbuf 池数量决定抗突发能力MEMP_NUM_TCP_SEG128~512TCP 分段数量影响吞吐TCP_MSS1460标准以太网 MSSTCP_WND4*TCP_MSS默认接收窗口可按需放大TCP_SND_BUF4*TCP_MSS默认发送缓冲LWIP_STATS1开启统计调试时很有用LWIP_DEBUG1开发期开 debug发布关掉这张表不是标准答案而是“开发初期能稳定跑起来”的底线。实际调优时重点看LWIP_STATS输出的lwip_stats.mem.err和lwip_stats.memp.err是否在增长再反过来调大对应池子。3. sys_arch 适配把 lwIP 落到 Windows 内核线程模型上3.1 线程抽象PsCreateSystemThread 的正确用法lwIP 在NO_SYS0的模型下会通过sys_thread_new()创建协议栈线程。最典型的场景是tcpip_init()里创建tcpip_thread它负责转发所有协议栈事件是 lwIP 消息驱动的核心循环。在 Windows 内核里创建线程用PsCreateSystemThread是最直接的方式static sys_thread_t sys_thread_new(const char *name, lwip_thread_fn thread, void *arg, int stacksize, int prio) { HANDLE hThread NULL; NTSTATUS status; status PsCreateSystemThread(hThread, THREAD_ALL_ACCESS, NULL, NULL, NULL, (PKSTART_ROUTINE)thread, arg); if (!NT_SUCCESS(status)) { return NULL; } // 注意这里不能直接把 HANDLE 当作 sys_thread_t 返回 // 因为销毁线程时 ZwClose 之后句柄就失效了所以要先引用对象 return (sys_thread_t)hThread; }这段代码里有几个容易踩坑的地方。第一PsCreateSystemThread要求传入的线程函数原型是VOID (*)(PVOID)而 lwIP 的线程函数是void (*)(void *)两者调用约定一致直接强转即可。第二线程创建后如果业务层需要等待它退出最好保留线程对象引用否则纯粹用 HANDLE 管理在线程自杀的场景下可能产生竞态。第三优先级prio建议直接传一个较高的实时优先级或者用tp-Priority HIGH_PRIORITY单独设置。协议栈线程一旦被饿死整个网络链路就直接卡死了。我开发初期犯过一个错误没给tcpip_thread足够的栈空间。PsCreateSystemThread的stacksize为 0 时使用默认系统栈大小而 lwIP 默认的线程栈要求是TCPIP_THREAD_STACKSIZE默认 0 的话 sys_arch 负责给。内核线程栈太小一旦协议栈处理了较大报文很容易触发栈溢出检查表现为莫名其妙的蓝屏。建议一开始就给足 16KB 以上。3.2 信号量、互斥锁与邮箱的映射这是整个移植最核心的部分。lwIP 对底层同步原语的要求有互斥锁sys_mutex、信号量sys_sem、邮箱sys_mbox。把这三种原语翻译成 Windows 内核对象规则很清楚sys_mutex→KMUTEX用KeInitializeMutex、KeWaitForSingleObject、KeReleaseMutexsys_sem→KSEMAPHORE用KeInitializeSemaphore、KeWaitForSingleObject、KeReleaseSemaphoresys_mbox→ 没有现成对应物通常用一个“互斥锁 令牌信号量”的环形消息队列来模拟。信号量是最简单的核心代码如下static err_t sys_sem_new(sys_sem_t *sem, u8_t count) { KeInitializeSemaphore(sem, count, MAX_SEM_COUNT); return ERR_OK; } static void sys_sem_signal(sys_sem_t *sem) { KeReleaseSemaphore(sem, IO_NO_INCREMENT, 1, FALSE); } static u32_t sys_sem_wait_timeout(sys_sem_t *sem, u32_t timeout_ms) { LARGE_INTEGER timeout; NTSTATUS status; if (timeout_ms 0) { KE_WAIT_INFORMATION waitInfo; status KeWaitForSingleObject(sem, Executive, KernelMode, FALSE, NULL); } else { timeout.QuadPart -(LONGLONG)timeout_ms * 10000; // 毫秒转100ns status KeWaitForSingleObject(sem, Executive, KernelMode, FALSE, timeout); } return (status STATUS_SUCCESS) ? SYS_ARCH_TIMEOUT : SYS_ARCH_WAIT_OK; }这里有一个需要注意的语义问题。lwIP 的信号量等待函数sys_arch_sem_wait返回 0 表示信号量可用即SYS_ARCH_WAIT_OK返回非 0 表示等待了多长时间或者超时。不同版本的 lwIP 对这个返回值的约定不完全一样2.x 统一为“等待的毫秒数”超时用SYS_ARCH_TIMEOUT表示。你得看当前源码里sys.h里的宏定义别想当然地照抄别的版本。邮箱的实现要稍微多想一下。sys_mbox需要支持sys_mbox_new创建邮箱sys_mbox_trypost往邮箱里放一条消息非阻塞满则返回ERR_MEMsys_mbox_fetch阻塞取一条消息sys_mbox_tryfetch非阻塞取一条消息。最经典的实现是用数组做环形队列加一把互斥锁保护队列再配两个信号量分别记录“队列中有数据”和“队列中有空位”。核心代码如下typedef struct sys_mbox_s { void **msgs; int size, head, tail, count; KMUTEX lock; KSEMAPHORE notEmpty; // 有数据 KSEMAPHORE notFull; // 有空间 } sys_mbox_s;trypost时获取notFull信号量如果超时立刻返回ERR_MEM拿到空位后加锁、写队列、解锁然后释放notEmpty。fetch则反过来。这个模式跟我在 RTOS 上写过的一模一样区别只是把互斥信号量换成了KMUTEX把等待函数换成了KeWaitForSingleObject。有一个细节是sys_mbox_new在 2.0 以上版本要求传入size参数表示队列容量而且sys_mbox这个类型在 Windows 上最好定义成指针类型否则 32/64 位切换会出问题。3.3 时间基准不要用 KeQueryTickCountlwIP 内部有大量的超时判定逻辑靠的是sys_now()返回当前时间单位毫秒。在裸机上要么用一个全局计数器要么读硬件定时器在 Windows 内核里很多人第一反应是KeQueryTickCount但这个 API 有个坑它的频率是系统时钟节拍默认可能是 100Hz 或 1000Hz而且精度不稳定。你用KeQueryTickCount换算出来的时间误差可能高达几十毫秒。这对 TCP 重传定时器来说是致命的。我推荐用KeQueryInterruptTime它返回一个 100ns 精度的单调递增时间不受系统时间调整影响适合做超时计算static u32_t sys_now(void) { ULONGLONG interruptTime KeQueryInterruptTime(); // 100ns units return (u32_t)(interruptTime / 10000); // 转成毫秒 }注意KeQueryInterruptTime返回的是ULONGLONG取低 32 位当毫秒数用在系统连续运行 49 天左右会回绕。lwIP 内部很多超时比较已经考虑了回绕问题但如果你在业务层自己写时间差逻辑要记得用有符号减法来做差而不是直接比较绝对值大小。3.4 sys_arch_protect 与临界区lwIP 有一个比较古老的临界区保护接口sys_arch_protect和sys_arch_unprotect。在裸机移植中它通常用来关中断在 Windows 内核中当然不能真的关中断否则系统直接就卡死了。合理的做法是返回一个sys_prot_t类型的标志并且内部用高速自旋锁保护核心临界区。不过 2.x 版本的 lwIP 在主流的LWIP_TCPIP_CORE_LOCKING模型下对这个接口的依赖已经大幅减少。我建议直接把sys_arch_protect实现成static sys_prot_t sys_arch_protect(void) { // 单核可以用 KeRaiseIrql 到 DISPATCH_LEVEL 保底 // 多核环境建议配合自旋锁使用 KIRQL oldIrql; KeRaiseIrql(DISPATCH_LEVEL, oldIrql); return (sys_prot_t)oldIrql; } static void sys_arch_unprotect(sys_prot_t oldIrql) { KeLowerIrql((KIRQL)oldIrql); }这个方案能保证临界区里不会发生线程切换适合保护多生产者/多消费者共享的少量数据。但不要在临界区里做耗时操作毕竟它是直接抬 IRQL相当于把整个 CPU 钉住了。4. NDIS 网卡接入让 lwIP 真正“通路”4.1 用 NDIS 过滤驱动绑定物理网卡lwIP 作为一个协议栈最终要挂到一个netif上而这个netif必须对应一个真实的收发通道。在 Windows 里最合理的方式是写一个 NDIS 过滤驱动Filter Driver绑定到一块物理以太网网卡上然后由这个驱动把网卡收到的报文转交给 lwIP。为什么选过滤驱动而不是中间层驱动NDIS 中间层驱动IM的架构比较复杂需要实现一组虚拟小端口和协议驱动而且微软后来更推荐用过滤驱动完成类似工作。过滤驱动的入口逻辑简单只需要注册一个NET_BUFFER_LIST接收回调和一个发送回调。具体来说过滤驱动初始化时调用NdisFRegisterFilterDriver并在配置里声明FilterClass为ms_switch或自定义类用INF文件配置绑定关系。绑定完网卡之后你会得到一个NDIS_HANDLE过滤器句柄。收发路径上的NET_BUFFER_LIST通过回调函数进入你的代码。这里要记住一个铁律NDIS 的接收回调运行在DISPATCH_LEVEL在回调里不能调用任何可能阻塞的函数也不能直接调用 lwIP 里需要睡眠等待的函数。后面我会专门讲怎么处理这个 IRQL 问题。4.2 收包路径从 NBL 到 pbuf接收回调在FilterReceiveNetBufferLists里被触发参数是NET_BUFFER_LISTNBL。一个 NBL 可能包含多个NET_BUFFERNB每个 NB 对应一个包。我的处理方式分两步第一步在DISPATCH_LEVEL下把 NBL 挂到一个自旋锁保护的内核队列里然后释放 NBL 的所有权继续向上传递或者按需求自己保留。这一步不拷贝数据只搬移指针开销极小。第二步唤醒一个专门的接收 worker 线程。这个线程运行在PASSIVE_LEVEL从队列里取出 NBL逐个 NB 读取数据把报文内容拷贝到 lwIP 的 pbuf 里然后调用tcpip_input()。为什么不在回调里直接构造 pbuf因为 pbuf 池的分配和释放可能会触发内存管理操作内存管理要求 IRQL 不高于DISPATCH_LEVEL但万一内存池耗尽lwIP 内部的处理路径里有可能出现等待或调度这在DISPATCH_LEVEL下是绝对禁止的。所以标准做法就是排队 异步处理。这个设计我也见很多 NDIS 驱动用过属于必经之路。读取 NB 数据时我习惯用NdisGetDataBufferUCHAR *data NdisGetDataBuffer(NB, dataLength, stackBuf, // 避免分配的一块固定栈空间 1, // 对齐 0);如果NdisGetDataBuffer返回非空说明数据在内存中是连续的可以直接用。如果返回空说明数据分散在多个 MDL 里需要自己遍历NET_BUFFER_CURRENT_MDL把数据拼起来。考虑到我们要构造 pbuf其实没必要拼到连续缓冲区可以直接为每一段 MDL 分配一个 pbuf 并链成 pbuf 链。但开发初期为了降低复杂度我是先在栈缓冲区里拼好再一次性拷进 pbuf。pbuf 的构造要注意头部预留问题。物理网卡收到的报文带以太网头14 字节lwIP 的ethernet_input()会解析以太网头并交给对应的上层协议。因此构造 pbuf 时要用PBUF_RAW类型并把整帧数据原封不动地塞进去struct pbuf *p pbuf_alloc(PBUF_RAW, totalLength, PBUF_POOL); if (p) { pbuf_take(p, data, totalLength); netif-input(p, netif); // 这里实际是通过 tcpip_input 投递 }调用tcpip_input(p, netif)之后pbuf 的所有权就转移给 lwIP 了协议栈会负责释放。千万不要在投递后再碰这个 pbuf否则就是 double free。4.3 发包路径从 pbuf 到 NBL发送路径相对简单。lwIP 最终会回调你注册的netif-linkoutput这个函数接收一个 pbuf 指针里面是完整的以太网帧。你的任务就是把它送进 NDIS 发送通道。实现逻辑分几步根据网卡 MTU 和 pbuf 总长度计算需要分配的NET_BUFFER_LIST数量从NdisAllocateNetBufferList和NdisAllocateNetBuffer分配内存锁好非分页内存遍历 pbuf 链把每一段的地址和长度填入 NB 的 MDL调用NdisFSendNetBufferLists下发交给底层的协议栈绑定。这里最重要的一个坑是NdisFSendNetBufferLists是异步的调用之后你的NET_BUFFER_LIST所有权马上转移给 NDIS 了底层网卡发送完成后会通过FilterSendNetBufferListsComplete回调返还给你。所以你不能在linkoutput里用完 NBL 就释放必须在完成回调里释放。如果你把 lwIP 的 pbuf 数据直接放进 NBL 里那底层的完成回调必须负责把 pbuf 释放掉否则就是内存泄漏。更稳妥的方案是在linkoutput里分配 NBL 时把 pbuf 指针作为上下文context保存进去在FilterSendNetBufferListsComplete里取出 pbuf调用pbuf_free再释放 NBL。这样 pbuf 何时归还给 lwIP 的内存池完全由发送完成事件驱动是最安全的生命周期管理方案。4.4 IRQL 与异步投递问题新手移植 lwIP 到 Windows 内核时最容易出的问题就是 IRQL。NDIS 接收回调在DISPATCH_LEVEL而 lwIP 的tcpip_input()内部会往tcpip_mbox里投递消息。我之前说过sys_mbox_trypost在这个调用链里是非阻塞的理论上在DISPATCH_LEVEL调用不算越界。但是tcpip_input()在投递消息之前还会做timeouts遍历、pkt 队列操作等一系列事情这些操作里涉及的内存访问和锁行为在高 IRQL 下是存在风险的。最保险的是用 worker 线程搬运接收回调里只做队列入队和事件通知真正调用tcpip_input()的代码永远跑在PASSIVE_LEVEL的线程里。这也是我最终采用的方案。我见过一种偷懒的写法直接在DISPATCH_LEVEL里转发tcpip_input()测试时可能也能跑但一旦开启Driver Verifier或者系统负载高了蓝屏就会找上门来。IT 行业有个原则能在 IRQL 上规避的问题不要靠运气。工作项IoQueueWorkItem也是一种选择但它依然跑在系统 worker 线程上下文里而且执行时机受系统调度影响。自建专用 worker 线程更可控尤其是消息量大时还可以做批量出队、批量投递的收包合并优化。5. 调试、性能与常见故障排查5.1 新手最容易踩的 4 个坑移植过程中我遇到的故障基本都集中在这四类。第一类是编译层面的cc.h里没有正确定义整数类型导致 pbuf 的 offset 字段被编译器按 4 字节对齐而不是按 2 字节对齐最终在协议头解析时出现错位。这个问题非常隐蔽表现是收包后先能看到 IP 头但 TCP 端口全部乱掉。解决办法很简单p 结构体最典型的是struct ip_hdr里有u16_t类型的字段如果u16_t被错误定义成 4 字节类型整个报头就读错了。所以cc.h里的整数类型定义必须跟编译器实际对齐严格匹配这一点上直接抄 lwIP 官方移植模板最稳妥。第二类是内核内存分配问题。lwIP 的mem_malloc内部从一个大数组里分配这个数组如果按LWIP_RAM_HEAP_POINTER定义在某个段里可能会被链接进一个不具备硬件缓存一致性的内存区域。更常见的问题是在 Windows 内核里你给MEM_SIZE开得太大比如 8MB然后在DriverEntry阶段一次性初始化结果非分页池不足导致ZwAllocateVirtualMemory失败。内核态内存不是用户态虚拟内存不要贪心先用小值验证功能。第三类是线程饿死问题。lwIP 的tcpip_thread如果没有及时处理消息接收 worker 线程可能因为信号量等待堆积而把所有内核线程资源耗尽。表现是系统卡顿、网卡 watchdog 超时。这个要通过调高tcpip_thread的优先级来解决还要在 worker 线程里做简单的流量控制。第四类是最典型的“以太网头处理”问题。我调试 ARP 时遇到一种非常奇怪的现象TCP 连接能建立但 ping 不通。后来发现是netif_add时没有正确设置hwaddr_len 6导致 ARP 报文里的 MAC 地址长度字段错误对端直接丢弃。这类问题全靠对比抓包才能定位建议开发期间在测试机上装好抓包工具或者在 lwIP 里用LWIP_DEBUG打开ETHARP_DEBUG级别的日志。5.2 IRQL 引发的神秘蓝屏“神秘蓝屏”是内核开发的家常便饭而在移植 lwIP 时最常见的蓝屏就是这个附一张经典蓝色背景图的画面感在ip4_input里访问某个 pbuf 的 payload 指针时系统直接报IRQL_NOT_LESS_OR_EQUAL。原因通常是在DISPATCH_LEVEL上调用了 pbuf 内存的分配或释放。pfn 之类的非分页池内存在DISPATCH_LEVEL下是可以访问的但是 lwIP 的内存池管理里可能有自旋锁保护。如果 pbuf 池在释放时发生内存驻留页面的换页操作就会触发 IRQL 冲突。内存管理在 Windows 内部要满足所谓的PASSIVE_LEVEL要求只要涉及分页内存比如EX_NONPAGED_POOL之外的普通池IRQL 稍高就会蓝屏。我从一开始就坚持“接收回调不碰 lwIPworker 线程碰 lwIP”的这个原则整个调试周期里没有因为在 IRQL 问题上反复蓝屏过。这比我第一次写 NDIS 驱动时凭感觉乱调 API 要省心得多。5.3 内存池与性能调优lwIP 跑通之后接下来就是压力测试。用打流工具或一个简单的 TCP 回环程序把数据量慢慢加上去。一开始用lwip_stats观察内存池使用情况if (lwip_stats.memp[MEMP_TCP_SEG].err) { KdPrint((TCP_SEG exhausted\n)); } if (lwip_stats.mem.err) { KdPrint((mem pool exhausted\n)); }压测中我发现MEM_SIZE64KB 很快就会被打满内存池报 err 后TCP 发送窗口收缩到很小吞吐量大幅下降。后来我把MEM_SIZE调到 256KBMEMP_NUM_TCP_SEG调到 512效果立竿见影。原因在于 TCP 发送缓冲和接收窗口都与MEMP_NUM_TCP_SEG直接挂钩每个 TCP 段都要占用一个tcp_seg结构。如果你的业务是大量小包高频交互那么这个数值要更大。另一个优化点是PBUF_POOL的数量。我最初设为 64当接收队列在短时间内堆积多个包时会发现大量丢包ip4_input因为 pbuf 不够直接丢弃。收包场景下PBUF_POOL数量至少要能覆盖TCP_WND/MSS 一定余量。一个简单的经验值是收包路径的突发队列深度 × 2。发送性能方面一个大坑是每发一个包就分配一个 NBL然后在完成回调里释放 NBL 和 pbuf。这个分配释放频率在高吞吐下是很夸张的容易造成 CPU 使用率偏高。优化方向是预分配 NBL 池或者在linkoutput里尽量复用已有 NBL。不过这个优化会引入更复杂的所有权管理我的建议是先跑通再改。5.4 用 WinDbg 排查失败现场内核驱动的调试手段和用户态完全不一样。我几乎是靠 WinDbg 双机调试活下来的。配置好内核调试之后有几种特别有用的操作!analyze -v蓝屏后第一时间查看 bugcheck 原因!locks查看是否有自旋锁死锁!poolused查看各种池的用量判断内存池是否耗尽!ndiskd系列命令直接检查 NDIS 过滤器状态和队列深度!stacks查看所有内核线程的调用栈尤其看tcpip_thread和接收 worker 线程是否卡在等待上。有一次我为了排查丢包问题直接在ip4_input入口处打了个条件断点然后查看 pbuf 的len和payload的原始字节。通过对比抓包很快发现是网卡驱动在接收时把 VLAN 标签残留在了以太网头的附加字段里导致 lwIP 解析 IP 头时 offffset 偏移了一位。这种问题如果不开调试器基本只能靠猜。5.5 常见问题速查表现象大概率原因排查思路编译报错找不到 time.h 等头文件cc.h 未配置或者包含了用户态头文件检查所有头文件包含路径屏蔽非内核头文件TCP 连接建立不了ARP 也不通netif 的 hwaddr_len 没有设置MAC 地址错误打 ETHARP_DEBUG核对 netif-hwaddr 内容能 ping 通TCP 丢包严重PBUF_POOL_SIZE 太小收包 worker 处理不过来查看 lwip_stats.memp[MEMP_PBUF_POOL].err高负载下蓝屏 IRQL_NOT_LESS_OR_EQUAL在 DISPATCH_LEVEL 调用了 lwIP 的阻塞函数或分页内存操作排查所有 NDIS 回调禁止直接调用 lwIP系统卡顿网卡无响应tcpip_thread 优先级太低被其他线程饿死调高线程优先级检查线程栈大小发送后对端收不到驱动无报错NBL 所有权理解错误可能提前释放了数据缓冲在 FilterSendNetBufferListsComplete 里统一释放 NBL 和 pbuf6. 写在最后这件事到底值不值得做现在回顾这个项目我的答案是非常值但前提是你清楚自己要去哪儿。如果你只是想要一个能发 TCP 包的内核模块直接用 WSK 可能五分之一的时间就够了。但如果你想要的是对协议栈的完整掌控权想把 TCP 重传、拥塞窗口、缓冲区行为都摸清楚那移植 lwIP 几乎是成本最低的路线。整个过程中让我最意外的其实是 lwIP 内部的“操作系统无关性”。它在设计上把自己的活动范围收敛得非常干净对外只依赖一个sys_arch层对内则靠进程模型和消息循环驱动一切。这种工程抽象能力比它本身的 TCP 实现更值得学习。我在 Windows 内核里写sys_arch时反复体会到一句话好的移植不是熬出来的而是清晰架构撑出来的。最后再分享一个小技巧如果你打算做类似的事情强烈建议第一步不是写代码而是先在用户态搭一个 lwIP 的模拟环境用回环驱动或者直接调netif的收包接口喂包把协议栈行为全部调通再沉到内核态。我因为跳过这一步多花了至少一周时间在内核调试器里看tcpip_thread的调用栈。内核态一旦出错排查成本是用户态的十倍。先易后难稳扎稳打这套移植路径才会走得顺畅。