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

NDIS Intermediate DriversNDIS Intermediate Drivers

Larry CleetonLarry CleetonProgram ManagerProgram ManagerWindows Networking And Windows Networking And CommunicationsCommunicationsMicrosoft CorporationMicrosoft Corporation

AgendaAgenda

NDIS Intermediate Driver OverviewNDIS Intermediate Driver Overview Writing an NDIS Intermediate DriverWriting an NDIS Intermediate Driver Installing an NDIS Intermediate DriverInstalling an NDIS Intermediate Driver

Miniport DriverMiniport Driver

TCP/IPTCP/IP

Miniport driverMiniport driver

NDISNDIS NDIS.SYSNDIS.SYS

Other Other ProtocolsProtocols

Intermediate DriverIntermediate Driver

TCP/IPTCP/IP

Miniport driverMiniport driver

NDISNDIS NDIS.SYSNDIS.SYS

OtherOtherProtocolsProtocols

Intermediate driverIntermediate driver

Intermediate DriverIntermediate Driver

NDIS Miniport InterfaceNDIS Miniport Interface

NDIS Protocol InterfaceNDIS Protocol Interface

Internal Internal Binding Binding

RelationshipRelationship

Kinds Of Kinds Of Intermediate DriversIntermediate Drivers Ndis Filter Intermediate DriverNdis Filter Intermediate Driver Ndis Mux Intermediate DriverNdis Mux Intermediate Driver

FilterFilter

One upper virtual miniport instance per One upper virtual miniport instance per lower bound adapterlower bound adapter

Inserts itself into all existing protocol-Inserts itself into all existing protocol-to-miniport bindingsto-miniport bindings

Upper and lower binding type equalUpper and lower binding type equal The number of interfaces to top-most The number of interfaces to top-most

protocols remains the same as the protocols remains the same as the number of physical adaptersnumber of physical adapters

Filter miniport connections are hidden Filter miniport connections are hidden in User Interfacein User Interface

FilterFilter

Adapter 2Adapter 2Adapter 1Adapter 1

ProtocolProtocolOpen Adapter 1Open Adapter 1 Open Adapter 2Open Adapter 2

MiniportMiniport

ExternalExternalBindingsBindings

Miniport edgeMiniport edge

Filter DriverFilter Driver

Protocol edgeProtocol edgeOpen Adapter 1Open Adapter 1 Open Adapter 2Open Adapter 2

Virtual Adapter 1Virtual Adapter 1 Virtual Adapter 2Virtual Adapter 2

External BindingsExternal Bindings


Internal BindingsInternal Bindings

Filter ExamplesFilter Examples

WindowsWindows®® 2000 Packet Scheduler 2000 Packet Scheduler Layer 2 FirewallLayer 2 Firewall Packet CapturePacket Capture

MuxMux

The number of upper interfaces The number of upper interfaces can be different than the number can be different than the number of lower physical adaptersof lower physical adapters

1-to-n, n-to-1, even m-to-n1-to-n, n-to-1, even m-to-n Complicated internal bindings Complicated internal bindings

and data pathsand data paths

Mux – 1 To nMux – 1 To n

Adapter 2Adapter 2Adapter 1Adapter 1

ProtocolProtocol Open Adapter 1Open Adapter 1 Open Adapter 2Open Adapter 2

MiniportMiniport

ExternalExternalBindingsBindings

Open Adapter xOpen Adapter x


Mux DriverMux Driver

Protocol edgeProtocol edgeOpen Adapter 1Open Adapter 1 Open Adapter 2Open Adapter 2

Virtual Adapter xVirtual Adapter x




Adapter 1Adapter 1

Open Adapter 1Open Adapter 1

Mux – n To 1Mux – n To 1

ProtocolProtocol

MiniportMiniport

External External BindingsBindings

Open Adapter xOpen Adapter x Open Adapter yOpen Adapter y



Mux DriverMux Driver

Protocol edgeProtocol edgeOpenAdapter 1OpenAdapter 1

Virtual Adapter yVirtual Adapter yVirtual Adapter xVirtual Adapter x



Mux ExamplesMux Examples

n to 1n to 1 Windows 2000 ATM LAN EmulationWindows 2000 ATM LAN Emulation 802 and proprietary Virtual LANs802 and proprietary Virtual LANs

1 to n1 to n Non-miniport LBFO solutionsNon-miniport LBFO solutions

Writing A DriverWriting A Driver

Use the Windows 2000 DDKUse the Windows 2000 DDK Learn NDIS miniport operations Learn NDIS miniport operations

and functionsand functions Learn NDIS protocol operations Learn NDIS protocol operations

and functionsand functions Design your intermediate modelDesign your intermediate model Reference pass-through DDK sampleReference pass-through DDK sample

DriverEntryDriverEntry

Basically just registration:Basically just registration: NdisMInitializeWrapperNdisMInitializeWrapper NdisIMRegisterLayeredMiniportNdisIMRegisterLayeredMiniport NdisRegisterProtocolNdisRegisterProtocol NdisIMAssociateMiniportNdisIMAssociateMiniport

Dynamic BindingDynamic Binding

An intermediate driver must support An intermediate driver must support dynamic binding to lower edge adaptersdynamic binding to lower edge adapters

Your driver controls the state of its upper Your driver controls the state of its upper edge miniports edge miniports

Lower edge adapter binding state events Lower edge adapter binding state events are typically the trigger to start/stop the are typically the trigger to start/stop the upper miniport(s)upper miniport(s)

Upper-Edge InitializeUpper-Edge Initialize

Call NdisIMInitializeDeviceInstance(Ex) Call NdisIMInitializeDeviceInstance(Ex) after an event like a lower adapter after an event like a lower adapter binding notificationbinding notification

Results in callback to your Results in callback to your MiniportInitializeMiniportInitialize

NdisMSetAttributesExNdisMSetAttributesEx NDIS_ATTRIBUTE_INTERMEDIATE_DRIVERNDIS_ATTRIBUTE_INTERMEDIATE_DRIVER NDIS_ATTRIBUTE_DESERIALIZENDIS_ATTRIBUTE_DESERIALIZE

Upper-Edge De-InitializeUpper-Edge De-Initialize

NDIS may call MiniportHalt anytimeNDIS may call MiniportHalt anytime Driver can call Driver can call

NdisIMDeInitializeDeviceInstance to NdisIMDeInitializeDeviceInstance to cause the MiniportHalt to be calledcause the MiniportHalt to be called

Query/Set InformationQuery/Set Information

Upper Miniport Edge – miniport request Upper Miniport Edge – miniport request handlers are calledhandlers are called

Lower Protocol Edge – do NdisRequest Lower Protocol Edge – do NdisRequest to query/set lower adapterto query/set lower adapter

Filter - typically pass-through except Filter - typically pass-through except OID_PNP_SET_POWEROID_PNP_SET_POWER OID_PNP_QUERY_POWEROID_PNP_QUERY_POWER

Mux – same rule but pass-through Mux – same rule but pass-through depends on designdepends on design

Power management issues Power management issues on later slideson later slides

Status IndicationsStatus Indications

Filter – typically pass up directlyFilter – typically pass up directly Lower ProtocolStatus causes upper Lower ProtocolStatus causes upper

NdisMIndicateStatusNdisMIndicateStatus Mux – behavior depends on designMux – behavior depends on design Power management issues Power management issues

on later slideson later slides

Packet HandlingPacket Handling

NDIS_PACKET data structure is not NDIS_PACKET data structure is not designed for multilayered driversdesigned for multilayered drivers

Packets must get new NDIS_PACKET Packets must get new NDIS_PACKET descriptor as it passes up or down descriptor as it passes up or down through the intermediate driverthrough the intermediate driver

Passthru sample has detailed examplesPassthru sample has detailed examples Packets that originate in the driver are Packets that originate in the driver are

created the same as a simple NDIS created the same as a simple NDIS protocol driverprotocol driver

Power ManagementPower Management

NDIS gets power management events NDIS gets power management events in no particular orderin no particular order

NDIS forwards them to protocols and NDIS forwards them to protocols and miniport as appropriateminiport as appropriate

Intermediate drivers must be able to Intermediate drivers must be able to handle these events in any order and handle these events in any order and behave correctlybehave correctly

Reporting Power CapabilitiesReporting Power Capabilities

Handling OID_PNP_CAPABILITIES Handling OID_PNP_CAPABILITIES upper edge miniport query upper edge miniport query information callinformation call

Forward query down to lower Forward query down to lower edge adapteredge adapter

Modify response before completing at Modify response before completing at upper edge - Override these params upper edge - Override these params with NdisDeviceStateUnspecifiedwith NdisDeviceStateUnspecified MinMagicPacketWakeUpMinMagicPacketWakeUp MinPatternWakeUpMinPatternWakeUp MinLinkChangeWakeUpMinLinkChangeWakeUp

Power EventsPower Events

Events are called into both protocol and Events are called into both protocol and miniport handlers in no particular orderminiport handlers in no particular order ProtocolPnPEventProtocolPnPEvent Miniport(Set/Query)InformationMiniport(Set/Query)Information

Maintain separate power stateMaintain separate power state For each upper miniport instanceFor each upper miniport instance For each lower open adapterFor each lower open adapter

Maintain a “StandingBy” flag that is:Maintain a “StandingBy” flag that is: Set to True when either power state leaves D0Set to True when either power state leaves D0 Set to False when either power state returns to D0Set to False when either power state returns to D0

Using The Power States (1)Using The Power States (1)

MiniportSendMiniportSend Fail unless upper miniport and lower Fail unless upper miniport and lower

adapter are both D0adapter are both D0 MiniportQueryInformationMiniportQueryInformation

Always succeed Always succeed OID_PNP_QUERY_POWER to ensure OID_PNP_QUERY_POWER to ensure getting OID_PNP_SET_POWER requestsgetting OID_PNP_SET_POWER requests

Fail all other requests if miniport is not D0 Fail all other requests if miniport is not D0 or StandingBy is Trueor StandingBy is True

Queue single request if lower adapter is Queue single request if lower adapter is not D0, process when it becomes D0not D0, process when it becomes D0

Using The Power States (2)Using The Power States (2)

MiniportSetInformationMiniportSetInformation Fail if miniport is not D0 or StandingBy is TrueFail if miniport is not D0 or StandingBy is True Queue single request if lower adapter is not D0, Queue single request if lower adapter is not D0,

process when it becomes D0process when it becomes D0 ProtocolStatusProtocolStatus

Only indicate on upper miniport edge if both lower Only indicate on upper miniport edge if both lower edge adapter and upper miniport are D0 edge adapter and upper miniport are D0

ProtocolPnPEventProtocolPnPEvent When lower edge adapter is transitioning away When lower edge adapter is transitioning away

from D0, wait until outstanding lower edge sends from D0, wait until outstanding lower edge sends and requests have completedand requests have completed

Filter InstallFilter Install

Two INF filesTwo INF files Class = Net INF for miniport edgeClass = Net INF for miniport edge Class = NetService INF for protocol edgeClass = NetService INF for protocol edge

NetService INF is what user installsNetService INF is what user installs NetService INF references net INF with NetService INF references net INF with

special NDI keysspecial NDI keys Network Installer does all the work – Network Installer does all the work –

installing service and miniport(s)installing service and miniport(s)

Filter INF keywordsFilter INF keywords

FilterClassFilterClass schedulerscheduler loadbalanceloadbalance failoverfailover

FilterDeviceInfFileFilterDeviceInfFile FilterDeviceInfIdFilterDeviceInfId FilterMediaTypesFilterMediaTypes

Mux InstallMux Install

Two INF filesTwo INF files Class = Net INF for miniport edgeClass = Net INF for miniport edge Class = Nettrans INF for protocol edgeClass = Nettrans INF for protocol edge

Notify Object referenced in Notify Object referenced in Nettrans INFNettrans INF HKR, Ndi, ComponentDll, 0, "notifyobject.dll"HKR, Ndi, ComponentDll, 0, "notifyobject.dll"

Nettrans INF is what user installsNettrans INF is what user installs Notify Object is responsible for Notify Object is responsible for

installation of miniport(s )installation of miniport(s )

What Is A Notify Object?What Is A Notify Object?

An extension of the An extension of the Network Class InstallerNetwork Class Installer

A COM object housed in a DLL that is a A COM object housed in a DLL that is a COM component serverCOM component server

You put a reference to it in your You put a reference to it in your Netservice or Nettrans INFNetservice or Nettrans INF

Network class installer does the Network class installer does the equivalent of regsrv32 your.dllequivalent of regsrv32 your.dll

Network class installer instantiates your Network class installer instantiates your object and sends it notifications of object and sends it notifications of events related to your network driverevents related to your network driver

Mux Notify Mux Notify Object Requirements Object Requirements Install/Remove upper-edge miniportsInstall/Remove upper-edge miniports Manage the miniport device name list in Manage the miniport device name list in

the registry under the NetService the registry under the NetService Control external bindings if necessaryControl external bindings if necessary Present additional property sheet for Present additional property sheet for

configuration (optional)configuration (optional)

Call To ActionCall To Action

Carefully choose the right NDIS Carefully choose the right NDIS Intermediate driver model (Filters Intermediate driver model (Filters are simpler)are simpler)

Write quality driversWrite quality drivers Test using NDIS testerTest using NDIS tester

DiscussionDiscussion

Documents

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