GET_IDLE_WAKE_INFO función de devolución de llamada (wdm.h)

Artículo
03/08/2023

La rutina GetIdleWakeInfo permite al controlador detectar los estados de energía del dispositivo desde los que el dispositivo puede indicar un evento de reactivación.

Sintaxis

GET_IDLE_WAKE_INFO GetIdleWakeInfo;

NTSTATUS GetIdleWakeInfo(
  [in, optional] PVOID Context,
  [in]           SYSTEM_POWER_STATE SystemPowerState,
  [out]          PDEVICE_WAKE_DEPTH DeepestWakeableDstate
)
{...}

Parámetros

[in, optional] Context

Puntero a información de contexto específica de la interfaz. El autor de la llamada establece este parámetro en el valor del miembro Context de la estructura D3COLD_SUPPORT_INTERFACE para la interfaz.

[in] SystemPowerState

Estado de alimentación del sistema. Establezca este parámetro en uno de los siguientes valores de enumeración SYSTEM_POWER_STATE:

PowerSystemWorking
PowerSystemSleeping1
PowerSystemSleeping2
PowerSystemSleeping3
PowerSystemHibernate

Estos valores representan estados de energía del sistema S0 (estado de funcionamiento del sistema) a través de S4. Para el valor SystemPowerState proporcionado por el autor de la llamada, la rutina determina el estado de alimentación más profundo del dispositivo desde el que el dispositivo puede emitir una señal de reactivación.

[out] DeepestWakeableDstate

Estado Dx de reactivación más profundo. Este parámetro es un puntero a una variable DEVICE_WAKE_DEPTH . Si la llamada se realiza correctamente, la rutina escribe uno de los siguientes valores de enumeración en esta variable:

DeviceWakeDepthNotWakeable
DeviceWakeDepthD0
DeviceWakeDepthD1
DeviceWakeDepthD2
DeviceWakeDepthD3hot
DeviceWakeDepthD3cold

Un valor del intervalo DeviceWakeDepthD0 a DeviceWakeDepthD3cold indica el estado Dx con tecnología más baja desde el que el dispositivo puede enviar una señal de reactivación cuando el equipo está en el estado de alimentación del sistema especificado por el parámetro SystemPowerState . DeviceWakeDepthNotWakeable indica que no hay ningún estado de alimentación del dispositivo desde el que el dispositivo puede enviar una señal de reactivación cuando el equipo está en el estado de alimentación del sistema especificado por SystemPowerState.

Si la rutina no puede determinar el estado de dispositivo de reactivación más profundo (quizás porque el firmware de la plataforma no contiene esta información), se produce un error en la llamada y la rutina devuelve un código de estado de error. Si se produce un error en una llamada GetIdleWakeInfo para cualquier valor de parámetro SystemPowerState en el intervalo PowerSystemWorking en PowerSystemHibernate, se producirá un error para todos estos valores.

Valor devuelto

La rutina GetIdleWakeInfo devuelve STATUS_SUCCESS si recupera correctamente el estado más profundo del dispositivo reactivable. De lo contrario, devuelve un código de estado de error adecuado.

Comentarios

En el caso del estado de alimentación del sistema especificado por el autor de la llamada, esta rutina intenta determinar el estado de alimentación del dispositivo más bajo desde el que el dispositivo puede indicar un evento de reactivación al procesador. Si se ejecuta correctamente, la rutina escribe el estado de energía del dispositivo en la ubicación a la que apunta el parámetro De más profundoWakeableDstate y devuelve STATUS_SUCCESS. O bien, si la rutina determina que el dispositivo no puede indicar un evento de reactivación desde cualquier estado de alimentación del dispositivo, la rutina escribe el valor DeviceWakethNotWakeable en esta ubicación y devuelve STATUS_SUCCESS.

El controlador de un dispositivo usa la información proporcionada por la rutina GetIdleWakeInfo para determinar las condiciones en las que el dispositivo puede indicar un evento de reactivación. Un dispositivo que necesite poder señalar determinados eventos de reactivación no debe entrar en un estado de alimentación del dispositivo desde el que no puede señalar estos eventos. Para algunos tipos de dispositivos, la reactivación indica que el dispositivo debe enviarse cuando el equipo está en el estado de alimentación del sistema S0 (funcionando) difiere de los que el dispositivo debe enviar cuando el equipo parece estar apagado.

Por ejemplo, cuando se inserta una tarjeta en una ranura de tarjeta PCI Express, y el dispositivo controlador de conexión activa PCI Express para la ranura está en estado de alimentación del dispositivo D0, este dispositivo señala una interrupción al procesador. Sin embargo, si el dispositivo controlador está en un estado Dx de bajo consumo cuando se inserta la tarjeta, el estado de alimentación del sistema del equipo podría determinar si este dispositivo debe indicar un evento de reactivación al procesador. Lo ideal es que el dispositivo del controlador se comporte de la siguiente manera:

Si el equipo está en el estado de alimentación del sistema S0 (funciona), el dispositivo debe indicar un evento de reactivación al procesador.
Si el equipo está en suspensión (en un estado de Sx de bajo consumo), el dispositivo no debe indicar un evento de reactivación.

Es posible que algunos dispositivos más antiguos no admitan este comportamiento ideal. Si el dispositivo controlador de conexión activa PCI Express en este ejemplo puede indicar un evento de reactivación solo cuando el equipo está en estado S3, el controlador (que, en este caso, es la bandeja de entrada Pci.sys controlador) para el controlador debe mantener el controlador en D0 cuando el equipo está en S0 (y no se prepara para entrar en estado de suspensión).

El controlador de este ejemplo puede llamar a la rutina GetIdleWakeInfo para determinar si el dispositivo controlador de conexión activa debe dejar el estado D0 mientras el equipo está en S0. Para esta llamada, el controlador establece SystemPowerState = PowerSystemWorking. Este dispositivo no debe dejar el estado D0 (cuando el equipo está en S0) en cualquiera de los casos siguientes:

La llamada a GetIdleWakeInfo establece el parámetro de salida en DeviceWakeDepthNotWakeable o DeviceWakeDepthD0 y devuelve STATUS_SUCCESS.
Se produce un error en la llamada a GetIdleWakeInfo y devuelve un código de estado de error.

El controlador debe interpretar cualquiera de estos resultados para significar que el dispositivo no puede indicar un evento de reactivación cuando el equipo está en S0. En función de esta información, el controlador debe mantener el dispositivo en D0 hasta que el equipo se prepare para salir de S0.

Los controladores para la mayoría de los dispositivos pueden tratar un valor de salida de DeviceWakeDepthD0 igual que DeviceWakeDepthNotWakeable. Solo algunos controladores pueden tener una razón para armar una señal de reactivación cuando sus dispositivos están en D0. Estos son controladores para dispositivos simples que supervisan eventos externos que desencadenan señales de reactivación independientemente de si los dispositivos están en estados D0 o Dx de bajo consumo. Un ejemplo de este tipo de dispositivo es un botón de encendido o un botón de suspensión en un equipo.

La rutina GetIdleWakeInfo consulta el controlador de bus subyacente y el firmware del sistema ACPI para determinar el estado de energía del dispositivo más bajo desde el que el dispositivo puede señalar un evento de reactivación. Si el controlador y el firmware del bus no pueden proporcionar esta información, la rutina produce un error y devuelve un código de estado de error.

La estructura DEVICE_CAPABILITIES incluye un miembro DeviceWake que proporciona información similar a la disponible en la rutina GetIdleWakeInfo . Sin embargo, la información del miembro DeviceWake solo se aplica a los estados de baja potencia del sistema S1 a S4. En algunos dispositivos, la información del miembro DeviceWake también se puede aplicar al estado de alimentación del sistema S0, pero los controladores no deben depender de este comportamiento. Solo la rutina GetIdleWakeInfo notifica de forma confiable la capacidad de un dispositivo para indicar un evento de reactivación si el equipo está en S0.

Se proporciona una función auxiliar insertada, MapWakeDepthToDstate, para convertir el valor de salida DEVICE_WAKE_DEPTH de la rutina GetIdleWakeInfo a un valor de DEVICE_POWER_STATE que puede usarse como parámetro de entrada por la rutina PoRequestPowerIrp .

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible a partir de Windows 8.
Plataforma de destino	Escritorio
Encabezado	wdm.h (incluya Wdm.h)
IRQL	PASSIVE_LEVEL