GET_D3COLD_CAPABILITY Rückruffunktion (wdm.h)

Artikel
02/07/2025

Mit der GetBusDriverD3ColdSupport Routine kann der Treiber für ein Gerät abfragen, ob der aufzählende Bustreiber den D3cold-Gerätestromzustand unterstützt.

Syntax

GET_D3COLD_CAPABILITY GetD3coldCapability;

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

Parameter

[in, optional] Context

Ein Zeiger auf schnittstellenspezifische Kontextinformationen. Der Aufrufer legt diesen Parameter auf den Wert des Context Member der D3COLD_SUPPORT_INTERFACE Struktur für die Schnittstelle fest.

[out] D3ColdSupported

Ein Zeiger auf eine BOOLEAN-Variable, in die die Routine einen Wert schreibt, um anzugeben, ob der Bustreiber den D3cold unterstützt. Wenn dieser Wert TRUEist, unterstützt der Bustreiber D3cold. Wenn FALSE, unterstützt der Bustreiber D3cold nicht. Wenn der Aufruf fehlschlägt, gibt die Routine einen Fehlerstatuscode zurück und schreibt nichts in diese Variable.

Rückgabewert

Die GetBusDriverD3ColdSupport- Routine gibt STATUS_SUCCESS zurück, wenn sie erfolgreich ist. Andernfalls wird ein entsprechender Fehlerstatuscode zurückgegeben.

Bemerkungen

Der Treiber für das Gerät ruft die Version dieser Routine auf, die vom Windows ACPI-Treiber, Acpi.sysimplementiert wird. Diese Routine überprüft den übergeordneten Bustreiber für das Gerät, um festzustellen, ob dieser Bustreiber den D3cold-Stromzustand unterstützt.

Ab Windows 8 stellt Microsoft beispielsweise einen USB 3.0 eXtensible Host Controller Interface (xHCI)-Treiber für den Posteingang zur Auswahl, der D3cold unterstützt. Einige Hardwareanbieter von Drittanbietern liefern Windows-Treiber für ihre xHCI-Controller, aber diese Treiber unterstützen möglicherweise nicht D3cold. Der Treiber für ein USB 3.0-Gerät kann die GetBusDriverD3ColdSupport- Routine aufrufen, um zu ermitteln, ob der übergeordnete xHCI-Controllertreiber D3cold unterstützt.

Ein Bustreiber unterstützt D3cold, wenn alle folgenden Bedingungen erfüllt sind:

Der Bustreiber implementiert die GUID_D3COLD_SUPPORT_INTERFACE Treiberschnittstelle.
Der Bustreiber implementiert die GetBusDriverD3ColdSupport Routine in dieser Schnittstelle.
Der Ausgabewert der GetBusDriverD3ColdSupport Routine gibt an, dass der Bustreiber D3cold unterstützt.

Der Treiber für ein Gerät kann die GetIdleWakeInfo Routine aufrufen, um zu ermitteln, ob die zugrunde liegenden Bustreiber und die ACPI-Systemfirmware D3cold für das Gerät unterstützen. Wenn dieser Aufruf fehlschlägt und einen Fehlerstatuscode zurückgibt, kann der Gerätetreiber die GetBusDriverD3ColdSupport Routine aufrufen, um festzustellen, ob der Fehler durch fehlende D3cold-Unterstützung durch den übergeordneten Bustreiber verursacht wird.

Ein Gerät auf einem Bus kann nur dann zum D3cold-Unterstatus wechseln, wenn der Bustreiber diesen Übergang unterstützt. Wenn der Bustreiber D3cold nicht unterstützt, wechselt das Gerät nie in D3cold, auch wenn der Funktionstreiber für das Gerät die SetD3ColdSupport Routine aufruft, um den Übergang zu D3cold zu ermöglichen. In diesem Fall haben SetD3ColdSupport- Aufrufe keine Auswirkung, sind aber harmlos.

Aus diesem Grund müssen die meisten Gerätetreiber nie die GetBusDriverD3ColdSupport Routine aufrufen.