структура PO_FX_DEVICE_V3 (wdm.h)

Статья
02/07/2025

Структура PO_FX_DEVICE_V3 описывает атрибуты питания устройства в платформу управления питанием (PoFx), DFx (направленная PoFx)

Синтаксис

typedef struct _PO_FX_DEVICE_V3 {
  ULONG                                      Version;
  ULONGLONG                                  Flags;
  PPO_FX_COMPONENT_ACTIVE_CONDITION_CALLBACK ComponentActiveConditionCallback;
  PPO_FX_COMPONENT_IDLE_CONDITION_CALLBACK   ComponentIdleConditionCallback;
  PPO_FX_COMPONENT_IDLE_STATE_CALLBACK       ComponentIdleStateCallback;
  PPO_FX_DEVICE_POWER_REQUIRED_CALLBACK      DevicePowerRequiredCallback;
  PPO_FX_DEVICE_POWER_NOT_REQUIRED_CALLBACK  DevicePowerNotRequiredCallback;
  PPO_FX_POWER_CONTROL_CALLBACK              PowerControlCallback;
  PPO_FX_DIRECTED_POWER_UP_CALLBACK          DirectedPowerUpCallback;
  PPO_FX_DIRECTED_POWER_DOWN_CALLBACK        DirectedPowerDownCallback;
  ULONG                                      DirectedFxTimeoutInSeconds;
  PVOID                                      DeviceContext;
  ULONG                                      ComponentCount;
  PO_FX_COMPONENT_V2                         Components[ANYSIZE_ARRAY];
} PO_FX_DEVICE_V3, *PPO_FX_DEVICE_V3;

Члены

Version

Номер версии этой структуры. Если драйвер зарегистрирует поддержку перенаправленной мощности в DFx, установите для этого члена значение PO_FX_VERSION_V3.

Flags

Определяет, могут ли прямые дочерние устройства и дочерние устройства отказаться от direct PoFx.

Возможные значения флага:

Флаг	Описание
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Позволяет прямым дочерним устройствам этого устройства при необходимости поддерживать Direct PoFx. Если не задано, все прямые дочерние элементы должны поддерживать Direct PoFx для этого устройства, чтобы полностью поддерживать Direct PoFx.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Позволяет дочерним устройствам питания этого устройства при необходимости поддерживать перенаправленный PoFx. Если оно не предоставлено, все дочерние элементы питания должны поддерживать Перенаправленное poFx для этого устройства, чтобы полностью поддерживать Направленный PoFx.
PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL	Задает PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL и PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL
PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME	Заставляет PoFx предотвратить завершение S0-IRP до D0-IRP возобновления из состояния системы, например Гибернации или спящего режима. Взаимоисключаемая с PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.
PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME	Позволяет PoFx разрешить S0-IRP быть завершенным до D0-IRP возобновления из состояния системы, например Гибернации или спящего режима. Взаимоисключаемая с PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME.

ComponentActiveConditionCallback

Указатель на подпрограмму обратного вызова компонента ComponentActiveConditionCallback, реализуемую драйвером устройства.

ComponentIdleConditionCallback

Указатель на подпрограмму обратного вызова компонента ComponentIdleConditionCallback, реализованную драйвером устройства.

ComponentIdleStateCallback

Указатель на подпрограмму обратного вызова компонента ComponentIdleStateCallback, реализованную драйвером устройства.

DevicePowerRequiredCallback

Указатель на процедуру обратного вызова DevicePowerRequiredCallback, реализованную драйвером устройства.

DevicePowerNotRequiredCallback

Указатель на процедуру обратного вызова DevicePowerNotRequiredCallback, реализованную драйвером устройства.

PowerControlCallback

Указатель на процедуру обратного вызова PowerControlCallback, реализованную драйвером устройства.

DirectedPowerUpCallback

Указатель на подпрограмму обратного вызова PO_FX_DIRECTED_POWER_UP_CALLBACK, реализованную драйвером устройства. Устройство может предоставлять только обратные вызовы DirectedPower* при регистрации для PoFx. Не требуется реализовать остальные обратные вызовы PoFx.

DirectedPowerDownCallback

Указатель на подпрограмму обратного вызова PO_FX_DIRECTED_POWER_DOWN_CALLBACK, реализованную драйвером устройства.

DirectedFxTimeoutInSeconds

Предоставляет намек на платформу, указывающую рекомендуемое время ожидания в секундах, в которых устройство должно отсутствовать после отсутствия активности программного обеспечения. Значение по умолчанию — 2 минуты.

DeviceContext

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

ComponentCount

Количество элементов в массиве компонентов . Кроме того, этот элемент указывает количество компонентов на устройстве.

Components[ANYSIZE_ARRAY]

Этот элемент является первым элементом в массиве одного или нескольких элементов PO_FX_COMPONENT_V2. Если массив содержит несколько элементов, дополнительные элементы сразу же следуют PO_FX_DEVICE_V2 структуре. Массив содержит один элемент для каждого компонента устройства. Состояние питания каждого компонента Fx можно контролировать независимо от состояний питания Fx других компонентов на устройстве. Константа ANYSIZE_ARRAY определена как 1 в файле заголовка Ntdef.h.

Замечания

Чтобы зарегистрировать устройство с помощью PoFx, драйвер вызывает PoFxRegisterDevice подпрограмму и предоставляет в качестве параметра указатель на структуру PO_FX_DEVICE, описывающую устройство. Чтобы использовать PoFx, но не DFx, зарегистрируйтесь в PoFx с помощью структуры PO_FX_DEVICE_V2 или PO_FX_DEVICE_V3 структуры.

Каждый элемент в массиве компонентов описывает атрибуты состояния питания одного компонента на устройстве. Каждый компонент на устройстве определяется своими компонентами индексом массива. Подпрограммы, такие как PoFxActivateComponent и PoFxCompleteIdleCondition использовать индекс массива компонента для идентификации компонента.

Драйвер устройства не требуется для реализации всех восьми подпрограмм обратного вызова. Драйвер может задать указатель функции в структуре PO_FX_DEVICE значение NULL, если драйвер не реализует соответствующую подпрограмму обратного вызова. Однако некоторые подпрограммы обратного вызова должны быть реализованы. В частности, если на устройстве имеется несколько компонентов, драйвер должен реализовать ComponentIdleStateCallback, ComponentActiveConditionCallbackи подпрограмм ComponentIdleConditionCallback. В противном случае регистрация устройства завершается ошибкой и PoFxRegisterDevice возвращает STATUS_INVALID_PARAMETER.

Если драйвер не предоставляет одну из PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME или PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME система откатится к конфигурации по умолчанию платформы. Конфигурация по умолчанию PO_FX_DEVICE_FLAG_ENABLE_FAST_RESUME для платформ x86/x64 и PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME для платформ ARM32/ARM64. Эти флаги учитываются только для Win11 22000+ и автоматически игнорируются для предыдущих выпусков. Для драйверов WDF эти флаги можно указать с помощью поля PoFxDeviceFlagsWDF_POWER_FRAMEWORK_SETTINGS.