Initializing as a Miniport (NDIS 5.1)
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
An intermediate driver initializes its virtual miniports after it has successfully opened an underlying NIC and is ready to accept requests and sends on its virtual miniports. An intermediate driver calls NdisIMInitializeDeviceInstanceEx from its ProtocolBindAdapter handler one or more times to request initialization of one or more virtual miniports.
Note An intermediate driver is not required to call NdisIMInitializeDeviceInstanceEx when it opens an underlying NIC. There does not have to be a one-to-one relationship between virtual miniports and open adapters.
Set the DriverInstance parameter of NdisIMInitializeDeviceInstanceEx to the device name for the virtual miniport being initialized. The intermediate driver obtains the device name from the UpperBindings registry key.
A filter intermediate driver has a one-to-one relationship between virtual miniports and physical NICs. Therefore, the UpperBindings registry key contains exactly one name. For filter intermediate drivers, the net class installer creates a virtual miniport instance for each physical NIC and stores a string that identifies the virtual miniport in the UpperBindings registry key.
For an n-to-one MUX intermediate driver that layers multiple virtual miniports over a single physical NIC, there must be a device name for every virtual miniport. The MUX intermediate driver requires a notify object that maintains the list of virtual miniport device names. The recommended location for the list is the UpperBindings registry key. In this case, the UpperBindings registry key is a MULTI_SZ entry containing the list of device names. The MUX intermediate driver calls NdisIMInitializeDeviceInstanceEx once for each device name specified in the device name list.
A call to NdisIMInitializeDeviceInstanceEx causes a call to the intermediate driver's MiniportInitialize function to perform the initialization of the specified virtual miniport, if NDIS receives an IRP_MN_START_DEVICE to start the device. If NDIS does not receive such an IRP, NDIS will not call the intermediate driver's MiniportInitializefunction.. The call to MiniportInitialize can happen at a later time and therefore is not necessarily within the context of the call to NdisIMInitializeDeviceInstanceEx. If NDIS never calls MiniportInitializefor the virtual miniport referenced in a call to NdisIMInitializeDeviceInstanceEx, and the intermediate driver no longer requires the virtual miniport, the intermediate driver should call NdisIMCancelInitializeDeviceInstance to cancel the initialization of the virtual miniport. For example, suppose that an intermediate driver creates a virtual miniport in response to a successful binding to an underlying miniport. If that binding is removed before NDIS calls MiniportInitialize, the intermediate driver should call NdisIMCancelInitializeDeviceInstance to cancel the initialization of the miniport.
MiniportInitialize must allocate and initialize a virtual-miniport-specific context area. As part of initialization, MiniportInitialize must call NdisMSetAttributesExand pass a handle to that context area. NDIS will pass this context handle in subsequent calls to the MiniportXxx functions. MiniportInitialize also must set the NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER flag the AttributeFlags passed to NdisMSetAttributesEx. An intermediate driver sets the NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER flag to identify its driver type to NDIS.
In addition, MiniportInitializeshould set the NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT flags in AttributeFlagspassed to NdisMSetAttributesEx. These timeouts are not needed because intermediate drivers are reserialized and NDIS does not queue packets for reserialized drivers.
If the intermediate driver registers a CheckForHangHandler, and does not change the time-out interval, NDIS calls the drivers MiniportCheckForHang function, by default, every two seconds. If MiniportCheckForHangreturns TRUE, NDIS calls the MiniportResetfunction. If the driver supplies a MiniportCheckForHangfunction, it can change the default two-second interval by specifying a different TimeInSeconds when it calls NdisMSetAttributesEx.
An intermediate driver must operate as a deserialized driver and must register itself as such by setting the NDIS_ATTRIBUTE_DESERIALIZE flag in the AttributeFlagsparameter that it passes to NdisMSetAttributesEx. A deserialized driver serializes the operation of its MiniportXxx functions and queues internally all incoming send packets rather than relying on NDIS to maintain its send queue. For more information about deserialized drivers, see Deserialized NDIS Miniport Drivers.
An intermediate driver must also set the NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND flag in the AttributeFlagsparameter that it passes to NdisMSetAttributesEx. Setting this flag prevents NDIS from halting the virtual miniport when the system makes a transition to a low-power state.
An intermediate driver should verify that the state information it maintains is properly initialized. If the driver requires send-related resources--for example, new packet descriptors for packets that MiniportSendor MiniportSendPacketswill transmit to the next lower layer--the packet pool can be allocated at this time.