1. NDIS Intermediate Drivers Larry Cleeton Program Manager Windows Networking And Communications Microsoft Corporation

3. Agenda  NDIS Intermediate Driver Overview  Writing an NDIS Intermediate Driver  Installing an NDIS Intermediate Driver

4. Miniport Driver TCP/IP Miniport driver NDISNDIS.SYS Other Protocols

5. Intermediate Driver TCP/IP Miniport driver NDISNDIS.SYS OtherProtocols Intermediate driver

6. Intermediate Driver NDIS Miniport Interface NDIS Protocol Interface Internal Binding Relationship

7. Kinds Of Intermediate Drivers  Ndis Filter Intermediate Driver  Ndis Mux Intermediate Driver

8. Filter  One upper virtual miniport instance per lower bound adapter  Inserts itself into all existing protocol- to-miniport bindings  Upper and lower binding type equal  The number of interfaces to top-most protocols remains the same as the number of physical adapters  Filter miniport connections are hidden in User Interface

9. Filter Adapter 2 Adapter 1 Protocol Open Adapter 1 Open Adapter 2 Miniport External Bindings Miniport edge Filter Driver Protocol edge Open Adapter 1 Open Adapter 2 Virtual Adapter 1 Virtual Adapter 2 External Bindings Internal Bindings

10. Filter Examples  Windows ® 2000 Packet Scheduler  Layer 2 Firewall  Packet Capture

11. Mux  The number of upper interfaces can be different than the number of lower physical adapters  1-to-n, n-to-1, even m-to-n  Complicated internal bindings and data paths

12. Mux – 1 To n Adapter 2 Adapter 1 Protocol Open Adapter 1 Open Adapter 2 Miniport External Bindings Open Adapter x Miniport edge Mux Driver Protocol edge Open Adapter 1 Open Adapter 2 Virtual Adapter x External Bindings Internal Bindings

13. Adapter 1 Open Adapter 1 Mux – n To 1 Protocol Miniport External Bindings Open Adapter x Open Adapter y External Bindings Miniport edge Mux Driver Protocol edge OpenAdapter 1 Virtual Adapter y Virtual Adapter x External Bindings Internal Bindings

14. Mux Examples  n to 1  Windows 2000 ATM LAN Emulation  802 and proprietary Virtual LANs  1 to n  Non-miniport LBFO solutions

15. Writing A Driver  Use the Windows 2000 DDK  Learn NDIS miniport operations and functions  Learn NDIS protocol operations and functions  Design your intermediate model  Reference pass-through DDK sample

16. DriverEntry  Basically just registration:  NdisMInitializeWrapper  NdisIMRegisterLayeredMiniport  NdisRegisterProtocol  NdisIMAssociateMiniport

17. Dynamic Binding  An intermediate driver must support dynamic binding to lower edge adapters  Your driver controls the state of its upper edge miniports  Lower edge adapter binding state events are typically the trigger to start/stop the upper miniport(s)

18. Upper-Edge Initialize  Call NdisIMInitializeDeviceInstance(Ex) after an event like a lower adapter binding notification  Results in callback to your MiniportInitialize  NdisMSetAttributesEx  NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER  NDIS_ATTRIBUTE_DESERIALIZE

19. Upper-Edge De-Initialize  NDIS may call MiniportHalt anytime  Driver can call NdisIMDeInitializeDeviceInstance to cause the MiniportHalt to be called

20. Query/Set Information  Upper Miniport Edge – miniport request handlers are called  Lower Protocol Edge – do NdisRequest to query/set lower adapter  Filter - typically pass-through except  OID_PNP_SET_POWER  OID_PNP_QUERY_POWER  Mux – same rule but pass-through depends on design  Power management issues on later slides

21. Status Indications  Filter – typically pass up directly  Lower ProtocolStatus causes upper NdisMIndicateStatus  Mux – behavior depends on design  Power management issues on later slides

22. Packet Handling  NDIS_PACKET data structure is not designed for multilayered drivers  Packets must get new NDIS_PACKET descriptor as it passes up or down through the intermediate driver  Passthru sample has detailed examples  Packets that originate in the driver are created the same as a simple NDIS protocol driver

23. Power Management  NDIS gets power management events in no particular order  NDIS forwards them to protocols and miniport as appropriate  Intermediate drivers must be able to handle these events in any order and behave correctly

24. Reporting Power Capabilities  Handling OID_PNP_CAPABILITIES upper edge miniport query information call  Forward query down to lower edge adapter  Modify response before completing at upper edge - Override these params with NdisDeviceStateUnspecified  MinMagicPacketWakeUp  MinPatternWakeUp  MinLinkChangeWakeUp

25. Power Events  Events are called into both protocol and miniport handlers in no particular order  ProtocolPnPEvent  Miniport(Set/Query)Information  Maintain separate power state  For each upper miniport instance  For each lower open adapter  Maintain a “StandingBy” flag that is:  Set to True when either power state leaves D0  Set to False when either power state returns to D0

26. Using The Power States (1)  MiniportSend  Fail unless upper miniport and lower adapter are both D0  MiniportQueryInformation  Always succeed OID_PNP_QUERY_POWER to ensure getting OID_PNP_SET_POWER requests  Fail all other requests if miniport is not D0 or StandingBy is True  Queue single request if lower adapter is not D0, process when it becomes D0

27. Using The Power States (2)  MiniportSetInformation  Fail if miniport is not D0 or StandingBy is True  Queue single request if lower adapter is not D0, process when it becomes D0  ProtocolStatus  Only indicate on upper miniport edge if both lower edge adapter and upper miniport are D0  ProtocolPnPEvent  When lower edge adapter is transitioning away from D0, wait until outstanding lower edge sends and requests have completed

28. Filter Install  Two INF files  Class = Net INF for miniport edge  Class = NetService INF for protocol edge  NetService INF is what user installs  NetService INF references net INF with special NDI keys  Network Installer does all the work – installing service and miniport(s)

29. Filter INF keywords  FilterClass  scheduler  loadbalance  failover  FilterDeviceInfFile  FilterDeviceInfId  FilterMediaTypes

30. Mux Install  Two INF files  Class = Net INF for miniport edge  Class = Nettrans INF for protocol edge  Notify Object referenced in Nettrans INF  HKR, Ndi, ComponentDll, 0, "notifyobject.dll"  Nettrans INF is what user installs  Notify Object is responsible for installation of miniport(s )

31. What Is A Notify Object?  An extension of the Network Class Installer  A COM object housed in a DLL that is a COM component server  You put a reference to it in your Netservice or Nettrans INF  Network class installer does the equivalent of regsrv32 your.dll  Network class installer instantiates your object and sends it notifications of events related to your network driver

32. Mux Notify Object Requirements  Install/Remove upper-edge miniports  Manage the miniport device name list in the registry under the NetService  Control external bindings if necessary  Present additional property sheet for configuration (optional)

33. Call To Action  Carefully choose the right NDIS Intermediate driver model (Filters are simpler)  Write quality drivers  Test using NDIS tester

34. Discussion