【转帖】DriverNetwork miniport驱动学习

朴灿烈づ我的快乐病毒、 2022-08-24 00:41 299阅读 0赞

**DriverNetwork miniport** **驱动学习（** **1** **）**

NDIS Miniport驱动框架介绍  
NDIS miniport adapter 类继承了 KNdisMiniAdapter 类并且声明了处理程序所需的signatures，例如Initialize(), Halt()和 Reset()。它们可以是虚拟的或者非虚拟的，或是派生类内联成员。对于这些处理程序的命名和DDK很接近。例如Initialize()对应MiniportInitialize(),Halt()对应MiniportHalt()。这些处理程序的处理过程和IRQL级与相应的DDK处理程序类似。  
下面的UML类图表描述了DriverNetworks框架类和驱动开发者实现的类之间的关系。驱动开发者提供的类用黄颜色显示。  
驱动开发者主要提供两个类  
• KNdisMiniDriver-继承 driver 类  
• KNdisMiniAdapter-继承 adapter 类  
注意:Network Driver Wizard应用程序将为NDIS驱动项目自动生成这两个类。  
在驱动安装之前，框架调用adapter的DriverEntry()方法，该方法将在NDIS中注册adapter。注册由帮助模块类KNDIS\_MINIPORT\_CHARACTERISTICS处理，它将一组adapter支持的处理程序提交给NDIS。默认的处理程序集合以及其他miniport特征都在帮助模块类中说明,KNdisAdapterTraits。每个miniport驱动项目都包括一个头文件Characteristics.h，这可以用来重新定义特殊adapter的某些特征（例如，处理程序集合）。  
Adapter注册完成之后，NDIS开始调用adapter的处理程序。这些处理程序通过框架模块类KNdisWrapper从NDIS中调用。对每个adapter类A，框架都用具体的例子说明KNdisWrapper的实现，KNdisWrapper转发NDIS回调给正确的A定义的处理程序。驱动开发者不必实现QueryInformation()和SetInformation()处理程序，这两个程序用来处理NDIS OIDs。在DriverNetworks中，框架通过OID maps来实现对OID的处理。  
任何一个KNdisMiniAdapter派生类的实体都由DriverNetworks框架自动创建。因此不必为adapter调用new()。框架负责向NDIS注册，解释原始NDIS的MiniportInitialize()的回调，并创建adapter类的一个实体。创建实体之后，框架将控制提交给派生类的Initialize()处理程序。Initialize()处理程序执行必要的定制步骤，例如声明硬件资源和NIC初始化。从Initialize()处理程序成功的返回，adapter才能被系统使用。  
KNdisMiniAdapter派生对象的消除也由框架处理。在消除之前立即调用Halt()处理程序。Adapter类执行硬件特性的shutdown，资源回收等等。当miniport通过控制面板或者系统shutdown时，才调用Halt()处理程序。  
NDIS Miniport Driver Handler Signatures  
class CMyAdapter : public KNdisMiniAdapter \{  
public:  
// Initialization and shutdown  
NDIS\_STATUS Initialize(IN OUT KNdisMedium& Medium, IN KNdisConfig& Config) ;  
VOID Halt(VOID);  
NDIS\_STATUS Reset(OUT PBOOLEAN AddressingReset);  
void Shutdown(VOID);  
// OID requests  
NDIS\_STATUS QueryInformation(  
IN NDIS\_OID Oid,  
IN PVOID InformationBuffer,  
IN ULONG InformationBufferLength,  
OUT PULONG BytesWritten,  
OUT PULONG BytesNeeded  
) ;  
NDIS\_STATUS SetInformation(  
IN NDIS\_OID Oid,  
IN PVOID InformationBuffer,  
IN ULONG InformationBufferLength,  
OUT PULONG BytesRead,  
OUT PULONG BytesNeeded  
) ;  
// Sending packets  
VOID SendPackets(  
IN PPNDIS\_PACKET PacketArray,  
IN UINT NumberOfPackets  
) ;  
VOID ReturnPacket(IN PNDIS\_PACKET Packet);  
  
// overridables for interrupt-driven miniports  
BOOLEAN CheckForHang() ;  
VOID DisableInterrupt() ;  
VOID EnableInterrupt() ;  
VOID HandleInterrupt() ;  
VOID Isr(OUT PBOOLEAN InterruptRecognized,  
OUT PBOOLEAN QueueMiniportHandleInterrupt ) ;  
\};  
提示: 最容易熟悉框架的途径就是启动Network Driver Wizard生成一个基本 NDIS miniport 或者NDIS IM 驱动项目。

**DriverNetwork miniport****驱动学习（****2****）**

声明硬件资源  
Windows NT和Windows 2000定义了四种基本外围设备的硬件资源，例如NIC:  
• I/O Ports  
• Interrupt  
• Memory  
• DMA  
枚举类型CM\_RESOURCE\_TYPE定义在ndis.h文件中,用于确定资源类型。  
每一类资源都具有CM\_PARTIAL\_RESOURCE\_DESCRIPTOR 结构描述的一组属性，该结构也定义在ndis.h文件中。例如， I/O端口属性包括I/O端口基地址，I/O端口长度范围等等。  
DriverNetworks将硬件资源抽象成KNdisResource< CM\_RESOURCE\_TYPE>模块，提供了查询资源属性的访问方法。  
NDIS Miniport 驱动处理硬件资源一般有以下三步：  
1） Query the system 查询系统有关分配给miniport的硬件资源信息。  
2） Query the attributes 查询每个资源的属性。  
3） Initialize system objects 基于属性对系统对象初始化(例如， Interrupt 和I/O端口范围) 。  
1．查询系统有关分配给miniport的硬件资源信息  
根据NDIS版本和NIC总线类型，查询系统有许多不同的方法。NDIS4驱动采用总线特有的请求来完成Pre-PnP。DriverNetworks提供了两个类来完成该过程：KNdisPciResourceRequest和KNdisParamResourceRequest。  
在NDIS 5中，PnP管理器处理所有硬件资源，包括non-PnP设备。对于NDIS 5驱动，系统采用非总线特有的KNdisPnpResourceRequest来查询，这是基于NdisMQueryAdapterResources的。尽管所有其他的NDIS 5资源请求类都很好用，但是一般还是习惯用KNdisPnpResourceRequest来查询硬件资源。  
一般在Initialize()处理程序中对正确的请求初始化来实现系统查询。例如：  
KNdisPciResourceRequest req(this);  
2．查询属性和初始化系统对象  
在无论采用什么查询方法查询系统之后，接下来就要完成属性查询和初始化系统对象。访问每一个资源都要求对正确资源类型初始化。例如：  
KNdisResource nt(req);  
上面初始化一个中断资源描述符。  
当系统对象初始化后，可以利用资源属性创建一个正确的系统对象。例如：  
m\_pInterrupt = new KNdisInterrupt(this,Int.Level(), Int.Affinity());  
通过IsValid()方法检查错误，来确保资源对驱动来说是可用的。下面的代码示范了获得中断和I/O端口资源的技术：  
NDIS\_STATUS MyAdapter::Initialize(KNdisMedium& Medium, IN KNdisConfig& Config)  
\{. . .  
// get h/w resources  
KNdisPnpResourceRequest request(Config); // how do we query  
KNdisResource Port(request); // what do we query  
KNdisResource Int(request); // what do we query  
// Make sure the resources are available  
if (!Port.IsValid())  
KNDIS\_RETURN\_ERROR (NDIS\_STATUS\_NOT\_ACCEPTED);  
if (!Int.IsValid())  
KNDIS\_RETURN\_ERROR (NDIS\_STATUS\_NOT\_ACCEPTED);  
// Register i/o port range system object:  
m\_Ports.Initialize(this, Port);  
if (!m\_Ports.IsValid())  
KNDIS\_RETURN\_ERROR (NDIS\_STATUS\_RESOURCES);  
// Register interrupt system object:  
m\_Interrupt.Initialize(this, Int, NdisInterruptLatched);  
if (!m\_Interrupt.IsValid())  
KNDIS\_RETURN\_ERROR (NDIS\_STATUS\_RESOURCES);  
. . .  
// OK!  
return NDIS\_STATUS\_SUCCESS;  
\}

**DriverNetwork miniport****驱动学习（****8****）**

NDIS Miniports实现OID处理  
NDIS采用对象标示符OID，在DDK的ntddndis.h中定义，重新定位和设置NDIS miniport驱动的各种配置和操作参数。每一个OID代表了一个32位值，与正确的数据结构一起通过MiniportQueryInformation 和MiniportSetInformation处理程序提交给驱动。  
DDK类型NDIS驱动一般都要实现OID处理过程，通过MiniportQueryInformation和MiniportSetInformation内一个比较长的switch statement。另一方面，DriverNetworks开发了一种消息映射方法，将每个OID当作一个消息由特定的OID处理程序处理。  
OID消息映射方法允许你将OID请求分析和特殊OID处理过程分开，这样就增强了可读性和可维护性。  
1．OID 消息映射  
OID 消息映射就是一组宏状态声明支持某种NDIS OIDs并实现OID消息解码cracker 。例如：  
// "查询" 映射  
BEGIN\_OID\_QUERY\_MAP(MyAdapter)  
OID\_QUERY\_ENTRY (OID\_GEN\_HARDWARE\_STATUS)  
OID\_QUERY\_ENTRY (OID\_GEN\_MEDIA\_SUPPORTED)  
. . .  
END\_OID\_QUERY\_MAP  
// "设置"映射  
BEGIN\_OID\_SET\_MAP(MyAdapter)  
OID\_SET\_ENTRY( OID\_GEN\_CURRENT\_LOOKAHEAD)  
OID\_SET\_ENTRY( OID\_GEN\_CURRENT\_PACKET\_FILTER)  
OID\_SET\_ENTRY( OID\_GEN\_PROTOCOL\_OPTIONS)  
. . .  
END\_OID\_SET\_MAP()  
NDIS miniport项目包含了两个映射：一个是查询请求，一个是设置请求。每一个OID映射就是一块在BEGIN\_OID\_MAP和END\_OID\_MAP宏状态之间的宏块组成，对应着MyAdapter::QueryInformation()和MyAdapter::SetInformation()处理程序的实现。Network Driver Wizard生成的NDIS Miniport项目包括含有映射定义的XxxOids.cpp文档。  
在映射中，OID\_QUERY\_ENTRY (or OID\_SET\_ENTRY) 声明支持对特定的OID。因此编译器能生成代码来激活一个相应的OID处理程序。  
OID消息映射在内部可以执行必要的样本文件OID分析代码，例如检查输入/输出缓冲大小匹配。OID映射可以实现为一种C switch statement，它与DDK miniport驱动的运行效率一样。  
2．OID 处理  
DriverNetworks OID处理程序是KNdisMiniAdapter派生类的一个成员函数，用来处理特殊的NDIS OID请求。OID处理程序由OID消息映射中激活。 DriverNetworks 定义了OID处理程序的命名习惯和函数原型。对于OID 常量OID\_XXX\_YYY的命名习惯是： getOID\_XXX\_YYY() 是查询信息请求； setOID\_XXX\_YYY()是设置信息请求。  
OID查询（获得）处理程序的三种有效形式：  
1） short property（返回一个T类型的值）：  
T getOID\_XXX\_YYY ();  
2） short handler（返回NDIS\_STATUS，如果成功――T类型的值）  
NDIS\_STATUS getOID\_XXX\_YYY (T\* pValue);  
3） variable-size handler（返回NDIS\_STATUS，如果成功――变量矩阵）  
NDIS\_STATUS getOID\_XXX\_YYY(T\* pValue,IN OUT PULONG ByteCount, OUT PULONG ByteNeeded);  
OID设置处理程序的两种有效形式：  
1）short property（接收一个T类型值，返回NDIS\_STATUS）  
NDIS\_STATUS setOID\_XXX\_YYY (T\* pValue);  
2）variable handler（接收一个变量矩阵，返回NDIS\_STATUS）  
NDIS\_STATUS setOID\_XXX\_YYY (T\* pValue,IN OUT PULONG ByteCount, OUT PULONG ByteNeeded);  
为了决定选择哪一种特定OID处理程序，DriverNetworks开发一种C++技术基于OID属性为给定的OID来选择一个处理程序原型。OID属性参考OID Traits。DriverNetworks基于对既定OID的常规处理为大多数NDIS OIDs定义了OID Traits。例如，大多数NDIS miniport驱动都对OID\_GEN\_MAXIMUM\_FRAME\_SIZE查询响应并返回某些常数值。查询的第一种形式是OID消息映射激活的默认选择。然而，C++ traits技术允许忽略很多细节。（参看OID Traits）。  
DriverNetworks并不限制处理程序怎样实现的，只要它们的特征和上面的一种形式匹配就可以了。例如，short property处理程序（查询和设置的第一种形式）一般都是内联的或者静态的，和DDK的实现具有一样的运行效率。  
3．OID Traits  
OID Traits声明了NDIS OIDs的属性，也就定义了OID消息映射使用的OID 处理程序的形式。The OID traits可以是可变的和也可以是不可变的。  
不可变的Traits声明了OID的本质属性，例如OID代表的值得长度。不可变traits从DDK的定义中派生而来的（参考表1.1 Network Drivers: Windows 2000）。在DriverNetworks中，不可变traits由KNdisOid模板类描述，并且通过KNdisOidTraitsBase模板类直接交给用户。这些模板的参数都是OID\_XXX\_YYY常数值。DriverNetworks定义了下面的不可变traits：  
1）类型：代表给定OID的值的类型。  
2） ULONG 长度：值的字节长度 (通常有, sizeof(Type))  
3） bool IsVarSize():说明OID是描述一个类型Type的一个单元还是一个变量大小的矩阵。  
可变Traits声明了用户可修改的OID的属性。可变OID traits通过KNdisOidTraits模板类直接提供给用户。这个模板由KNdisOidTraitsBase类派生的，并且参数包括OID\_XXX\_YYY常量值和adapter类的类型。C++ 模板规范经过特殊处理后提供可变性。DriverNetworks定义了下面一些可变trait：  
•bool Failable():说明在给定的miniport驱动中OID查询请求曾经是否失败过。当一个OID查询返回的不是NDIS\_STATUS\_SUCCESS，就认为它是失败了。  
Failable()仅用于查询请求。所有的设置请求都认为是失败的。所有的查询请求默认为非失败的。用户通过为特殊的adapter类型定义Failable()，而不用考虑细节。例如：  
inline bool  
KNdisOidTraits::Failable() \{ return true; \}  
这样一来，对于给定的adapter――MyAdapter，查询链接速率可能会是会失败。因此，OID解码的MyAdapter::getOID\_GEN\_LINK\_SPEED()处理程序运用查询的第二种形式，而不是第一种形式。  
OID处理程序的形式根据IsVarSize和Failable traits来决定。下表总结了DriverNetworks基于OID traits选择正确的处理程序的形式。  
Request IsVarSize Failable Handler Form Comment/Example  
Query F F q1 Trivial const parameter  
Query F T q2 Run time read value  
Query T F q3 Input size might not be valid  
Query T T q3 Data array read from hardware  
Set F F N/A Set() can fail by definition  
Set T F N/A Set() can fail by definition  
Set F T s1 Set a single parameter value  
Set T T s2 Set an array of values  
  
4．添加和删除OID支持  
1）为专门的OID\_XXX\_YYY添加支持  
下面应该对项目文件XxxOids.cpp进行修改，并假设NDIS Miniport驱动项目由Network Driver Wizard生成的。  
1. 在需要支持的OIDs矩阵中添加OID\_XXX\_YYY 。也就是将OID\_XXX\_YYY符号插入到静态矩阵sm\_OID\_GEN\_SUPPORTED\_LIST\[\]中。注意：该矩阵OIDs的上升顺序不能被打乱。  
2. 如果要实现OID\_XXX\_YYY 的查询，在OID查询消息映射中插入一行OID\_QUERY\_ENTRY(OID\_XXX\_YYY)。如果已经实现了一组OID\_XXX\_YYY，就将OID\_SET\_ENTRY(OID\_XXX\_YYY)插入到OID查询消息映射中。  
3. 如果查询请求可能会失败或者是异步完成的，就可以不考虑Failable() trait 。这是可选的。  
4. 实现查询，如果可应用，那么基于上表描述的原型设置处理程序。  
2）为专门的OID\_XXX\_YYY删除支持  
假设NDIS Miniport驱动项目由Network Driver Wizard生成的。  
1. 注释sm\_OID\_GEN\_SUPPORTED\_LIST\[\]矩阵的OID\_XXX\_YYY；  
2. 从OID消息映射中注释OID\_QUERY/SET\_ENTRY。  
注意: 可以选择删除处理程序代码，因为这些代码将被优化掉。

**DriverNetwork miniport****驱动学习（****9****）**

KNdisLookahead类  
:  
KNdisLookahead抽象了完成部分分组的NDIS机制。Miniport驱动允许协议先检查接收帧的头部和一小部分内容。而不需要立即将整个帧都交给它。因此，协议要先调用介质相关NdisMXXXReceiveIndicate() API。协议然后调用MiniportTransferData处理程序来接收分组剩余内容。  
模板类KNdisLookahead封装了部分说明机制。该模板由两个参数：  
L ：最大Lookahead缓冲长度；缓冲创建在类内。  
M：介质类型；定义了怎样调用NDIS来说明帧；802.3是默认的。  
类的使用  
1. 在adapter 类中包括一个成员数据KNdisLookahead<> 。例如：  
KNdisLookahead<256> m\_Lookahead;  
2. 在adapter 类中, 提供下面的公共函数:  
UINT CopyDataUp(PVOID FrameBase, PUCHAR Buf, UINT Len, UINT Offset);  
这同步传输的内容有：长度Len，起始偏移Offset，缓冲Buf中当前帧的内容。The frame is identified by an opaque to the framework value FrameBase. 驱动开发者用硬件特定的方法使用FrameBase。也就是，它可能说明了卡上环形缓冲中当前帧的偏移地址。  
3. 在HandleInterrupt()处理程序中，在配置用来说明的接收数据长度和卡内存中的帧的FrameBase 之后，调用：  
m\_Lookahead.Indicate (this, header\_len, lookah\_len, packet\_len, FrameBase);  
这样帧的lookahead部分将存入KNdisLookahead实体中，并且接着调用NDIS来说明lookahead。因此NDIS就可以将lookahead展示给捆绑的协议。如果协议对该分组感兴趣，控制权将转到适配的TransferData()处理程序。参看第五步。FrameBase值存在类中并且当调用CopyDataUp()时就回传给CopyDataUp()。如果在硬件中存在多个接收帧，上面的过程就重复多次。  
4. 在离开HandleInterrupt()处理程序之前，至少要调用下面一次：  
m\_Lookahead.IndicateComplete(this);  
这样调用NDIS说明当前接收突发结束。  
5. 在TransferData()处理程序中调用：  
m\_Lookahead.Transfer(this, Packet, BytesToCopy, ByteOffset);  
这将传输当前帧的部分给协议提供的分组。该当前帧的部分是协议请求的且偏移量为ByteOffset。  
注意:在 m\_Lookahead.Indicate()和Adapter::TransferData()调用之前,连续 miniports不能被调用（除了中断）。完整交互过程都是DISPATCH\_LEVEL ，卡上的中断去能了。当调用TransferData()，当前帧部分存在m\_LookaheadData，部分仍然在卡上。KNdisLookahead::Transfer()知道从哪里传输数据。如果协议对该帧不敢兴趣，TransferData()处理程序就根本不调用。Lookahead缓冲将给下一个接收帧覆盖。  
Members  
KNdisLookahead

**DrvierNetwork miniport****驱动学习（****10****）**

前言   
 这一次重新研读 DriverNetwork 的有关 miniport 驱动的帮助文档，并以 DriverNetwork 中自带的 nmne2k 例子说明相应的知识点。   
  
 第一次重新学习内容： NDIS 的 miniport 驱动框架   
  
NDIS miniport 的 adapter 类继承了 KNdisMiniAdapter 类，主要声明了所需的例程，例如 Initialize(), Halt() 和 Reset() 。这些例程可以是虚拟的或者非虚拟的，或者是派生类内联的成员函数。这些例程和模块的命名和 DDK 一一对应： Initialize()  对应 MiniportInitialize() ； Halt()  对应 MiniportHalt() 。对这些例程的处理和 IRQL 级也和 DDK 相应的 MiniportXxxx() 一样。   
  
 参看文档 Understanding the NDIS Miniport Driver Framework 的图：该图描述了 DriverNetworks 框架类和驱动开发者要实现的类（黄颜色给出了）之间的关系。   
  
 驱动开发者提供了两个主要的类：   
1 ） KNdisMiniDriver 派生 driver 类： class NMNE2KDriver : protected KNdisMiniDrive  
driver 派生类负责向 NDIS 注册 miniport 的 adapter ，并且必须实现唯一的虚拟方法 KNdisMiniDriver::DriverEntry() 。 DriverEntry() 一般只要注册 KNdisMiniAdapter 派生的 miniport 的  adapter 类。在向 NDIS 注册了 adapter 之后， NDIS 立即调用 adapter 类的 Initialize() 例程。 DriverNetwork 框架要求源文件包括宏： DECLARE\_MINIDRIVER\_CLASS(DriverClass)  
  
2 ） KNdisMiniAdapter 派生 adapter 类： class NMNE2KAdapter : public KNdisMiniAdapter  
Adapter 类实现了全部的方法，分成两种类型： handlers 和 service 。 Handlers ：驱动提供给 NDIS 回调用的，例如 Initialize() ， Halt() 和 Reset() 等等。 NDIS 通过 KNdisWrapper 类调用这些 handlers 。对于每一个适配器类 A ，框架创建了一个 KNdisWrapper 的一个实现，将 NDIS 回调转发给 A 定义的正确的 handlers 。所需要的 handlers 都在 Characteristics.h 文件的宏 KNDIS\_MINIPORT\_HANDLER 声明了，而且都必须声明，如果在该头文件中声明而又没有在 adapter 类中实现， NDIS 就会调用默认的基类 handler ，报告 “Handler not implemented!Check Characteristics.h” 。 services 是 NDIS 提供给 miniport 调用的方法，这些服务通常由 handler 调用。   
Instantiation 过程： DriverNetwork 框架自动生成一个 KNdisMniportAdapter 派生类的实体。框架向 NDIS 注册，截取初始 NDIS 的 MiniportInitialize() 回调函数，并创建一个 adapter 类的实体。创建 adapter 实体之后，框架将控制权交给 Initialize() handler ， Initialize() 完成如下功能： 1 ）声明硬件资源 2 ）对 NIC 初始化。从 Initialize() 成功返回之后系统才能使用 adapter 。   
Destruction 过程： KNdisMiniportAdapter 派生对象的销毁也由框架实现。在销毁之前，调用 Halt() handler ，完成如下功能： 1 ）执行硬件关闭 2 ）释放在 Initialize() 声明的资源。   
 成员函数：   
KNdisMiniAdapter -  构造函数   
~KNdisMiniAdapter -  析构函数   
AllocateComplete -  共享内存分配完成  (handler)  
CancelSendPackets -  取消悬挂状态的发送分组 (handler)(NDIS5.1 only)  
 当捆绑的协议或者中间驱动执行 NdisCancelSendPackets 请求时，调用该 handle 。如果 miniport 将分组在内部排队，他应该遍历整个悬挂发送分组链表，并且取消每一个取消 id 和 CancelId 匹配的分组。   
CheckForHang -  检测适配器的悬挂条件  (handler)  
 这是一个可选 handler 。如果定义了该 handler ， NDIS 每两秒钟调用一次。如果 CheckForHang 返回真， NDIS 就调用驱动的 Reset() handler 。如果满足悬挂条件，就返回真。   
DisableInterrupt -  适配器中断去能  (handler)  
EnableInterrupt -  适配器中断使能 (handler)  
GetDeviceProperty