简介这是一份专为 NDIS 6.0 驱动开发者准备的千兆以太网卡 miniport 驱动实例源代码面向需要编写、移植或阅读网卡小端口驱动的工程师。作者针对 Realtek 8111/8168/8169/8110 等流行 PCI 千兆控制器编写用完整工程演示从 DriverEntry 到收发数据包、中断处理、电源管理等核心环节弥补官方 DDK 示例仅有 E100BEX、参考代码过少的不足。资源共 69 个文件压缩包约 615KB内部包含 3 个 zip 驱动工程包分别对应基础版本、PM 电源管理支持版本、LSO 与巨型帧支持版本其余 htm/js/css/gif/png 网页文件则提供驱动说明、脚本和界面截图便于边阅读边对照。目前已有 1238 人学习下载。通过学习这份代码可以了解 NDIS 6.0 小端口驱动的初始化流程、OID 查询与设置、发送接收路径、PNP 电源管理和任务卸载等实现方法并能参考其中对真实硬件的寄存器操作与中断逻辑适合希望从官方示例走向真实硬件开发的中高级开发者。 做网络驱动开发的人迟早都要直面 NDIS 小端口驱动这个绕不开的关卡。Windows 下面网卡要工作协议栈要发包收包全都依赖你写的这一个小模块。说实话小端口驱动在我眼里是整个 NDIS 体系里最“拧巴”的一层它既要贴着硬件寄存器打交道又要按 NDIS 的抽象规则办事稍不留神就是蓝屏或者网卡掉线。这篇文章就围绕 NDIS 小端口驱动miniport driver 在以太网卡上的开发实践把架构思路、关键流程、收发路径和掉坑经历都拉出来聊一遍希望给正在做或准备做这一块的同行一点参考。1. 整体设计思路为什么网卡驱动要“小端口化”1.1 NDIS 这套机制到底解决了什么问题先不要一上来就看代码。你得先理解 NDIS 为什么要把驱动设计成这种奇怪的结构。Windows 的网络驱动不是像 Linux 那样直接一头扎进协议栈而是在中间插了 NDISNetwork Driver Interface Specification这个库层。你可以把 NDIS 理解成一个“超级中介”它向上给 TCP/IP 协议栈提供统一的发送接收接口向下给各种网卡驱动提供统一的硬件访问抽象。这样一来网卡厂商不用关心协议栈内部怎么组织报文只需要按要求实现 NDIS 规定的回调函数然后把自己的网卡能力注册进去。反过来微软也不用为每一块网卡去适配协议栈只要各厂商按 NDIS 规范写好驱动大家各司其职。这就是为什么网络驱动领域的现状是“协议栈基本不用动网卡驱动换了一代又一代”。小端口驱动就是这套机制里最底层的那一棒。它负责管理网卡的初始化、启动、停止、数据收发、中断处理、电源管理以及硬件卸载能力比如校验和计算、TCP 分段卸载这类活儿。名字叫 miniport但它干的绝不是小活儿反而是一切上层功能能不能落地的地基。1.2 谁是 NDIS 体系里的“上下游”想知道小端口驱动怎么定位就得把它放进整个网络驱动栈里看。从顶到底大概是这样的应用层程序浏览器、邮件客户端等Winsock / 用户态 APITDI / Winsock Kernel现在基本都是 Winsock Kernel即 WSK协议驱动TCP/IP 协议栈比如 tcpip.sysNDIS 库ndis.sys小端口驱动miniport driver网卡硬件也就是说小端口驱动夹在 NDIS 和硬件之间。它要做的事分两类一类是“上行”就是网卡收到数据后通过中断或轮询告诉驱动驱动把数据封装成 NDIS 能认识的结构NET_BUFFER_LIST再交到 NDIS 层另一类是“下行”NDIS 把协议栈发下来的数据包交给小端口驱动驱动负责把包塞进硬件发送队列然后操控 DMA 或者 PIO 让数据从网线出去。很多新手容易把“小端口驱动”和“网卡驱动”划等号事实上小端口驱动只是网卡驱动在 NDIS 框架下的一种形态。如果你的网卡还需要支持 Wake-on-LAN、虚拟机队列VMQ、单根 I/O 虚拟化SR-IOV之类的高级功能那还会有更多细分模块配合。但无论怎么扩展最核心的数据通道永远绕不开小端口驱动这一层。1.3 开发方案选型NDIS 6.x 起步别走老路如果你现在才刚开始设计一个新的以太网卡驱动我的建议非常明确直接采用 NDIS 6.x特别是 Windows 10/11 和 Server 2016 以后对应的高版本。不要再用 NDIS 5.x 的老接口写新代码虽然某些老代码在网上还能查到但系统兼容性、性能表现、调试工具链都已经不在一个水平线上。NDIS 6.x 最大的变化是收发路径上引入了 NET_BUFFER 和 NET_BUFFER_LIST 这套池化结构。相比 5.x 时代的 OOB 数据块和更复杂的内存管理6.x 的模型要清爽得多发送数据支持异步完成驱动可以同时挂起大量数据包配合多核处理器做 RSS接收端缩放也非常顺畅。你写驱动的时候应该把“一包一请求”这种老思路彻底扔一边改成“批量提交、批量完成”的思维模式。2. 小端口驱动的核心结构和工作机制2.1 注册入口DriverEntry 这一步该干什么每个 NDIS 小端口驱动都有一个入口函数叫 DriverEntry但它做的事情和普通 WDMWindows Driver Model驱动不太一样。除了常规的驱动对象初始化外它最核心的任务是填一个 NDIS_MINIPORT_DRIVER_CHARACTERISTICS 结构体这个结构体就像一份“能力声明书”告诉 NDIS“我能处理哪些回调函数我支持哪些特性我需要的头节点大小是多少。”比如这样一段典型的注册代码NDIS_MINIPORT_DRIVER_CHARACTERISTICS mpChars; NdisZeroMemory(mpChars, sizeof(mpChars)); mpChars.Header.Type NDIS_OBJECT_TYPE_MINIPORT_DRIVER_CHARACTERISTICS; mpChars.Header.Size sizeof(mpChars); mpChars.Header.Revision NDIS_MINIPORT_DRIVER_CHARACTERISTICS_REVISION_2; mpChars.MiniportInitializeEx MpInitialize; mpChars.MiniportHaltEx MpHalt; mpChars.MiniportShutdownEx MpShutdown; mpChars.MiniportResetEx MpReset; mpChars.MiniportSendNetBufferLists MpSendNetBufferLists; mpChars.MiniportReturnNetBufferLists MpReturnNetBufferLists; mpChars.MiniportCancelSend MpCancelSend; mpChars.MiniportDevicePnPEventNotify MpDevicePnPEventNotify; mpChars.MiniportOidRequest MpOidRequest; mpChars.MiniportCancelOidRequest MpCancelOidRequest; mpChars.MiniportInterruptDPC MpInterruptDpc; mpChars.MiniportDisableInterruptEx MpDisableInterrupt; mpChars.MiniportEnableInterruptEx MpEnableInterrupt; NdisMRegisterMiniportDriver( DriverObject, RegistryPath, NULL, mpChars, mpDriverHandle );这段代码没有做太多“业务”但它是整个驱动的生命线。只要这里漏配一个回调函数后面网卡初始化就可能找不到入口或者系统在某种特定场景下调用空指针直接蓝屏。我见过不少同事抄老代码忘了填 MiniportShutdownEx结果在系统休眠唤醒测试时翻车。注册完成之后NDIS 会调用你提供的 MiniportInitializeEx。这个函数把真正的硬件初始化工作捡起来但它不是简单地把寄存器写一遍就完了而是要和 NDIS 反复交互完成资源注册、能力上报等动作。2.2 初始化流程从 PnP 到可用的完整链路小端口驱动的初始化在设备驱动领域算是比较复杂的异步流程。它不像普通总线驱动那样你在 AddDevice 里一口气做完所有准备工作就返回成功。NDIS 小端口驱动讲究“分段完成”这既是机制设计的结果也是现实硬件的需求。当系统检测到你的以太网卡出现在 PCIe 总线上时PnP即插即用管理器会找到对应的驱动然后触发 NDIS 调用你的 MiniportInitializeEx。这个回调里你需要做以下这些事读取 PCIe 配置空间获取 BAR 地址、中断资源、DMA 掩码等信息。映射 MMIO内存映射 I/O寄存器到系统虚拟地址空间。分配 DMA 资源包括 DMA 适配器对象、公共缓冲区Common Buffer等。初始化硬件状态比如关闭收发引擎、设置 MAC 地址、配置流控寄存器。调用 NdisMSetMiniportAttributes 上报网卡的类型、媒体类型、MAC 地址等关键属性。注册中断调用 NdisMRegisterInterruptEx关联中断服务例程ISR和延迟过程调用DPC。创建收发队列预分配接收缓冲区池。最后启动硬件收发引擎。关键点在于MiniportInitializeEx 可以返回 NDIS_STATUS_PENDING然后真正干完所有工作后通过 NdisMInitializeComplete 回调通知 NDIS。这种异步机制的好处是如果硬件需要的复位时间比较长驱动不必一直占着系统线程不放手。对 PCIe 网卡来说复位 固件加载动辄要几十毫秒甚至更久同步等待只会拖慢开机速度。2.3 头节点私有空间的妙用NDIS 初始化时有个容易被忽略的参数头节点大小HeaderNodeSize。这个参数会告诉 NDIS在分配 NET_BUFFER_LIST 的时候额外多留出一块空间给你存放私有上下文比如硬件描述符的索引、DMA 映射信息、时间戳数据等。我强烈建议在这个私有空间里至少放两种信息一个是这个包对应的物理地址或者 DMA 映射描述符另一个是包的状态标志位。这样一来发送完成和接收指示时驱动可以直接从 NBLNET_BUFFER_LIST里拿回自己的私有数据而不用再做一次哈希查找或者链表搜索性能损耗可以压到最低。对于多队列网卡私有空间里也可以放队列 ID。比如你的网卡有 4 个 TX 队列驱动可以在发送时根据包的 FlowHash 或者 CPU ID 选中队列然后把队列编号塞进私有空间这样完成中断回来的时候DPC 就知道该去清理哪个队列的完成队列项了。3. 收发路径的实操实现数据是怎么跑起来的3.1 接收路径中断、DPC 与 NBL 交付以太网卡的接收路径是整块驱动设计里最容易出问题的地方。物理网卡收到报文以后会通过 DMA 把数据写到驱动预先准备好的缓冲区里然后触发中断MSI-X 中断通常按队列分配CPU 进入 ISR。ISR 里不能做太多工作基本原则是“赶紧关中断把脏活交给 DPC延迟过程调用”。标准的做法是ISR 里读中断状态寄存器确认是哪个队列产生了接收完成事件然后调用 NdisMQueueDpc 把对应队列的 DPC 排入执行队列。DPC 里再去做实际的数据搬运、解析完成描述符、构建 NBL 等工作。我说的“构建 NBL”直观上是把网卡 DMA 写好的接收缓冲区包成 NDIS 标准的 NET_BUFFER_LIST 结构。关键点是你的接收缓冲区本来就是从 NDIS 池里分配的所以这里不需要拷贝数据只需要把缓冲区地址、长度、校验和状态等信息填进 NBL然后调用 NdisMIndicateReceiveNetBufferLists 把数据“顶”给 NDIS。如果网卡的 DMA 引擎要求地址连续你就要注意缓冲区分配方式。简单的做法是初始化时为每个 RX 队列分配一个固定大小的环形缓冲区池每个缓冲区都是一个物理页大小这样 DMA 的地址映射最简单一个页面一段 DMA 映射不涉及跨页拼接问题。硬件能力更强的网卡可以支持多段描述符一个缓冲区可以拆成多个不连续的物理块但这对 DMA 描述符的编程复杂度又上了一个台阶。性能优化方面轮询模式也就是 Linux 上的 NAPI 那种思路在 Windows 上也有对应物但那属于砍掉中断、纯轮询收包的进阶玩法。普通驱动先把“中断触发 DPCDPC 里批量处理”这条路走稳性能已经能说过去先别急着搞花活。3.2 发送路径异步完成是核心语义小端口驱动的发送回调是 MiniportSendNetBufferLists它接收一个 NBL 链表。对于网卡驱动来说你拿到这批 NBL 以后不能简单地把数据往硬件队列里一丢就返回而是要理解 NDIS 的异步完成语义。协议栈把数据包交给你不是“交给你处理完了就完了”而是“暂时由你托管你必须在自己认为合适的时候通过 NdisMSendNetBufferListsComplete 通知 NDIS 这些包已经处理完了”。如果网卡的 TX 队列满或者硬件正在忙你可以先挂起这些 NBL等硬件有能力消费了再处理。这个完成时间点非常重要因为协议栈要依赖这个完成事件来释放缓冲区资源。实际开发中最简单可靠的 TX 路径是这样的遍历 NDIS 传来的 NBL 链表。为每个 NBL 做 DMA 映射如果硬件需要物理地址。把物理地址和长度写入 TX 描述符环。更新硬件寄存器中的尾指针触发 DMA 引擎发送。保存 NBL 指针到软件环等待发送完成中断。中断回来之后遍历完成描述符对已完成包调用 NdisMSendNetBufferListsComplete。这里容易犯的错误是忘记考虑“映射失败”的情况。如果某个 NBL 因为 DMA 资源不足而无法映射你不能就这么卡在发送路径里什么都不干而是应该立刻把失败包还回去调用 NdisMSendNetBufferListsComplete 并设置完成状态为失败协议栈才能正确释放并重传。3.3 中断处理ISR / DPC 怎么配合才不丢中断中断处理设计得不好网络驱动的性能就废了一半。以太网卡走 MSI-X 中断是主流每个队列一个中断向量这样多核 CPU 可以并行处理多个队列的收发这就是 RSS接收端缩放在中断层面的硬件基础。ISR 里必须火速判断“这个中断是不是我设备的”。读状态寄存器如果不是立刻返回 FALSE让 NDIS 继续找别的设备。如果是就要在 DPC 里关掉这个队列的中断防止出现同一个中断持续占用 CPU 的情况。DPC 里把所有收包都处理完了再通过 NdisMEnableInterruptEx 重新打开中断。这里有个老鸟都懂的坑中断丢失。如果你的硬件在高负载下把中断合并Interrupt Coalescing的阈值调得太大DPC 还没来得及处理完新包就已经入队并触发了新的中断但此时中断已经被你关了结果就是数据滞留在 DMA 缓冲区里无人问津。解决办法是在 DPC 收尾阶段再检查一次硬件状态如果发现 RX 完成队列里还有新描述符没处理就继续循环处理直到清空为止最后再重新开中断。3.4 硬件卸载别把校验和计算浪费在 CPU 上现在的高性能网卡基本上都支持硬件校验和计算Checksum Offload、TCP 分段卸载LSO等功能。你作为小端口驱动开发者要在初始化的时候通过 NdisMSetMiniportAttributes 上报这些能力同时正确处理 NDIS 传来的 OID 请求。比如协议栈发送一个非常大的 TCP 报文段如果 LSO 开启这个报文段的长度可能会超过 MSS 好几倍驱动不能直接把它塞给硬件相反驱动要把这个负载的段大小信息解析出来填到硬件描述符里让网卡自己拆分并且给每个分段补上 TCP 头和 IP 头。如果你对这个机制不熟最容易出现的问题就是网卡发出去的包不对粘包、校验失败、对端不认账。启动加载卸载能力之后务必要用真实的 TCP 大文件传输测试一下不要只看驱动加载不蓝屏就以为万事大吉。我见过一个项目网卡驱动收包正常但上传大文件时服务器端收到的包总是比预期大查了半天才发现是 LSO 的段大小字段填错了一个字节。4. 设备管理OID 请求、PnP 事件和电源管理4.1 OID 请求查询与设置的正确姿势NDIS 对网卡的管理大多数是通过 OIDObject Identifier请求来完成的。比如协议栈想知道网卡的 MAC 地址、链路速度、MTU 大小或者想让网卡进入休眠模式都会通过 OID 找上门来。你的驱动需要实现 MiniportOidRequest 回调。这个回调接收一个 NDIS_OID_REQUEST 结构里面包含请求类型查询或设置、OID 编号、数据缓冲区等。核心逻辑就是 switch-case 各种 OID把对应数据填回去或者把数据取出来操作硬件。新手最容易掉进去的坑是 OID 请求的完成方式。和发送路径一样OID 请求也是可以异步完成的。如果你的驱动要查询硬件寄存器或者等待固件响应不可能在 OID 回调里同步阻塞这时候应该把请求挂起返回 NDIS_STATUS_PENDING等硬件操作完成后再调用 NdisMOidRequestComplete 完成它。记得在驱动卸载时要把所有挂起的 OID 请求都取消并完成否则系统会认为你的驱动还“忙”导致卸载过程被阻塞或者直接提交失败。4.2 电源管理休眠唤醒的细节决定成败现代系统对电源管理要求很严格。以太网卡支持 WoLWake-on-LAN已经是标配所以小端口驱动必须配合 NDIS 处理设备从 S0工作状态到 S3/S4 的转换以及从低功耗状态唤醒回工作状态的完整流程。这个过程中会有 MiniportDevicePnPEventNotify 之类的回调通知驱动驱动需要保证在低功耗状态下网卡的基本管理能力仍然可用。如果你的网卡有多个功耗状态D0/D1/D2/D3驱动还得通过 NdisMIdleNotification 配合 NDIS 完成空闲检测和选择性挂起。我通常的做法是在 D0 状态正常收发当系统进入 S3 前驱动要把收发引擎停掉、中断关闭但保留网卡的 magic packet 检测逻辑唤醒后再把收发引擎重新启动完成必要的复位操作。想当然地以为“不需要特别处理电源”的驱动轻则导致系统无法进休眠重则唤醒后网卡直接失效只能重启才能恢复。4.3 设备移除和意外移除的兜底逻辑PCIe 设备支持热插拔所以驱动必须处理设备在任何时刻被拔掉的场景。NDIS 会调用你的 MiniportDevicePnPEventNotify同时可能触发 MiniportHaltEx。这时候你的驱动要做的第一件事是停止一切新请求的接受然后取消挂起的 DMA 操作释放中断资源最后释放缓冲区池和 DMA 资源。很多驱动崩溃问题出在设备已经被移除的时候驱动还在做 MMIO 操作。设备不见了你访问它的寄存器就可能导致总线错误。规避方法是在驱动的所有关键路径里都检查一个“设备已移除”的 Flag一旦置位就放弃操作并立刻返回失败。5. 常见问题与排查技巧那些年蓝过的屏、掉过的线5.1 初始化失败的各种“疑难杂症”初始化是驱动开发的“第一大关”也是问题高发区。最常见的现象就是设备管理器里网卡显示黄色感叹号系统事件日志里写着“设备无法启动”。这种情况一大半原因是 MiniportInitializeEx 返回了失败状态。每次 NdisMSetMiniportAttributes 调用后最好检查一下返回值虽然大多数情况下这个调用会成功但一旦属性结构内部出现版本不匹配比如你填了较新的 Revision而系统不认返回错误后你还继续往下走初始化最终就必然失败。这类“后续失败”往往很难排查所以早期把每个关键调用都检查好能省掉很多调试时间。5.2 接收丢包不只是硬件的问题我遇到过驱动在低负载下收发全部正常但只要打满带宽就开始丢包的情况。一部分原因确实是 DMA 缓冲区不足但对于多队列网卡还有一个容易被忽视的因素是 RSS 散列不均。如果系统的 RSS 密钥配置或哈希类型选择和硬件支持项不一致就会出现某些 CPU 队列过载、其他 CPU 空闲的现象间接导致接收处理不过来。解决思路有两个层面一个是驱动层面做动态负载均衡根据 DPC 执行时间和队列深度动态调整哈希输入一个是在较高层设置里调整 RSS 参数比如通过 netsh 命令设置 RSS profile。但归根结底驱动应该提前把所有队列都初始化为同等深度然后让硬件自己把包散列到不同队列避免处理过程成为瓶颈。5.3 调试辅助WinDbg 和 NDIS 提供的保命工具做小端口驱动手里不能没有一套好用的调试工具。WinDbg 是标配配合 NDIS 扩展命令!ndiskd可以查看 adapter 状态、NBL 链、OID 请求队列等。比如用 !ndiskd.netadapter 查看你的网卡适配器是否成功注册用 !ndiskd.miniport 查看小端口驱动的实时状态。如果驱动导致系统蓝屏抓 dump 分析是最直接的路径。在驱动里加上 WPP 软件跟踪基于 ETW 的日志机制也是一个好习惯运行期间可以实时打开日志看代码执行流方便快速定位是硬件异常还是逻辑错误。我的习惯是在发送完成、接收指示、OID 完成这些关键路径里都加上 WPP 日志线上出问题时开启 trace基本三轮之内就能锁到问题点。这比单纯用调试器断点强太多因为断点会改变时序很多驱动问题恰恰是时序敏感型你一打断点它就不复现了。6. 总结之外一点实在的开发建议前面已经把 NDIS 小端口驱动的架构、数据路径、设备管理、问题排查讲得比较透了。最后再分享几个我从项目里硬踩出来的经验。第一个建议是先别急着写大量逻辑先用“最小驱动”把网卡从设备管理器里跑起来。所谓最小就是只实现 DriverEntry、MiniportInitializeEx、MpHalt、以及最基础的 OID 回调让系统能正确枚举网卡并能配置 IP。这一步通了相当于整个驱动框架的“地基”稳了再做收发路径会轻松很多。第二个建议是管理好你对 NDIS 对象的生命周期理解。你在驱动里拿到的 NBL 并不天然属于你你要么尽快把它返回给 NDIS要么在拿到后接管它的所有权并且明确自己必须在什么时候归还。这个“所有权”思维理不清内存泄漏和双重释放跑不掉。第三个建议是经常做压力测试和异常拔插测试。驱动开发能不能交付不在于功能跑通而在于异常情况下还站得住。强制断电前拔卡、长时间满带宽打流、休眠唤醒循环几百次这些场景只要能稳住上线后大概率不会掉链子。做小端口驱动很磨人但掌握了 NDIS 的这套规矩再把硬件细节抠透你会发现这个领域其实非常“讲道理”。模块之间怎么配合、请求怎么流转、异常如何处理都有一整套规则在那摆着。你遵循它它就是最可靠的地基你想偷懒绕过它它就会用蓝屏教你做人。本文还有配套的精品资源点击获取 NDIS小端口驱动开发实战：架构解析、收发路径与问题排查指南
简介这是一份专为 NDIS 6.0 驱动开发者准备的千兆以太网卡 miniport 驱动实例源代码面向需要编写、移植或阅读网卡小端口驱动的工程师。作者针对 Realtek 8111/8168/8169/8110 等流行 PCI 千兆控制器编写用完整工程演示从 DriverEntry 到收发数据包、中断处理、电源管理等核心环节弥补官方 DDK 示例仅有 E100BEX、参考代码过少的不足。资源共 69 个文件压缩包约 615KB内部包含 3 个 zip 驱动工程包分别对应基础版本、PM 电源管理支持版本、LSO 与巨型帧支持版本其余 htm/js/css/gif/png 网页文件则提供驱动说明、脚本和界面截图便于边阅读边对照。目前已有 1238 人学习下载。通过学习这份代码可以了解 NDIS 6.0 小端口驱动的初始化流程、OID 查询与设置、发送接收路径、PNP 电源管理和任务卸载等实现方法并能参考其中对真实硬件的寄存器操作与中断逻辑适合希望从官方示例走向真实硬件开发的中高级开发者。 做网络驱动开发的人迟早都要直面 NDIS 小端口驱动这个绕不开的关卡。Windows 下面网卡要工作协议栈要发包收包全都依赖你写的这一个小模块。说实话小端口驱动在我眼里是整个 NDIS 体系里最“拧巴”的一层它既要贴着硬件寄存器打交道又要按 NDIS 的抽象规则办事稍不留神就是蓝屏或者网卡掉线。这篇文章就围绕 NDIS 小端口驱动miniport driver 在以太网卡上的开发实践把架构思路、关键流程、收发路径和掉坑经历都拉出来聊一遍希望给正在做或准备做这一块的同行一点参考。1. 整体设计思路为什么网卡驱动要“小端口化”1.1 NDIS 这套机制到底解决了什么问题先不要一上来就看代码。你得先理解 NDIS 为什么要把驱动设计成这种奇怪的结构。Windows 的网络驱动不是像 Linux 那样直接一头扎进协议栈而是在中间插了 NDISNetwork Driver Interface Specification这个库层。你可以把 NDIS 理解成一个“超级中介”它向上给 TCP/IP 协议栈提供统一的发送接收接口向下给各种网卡驱动提供统一的硬件访问抽象。这样一来网卡厂商不用关心协议栈内部怎么组织报文只需要按要求实现 NDIS 规定的回调函数然后把自己的网卡能力注册进去。反过来微软也不用为每一块网卡去适配协议栈只要各厂商按 NDIS 规范写好驱动大家各司其职。这就是为什么网络驱动领域的现状是“协议栈基本不用动网卡驱动换了一代又一代”。小端口驱动就是这套机制里最底层的那一棒。它负责管理网卡的初始化、启动、停止、数据收发、中断处理、电源管理以及硬件卸载能力比如校验和计算、TCP 分段卸载这类活儿。名字叫 miniport但它干的绝不是小活儿反而是一切上层功能能不能落地的地基。1.2 谁是 NDIS 体系里的“上下游”想知道小端口驱动怎么定位就得把它放进整个网络驱动栈里看。从顶到底大概是这样的应用层程序浏览器、邮件客户端等Winsock / 用户态 APITDI / Winsock Kernel现在基本都是 Winsock Kernel即 WSK协议驱动TCP/IP 协议栈比如 tcpip.sysNDIS 库ndis.sys小端口驱动miniport driver网卡硬件也就是说小端口驱动夹在 NDIS 和硬件之间。它要做的事分两类一类是“上行”就是网卡收到数据后通过中断或轮询告诉驱动驱动把数据封装成 NDIS 能认识的结构NET_BUFFER_LIST再交到 NDIS 层另一类是“下行”NDIS 把协议栈发下来的数据包交给小端口驱动驱动负责把包塞进硬件发送队列然后操控 DMA 或者 PIO 让数据从网线出去。很多新手容易把“小端口驱动”和“网卡驱动”划等号事实上小端口驱动只是网卡驱动在 NDIS 框架下的一种形态。如果你的网卡还需要支持 Wake-on-LAN、虚拟机队列VMQ、单根 I/O 虚拟化SR-IOV之类的高级功能那还会有更多细分模块配合。但无论怎么扩展最核心的数据通道永远绕不开小端口驱动这一层。1.3 开发方案选型NDIS 6.x 起步别走老路如果你现在才刚开始设计一个新的以太网卡驱动我的建议非常明确直接采用 NDIS 6.x特别是 Windows 10/11 和 Server 2016 以后对应的高版本。不要再用 NDIS 5.x 的老接口写新代码虽然某些老代码在网上还能查到但系统兼容性、性能表现、调试工具链都已经不在一个水平线上。NDIS 6.x 最大的变化是收发路径上引入了 NET_BUFFER 和 NET_BUFFER_LIST 这套池化结构。相比 5.x 时代的 OOB 数据块和更复杂的内存管理6.x 的模型要清爽得多发送数据支持异步完成驱动可以同时挂起大量数据包配合多核处理器做 RSS接收端缩放也非常顺畅。你写驱动的时候应该把“一包一请求”这种老思路彻底扔一边改成“批量提交、批量完成”的思维模式。2. 小端口驱动的核心结构和工作机制2.1 注册入口DriverEntry 这一步该干什么每个 NDIS 小端口驱动都有一个入口函数叫 DriverEntry但它做的事情和普通 WDMWindows Driver Model驱动不太一样。除了常规的驱动对象初始化外它最核心的任务是填一个 NDIS_MINIPORT_DRIVER_CHARACTERISTICS 结构体这个结构体就像一份“能力声明书”告诉 NDIS“我能处理哪些回调函数我支持哪些特性我需要的头节点大小是多少。”比如这样一段典型的注册代码NDIS_MINIPORT_DRIVER_CHARACTERISTICS mpChars; NdisZeroMemory(mpChars, sizeof(mpChars)); mpChars.Header.Type NDIS_OBJECT_TYPE_MINIPORT_DRIVER_CHARACTERISTICS; mpChars.Header.Size sizeof(mpChars); mpChars.Header.Revision NDIS_MINIPORT_DRIVER_CHARACTERISTICS_REVISION_2; mpChars.MiniportInitializeEx MpInitialize; mpChars.MiniportHaltEx MpHalt; mpChars.MiniportShutdownEx MpShutdown; mpChars.MiniportResetEx MpReset; mpChars.MiniportSendNetBufferLists MpSendNetBufferLists; mpChars.MiniportReturnNetBufferLists MpReturnNetBufferLists; mpChars.MiniportCancelSend MpCancelSend; mpChars.MiniportDevicePnPEventNotify MpDevicePnPEventNotify; mpChars.MiniportOidRequest MpOidRequest; mpChars.MiniportCancelOidRequest MpCancelOidRequest; mpChars.MiniportInterruptDPC MpInterruptDpc; mpChars.MiniportDisableInterruptEx MpDisableInterrupt; mpChars.MiniportEnableInterruptEx MpEnableInterrupt; NdisMRegisterMiniportDriver( DriverObject, RegistryPath, NULL, mpChars, mpDriverHandle );这段代码没有做太多“业务”但它是整个驱动的生命线。只要这里漏配一个回调函数后面网卡初始化就可能找不到入口或者系统在某种特定场景下调用空指针直接蓝屏。我见过不少同事抄老代码忘了填 MiniportShutdownEx结果在系统休眠唤醒测试时翻车。注册完成之后NDIS 会调用你提供的 MiniportInitializeEx。这个函数把真正的硬件初始化工作捡起来但它不是简单地把寄存器写一遍就完了而是要和 NDIS 反复交互完成资源注册、能力上报等动作。2.2 初始化流程从 PnP 到可用的完整链路小端口驱动的初始化在设备驱动领域算是比较复杂的异步流程。它不像普通总线驱动那样你在 AddDevice 里一口气做完所有准备工作就返回成功。NDIS 小端口驱动讲究“分段完成”这既是机制设计的结果也是现实硬件的需求。当系统检测到你的以太网卡出现在 PCIe 总线上时PnP即插即用管理器会找到对应的驱动然后触发 NDIS 调用你的 MiniportInitializeEx。这个回调里你需要做以下这些事读取 PCIe 配置空间获取 BAR 地址、中断资源、DMA 掩码等信息。映射 MMIO内存映射 I/O寄存器到系统虚拟地址空间。分配 DMA 资源包括 DMA 适配器对象、公共缓冲区Common Buffer等。初始化硬件状态比如关闭收发引擎、设置 MAC 地址、配置流控寄存器。调用 NdisMSetMiniportAttributes 上报网卡的类型、媒体类型、MAC 地址等关键属性。注册中断调用 NdisMRegisterInterruptEx关联中断服务例程ISR和延迟过程调用DPC。创建收发队列预分配接收缓冲区池。最后启动硬件收发引擎。关键点在于MiniportInitializeEx 可以返回 NDIS_STATUS_PENDING然后真正干完所有工作后通过 NdisMInitializeComplete 回调通知 NDIS。这种异步机制的好处是如果硬件需要的复位时间比较长驱动不必一直占着系统线程不放手。对 PCIe 网卡来说复位 固件加载动辄要几十毫秒甚至更久同步等待只会拖慢开机速度。2.3 头节点私有空间的妙用NDIS 初始化时有个容易被忽略的参数头节点大小HeaderNodeSize。这个参数会告诉 NDIS在分配 NET_BUFFER_LIST 的时候额外多留出一块空间给你存放私有上下文比如硬件描述符的索引、DMA 映射信息、时间戳数据等。我强烈建议在这个私有空间里至少放两种信息一个是这个包对应的物理地址或者 DMA 映射描述符另一个是包的状态标志位。这样一来发送完成和接收指示时驱动可以直接从 NBLNET_BUFFER_LIST里拿回自己的私有数据而不用再做一次哈希查找或者链表搜索性能损耗可以压到最低。对于多队列网卡私有空间里也可以放队列 ID。比如你的网卡有 4 个 TX 队列驱动可以在发送时根据包的 FlowHash 或者 CPU ID 选中队列然后把队列编号塞进私有空间这样完成中断回来的时候DPC 就知道该去清理哪个队列的完成队列项了。3. 收发路径的实操实现数据是怎么跑起来的3.1 接收路径中断、DPC 与 NBL 交付以太网卡的接收路径是整块驱动设计里最容易出问题的地方。物理网卡收到报文以后会通过 DMA 把数据写到驱动预先准备好的缓冲区里然后触发中断MSI-X 中断通常按队列分配CPU 进入 ISR。ISR 里不能做太多工作基本原则是“赶紧关中断把脏活交给 DPC延迟过程调用”。标准的做法是ISR 里读中断状态寄存器确认是哪个队列产生了接收完成事件然后调用 NdisMQueueDpc 把对应队列的 DPC 排入执行队列。DPC 里再去做实际的数据搬运、解析完成描述符、构建 NBL 等工作。我说的“构建 NBL”直观上是把网卡 DMA 写好的接收缓冲区包成 NDIS 标准的 NET_BUFFER_LIST 结构。关键点是你的接收缓冲区本来就是从 NDIS 池里分配的所以这里不需要拷贝数据只需要把缓冲区地址、长度、校验和状态等信息填进 NBL然后调用 NdisMIndicateReceiveNetBufferLists 把数据“顶”给 NDIS。如果网卡的 DMA 引擎要求地址连续你就要注意缓冲区分配方式。简单的做法是初始化时为每个 RX 队列分配一个固定大小的环形缓冲区池每个缓冲区都是一个物理页大小这样 DMA 的地址映射最简单一个页面一段 DMA 映射不涉及跨页拼接问题。硬件能力更强的网卡可以支持多段描述符一个缓冲区可以拆成多个不连续的物理块但这对 DMA 描述符的编程复杂度又上了一个台阶。性能优化方面轮询模式也就是 Linux 上的 NAPI 那种思路在 Windows 上也有对应物但那属于砍掉中断、纯轮询收包的进阶玩法。普通驱动先把“中断触发 DPCDPC 里批量处理”这条路走稳性能已经能说过去先别急着搞花活。3.2 发送路径异步完成是核心语义小端口驱动的发送回调是 MiniportSendNetBufferLists它接收一个 NBL 链表。对于网卡驱动来说你拿到这批 NBL 以后不能简单地把数据往硬件队列里一丢就返回而是要理解 NDIS 的异步完成语义。协议栈把数据包交给你不是“交给你处理完了就完了”而是“暂时由你托管你必须在自己认为合适的时候通过 NdisMSendNetBufferListsComplete 通知 NDIS 这些包已经处理完了”。如果网卡的 TX 队列满或者硬件正在忙你可以先挂起这些 NBL等硬件有能力消费了再处理。这个完成时间点非常重要因为协议栈要依赖这个完成事件来释放缓冲区资源。实际开发中最简单可靠的 TX 路径是这样的遍历 NDIS 传来的 NBL 链表。为每个 NBL 做 DMA 映射如果硬件需要物理地址。把物理地址和长度写入 TX 描述符环。更新硬件寄存器中的尾指针触发 DMA 引擎发送。保存 NBL 指针到软件环等待发送完成中断。中断回来之后遍历完成描述符对已完成包调用 NdisMSendNetBufferListsComplete。这里容易犯的错误是忘记考虑“映射失败”的情况。如果某个 NBL 因为 DMA 资源不足而无法映射你不能就这么卡在发送路径里什么都不干而是应该立刻把失败包还回去调用 NdisMSendNetBufferListsComplete 并设置完成状态为失败协议栈才能正确释放并重传。3.3 中断处理ISR / DPC 怎么配合才不丢中断中断处理设计得不好网络驱动的性能就废了一半。以太网卡走 MSI-X 中断是主流每个队列一个中断向量这样多核 CPU 可以并行处理多个队列的收发这就是 RSS接收端缩放在中断层面的硬件基础。ISR 里必须火速判断“这个中断是不是我设备的”。读状态寄存器如果不是立刻返回 FALSE让 NDIS 继续找别的设备。如果是就要在 DPC 里关掉这个队列的中断防止出现同一个中断持续占用 CPU 的情况。DPC 里把所有收包都处理完了再通过 NdisMEnableInterruptEx 重新打开中断。这里有个老鸟都懂的坑中断丢失。如果你的硬件在高负载下把中断合并Interrupt Coalescing的阈值调得太大DPC 还没来得及处理完新包就已经入队并触发了新的中断但此时中断已经被你关了结果就是数据滞留在 DMA 缓冲区里无人问津。解决办法是在 DPC 收尾阶段再检查一次硬件状态如果发现 RX 完成队列里还有新描述符没处理就继续循环处理直到清空为止最后再重新开中断。3.4 硬件卸载别把校验和计算浪费在 CPU 上现在的高性能网卡基本上都支持硬件校验和计算Checksum Offload、TCP 分段卸载LSO等功能。你作为小端口驱动开发者要在初始化的时候通过 NdisMSetMiniportAttributes 上报这些能力同时正确处理 NDIS 传来的 OID 请求。比如协议栈发送一个非常大的 TCP 报文段如果 LSO 开启这个报文段的长度可能会超过 MSS 好几倍驱动不能直接把它塞给硬件相反驱动要把这个负载的段大小信息解析出来填到硬件描述符里让网卡自己拆分并且给每个分段补上 TCP 头和 IP 头。如果你对这个机制不熟最容易出现的问题就是网卡发出去的包不对粘包、校验失败、对端不认账。启动加载卸载能力之后务必要用真实的 TCP 大文件传输测试一下不要只看驱动加载不蓝屏就以为万事大吉。我见过一个项目网卡驱动收包正常但上传大文件时服务器端收到的包总是比预期大查了半天才发现是 LSO 的段大小字段填错了一个字节。4. 设备管理OID 请求、PnP 事件和电源管理4.1 OID 请求查询与设置的正确姿势NDIS 对网卡的管理大多数是通过 OIDObject Identifier请求来完成的。比如协议栈想知道网卡的 MAC 地址、链路速度、MTU 大小或者想让网卡进入休眠模式都会通过 OID 找上门来。你的驱动需要实现 MiniportOidRequest 回调。这个回调接收一个 NDIS_OID_REQUEST 结构里面包含请求类型查询或设置、OID 编号、数据缓冲区等。核心逻辑就是 switch-case 各种 OID把对应数据填回去或者把数据取出来操作硬件。新手最容易掉进去的坑是 OID 请求的完成方式。和发送路径一样OID 请求也是可以异步完成的。如果你的驱动要查询硬件寄存器或者等待固件响应不可能在 OID 回调里同步阻塞这时候应该把请求挂起返回 NDIS_STATUS_PENDING等硬件操作完成后再调用 NdisMOidRequestComplete 完成它。记得在驱动卸载时要把所有挂起的 OID 请求都取消并完成否则系统会认为你的驱动还“忙”导致卸载过程被阻塞或者直接提交失败。4.2 电源管理休眠唤醒的细节决定成败现代系统对电源管理要求很严格。以太网卡支持 WoLWake-on-LAN已经是标配所以小端口驱动必须配合 NDIS 处理设备从 S0工作状态到 S3/S4 的转换以及从低功耗状态唤醒回工作状态的完整流程。这个过程中会有 MiniportDevicePnPEventNotify 之类的回调通知驱动驱动需要保证在低功耗状态下网卡的基本管理能力仍然可用。如果你的网卡有多个功耗状态D0/D1/D2/D3驱动还得通过 NdisMIdleNotification 配合 NDIS 完成空闲检测和选择性挂起。我通常的做法是在 D0 状态正常收发当系统进入 S3 前驱动要把收发引擎停掉、中断关闭但保留网卡的 magic packet 检测逻辑唤醒后再把收发引擎重新启动完成必要的复位操作。想当然地以为“不需要特别处理电源”的驱动轻则导致系统无法进休眠重则唤醒后网卡直接失效只能重启才能恢复。4.3 设备移除和意外移除的兜底逻辑PCIe 设备支持热插拔所以驱动必须处理设备在任何时刻被拔掉的场景。NDIS 会调用你的 MiniportDevicePnPEventNotify同时可能触发 MiniportHaltEx。这时候你的驱动要做的第一件事是停止一切新请求的接受然后取消挂起的 DMA 操作释放中断资源最后释放缓冲区池和 DMA 资源。很多驱动崩溃问题出在设备已经被移除的时候驱动还在做 MMIO 操作。设备不见了你访问它的寄存器就可能导致总线错误。规避方法是在驱动的所有关键路径里都检查一个“设备已移除”的 Flag一旦置位就放弃操作并立刻返回失败。5. 常见问题与排查技巧那些年蓝过的屏、掉过的线5.1 初始化失败的各种“疑难杂症”初始化是驱动开发的“第一大关”也是问题高发区。最常见的现象就是设备管理器里网卡显示黄色感叹号系统事件日志里写着“设备无法启动”。这种情况一大半原因是 MiniportInitializeEx 返回了失败状态。每次 NdisMSetMiniportAttributes 调用后最好检查一下返回值虽然大多数情况下这个调用会成功但一旦属性结构内部出现版本不匹配比如你填了较新的 Revision而系统不认返回错误后你还继续往下走初始化最终就必然失败。这类“后续失败”往往很难排查所以早期把每个关键调用都检查好能省掉很多调试时间。5.2 接收丢包不只是硬件的问题我遇到过驱动在低负载下收发全部正常但只要打满带宽就开始丢包的情况。一部分原因确实是 DMA 缓冲区不足但对于多队列网卡还有一个容易被忽视的因素是 RSS 散列不均。如果系统的 RSS 密钥配置或哈希类型选择和硬件支持项不一致就会出现某些 CPU 队列过载、其他 CPU 空闲的现象间接导致接收处理不过来。解决思路有两个层面一个是驱动层面做动态负载均衡根据 DPC 执行时间和队列深度动态调整哈希输入一个是在较高层设置里调整 RSS 参数比如通过 netsh 命令设置 RSS profile。但归根结底驱动应该提前把所有队列都初始化为同等深度然后让硬件自己把包散列到不同队列避免处理过程成为瓶颈。5.3 调试辅助WinDbg 和 NDIS 提供的保命工具做小端口驱动手里不能没有一套好用的调试工具。WinDbg 是标配配合 NDIS 扩展命令!ndiskd可以查看 adapter 状态、NBL 链、OID 请求队列等。比如用 !ndiskd.netadapter 查看你的网卡适配器是否成功注册用 !ndiskd.miniport 查看小端口驱动的实时状态。如果驱动导致系统蓝屏抓 dump 分析是最直接的路径。在驱动里加上 WPP 软件跟踪基于 ETW 的日志机制也是一个好习惯运行期间可以实时打开日志看代码执行流方便快速定位是硬件异常还是逻辑错误。我的习惯是在发送完成、接收指示、OID 完成这些关键路径里都加上 WPP 日志线上出问题时开启 trace基本三轮之内就能锁到问题点。这比单纯用调试器断点强太多因为断点会改变时序很多驱动问题恰恰是时序敏感型你一打断点它就不复现了。6. 总结之外一点实在的开发建议前面已经把 NDIS 小端口驱动的架构、数据路径、设备管理、问题排查讲得比较透了。最后再分享几个我从项目里硬踩出来的经验。第一个建议是先别急着写大量逻辑先用“最小驱动”把网卡从设备管理器里跑起来。所谓最小就是只实现 DriverEntry、MiniportInitializeEx、MpHalt、以及最基础的 OID 回调让系统能正确枚举网卡并能配置 IP。这一步通了相当于整个驱动框架的“地基”稳了再做收发路径会轻松很多。第二个建议是管理好你对 NDIS 对象的生命周期理解。你在驱动里拿到的 NBL 并不天然属于你你要么尽快把它返回给 NDIS要么在拿到后接管它的所有权并且明确自己必须在什么时候归还。这个“所有权”思维理不清内存泄漏和双重释放跑不掉。第三个建议是经常做压力测试和异常拔插测试。驱动开发能不能交付不在于功能跑通而在于异常情况下还站得住。强制断电前拔卡、长时间满带宽打流、休眠唤醒循环几百次这些场景只要能稳住上线后大概率不会掉链子。做小端口驱动很磨人但掌握了 NDIS 的这套规矩再把硬件细节抠透你会发现这个领域其实非常“讲道理”。模块之间怎么配合、请求怎么流转、异常如何处理都有一整套规则在那摆着。你遵循它它就是最可靠的地基你想偷懒绕过它它就会用蓝屏教你做人。本文还有配套的精品资源点击获取