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

  • Статья

[Относится к 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 поддерживает F0 только для этого компонента. Эта структура определяет количество и атрибуты F-состояний, поддерживаемых компонентом, а также самое глубокое состояние Fx, из которого компонент может пробуждаться.

ComponentActiveConditionCallback

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

ComponentIdleConditionCallback

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

ComponentIdleStateCallback

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

PowerControlCallback

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

PoFxDeviceContext

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

PoFxDeviceFlags

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

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

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

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

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

Для драйверов, предназначенных для WDF до версии 33, вместо этого укажите директиву 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.

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

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

Комментарии

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

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

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

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

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

Требования

Требование Значение
Минимальная версия KMDF 1.11
Минимальная версия UMDF 2.33
Верхняя часть wdfdevice.h (включая Wdf.h)

См. также раздел

EvtDeviceWdmPostPoFxRegisterDevice

EvtDeviceWdmPrePoFxUnregisterDevice

WDF_POWER_FRAMEWORK_SETTINGS_INIT

WdfDeviceWdmAssignPowerFrameworkSettings