estructura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS (wdfdevice.h)

Artículo
08/08/2023

[Se aplica a KMDF y UMDF]

La estructura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS contiene información proporcionada por el controlador sobre la capacidad de un dispositivo para reactivarse y el sistema, cuando ambos están en un estado de bajo consumo.

Sintaxis

typedef struct _WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS {
  ULONG                                 Size;
  DEVICE_POWER_STATE                    DxState;
  WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings;
  WDF_TRI_STATE                         Enabled;
  BOOLEAN                               ArmForWakeIfChildrenAreArmedForWake;
  BOOLEAN                               IndicateChildWakeOnParentWake;
} WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS, *PWDF_DEVICE_POWER_POLICY_WAKE_SETTINGS;

Miembros

Size

Tamaño, en bytes, de esta estructura.

DxState

Enumerador con tipo DEVICE_POWER_STATE que identifica el estado de baja potencia del dispositivo que el dispositivo entrará cuando el estado de alimentación del sistema caiga en un estado de baja potencia reactivable. El valor de DxState no puede ser PowerDeviceD0. DEVICE_POWER_STATE valores se definen en wdm.h.

UserControlOfWakeSettings

Enumerador con tipo WDF_POWER_POLICY_SX_WAKE_USER_CONTROL que indica si los usuarios tienen la capacidad de modificar la configuración de reactivación del dispositivo.

Enabled

Enumerador con tipo WDF_TRI_STATE que indica si el dispositivo puede reactivar el sistema (es decir, restaurar el sistema a S0) cuando el sistema está en estado de baja potencia. Este miembro puede tener uno de los siguientes valores:

WdfTrue : activar el sistema está habilitado.

WdfFalse : la reactivación del sistema está deshabilitada.

WdfUseDefault : la reactivación del sistema está habilitada inicialmente de forma predeterminada; pero si el miembro UserControlOfWakeSettings está establecido en WakeAllowUserControl, la configuración del usuario o el archivo INF del controlador invalida el valor inicial.

Si la reactivación del sistema está habilitada y el sistema está a punto de entrar en un estado de baja potencia, el marco llama a la función de devolución de llamada EvtDeviceArmWakeFromSx o EvtDeviceArmWakeFromSxWithReason antes de que el dispositivo entre en un estado de baja potencia.

ArmForWakeIfChildrenAreArmedForWake

Un valor booleano que, si se establece en TRUE, indica que la capacidad de un dispositivo primario para reactivarse y el sistema debe habilitarse cuando esta capacidad está habilitada para los dispositivos secundarios del dispositivo. Para obtener más información, vea la sección Comentarios que se muestra más adelante. Este miembro está disponible en la versión 1.7 y versiones posteriores de KMDF.

IndicateChildWakeOnParentWake

Un valor booleano que, si se establece en TRUE, indica que el marco proporcionará el estado de reactivación a los dispositivos secundarios si un dispositivo primario detecta una señal de reactivación. Para obtener más información, vea la sección Comentarios que se muestra más adelante. Este miembro está disponible en la versión 1.7 y versiones posteriores de KMDF.

Comentarios

La estructura WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS se usa como entrada para WdfDeviceAssignSxWakeSettings.

Para inicializar su estructura de WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS , el controlador debe llamar a WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS_INIT.

La primera vez que un controlador llama a WdfDeviceAssignSxWakeSettings, se producen las siguientes acciones:

El marco almacena los valores de todos los miembros de estructura de WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS .
Si el miembro UserControlOfWakeSettings se establece en WakeAllowUserControl y si el miembro Enabled está establecido en WdfUseDefault, el marco lee el registro para averiguar si el usuario ha habilitado la reactivación del sistema.

Durante las llamadas posteriores a WdfDeviceAssignSxWakeSettings, el marco no almacena el valor del miembro UserControlOfWakeSettings . En otras palabras, el marco realiza los pasos siguientes la primera vez que el controlador llama a WdfDeviceAssignSxWakeSettings , pero no durante las llamadas posteriores:

Almacena el valor del miembro UserControlOfWakeSettings .
Busca una configuración de usuario en el Registro, si el valor del miembro Enabled es WdfUseDefault.

Las reglas siguientes se aplican al valor especificado para el miembro DxState :

El valor no puede ser PowerDeviceD0.
Si especifica PowerDeviceMaximum, el marco usa el valor que el controlador del bus del dispositivo proporciona en el miembro DeviceWake de su estructura de WDF_DEVICE_POWER_CAPABILITIES .
No se puede especificar un estado de alimentación del dispositivo inferior al estado de alimentación del dispositivo en el miembro DeviceWake de la estructura WDF_DEVICE_POWER_CAPABILITIES del controlador de autobús. (En otras palabras, si el valor DeviceWake del controlador de bus es PowerDeviceD2, el valor dxState del controlador de función no puede ser PowerDeviceD3).

Para obtener información sobre las entradas del Registro que controlan las funcionalidades de reactivación de un dispositivo, consulte Control de usuario del comportamiento inactivo y de reactivación del dispositivo.

Si el dispositivo que describe la estructura de WDF_DEVICE_POWER_POLICY_WAKE_SETTINGS es un dispositivo primario, el controlador del dispositivo primario puede usar los miembros ArmForWakeIfChildrenAreArmedForWake e IndicateChildWakeOnParentWake de la siguiente manera:

Si el controlador establece el miembro ArmForWakeIfChildrenAreArmedForWake en TRUE, el marco llama a la función de devolución de llamada EvtDeviceArmWakeFromSx o EvtDeviceArmWakeFromSxWithReason cuando se habilita la capacidad de reactivación de un dispositivo secundario, incluso si la capacidad de reactivación del dispositivo primario no está habilitada.
Para reducir el consumo de energía, es posible que no quiera habilitar la capacidad de reactivación del dispositivo a menos que un dispositivo secundario que también admita una capacidad de reactivación esté conectada. Si el controlador establece el miembro ArmForWakeIfChildrenAreArmedForWake en TRUE, los valores del miembro Enabled tienen los siguientes significados:
- Si Enabled es WdfFalse, el marco habilita la capacidad de reactivación del controlador solo si está habilitada la capacidad de reactivación de un dispositivo secundario.
- Si Enabled es WdfTrue, el marco siempre habilita la capacidad de reactivación del controlador, tanto si el dispositivo tiene dispositivos secundarios habilitados para reactivación como si no.
- Si Enabled es WdfUseDefault y UserControlOfWakeSettings es WakeAllowUserControl, los usuarios pueden controlar si el dispositivo siempre está habilitado para reactivación o si está habilitado para reactivación solo cuando el dispositivo tiene dispositivos secundarios habilitados para reactivación.
Si el controlador establece el miembro IndicateChildWakeOnParentWake en TRUE, el marco llama a la función de devolución de llamada EvtDeviceWakeFromSxTriggered en el controlador del dispositivo primario y en el controlador para cada dispositivo secundario habilitado para reactivación. Si el controlador establece este miembro en FALSE, el marco llama a la función de devolución de llamada EvtDeviceWakeFromSxTriggered solo en el controlador del dispositivo primario. El controlador debe establecer IndicateChildWakeOnParentWake en TRUE si los controladores de los elementos secundarios del dispositivo deben examinar el hardware para determinar por qué se despertó el sistema.

Para obtener más información sobre cómo admitir la capacidad de reactivación de un dispositivo, consulte Compatibilidad con la reactivación del sistema.