Macro WdfDeviceStopIdle (wdfdevice.h)

  • Article

[S’applique à KMDF et UMDF]

La méthode WdfDeviceStopIdle informe l’infrastructure que l’appareil spécifié doit être placé dans son état d’alimentation opérationnel (D0).

Syntaxe

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

Paramètres

[in] Device

Handle pour un objet d’appareil d’infrastructure.

[in] WaitForD0

Valeur booléenne qui indique quand WdfDeviceStopIdle sera retourné. Si la valeur est TRUE, elle retourne uniquement une fois que l’appareil spécifié est entré dans l’état d’alimentation de l’appareil D0. Si la valeur est FALSE, la méthode retourne immédiatement.

Valeur de retour

None

Remarques

Cette macro peut retourner les valeurs suivantes :

Valeur retournée Signification
STATUS_PENDING L’appareil est mis sous tension de façon asynchrone.
STATUS_INVALID_DEVICE_STATE Le pilote n’est pas le propriétaire de la stratégie d’alimentation de l’appareil.
STATUS_POWER_STATE_INVALID Une défaillance de l’appareil s’est produite et l’appareil ne peut pas entrer dans son état d’alimentation D0.

La méthode peut retourner d’autres valeurs NTSTATUS.

Notes

Pour les appareils qui spécifient SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint dans l’énumération WDF_POWER_POLICY_IDLE_TIMEOUT_TYPE , lors de l’appel de WdfDeviceStopIdle avec WaitForD0 défini sur FALSE, si l’appareil est toujours dans D0 et que le délai d’inactivité n’est pas encore écoulé, à compter de WDF versions 1.33/2.33, WdfDeviceStopIdle retourne STATUS_SUCCESS (dans les versions précédentes, la valeur de retour était STATUS_PENDING).

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Si votre appareil peut entrer dans un état de faible consommation lorsqu’il devient inactif, votre pilote peut être amené à appeler occasionnellement WdfDeviceStopIdle pour ramener l’appareil à son état de fonctionnement (D0) ou pour l’empêcher d’entrer dans un état de faible consommation.

WdfDeviceStopIdle n’empêche pas l’infrastructure de passer l’appareil à un état de veille lorsque le système passe à un état de veille Sx. Son seul effet est d’empêcher les transitions vers des états de veille Dx pendant que le système est dans l’état de fonctionnement de S0. De même, si l’appareil prend en charge la gestion de l’alimentation dirigée, WdfDeviceStopIdle n’empêche pas l’appareil d’entrer sous tension dirigée.

Avertissement

N’appelez pas WdfDeviceStopIdle avec WaitForD0 = TRUE pendant la mise hors tension, directement ou indirectement. Par exemple, si le rappel EvtDeviceArmWakeFromS0 attend sur un autre thread qui appelle WdfDeviceStopIdle(TRUE), la transition d’alimentation est bloquée et le système se bloque.

Votre pilote n’a pas besoin d’appeler WdfDeviceStopIdle lorsqu’un appareil est inactif et que l’infrastructure place une demande d’E/S dans la file d’attente d’E/S gérée par l’alimentation de l’appareil. En outre, votre pilote n’a pas besoin d’appeler WdfDeviceStopIdle lorsqu’un appareil est inactif et qu’il détecte un signal de sortie de veille. Dans les deux cas, l’infrastructure demande au pilote de bus de restaurer l’état d’alimentation de l’appareil sur D0.

Bien que les pilotes n’aient généralement pas besoin d’appeler WdfDeviceStopIdle lors de la gestion des demandes d’E/S qu’ils obtiennent à partir d’une file d’attente d’E/S gérée par l’alimentation, l’appel est autorisé. Toutefois, les pilotes ne doivent pas définir le paramètre WaitForD0 sur TRUE lors de la gestion des demandes d’E/S à partir d’une file d’attente d’E/S gérée par l’alimentation.

Votre pilote doit appeler WdfDeviceStopIdle s’il doit accéder à l’appareil en raison d’une demande que le pilote a reçue en dehors d’une file d’attente d’E/S gérée par l’alimentation. Par exemple, votre pilote peut prendre en charge une interface définie par le pilote ou une requête WMI qui nécessite l’accès à l’appareil. Dans ce cas, vous devez vous assurer que l’appareil est dans son état de fonctionnement avant que le pilote accède à l’appareil, et que l’appareil reste dans son état de fonctionnement jusqu’à ce que le pilote ait terminé d’accéder à l’appareil.

L’appel de WdfDeviceStopIdle force l’appareil dans son état de fonctionnement (D0), si le système est dans son état de fonctionnement (S0). L’appareil reste dans son état de fonctionnement jusqu’à ce que le pilote appelle WdfDeviceResumeIdle. À ce stade, l’infrastructure peut placer l’appareil dans un état de faible consommation s’il reste inactif.

N’appelez pas WdfDeviceStopIdle avant que le framework ait appelé la fonction de rappel EvtDeviceD0Entry du pilote pour la première fois.

Un appel à WdfDeviceStopIdle peut restaurer un appareil inactif à son état opérationnel uniquement si le système est dans son état de fonctionnement (S0). Si le système passe à un état de faible consommation ou si l’appareil a déjà été mis hors tension en réponse à Sx (où x > 0) lorsqu’un pilote appelle WdfDeviceStopIdle avec le paramètre WaitForD0 défini sur TRUE, la fonction ne retourne pas à son état S0.

Chaque appel réussi à WdfDeviceStopIdle doit finalement être suivi d’un appel à WdfDeviceResumeIdle, sinon l’appareil ne reviendra jamais à un état de faible consommation s’il redevient inactif. Les appels à WdfDeviceStopIdle pouvant être imbriqués, le nombre d’appels à WdfDeviceResumeIdle doit être égal au nombre d’appels à WdfDeviceStopIdle. N’appelez pas WdfDeviceResumeIdle si un appel à WdfDeviceStopIdle échoue.

Si le système entre dans un état de faible consommation après le retour de WdfDeviceStopIdle , l’appareil passe également à l’état de faible consommation. Lorsque le système revient à son état de fonctionnement (S0), l’appareil revient également à son état de fonctionnement (D0). La référence d’alimentation de l’appel à WdfDeviceStopIdle reste active et empêche l’appareil d’entrer dans un état de faible consommation jusqu’à ce qu’il y ait un appel correspondant à WdfDeviceResumeIdle.

Pour plus d’informations, consultez Prise en charge de la mise hors tension inactive.

Si WaitForD0 a la valeur TRUE, WdfDeviceStopIdle doit être appelé à l’adresse IRQL = PASSIVE_LEVEL. Si WaitForD0 a la valeur FALSE, cette méthode doit être appelée dans IRQL <= DISPATCH_LEVEL.

L’appel de WdfDeviceStopIdleWithTag au lieu de WdfDeviceStopIdle fournit des informations supplémentaires (valeur de balise, numéro de ligne et nom de fichier) que vous pouvez afficher dans les débogueurs Microsoft.

Exemples

Dans l’exemple de code suivant, WdfDeviceStopIdle retourne une fois que l’appareil spécifié est entré dans l’état d’alimentation de l’appareil D0.

NTSTATUS  status;

status = WdfDeviceStopIdle(Device, TRUE);

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2.0
En-tête wdfdevice.h (inclure Wdf.h)
Bibliothèque Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL Consultez la section Notes.
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi