Macro WdfDeviceStopIdle (wdfdevice.h)

Articolo
03/08/2023

[Si applica a KMDF e UMDF]

Il metodo WdfDeviceStopIdle informa il framework che il dispositivo specificato deve essere inserito nello stato di alimentazione funzionante (D0).

Sintassi

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

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] WaitForD0

Valore booleano che indica quando verrà restituito WdfDeviceStopIdle . Se TRUE, restituisce solo dopo che il dispositivo specificato ha immesso lo stato di alimentazione del dispositivo D0. Se FALSE, il metodo restituisce immediatamente.

Valore restituito

nessuno

Osservazioni

Questa macro può restituire i valori seguenti:

Valore restituito	Significato
STATUS_PENDING	Il dispositivo viene alimentato in modo asincrono.
STATUS_INVALID_DEVICE_STATE	Il driver non è il proprietario dei criteri di alimentazione per il dispositivo.
STATUS_POWER_STATE_INVALID	Si è verificato un errore del dispositivo e il dispositivo non può immettere lo stato di alimentazione D0.

Il metodo potrebbe restituire altri valori NTSTATUS.

Nota

Per i dispositivi che specificano SystemManagedIdleTimeout o SystemManagedIdleTimeoutWithHint nell'enumerazione WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE, quando si chiama WdfDeviceStopIdle con WaitForD0 impostato su FALSE, se il dispositivo è ancora in D0 e il periodo di timeout inattiva non è ancora trascorso, a partire dalle versioni WDF 1.33/2.33, WdfDeviceStopIdle restituisce STATUS_SUCCESS (nelle versioni precedenti questo ha generato un valore restituito di STATUS_PENDING).

Un controllo di bug si verifica se il driver fornisce un handle di oggetti non valido.

Se il dispositivo può immettere uno stato di bassa potenza quando diventa inattivo, il driver potrebbe dover chiamare occasionalmente WdfDeviceStopIdle per ripristinare lo stato di lavoro (D0) o per impedire l'immissione di uno stato di bassa potenza.

WdfDeviceStopIdle non impedisce al framework di passare il dispositivo a uno stato di sospensione quando il sistema cambia in uno stato di sospensione Sx. L'unico effetto è impedire le transizioni agli stati di sospensione Dx mentre il sistema si trova nello stato di lavoro S0. Analogamente, se il dispositivo supporta la gestione dell'alimentazione diretta, WdfDeviceStopIdle non impedisce al dispositivo di immettere l'alimentazione diretta.

Avviso

Non chiamare WdfDeviceStopIdle con WaitForD0 = TRUE durante l'alimentazione, direttamente o indirettamente. Ad esempio, se il callback EvtDeviceArmWakeFromS0 attende un altro thread che chiama WdfDeviceStopIdle(TRUE), la transizione di alimentazione viene bloccata e il sistema si arresta in modo anomalo.

Il driver non deve chiamare WdfDeviceStopIdle quando un dispositivo è inattivo e il framework inserisce una richiesta di I/O nella coda di I/O del dispositivo. Inoltre, il driver non deve chiamare WdfDeviceStopIdle quando un dispositivo è inattivo e rileva un segnale di riattivazione. In entrambi questi casi, il framework richiede al driver del bus di ripristinare lo stato di alimentazione del dispositivo su D0.

Anche se i driver in genere non devono chiamare WdfDeviceStopIdle durante la gestione delle richieste di I/O ottenute da una coda di I/O gestita da alimentazione, la chiamata è consentita. Tuttavia, i driver non devono impostare il parametro WaitForD0 su TRUE durante la gestione delle richieste di I/O da una coda di I/O gestita da energia.

Il driver deve chiamare WdfDeviceStopIdle se deve accedere al dispositivo a causa di una richiesta ricevuta dal driver all'esterno di una coda di I/O gestita dall'alimentazione. Ad esempio, il driver potrebbe supportare un'interfaccia definita dal driver o una richiesta WMI che richiede l'accesso al dispositivo. In questo caso, è necessario assicurarsi che il dispositivo si trovi nello stato di lavoro prima che il driver acceda al dispositivo e che il dispositivo rimanga nello stato di lavoro fino al termine dell'accesso al dispositivo.

La chiamata a WdfDeviceStopIdle forza il dispositivo nello stato di lavoro (D0), se il sistema si trova nello stato di lavoro (S0). Il dispositivo rimane nello stato di funzionamento fino a quando il driver chiama WdfDeviceResumeIdle, a quel punto il framework può posizionare il dispositivo in uno stato di bassa potenza se rimane inattiva.

Non chiamare WdfDeviceStopIdle prima che il framework abbia chiamato la funzione di callback EvtDeviceD0Entry del driver per la prima volta.

Una chiamata a WdfDeviceStopIdle può ripristinare lo stato di funzionamento di un dispositivo inattivo solo se il sistema si trova nello stato di lavoro (S0). Se il sistema passa a uno stato a bassa potenza o il dispositivo è già stato spento in risposta a Sx (dove x > 0) quando un driver chiama WdfDeviceStopIdle con il parametro WaitForD0 impostato su TRUE, la funzione non restituisce fino a quando il sistema torna allo stato S0.

Ogni chiamata riuscita a WdfDeviceStopIdle deve essere seguita da una chiamata a WdfDeviceResumeIdle oppure il dispositivo non tornerà mai a uno stato di bassa potenza se diventa di nuovo inattivo. Le chiamate a WdfDeviceStopIdle possono essere annidate, quindi il numero di chiamate a WdfDeviceResumeIdle deve corrispondere al numero di chiamate a WdfDeviceStopIdle. Non chiamare WdfDeviceResumeIdle se una chiamata a WdfDeviceStopIdle ha esito negativo.

Se il sistema entra in uno stato a bassa potenza dopo che WdfDeviceStopIdle restituisce, il dispositivo entra anche in uno stato a bassa potenza. Quando il sistema torna allo stato di lavoro (S0), il dispositivo restituisce anche lo stato di lavoro (D0). Il riferimento di alimentazione dalla chiamata a WdfDeviceStopIdle rimane attivo e impedisce al dispositivo di immettere uno stato a bassa potenza fino a quando non è presente una chiamata corrispondente a WdfDeviceResumeIdle.

Per altre informazioni, vedere Supporto dell'alimentazione inattiva.

Se WaitForD0 è TRUE, È necessario chiamare WdfDeviceStopIdle in IRQL = PASSIVE_LEVEL. Se WaitForD0 è FALSE, questo metodo deve essere chiamato in IRQL <= DISPATCH_LEVEL.

La chiamata a WdfDeviceStopIdleWithTag anziché WdfDeviceStopIdle fornisce informazioni aggiuntive (valore tag, numero di riga e nome file) che è possibile visualizzare nei debugger Microsoft.

Esempio

Nell'esempio di codice seguente , WdfDeviceStopIdle restituisce dopo che il dispositivo specificato ha immesso lo stato di alimentazione del dispositivo D0.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	2,0
Intestazione	wdfdevice.h (includere Wdf.h)
Libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	Vedere La sezione Osservazioni.
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Share via