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

Статья
08/08/2023

Структура 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.

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

Flag	Описание
PO_FX_DEVICE_FLAG_DIRECT_CHILDREN_OPTIONAL	Позволяет прямым дочерним устройствам этого устройства при необходимости поддерживать direct PoFx. Если значение не задано, все прямые дочерние элементы должны поддерживать Direct PoFx, чтобы это устройство полностью поддерживало Direct PoFx.
PO_FX_DEVICE_FLAG_POWER_CHILDREN_OPTIONAL	Позволяет дочерним устройствам питания этого устройства при необходимости поддерживать направленный poFx. Если этот параметр не указан, все дочерние элементы питания должны поддерживать значение Directed PoFx, чтобы это устройство полностью поддерживало значение Directed 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 . Кроме того, этот элемент указывает количество компонентов на устройстве.

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 структуру.

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

Драйвер устройства не требуется для реализации всех восьми процедур обратного вызова. Драйвер может задать для указателя функции в структуре PO_FX_DEVICE значение NULL, если драйвер не реализует соответствующую процедуру обратного вызова. Однако необходимо реализовать некоторые процедуры обратного вызова. В частности, если один или несколько компонентов на устройстве имеют несколько состояний Fx, драйвер должен реализовать подпрограммы 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.