1.2.2  Initializing as a Miniport

ProtocolBindAdapter, after it has successfully opened an underlying NIC and is ready to accept requests and sends on its virtual NIC or NICs, calls NdisIMInitializeDeviceInstance one or more times to request initialization of one or more NICs. NdisIMInitializeDeviceInstance calls the intermediate driver’s MiniportInitialize function to perform the initialization of the specified virtual NIC. After MiniportInitialize returns, overlying NDIS drivers can bind to the intermediate driver's virtual NIC(s).

MiniportInitialize must allocate and initialize a virtual-NIC-specific context area. As part of initialization, MiniportInitialize must call NdisMSetAttributesEx and 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 in the AttributeFlags parameter passed to NdisMSetAttributesEx. In addition, MiniportInitialize must set the NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT and NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT flags if it does not want NDIS to call the MiniportCheckForHang (or MiniportReset) function whenever NDIS times out sends and requests it is holding queued to the intermediate driver.

An intermediate driver sets the NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER flag to identify its driver type to NDIS. An important characteristic of an intermediate driver is that it always runs full-duplex, unless the intermediate driver reports the media type of its virtual NIC as NdisMediumWan. (Drivers underlying NDISWAN are never full-duplex miniports.) Running full-duplex imposes some restrictions on the calling sequence of a driver’s MiniportXxx functions. See Part 2, Chapter 4, Section 4.5, for a discussion of full-duplex operation.

Setting the timeout flags instructs NDIS that the intermediate driver will be responsible for timing out its own virtual NIC. Since the intermediate driver does not control the underlying NIC and therefore has no control over how long it takes to complete pending sends and requests, it generally does not provide a MiniportCheckForHang function nor does it time-out its virtual NIC.

However, if the intermediate driver registers an entry point at CheckForHangHandler, does not request that NDIS ignore packet and request timeouts, and does not change the time-out interval, its MiniportCheckForHang function will be called, by default, every 2 seconds. If MiniportCheckForHang returns TRUE, the MiniportReset function will be called. If the driver supplies a MiniportCheckForHang function, it can change the default 2-second interval by explicitly specifying a different TimeInSeconds when it calls NdisMSetAttributesEx.

Although the intermediate driver does not manage actual hardware and thus does not need to initialize interrupts or test hardware, it should make sure that the state information it maintains is properly initialized. If the driver requires send-related resources, for instance, new packet descriptors for packets that MiniportSend or MiniportSendPackets will transmit to the next lower layer, the packet pool can be allocated at this time if it was not done in ProtocolBindAdapter before calling NdisIMInitializeDeviceInstance.