estructura WDF_POWER_FRAMEWORK_SETTINGS (wdfdevice.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

La estructura de WDF_POWER_FRAMEWORK_SETTINGS describe la configuración del marco de administración de energía (PoFx) para dispositivos de un solo componente.

Sintaxis

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;

Miembros

Size

Tamaño, en bytes, de esta estructura.

EvtDeviceWdmPostPoFxRegisterDevice

Puntero a la función de devolución de llamada de eventos EvtDeviceWdmPostPoFxRegisterDevice del controlador o NULL.

EvtDeviceWdmPrePoFxUnregisterDevice

Puntero a la función de devolución de llamada de eventos EvtDeviceWdmPrePoFxUnregisterDevice del controlador o NULL.

Component

Puntero a una estructura PO_FX_COMPONENT que describe el único componente del dispositivo de un solo componente o NULL. Si es NULL, KMDF solo admite F0 para este componente. Esta estructura especifica el número y los atributos de los estados F que admite el componente, así como el estado fx más profundo del que puede despertar el componente.

ComponentActiveConditionCallback

Puntero a la rutina de devolución de llamada ComponentActiveConditionCallback del controlador o NULL. El marco de administración de energía (PoFx) llama a esta función de devolución de llamada cuando un componente se activa. Mientras se encuentra en la condición Activo, se garantiza que el componente esté en F0.

ComponentIdleConditionCallback

Puntero a la función de devolución de llamada ComponentIdleConditionCallback del controlador o NULL. PoFx llama a esta función de devolución de llamada cuando un componente deja de estar inactivo. Mientras se encuentra en la condición De inactividad, el componente puede estar en cualquier estado F, incluido F0.

ComponentIdleStateCallback

Puntero a la función de devolución de llamada ComponentIdleStateCallback del controlador o NULL. PoFx llama a esta función de devolución de llamada cuando cambia el estado F del componente.

PowerControlCallback

Puntero a la función de devolución de llamada PowerControlCallback del controlador cliente o NULL. PoFx llama a esta rutina para pasar una solicitud de una operación de control de energía directamente al controlador. Si el controlador no admite ningún código de control de energía, establezca este parámetro en NULL.

PoFxDeviceContext

Puntero de contexto que el marco proporciona a ComponentActiveConditionCallback, ComponentIdleConditionCallback, ComponentIdleStateCallback y PowerControlCallback.

PoFxDeviceFlags

Valor de tipo ULONGLONG que contiene el OR bit a bit de los siguientes valores relacionados con El marco de administración de energía dirigido. Este campo está disponible a partir de la versión 1.33 de KMDF y UMDF 2.33.

PO_FX_DEVICE_FLAG_DFX_CHILDREN_OPTIONAL

Cuando la instancia de Power Framework dirigida ("DFx") está habilitada en un dispositivo, normalmente los dispositivos secundarios también habilitan DFx. Sin embargo, en algunos casos (por ejemplo, un dispositivo de software puro), un dispositivo secundario no implementa la administración de energía. Establezca esta marca para permitir que este dispositivo secundario omita DFx.

Para establecer esta marca en nombre de los dispositivos secundarios, el controlador WDF primario debe:

Participación en DFx
No ser un conductor de autobús
Tener al menos un dispositivo secundario virtual creado a través de un canal de banda lateral (por ejemplo, un filtro superior o un dispositivo creado mediante una llamada a SwDeviceCreate

En el caso de los controladores que tienen como destino WDF anterior a v33, especifique la directiva INF: WdfDirectedPowerTransitionChildrenOptional, que está disponible a partir de Windows 10, versión 1903. Si el controlador especifica la directiva INF y establece esta marca, la directiva INF tiene prioridad.

PO_FX_DEVICE_FLAG_DISABLE_FAST_RESUME

Esto es necesario para implementar IRP_MN_QUERY_DEVICE_RELATIONS/PowerRelations entre dos dispositivos.

De forma predeterminada, WDF implementa una reanudación rápida, lo que significa que durante la reactivación del sistema, el propietario de la directiva de energía en una pila de dispositivos completa un S0-IRP sin esperar a solicitar y completar un D0-IRP. Esto no funciona bien con PowerRelations.

Para que PowerRelations funcione correctamente, si un dispositivo depende de otro dispositivo para entrar en D0 en primer lugar, el segundo dispositivo debe establecer esta marca para no participar en la reanudación rápida.

En algunos casos, la directiva global puede deshabilitar la reanudación rápida globalmente incluso si esta marca no está establecida.

DirectedPoFxEnabled

Enumerador con tipo WDF_TRI_STATE que indica si el dispositivo habilita Directed Power Management Framework (DFx). Disponible a partir de la versión 1.33 de KMDF y UMDF 2.33.

WdfTrue : DFx está habilitado. WdfFalse : DFx está deshabilitado. WdfUseDefault : valor predeterminado si el controlador no establece uno. Este valor tiene el mismo significado que WdfTrue.

Directed PoFx (DFx) está disponible a partir de Windows 10, versión 1903 como opción para los controladores que usan SystemManagedIdleTimeout o SystemManagedIdleTimeoutWithHint.

Para un controlador que tenga como destino WDF anterior a la versión 31, establezca la directiva INF WdfDirectedPowerTransitionEnable en 1 para participar en DFx.
Para un controlador destinado a WDF v31+, DFx está habilitado de forma predeterminada. El controlador puede establecer WdfDirectedPowerTransitionEnable en cero para no participar en DFx.
Para un controlador destinado a WDF v33+, DFx también está habilitado de forma predeterminada. El controlador puede establecer WdfDirectedPowerTransitionEnable en cero o establecer este campo en WdfFalse (recomendado) para no participar en DFx. Si se establecen ambos, la directiva INF tiene prioridad.

Comentarios

La estructura WDF_POWER_FRAMEWORK_SETTINGS se usa una entrada para WdfDeviceWdmAssignPowerFrameworkSettings.

Para inicializar su estructura de WDF_POWER_FRAMEWORK_SETTINGS , el controlador debe llamar a WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Para UMDF, solo se usan Size, PoFxDeviceFlags y DirectedPoFxEnabled . Se omiten otros campos y se deben establecer en cero. El marco lo hace automáticamente cuando un controlador UMDF llama a WDF_POWER_FRAMEWORK_SETTINGS_INIT.

Para obtener más información, consulte Compatibilidad con estados de energía funcionales e información general de Power Management Framework.

Esta estructura no es aplicable a los controladores de cliente KMDF para dispositivos de varios componentes.