配置 NetAdapterCx 电源管理

项目
07/11/2023

所有 NetAdapterCx 客户端驱动程序都是 Windows 驱动程序框架 (WDF) 驱动程序，其电源管理功能类似于所有 WDF 驱动程序。如本文所述，NetAdapterCx 驱动程序需要其他特定于网络的电源配置。

典型的网络设备支持三种常见的电源管理功能：

在操作系统指示下，网络设备可以进入低功率 (Dx) 状态。
- 客户端驱动程序注册可选的 WDF 事件回调以接收电源转换通知，如在函数驱动程序中支持 PnP 和电源管理中所述。
- 如果网络设备可以在系统保持工作状态时进入其 Dx 状态， (S0) 状态，则客户端驱动程序应支持空闲关闭电源。请参阅支持空闲关机。除了对所有 WDF 设备可用的设备空闲和唤醒行为的标准用户控制外，NetAdapterCx 还允许通过 *IdleRestriction 进行其他特定于网络的空闲控制，如电源管理的标准化 INF 关键字中定义。
当网络设备处于 Dx 状态时，如果发生预配置的唤醒条件，它可以触发唤醒信号。
- 有关 WDF 设备如何从系统范围的低功耗状态唤醒系统的详细信息，请参阅支持系统唤醒。
- NetAdapterCx 为客户端驱动程序提供 API，用于声明其硬件支持唤醒的网络事件。请参阅设置网络适配器的电源功能。
当网络设备处于 Dx 状态时，它仍然可以响应一些常用的网络请求，以保持主机系统在网络上的状态，而无需唤醒主机系统。请参阅设置网络适配器的电源功能。

设置网络适配器的电源功能

配置 WDF 电源管理功能后，下一步是设置网络适配器的电源功能。电源功能分为两类：低功率协议卸载功能和唤醒功能。

低功耗协议卸载功能

有关 Windows 网络堆栈如何使用此功能的背景信息，请参阅 NDIS 电源管理的协议卸载。

客户端驱动程序通过调用适用于其硬件的以下方法来设置其低功耗协议卸载功能：

唤醒功能

客户端驱动程序调用以下任一方法来设置设备处于低功耗状态时硬件支持的唤醒功能， (Dx) ：

功耗和恢复延迟

当网络设备位于 Dx 中时，它仍会消耗电源来执行卸载和唤醒臂。设备从 Dx 启动唤醒后，设备可以再次传输数据包之前会有延迟。设备进入内部电源状态越深，在 Dx 中消耗的功率就越小，但恢复延迟越长。

下表介绍了有关每个唤醒功能在功耗与恢复延迟之间进行权衡的一般准则。

重要

某些信息与预发布产品有关，这些产品可能在商业发布之前进行重大修改。 Microsoft 对提供的信息不作任何明示或默示的保证。有关特定设备类型的详细信息，请参阅特定于媒体的文档和 Windows 硬件兼容性计划 (WHCP) 。

唤醒功能	唤醒事件	功率消耗	恢复延迟
PacketFilter	任何数据包匹配配置的 ReceivePacketFilter	应低于在 D0 中，并且设备需要保持适当的状态，以便恢复延迟非常小	<= 10 毫秒
Bitmap	任何数据包都与配置的位图模式匹配	应低于为 PacketFilter 武装时，因为它在恢复延迟方面具有更大的自由度	<= 300 毫秒
MagicPacket	幻数据包	类似于位图	<= 300 毫秒
MediaChange	媒体已连接或断开连接	类似于位图	<= 300 毫秒

以下示例演示客户端驱动程序如何初始化其电源功能。它在启动网络适配器时，但在调用 NetAdapterStart 之前执行此操作。在此示例中，客户端驱动程序设置其位图、媒体更改和数据包筛选器唤醒功能。

//
// 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);
}

客户端可以选择注册 EVT_NET_DEVICE_PREVIEW_POWER_OFFLOAD 和 EVT_NET_DEVICE_PREVIEW_WAKE_SOURCE 回调函数，以接受或拒绝传入协议卸载和唤醒模式。

编程协议电源卸载和唤醒模式

在设备关闭电源序列期间，驱动程序会循环访问已启用的唤醒模式和协议电源卸载，并将其编程到硬件中。驱动程序在其 EvtDeviceArmWakeFromS0 和 EvtDeviceArmWakeFromSx 回调函数中执行此操作。

以下示例演示客户端驱动程序如何循环访问唤醒模式列表，以检查对神奇数据包条目进行唤醒，然后循环访问电源卸载列表以处理 IPv4 ARP 协议卸载：

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;
}

在返回大功率的路上，驱动程序通常会在相应的 EvtDeviceDisarmWakeFromSx 和 EvtDeviceDisarmWakeFromS0 回调中禁用以前编程的协议电源卸载和唤醒模式。

报告唤醒原因

重要

客户端驱动程序必须向 NetAdapterCx 报告唤醒原因。

当 NIC 硬件唤醒系统时，客户端驱动程序必须向 NetAdapterCx 报告哪个唤醒源触发了唤醒。对于大多数唤醒源，驱动程序使用 NET_ADAPTER_WAKE_REASON_PACKET 结构来描述触发唤醒的网络数据包。

如果 NET_WAKE_SOURCE_TYPE 为：

NetWakeSourceTypeBitmapPattern，调用 NET_ADAPTER_WAKE_REASON_PACKET_INIT 以初始化 NET_ADAPTER_WAKE_REASON_PACKET 结构。调用 NetAdapterReportWakeReasonPacket 来报告此唤醒原因。
NetWakeSourceTypeMagicPacket，调用 NET_ADAPTER_WAKE_REASON_MAGIC_PACKET_INIT 以初始化 NET_ADAPTER_WAKE_REASON_PACKET 结构。调用 NetAdapterReportWakeReasonPacket 来报告此唤醒原因。
NetWakeSourceTypePacketFilterMatch，调用 NET_ADAPTER_WAKE_REASON_FILTER_PACKET_INIT 初始化 NET_ADAPTER_WAKE_REASON_PACKET 结构。调用 NetAdapterReportWakeReasonPacket 来报告此唤醒原因。
NetWakeSourceTypeMediaChange，调用 NetAdapterReportWakeReasonMediaChange 来报告此唤醒原因。

新式待机系统的电源管理方案

重要

对于新式待机平台，网络设备驱动程序必须：

调用 WdfDeviceInitSetPnpPowerEventCallbacks 以注册电源回调。
当系统处于工作状态时，调用 WdfDeviceAssignS0IdleSettings 以支持设备闲 (S0) 状态。
调用 WdfDeviceInitSetPowerPolicyEventCallbacks 以注册唤醒回调。
支持适用于设备类型的低功耗协议卸载功能。
支持适用于设备类型的唤醒功能。

有关设备类型的完整新式待机要求，请参阅特定于媒体的文档和 WHCP。

OS 负责网络设备的电源策略决策。例如，OS 控制设备何时必须转到 Dx，以及设备应唤醒的网络事件类型。设备驱动程序负责在 OS 请求时可靠地执行电源转换序列，然后针对 OS 设置的唤醒条件正确编程其硬件。

OS 基于一系列广泛的因素（包括系统范围的电源策略和用户选择）做出电源策略决策。以下是用于新式待机系统上网络设备的一些常见电源策略：

重要

这些电源策略可能会随 OS 更新而更改，并提供以下信息作为示例。应避免依赖 OS 的特定端到端行为。

当电脑屏幕处于打开状态且网络设备一直处于闲动状态时，OS 会要求设备转到 Dx，并对其进行支持，以便进行 PacketFilter 和 MediaChange 唤醒。
当电脑进入新式待机且网络设备一直处于闲状态时，OS 会要求 NIC 转到 Dx，并对其进行支持，以便进行位图、MediaChange 和 Magic Packet 唤醒。
当电脑进入休眠状态时，OS 会要求 NIC 转到 Dx，并对其进行武装，以便唤醒 Magic Packet。

注意：NetAdapterCx 客户端驱动程序控制电源管理选项卡的可见性。有关详细信息，请参阅用户控制设备空闲和唤醒行为。

通过