Configuring NetAdapterCx power management

  • Article

All NetAdapterCx client drivers are Windows Driver Framework (WDF) drivers with power management functionality similar to all WDF drivers. NetAdapterCx drivers require additional networking-specific power configurations as detailed in this article.

A typical networking device supports three common power management features:

Setting power capabilities of the network adapter

After configuring WDF power management functionality, the next step is to set the power capabilities of the network adapter. Power capabilities are divided into two categories: Low power protocol offload capabilities and Wake up capabilities.

Low power protocol offload capabilities

For background information on how the Windows network stack makes use of this capability, see Protocol Offloads for NDIS Power Management.

Client drivers set their low power protocol offload capabilities by calling the following methods appropriate for their hardware:

Wake up capabilities

Client drivers call any of the following methods to set the wake capabilities that their hardware supports when the device is in low power state (Dx):

Power consumption and resume latency

When the networking device is in Dx, it still consumes power to perform offload and arm for wake. After the device initiates wake-up from Dx, there's a delay before the device can transfer packets again. The deeper the internal power state the device goes into the less power it consumes while in Dx, but the longer the resume latency.

The following table describes the general guidelines regarding the trade-off between power consumption and resume latency for each wake capability.

Important

Some information relates to prereleased product which may be substantially modified before commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided. For more information about a specific device type, refer to media-specific documentation and the Windows Hardware Compatibility Program (WHCP).

Wake Capability Wake Events Power Consumption Resume Latency
PacketFilter Any packet matches configured ReceivePacketFilter Should be lower than when in D0, and the device needs to be kept in an appropriate state so that the resume latency is very small <= 10 ms
Bitmap Any packet matches configured bitmap pattern Should be lower than when armed for PacketFilter because it has more latitude in resume latency <= 300 ms
MagicPacket Magic packet Similar to Bitmap <= 300 ms
MediaChange Media connected or disconnected Similar to Bitmap <= 300 ms

The following example illustrates how a client driver might initialize its power capabilities. It does this while starting the net adapter but before calling NetAdapterStart. In this example, the client driver sets its bitmap, media change, and packet filter wake capabilities.

//
// Set bitmap wake capabilities
//
NET_ADAPTER_WAKE_BITMAP_CAPABILITIES bitmapCapabilities;
NET_ADAPTER_WAKE_BITMAP_CAPABILITIES_INIT(&bitmapCapabilities);

bitmapCapabilities.BitmapPattern = TRUE;
bitmapCapabilities.MaximumPatternCount = deviceContext->PowerFiltersSupported;
bitmapCapabilities.MaximumPatternSize = 256;

NetAdapterWakeSetBitmapCapabilities(Adapter, &bitmapCapabilities);

//
// Set media change wake capabilities
//
NET_ADAPTER_WAKE_MEDIA_CHANGE_CAPABILITIES mediaChangeCapabilities;
NET_ADAPTER_WAKE_MEDIA_CHANGE_CAPABILITIES_INIT(&mediaChangeCapabilities);

mediaChangeCapabilities.MediaConnect = TRUE;
mediaChangeCapabilities.MediaDisconnect = TRUE;

NetAdapterWakeSetMediaChangeCapabilities(Adapter, &mediaChangeCapabilities);

//
// Set packet filter wake capabilities
//
if(deviceContext->SelectiveSuspendSupported)
{
    NET_ADAPTER_WAKE_PACKET_FILTER_CAPABILITIES packetFilterCapabilities;
    NET_ADAPTER_WAKE_PACKET_FILTER_CAPABILITIES_INIT(&packetFilterCapabilities);

    packetFilterCapabilities.PacketFilterMatch = TRUE;

    NetAdapterWakeSetPacketFilterCapabilities(Adapter, &packetFilterCapabilities);
}

The client can optionally register EVT_NET_DEVICE_PREVIEW_POWER_OFFLOAD and EVT_NET_DEVICE_PREVIEW_WAKE_SOURCE callback functions to accept or reject incoming protocol offloads and wake patterns.

Programming protocol power offload and wake patterns

During the device's powering down sequence, the driver iterates through the enabled wake patterns and protocol power offloads and programs them into the hardware. The driver does this in its EvtDeviceArmWakeFromS0 and EvtDeviceArmWakeFromSx callback functions.

The following example shows how a client driver might iterate over the wake pattern list to check for a wake on magic packet entry, then iterate over the power offload list to process IPv4 ARP protocol offload:

NTSTATUS
EvtDeviceArmWakeFromSx(
    WDFDEVICE     Device
)
{
    NETADAPTER adapter = GetDeviceContext(Device)->Adapter;

    //
    // Process wake source list
    //
    NET_WAKE_SOURCE_LIST wakeSourceList;
    NET_WAKE_SOURCE_LIST_INIT(&wakeSourceList);

    NetDeviceGetWakeSourceList(Device, &wakeSourceList);

    for(UINT32 i = 0; i < NetWakeSourceListGetCount(&wakeSourceList; i++); i++)
    {
        NETWAKESOURCE wakeSource = NetWakeSourceListGetElement(&wakeSourceList, i);
        NET_WAKE_SOURCE_TYPE const wakeSourceType = NetWakeSourceGetType(wakeSource);

        if(wakeSourceType == NetWakeSourceTypeMagicPacket)
        {
            // Enable magic packet wake for the adapter
            ..
            //
        }
    }

    //
    // Process power offload list
    //
    NET_POWER_OFFLOAD_LIST powerOffloadList;
    NET_POWER_OFFLOAD_LIST_INIT(&powerOffloadList);

    NetDeviceGetPowerOffloadList(Device, &powerOffloadList);

    for(UINT32 i = 0; i < NetPowerOffloadListGetCount(&powerOffloadList); i++)
    {
        NETPOWEROFFLOAD powerOffload = NetPowerOffloadGetElement(&powerOffloadList, i);
        NET_POWER_OFFLOAD_TYPE const powerOffloadType = NetPowerOffloadGetType(powerOffload);

        if(powerOffloadType == NetPowerOffloadTypeArp)
        {
            // Enable ARP protocol offload for the adapter
            ..
            //
        }
    }

    return STATUS_SUCCESS;
}

On the way back to high power the driver normally disables the previously programmed protocol power offloads and wake patterns in the corresponding EvtDeviceDisarmWakeFromSx and EvtDeviceDisarmWakeFromS0 callbacks.

Reporting wake reason

Important

It is mandatory that client drivers report wake reason to NetAdapterCx.

When the NIC hardware wakes up the system, the client driver must report to NetAdapterCx which wake source triggered the wake. For most wake sources, drivers use the NET_ADAPTER_WAKE_REASON_PACKET structure to describe the network packet that triggered the wake.

If the NET_WAKE_SOURCE_TYPE is:

Power management scenarios for Modern Standby system

Important

For Modern Standby platform, the networking device driver must:

Please refer to media-specific documentation and WHCP for the complete Modern Standby requirements for your device type.

The OS is responsible for networking device's power policy decisions. For example, the OS controls when a device must go to Dx and what types of network events the device should wake on. The device driver's responsibility is to reliably execute the power transition sequence when requested by the OS, and then correctly program their hardware for the wake condition set by the OS.

The OS makes power policy decisions based on a broad set of factors, including system-wide power policies and user choices. The following are some common power policies used for networking devices on a Modern Standby system:

Important

These power policies may change with OS updates and the following information is provided as an example. Dependencies on specific end-to-end behavior of the OS should be avoided.

  • When the PC screen is on and the networking device has been idling, the OS asks the device to go to Dx and arms it for PacketFilter and MediaChange wake.

  • When the PC enters Modern Standby and the networking device has been idling, the OS asks the NIC go to Dx and arms it for Bitmap, MediaChange and Magic Packet wake.

  • When the PC goes to Hibernation, the OS asks the NIC to go to Dx and arms it for Magic Packet wake.

Note: NetAdapterCx client drivers control the visibility of the power management tab. For more information, see User Control of Device Idle and Wake Behavior.