Handling a Set-Power Request (NDIS 5.1)

  • Article

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 must handle set-power requests to the working state (a network device power state of D0) and to sleeping states (a network device power state of D1, D2, or D3). The intermediate driver should also maintain power state variables and a StandBy flag. These issues are discussed further in this topic. See the PassThru intermediate driver sample for examples of intermediate driver power management.

Handling a Set Power Request to a Sleeping State (NDIS 5.1)

There are two cases where an intermediate driver must handle a set power request to a sleeping state:

  • NDIS requests the virtual miniport upper edge of the intermediate driver to go to a sleeping state.

  • The intermediate driver protocol lower edge handles the underlying miniport driver transition to a sleeping state when it receives a Plug and Play event notification.

These events can happen in any order and one event does not necessarily accompany the other.

The sequence of events in handling set power requests to a sleeping state for the virtual miniport is as follows:

  1. NDIS calls the ProtocolPnPEvent function of each protocol driver bound to the virtual miniport. The call to ProtocolPnPEvent specifies a NetEventSetPower to a sleeping state. Protocol drivers that are bound to the intermediate driver stop sending packets and making OID requests to the intermediate driver virtual miniport. The protocol lower edge of the intermediate driver can continue to send packets and requests down until NDIS indicates that the underlying miniport driver is making the transition to a sleeping state.

  2. NDIS issues an OID_PNP_SET_POWER request to the virtual miniport of the intermediate driver. The intermediate driver succeeds the request by returning NDIS_STATUS_SUCCESS. The intermediate driver must not propagate the OID_PNP_SET_POWER request to the underlying miniport driver. Once the intermediate driver completes this request, it should not indicate any more receive packets or indicate status even if it keeps receiving packets and status indications from the underlying miniport driver.

  3. Typically, an intermediate driver does not reinitialize its virtual miniport. If the underlying miniport driver is PM-aware and supports wake-up events, the intermediate driver should not reinitialize its virtual miniport. If the intermediate driver does reinitialize its virtual miniport by calling NdisIMDeinitializeDeviceInstance, NDIS calls the ProtocolUnbindAdapter function of each bound protocol driver to unbind it from the virtual miniport.

The sequence of events in handling set power requests to a sleeping state for the underlying miniport driver is as follows:

  1. NDIS calls the ProtocolPnPEvent function of the intermediate driver protocol lower edge. The call to ProtocolPnPEvent specifies a NetEventSetPower to a sleeping state. The intermediate driver must stop sending packets and making OID requests to the underlying miniport driver. Before returning from the ProtocolPnPEvent function, the intermediate driver can use the NdisQueryPendingIOCount function to verify that outstanding requests and sends submitted to the underlying miniport driver have completed. If there are outstanding requests or sends, the intermediate driver should return NDIS_STATUS_PENDING from the call to ProtocolPnPEvent and then call NdisQueryPendingIOCount periodically until it returns zero. When NdisQueryPendingIOCount returns zero, the intermediate driver calls NDISCompletePnPEvent to complete the call to ProtocolPnPEvent. The protocol edge of an intermediate driver can still get received packet and status indications from the underlying miniport driver. Received packets can be ignored. If an intermediate driver's implementation depends upon monitoring the status of the underlying miniport driver, status indications should still be monitored.

  2. NDIS issues an OID_PNP_SET_POWER request to the underlying miniport driver or if the underlying miniport driver does not support power management, it will be halted. In this case, even though NDIS halts the underlying miniport driver, it does not request the intermediate driver protocol to unbind from the underlying miniport driver and NIC. Once the underlying miniport driver has successfully completed processing the OID (or the miniport driver is halted), it will not indicate any more packets or status.

Handling a Set Power Request to the Working State (NDIS 5.1)

There are two cases where an intermediate driver handles a set power request to the working state:

  • NDIS requests the virtual miniport (upper edge) of the intermediate driver to go to the working state.

  • The intermediate driver protocol lower edge handles the underlying miniport driver transition to the working state when it receives a Plug and Play event notification.

These events can occur in any order and one event does not necessarily accompany the other.

The sequence of events in handling set-power requests to a working state for the virtual miniport is as follows:

  1. NDIS issues an OID_PNP_SET_POWER to the virtual miniport of the intermediate driver. The intermediate driver returns NDIS_STATUS_SUCCESS to the set-power request. The intermediate driver must not propagate the OID_PNP_SET_POWER request to the underlying miniport driver.

  2. If the intermediate driver uninitialized its virtual miniport by calling NdisIMDeInitializeDeviceInstance, it can reinitialize the virtual miniport with NdisIMInitializeDeviceInstanceEx. The virtual miniport should be reinitialized when the intermediate driver is ready to accept I/O requests.

The sequence of events in handling set power requests to a working state for the underlying miniport driver is as follows:

  1. NDIS issues an OID_PNP_SET_POWER to the underlying miniport driver or calls its MiniportInitialize handler if the underlying miniport driver was halted.

  2. NDIS calls the ProtocolPnPEvent function of the intermediate driver. The call to ProtocolPnPEvent specifies a NetEventSetPower to the working state. Bound protocol drivers can start sending packets to the intermediate driver.

Power States and the Standby Flag (NDIS 5.1)

The intermediate driver should maintain a separate power state variable for each virtual miniport instance and for each underlying miniport driver to which the driver is bound. The intermediate driver should also maintain a StandingBy flag for each virtual miniport that is:

  • Set to TRUE when the power state of either the virtual miniport or the underlying miniport driver leaves D0.

  • Set to FALSE when the power state of either the virtual miniport or the underlying miniport driver returns to D0.

Note   For MUX intermediate drivers there can be multiple virtual miniports associated with an underlying miniport driver or multiple underlying miniports associated with each virtual miniport. When the power state of any miniport adapter changes, the behavior of all the associated miniports are also affected. How the behavior is affected is implementation specific. For example, a driver that implements an Load Balancing Failover (LBFO) solution might not deactivate the virtual miniports when a single underlying miniport driver is deactivated. However, a driver implementation that depends on all underlying miniport drivers would require deactivation of virtual miniports when any underlying miniport driver is deactivated.

 

The intermediate driver should use the StandingBy flag and power state variables when processing requests as follows:

  • The driver's MiniportSend function should fail unless the virtual miniport and its underlying miniport driver are both in D0.

  • The driver's MiniportQueryInformation function should always succeed OID_PNP_QUERY_POWER to ensure that the driver receives the subsequent OID_PNP_SET_POWER requests. MiniportQueryInformation should fail all other requests if the indicated virtual miniport is not in D0, or if its StandingBy flag is TRUE. Otherwise, if the underlying miniport driver that is associated with the indicated virtual miniport is not in D0, MiniportQueryInformation should queue a single request for the virtual miniport. A queued request should be processed when the underlying miniport driver state becomes D0.

  • The driver's MiniportSetInformation function should fail if the virtual miniport is not in D0 or StandingBy is TRUE. Otherwise, it should queue a single request if the underlying miniport driver is not in D0. A queued request should be processed when the underlying miniport driver state becomes D0.

  • The intermediate driver virtual miniport should only report status if both the underlying miniport driver and virtual miniport are in D0.

 

 

Send comments about this topic to Microsoft