структура WDF_POWER_FRAMEWORK_SETTINGS (wdfdevice.h)

2025-03-22

[Применимо к KMDF и UMDF]

Структура WDF_POWER_FRAMEWORK_SETTINGS описывает параметры платформы управления питанием (PoFx) для устройств с одним компонентом.

Синтаксис

typedef struct _WDF_POWER_FRAMEWORK_SETTINGS {
  ULONG                                         Size;
  PFN_WDFDEVICE_WDM_POST_PO_FX_REGISTER_DEVICE  EvtDeviceWdmPostPoFxRegisterDevice;
  PFN_WDFDEVICE_WDM_PRE_PO_FX_UNREGISTER_DEVICE EvtDeviceWdmPrePoFxUnregisterDevice;
  PPO_FX_COMPONENT                              Component;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK    ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK      ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK          ComponentIdleStateCallback;
  PPO_FX_POWER_CONTROL_CALLBACK                 PowerControlCallback;
  PVOID                                         PoFxDeviceContext;
  ULONGLONG                                     PoFxDeviceFlags;
  WDF_TRI_STATE                                 DirectedPoFxEnabled;
} WDF_POWER_FRAMEWORK_SETTINGS, *PWDF_POWER_FRAMEWORK_SETTINGS;

Члены

Size

Размер этой структуры в байтах.

EvtDeviceWdmPostPoFxRegisterDevice

Указатель на функцию обратного вызова события EvtDeviceWdmPostPoFxRegisterDevice функцию обратного вызова событий или NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Указатель на драйвера EvtDeviceWdmPrePoFxUnregisterDevice функцию обратного вызова событий или NULL.

Component

Указатель на структуру PO_FX_COMPONENT, описывающую единственный компонент на устройстве с одним компонентом или NULL. Если значение NULL, значение KMDF по умолчанию поддерживается только для этого компонента. Эта структура указывает количество и атрибуты F-состояний, поддерживаемых компонентом, а также самое глубокое состояние Fx, из которого компонент может проснуться.

ComponentActiveConditionCallback

Указатель на компонента ComponentActiveConditionCallback или NULL. Платформа управления питанием (PoFx) вызывает эту функцию обратного вызова, когда компонент становится активным. Хотя в активном состоянии компонент гарантированно находится в F0.

ComponentIdleConditionCallback

Указатель на функцию обратного вызова компонента ComponentIdleConditionCallback или NULL. PoFx вызывает эту функцию обратного вызова, когда компонент становится неактивным. Хотя в состоянии простоя компонент может находиться в любом состоянии F, включая F0.

ComponentIdleStateCallback

Указатель на функцию обратного вызова компонента ComponentIdleStateCallback или NULL. PoFx вызывает эту функцию обратного вызова при изменении состояния компонента.

PowerControlCallback

Указатель на функцию обратного вызова драйвера клиента PowerControlCallback или NULL. PoFx вызывает эту подпрограмму для передачи запроса на операцию управления питанием непосредственно драйверу. Если драйвер не поддерживает коды управления питанием, задайте для этого параметра значение NULL.

PoFxDeviceContext

Указатель контекста, который платформа предоставляет компоненту ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallbackи PowerControlCallback.

PoFxDeviceFlags

Значение типа ULONGLONG, содержащее побитовую OR следующих значений, связанных с платформой управления питанием. Это поле доступно начиная с KMDF версии 1.33 и UMDF 2.33.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

Если на устройстве включена направленная платформа Power Framework (DFx), обычно дочерние устройства также включают DFx. Однако в некоторых случаях (например, чистое программное устройство), дочернее устройство не реализует управление питанием. Установите этот флаг, чтобы позволить такому дочернему устройству пропускать DFx.

Чтобы задать этот флаг от имени дочерних устройств, родительский драйвер WDF должен:

согласие на DFx
Не быть водителем автобуса
Создание по крайней мере одного виртуального дочернего устройства через канал бокового диапазона (например, верхний фильтр или устройство, созданное путем вызова SwDeviceCreate

Для драйверов, предназначенных для предварительной версии 33 WDF, вместо этого укажите директиву INF: WdfDirectedPowerTransitionChildrenOptional, которая доступна начиная с Windows 10 версии 1903. Если драйвер задает директиву INF и задает этот флаг, директива INF имеет приоритет.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

Это необходимо для реализации IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations между двумя устройствами.

По умолчанию WDF реализует быстрое возобновление, что означает, что во время пробуждения системы владелец политики питания в стеке устройств завершает S0-IRP без ожидания запроса и завершения D0-IRP. Это не работает хорошо с PowerRelations.

Чтобы сделать PowerRelations правильной, если устройство зависит от другого устройства для ввода D0 первого, второй устройство должно задать этот флаг, чтобы отказаться от быстрого возобновления.

В некоторых случаях глобальная политика может отключить быстрое возобновление глобально, даже если этот флаг не задан.

DirectedPoFxEnabled

Перечислитель WDF_TRI_STATE типа, указывающий, включает ли устройство платформу управления питанием (DFx). Доступно начиная с KMDF версии 1.33 и UMDF 2.33.

WdfTrue — DFx включен. WdfFalse — DFx отключен. WdfUseDefault — значение по умолчанию, если драйвер не задан. Это значение имеет то же значение, что и WdfTrue.

Перенаправленный PoFx (DFx) доступен начиная с Windows 10 версии 1903 в качестве варианта для драйверов, использующих SystemManagedIdleTimeout или SystemManagedIdleTimeoutWithHint.

Для драйвера, предназначенного до версии 31 WDF, задайте директиву INF WdfDirectedPowerTransitionEnable значение 1, чтобы принять участие в DFx.
Для драйвера, предназначенного для версии 31+ WDF, DFx включен по умолчанию. Драйвер может задать WdfDirectedPowerTransitionEnable равным нулю, чтобы отказаться от DFx.
Для драйвера, предназначенного для версии 33+ WDF, DFx также включен по умолчанию. Драйвер может задать WdfDirectedPowerTransitionEnable равным нулю или задать для этого поля значение WdfFalse (рекомендуется), чтобы отказаться от DFx. Если задано оба значения, директива INF имеет приоритет.

Замечания

Структура WDF_POWER_FRAMEWORK_SETTINGS использует входные данные для WdfDeviceWdmAssignPowerFrameworkSettings.

Чтобы инициализировать структуру WDF_POWER_FRAMEWORK_SETTINGS, драйвер должен вызвать WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Для UMDF используются только размера, PoFxDeviceFlagsи DirectedPoFxEnabled. Другие поля игнорируются и должны иметь значение нулю. Платформа выполняет это автоматически, когда драйвер UMDF вызывает WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Дополнительные сведения см. в поддержке функциональных состояний питания и обзорплатформы управления питанием.

Эта структура неприменима к клиентским драйверам KMDF для устройств с несколькими компонентами.