WDM Net and Modem Drivers Power Management Guidelines for Net and Modem

Power Management Guidelines for Net and Modem From the PC99 design guide.
19.26. Driver-based modem uses a WDM-based driver solution for all modems in PC 99 Design Guide
Required
Windows 98 and Windows 2000 share WDM kernel calls. Driver-based modems must use the WDM kernel so that both operating systems can use a common driver binary. For Windows 2000, these drivers must also support symmetric multiprocessors.
19.38. Device complies with device class power management reference specification
Required
The Communications Device Class Power Management Reference Specification, Version 1.0 or later, provides definitions for the OnNow device power states (D0-D3) for modems. The specification also covers the device functionality expected in each power state and the possible wake-up event definitions for the class.
This specification is available at http://www.microsoft.com/hwdev/specs/PMref/PMcom.htm.
Power states D0 and D3 are required for modems on power-managed buses, including PCI, CardBus, and USB.
Modem adapters that use the PCI bus must be capable of generating a power management event (PME# assertion) from the D3 cold device state. It is recommended that modem adapters also support capture of Caller ID with hardware support for the AT+VRID "resend caller ID" voice modem command.
20.55. Device complies with device class power management reference specification
Required
The Network Device Class Power Management Reference Specification, Version 1.0a, provides definitions of the OnNow device power states (D0-D3) for network adapters. The specification also covers the device functionality expected in each power state and the possible wake-up event definitions for the class.
Network communications devices that directly attach to the PC over USB, PCI, and IEEE 1394 must comply with this specification.
This specification is available at
http://www.microsoft.com/hwdev/specs/PMref/PMnetwork.htm.
See also “Power Management for Network Drivers” at http://www.microsoft.com/hwdev/devdes/netpm.htm.
Network/Modem Device Power States
A network device power state describes a Network Interface Card level of power consumption and computing activity. Network device power states are defined in terms of the following criteria.
NOTE: These power state definitions apply only for network and modem devices.
Power consumption:
How much power does the NIC use? How much power is available to a NIC and what is operation (a clock, etc.) is bus-specific.
Device context:
How much of its operational context does the NIC retain before transitioning to a lower power state?
Miniport and NIC behavior: Does the miniport honor requests to transmit packets or indicate up received packets? Can the NIC generate interrupts?
Restore time:
How long does it take to restore the NIC to the fully operational state? Can the NIC wake the system from this state?
There are four network device power states: D0, D1, D2, and D3. D0 is the fully on state. D1, D2, and D3 are the sleeping states. The state number is inversely related to power consumption: higher numbered states use less power. Power may be fully removed from the NIC in the D3 state.
Power management-aware miniports must support all four network device power states.
The network device power states are defined as follows (for network and modem miniports only):
D0
Power Consumption:
The device is fully powered and delivering full functionality and performance.
Device Context:
The hardware device context is maintained.
Miniport and NIC behavior:
The NIC is fully compliant with the requirements of the attached network. There are no power-management restrictions on the NIC or miniport.
Restore time:
Not applicable
D1
Power Consumption:
D1 is the highest-powered sleeping state. Power consumption is less than that in the D0 state and greater than or equal to that in the D2 state.
Device Context:
The hardware device context may be lost.
Miniport and NIC behavior:
The miniport does not honor transmission requests from protocols. In fact, the miniport will not receive such requests from protocols, since NDIS will either notify a bound protocol of the transition to the sleeping state or, if the protocol is a legacy protocol that is not PM-aware, disable such requests from the protocol.
The miniport does not indicate up any packets that the NIC may receive while in this state.
The NIC does not generate interrupts. However, the miniport must be able to field interrupts, since a shared interrupt could be generated on the bus.
Restore time:
The time to restore the NIC to the D0 state is less than that required when the NIC is in the D2 state.
D2
Power Consumption:
D2 is an intermediate sleeping state. Power consumption is less than that in the D1 state and greater than or equal to that in the D3 state.
Device Context:
The hardware device context may be lost.
Miniport and NIC behavior:
The miniport does not honor transmission requests from protocols. In fact, the miniport will not receive such requests from protocols, since NDIS will either notify a bound protocol of the transition to the sleeping state or, if the protocol is a legacy protocol that is not PM-aware, disable such requests from the protocol.
The miniport does not indicate up any packets that the NIC may receive while in this state.
The NIC does not generate interrupts. However, the miniport must be able to field interrupts, since a shared interrupt could be generated on the bus.
Restore time:
The time to restore the NIC to the D0 state is greater than that required when the NIC is in the D1 state and less than that required when the NIC is in the D3 state.
D3
Power Consumption:
D3 is the lowest-powered sleeping state. In this state, power may be completely removed from the NIC.
Device Context:
The hardware device context is assumed to be lost.
Miniport and NIC behavior:
The miniport does not honor transmission requests from protocols. In fact, the miniport will not receive such requests from protocols, since NDIS will either notify a bound protocol that the miniport is in a sleeping state or, if the protocol is a legacy protocol that is not PM-aware, in effect disable such requests from the protocol.
The miniport does not indicate up any packets that the NIC may receive while in this state.
The NIC does not generate interrupts. However, the miniport must be able to field interrupts, since a shared interrupt could be generated on the bus.
Restore time:
The time to restore the NIC to the D0 state is greater than that required when the NIC is in the D2 state.
Before a NIC transitions to the D3 state, its miniport must turn-off everything under the miniport's control: interrupts must disabled, timers must be cancelled, etc. A miniport cannot access the NIC hardware after the NIC has been set to the D3 state by the bus driver.
The only allowable transitions between device power states are from the fully on state (D0) to a sleeping state (D1, D2, D3) or from a sleeping state to the fully on state. NDIS never explicitly commands a NIC to transition directly from one sleeping state to another sleeping state.
Power Interfaces for Net Drivers
This section describes power interfaces for Net/ Modem miniport drivers. This information does not apply for any other device class.
From the Windows 2000 DDK (published December 1999): under “Plug-and-Play and Power-Management Objects”: OID_PNP_CAPABILITIES
This OID requests a miniport to return the wake-up capabilities of its NIC or requests an intermediate driver to return the intermediate driver's wake-up capabilities. The wake-up capabilities are formatted as an NDIS_PNP_CAPABILITIES structure, which is defined as follows:
typedef struct _NDIS_PNP_CAPABILITIES {
ULONG Flags;
NDIS_PM_WAKE_UP_CAPABILITIES WakeUpCapabilities;
} NDIS_PNP_CAPABILITIES, *PNDIS_PNP_CAPABILITIES;
The members of this structure contain the following information:
Flags
NDIS_DEVICE_WAKE_UP_ENABLE
NDIS sets this flag if the underlying miniport supports one or more wake-up capabilities. Protocol drivers can test this flag to determine whether an underlying miniport has wake-up capabilities. Miniport drivers should not access this flag.
WakeUpCapabilities
An NDIS_PM_WAKE_UP_CAPABILITIES structure that specifies the wake-up capabilities of the miniport's NIC. The NDIS_PM_WAKE_UP_CAPABILITIES structure is defined as follows:
typedef struct _NDIS_PM_WAKE_UP_CAPABILITIES {
NDIS_DEVICE_POWER_STATE MinMagicPacketWakeUp;
NDIS_DEVICE_POWER_STATE MinPatternWakeUp;
NDIS_DEVICE_POWER_STATE MinLinkChangeWakeUp;
} NDIS_PM_WAKE_UP_CAPABILITIES, *PNDIS_PM_WAKE_UP_CAPABILITIES;
The members of this structure contain the following information:
MinMagicPacketWakeUp
Specifies the lowest device power state from which the miniport's NIC can signal a wake-up on receipt of a Magic Packet. (A Magic Packet is a packet that contains 16 contiguous copies of the receiving NIC's Ethernet address.) The device power state is specified as one of the following NDIS_DEVICE_POWER_STATE values:
NdisDeviceStateUnspecified
The NIC does not support magic-packet wake-ups.
NdisDeviceStateD0
The NIC can signal a magic-packet wake-up from device power state D0. Since D0 is the fully powered state, this does not cause a wake-up but can be used as a runtime event.
NdisDeviceStateD1
The NIC can signal a magic-packet wake-up from device power states D1 and D0.
NdisDeviceStateD2
The NIC can signal a magic-packet wake-up from device states D2, D1, and D0.
NdisDeviceStateD3
The NIC can signal a magic-packet wake-up from device power states D3, D2, D1, and D0.
MinPatternWakeUp
Specifies the lowest device power state from which the miniport's NIC can signal a wake-up event on receipt of a network frame that contains a pattern specified by the protocol driver. The power state is specified as one of the following NDIS_DEVICE_POWER_STATE values:
NdisDeviceStateUnspecified
The NIC does not support pattern-match wake-ups.
NdisDeviceStateD0
The NIC can signal a pattern-match wake-up from device power state D0. Since D0 is the fully powered state, this does not cause a wake-up but can be used as a runtime event.
NdisDeviceStateD1
The NIC can signal a pattern-match wake-up from device power states D1 and D0.
NdisDeviceStateD2
The NIC can signal a pattern-match wake-up from device power states D2, D1, and D0.
NdisDeviceStateD3
The NIC can signal a pattern-match wake-up from device power states D3, D2, D1, and D0.
MinLinkChangeWakeUp
Specifies the lowest device power state from which the miniport's NIC can signal a wake-up event in response to a link change (the connection or disconnection of the NIC's network cable). The power state is specified as one of the following NDIS_DEVICE_POWER_STATE values:
NdisDeviceStateUnspecified
The NIC does not support link-change wake-ups.
NdisDeviceStateD0
The NIC can signal a link-change wake-up from device power state D0. Since D0 is the fully-powered state, this does not cause a wake-up but can be used as a runtime event.
NdisDeviceStateD1
The NIC can signal a link-change wake-up from device power states D1 and D0.
NdisDeviceStateD2
The NIC can signal a link-change wake-up from device power states D2, D1, and D0.
NdisDeviceStateD3
The NIC can signal a link-change wake-up from device power states D3, D2, D1, and D0.
For Miniport Drivers
After the miniport completes initialization, both the protocol driver and NDIS can query the miniport with this OID to determine the following:
Whether the miniport is PM-aware
The NIC's capabilities of indicating network wake-up events.
If the miniport returns NDIS_STATUS_SUCCESS to a query of OID_PNP_CAPABILITIES, NDIS considers the miniport to be PM-aware. If the miniport returns NDIS_STATUS_NOT_SUPPORTED, NDIS considers the miniport to be a legacy miniport that is not PM-aware.
A miniport's NIC can support any combination of wake-up events, including no wake-up events. A miniport can still support power management even if its NIC cannot not signal wake-up events. In this case, the only power-management OIDs that the miniport supports in addition to OID_PNP_CAPABILITIES are OID_PNP_QUERY_POWER and OID_PNP_SET_POWER.
If a miniport's NIC does not support a particular wake-up event, the miniport should indicate an NDIS_DEVICE_POWER_STATE of NdisDeviceStateUnspecified for the wake-up event in the NDIS_PM_WAKE_UP_CAPABILITIES structure.
OID_PNP_CAPABILITIES only indicates the wake-up capabilities of a miniport's NIC; it does not enable such capabilities. OID_PNP_ENABLE_WAKE_UP is used to enable a NIC's wake-up capabilities.
For Intermediate NDIS Drivers
If the underlying NIC is power management-aware, the intermediate driver should return NDIS_STATUS_SUCCESS to a query of OID_PNP_CAPABILITIES. In the NDIS_PM_WAKE_UP_CAPABILITIES structure returned by this OID, the intermediate driver should specify a device power state of NdisDeviceStateUnspecified for each wake-up capability (MinMagicPacketWakeUp, MinPatternWakeUp, MinLinkChangeWakeUp). Such a response indicates that the intermediate driver is PM-aware but does not manage a physical device.
If the underlying NIC is not power management-aware, the intermediate driver should return NDIS_STATUS_NOT_SUPPORTED to a query of OID_PNP_CAPABILITIES.
|