GET_D3COLD_CAPABILITY fonction de rappel (wdm.h)

Article
02/07/2025

La routine GetBusDriverD3ColdSupport permet au pilote d’un appareil d’interroger si le pilote de bus énumérant prend en charge l’état d’alimentation de l’appareil D3cold.

Syntaxe

GET_D3COLD_CAPABILITY GetD3coldCapability;

NTSTATUS GetD3coldCapability(
  [in, optional] PVOID Context,
  [out]          PBOOLEAN D3ColdSupported
)
{...}

Paramètres

[in, optional] Context

Pointeur vers des informations de contexte spécifiques à l’interface. L’appelant définit ce paramètre sur la valeur du membre Context de la structure D3COLD_SUPPORT_INTERFACE de l’interface.

[out] D3ColdSupported

Pointeur vers une variable BOOLEAN dans laquelle la routine écrit une valeur pour indiquer si le pilote de bus prend en charge le D3cold. Si cette valeur est TRUE, le pilote de bus prend en charge D3cold. Si FAUX, le pilote de bus ne prend pas en charge D3cold. Si l’appel échoue, la routine retourne un code d’état d’erreur et n’écrit rien dans cette variable.

Valeur de retour

La routine GetBusDriverD3ColdSupport retourne STATUS_SUCCESS si elle réussit. Sinon, elle retourne un code d’état d’erreur approprié.

Remarques

Le pilote de l’appareil appelle la version de cette routine implémentée par le pilote WINDOWS ACPI, Acpi.sys. Cette routine vérifie le pilote de bus parent de l’appareil pour déterminer si ce pilote de bus prend en charge l’état d’alimentation D3cold.

Par exemple, à partir de Windows 8, Microsoft fournit une boîte de réception USB 3.0 eXtensible Host Controller Interface (xHCI) qui prend en charge D3cold. Certains fournisseurs de matériel tiers fournissent des pilotes Windows pour leurs contrôleurs xHCI, mais ces pilotes peuvent ne pas prendre en charge D3cold. Le pilote d’un périphérique USB 3.0 peut appeler la routine GetBusDriverD3ColdSupport pour déterminer si le pilote de contrôleur xHCI parent prend en charge D3cold.

Un pilote de bus prend en charge D3cold si toutes les valeurs suivantes sont vraies :

Le pilote de bus implémente l’interface du pilote GUID_D3COLD_SUPPORT_INTERFACE.
Le pilote de bus implémente la routine GetBusDriverD3ColdSupport dans cette interface.
La valeur de sortie de la routine GetBusDriverD3ColdSupport indique que le pilote de bus prend en charge D3cold.

Le pilote d’un appareil peut appeler la routine GetIdleWakeInfo pour déterminer si les pilotes de bus sous-jacents et le microprogramme système ACPI prennent en charge D3cold pour l’appareil. Si cet appel échoue et retourne un code d’état d’erreur, le pilote de périphérique peut appeler la GetBusDriverD3ColdSupport routine pour déterminer si l’échec est dû à un manque de prise en charge D3cold par le pilote de bus parent.

Un appareil sur un bus peut effectuer une transition vers le sous-état D3cold uniquement si le pilote de bus prend en charge cette transition. Si le pilote de bus ne prend pas en charge D3cold, l’appareil n’entre jamais D3cold, même si le pilote de fonction pour l’appareil appelle la routine SetD3ColdSupport pour activer la transition vers D3cold. Dans ce cas, SetD3ColdSupport appels n’ont aucun effet, mais sont inoffensifs.

Pour cette raison, la plupart des pilotes de périphérique n’ont jamais besoin d’appeler la routine GetBusDriverD3ColdSupport.