Macro WdfDeviceStopIdle (wdfdevice.h)

Artículo
03/08/2023

[Se aplica a KMDF y UMDF]

El método WdfDeviceStopIdle informa al marco de trabajo de que el dispositivo especificado debe colocarse en su estado de alimentación en funcionamiento (D0).

Sintaxis

NTSTATUS WdfDeviceStopIdle(
   _In_ WDFDEVICE Device,
   _In_ BOOLEAN WaitForD0
);

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] WaitForD0

Valor booleano que indica cuándo se devolverá WdfDeviceStopIdle . Si es TRUE, devuelve solo después de que el dispositivo especificado haya entrado en el estado de alimentación del dispositivo D0. Si es FALSE, el método devuelve inmediatamente.

Valor devuelto

None

Observaciones

Esta macro puede devolver los siguientes valores:

Valor devuelto	Significado
STATUS_PENDING	El dispositivo se está alimentando de forma asincrónica.
STATUS_INVALID_DEVICE_STATE	El controlador no es el propietario de la directiva de energía del dispositivo.
STATUS_POWER_STATE_INVALID	Se produjo un error en el dispositivo y el dispositivo no puede entrar en su estado de alimentación D0.

El método podría devolver otros valores NTSTATUS.

Nota

Para los dispositivos que especifican SystemManagedIdleTimeout o SystemManagedIdleTimeoutWithHint en la enumeración WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE , al llamar a WdfDeviceStopIdle con WaitForD0 establecido en FALSE, si el dispositivo todavía está en D0 y el período de tiempo de espera de inactividad aún no ha transcurrido, a partir de las versiones 1.33/2.33 de WDF, WdfDeviceStopIdle devuelve STATUS_SUCCESS (en versiones anteriores, esto dio como resultado un valor devuelto de STATUS_PENDING).

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Si el dispositivo puede entrar en un estado de bajo consumo cuando está inactivo, es posible que el controlador tenga que llamar ocasionalmente a WdfDeviceStopIdle para devolver el dispositivo a su estado de funcionamiento (D0) o para evitar que entre en un estado de bajo consumo.

WdfDeviceStopIdle no impide que el marco realice la transición del dispositivo a un estado de suspensión cuando el sistema cambia a un estado de suspensión de Sx. Su único efecto es evitar transiciones a estados de suspensión Dx mientras el sistema está en estado de trabajo S0. Del mismo modo, si el dispositivo admite la administración de energía dirigida, WdfDeviceStopIdle no impide que el dispositivo entre en la alimentación dirigida.

Advertencia

No llame a WdfDeviceStopIdle con WaitForD0 = TRUE durante el apagado, ya sea directa o indirectamente. Por ejemplo, si la devolución de llamada EvtDeviceArmWakeFromS0 espera en otro subproceso que llama WdfDeviceStopIdle(TRUE)a , la transición de energía se bloquea y el sistema se bloquea.

El controlador no tiene que llamar a WdfDeviceStopIdle cuando un dispositivo está inactivo y el marco coloca una solicitud de E/S en la cola de E/S administrada por energía del dispositivo. Además, el controlador no tiene que llamar a WdfDeviceStopIdle cuando un dispositivo está inactivo y detecta una señal de reactivación. En ambos casos, el marco solicita al controlador de bus que restaure el estado de alimentación del dispositivo en D0.

Aunque los controladores normalmente no necesitan llamar a WdfDeviceStopIdle al controlar las solicitudes de E/S que obtienen de una cola de E/S administrada por energía, se permite la llamada. Sin embargo, los controladores no deben establecer el parámetro WaitForD0 en TRUE al controlar las solicitudes de E/S desde una cola de E/S administrada por energía.

El controlador tiene que llamar a WdfDeviceStopIdle si debe acceder al dispositivo debido a una solicitud que el controlador ha recibido fuera de una cola de E/S administrada por energía. Por ejemplo, el controlador puede admitir una interfaz definida por el controlador o una solicitud WMI que requiera acceder al dispositivo. En este caso, debe asegurarse de que el dispositivo está en su estado de trabajo antes de que el controlador acceda al dispositivo y que el dispositivo permanezca en su estado de trabajo hasta que el controlador haya terminado de acceder al dispositivo.

La llamada a WdfDeviceStopIdle obliga al dispositivo a que funcione (D0), si el sistema está en su estado de funcionamiento (S0). El dispositivo permanece en su estado de trabajo hasta que el controlador llama a WdfDeviceResumeIdle, momento en el que el marco puede colocar el dispositivo en un estado de bajo consumo si permanece inactivo.

No llame a WdfDeviceStopIdle antes de que el marco haya llamado a la función de devolución de llamada EvtDeviceD0Entry del controlador por primera vez.

Una llamada a WdfDeviceStopIdle puede restaurar un dispositivo inactivo a su estado de funcionamiento solo si el sistema está en estado de funcionamiento (S0). Si el sistema realiza la transición a un estado de baja potencia o el dispositivo ya se ha apagado en respuesta a Sx (donde x > 0) cuando un controlador llama a WdfDeviceStopIdle con el parámetro WaitForD0 establecido en TRUE, la función no devuelve hasta que el sistema vuelve a su estado S0.

Cada llamada correcta a WdfDeviceStopIdle debe ir seguida de una llamada a WdfDeviceResumeIdle o, de lo contrario, el dispositivo nunca volverá a un estado de bajo consumo si vuelve a estar inactivo. Las llamadas a WdfDeviceStopIdle se pueden anidar, por lo que el número de llamadas a WdfDeviceResumeIdle debe ser igual al número de llamadas a WdfDeviceStopIdle. No llame a WdfDeviceResumeIdle si se produce un error en una llamada a WdfDeviceStopIdle .

Si el sistema entra en un estado de bajo consumo después de que WdfDeviceStopIdle vuelva, el dispositivo también entra en un estado de bajo consumo. Cuando el sistema vuelve a su estado de funcionamiento (S0), el dispositivo también vuelve a su estado de trabajo (D0). La referencia de energía de la llamada a WdfDeviceStopIdle permanece activa y evita que el dispositivo entre en un estado de bajo consumo hasta que haya una llamada coincidente a WdfDeviceResumeIdle.

Para obtener más información, consulte Compatibilidad con la alimentación inactiva.

Si WaitForD0 es TRUE, se debe llamar a WdfDeviceStopIdle en IRQL = PASSIVE_LEVEL. Si WaitForD0 es FALSE, se debe llamar a este método en IRQL <= DISPATCH_LEVEL.

Llamar a WdfDeviceStopIdleWithTag en lugar de WdfDeviceStopIdle proporciona información adicional (valor de etiqueta, número de línea y nombre de archivo) que puede ver en los depuradores de Microsoft.

Ejemplos

En el ejemplo de código siguiente, WdfDeviceStopIdle devuelve después de que el dispositivo especificado haya entrado en el estado de alimentación del dispositivo D0.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
Versión mínima de UMDF	2.0
Encabezado	wdfdevice.h (incluir Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	vea la sección Comentarios.
Reglas de cumplimiento de DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)