PO_FX_COMPONENT_IDLE_STATE_CALLBACK Rückruffunktion (wdm.h)

Artikel
03/08/2023

Die ComponentIdleStateCallback-Rückrufroutine benachrichtigt den Treiber über eine ausstehende Änderung des Fx-Energiezustands der angegebenen Komponente.

Syntax

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

Parameter

[in] Context

Ein Zeiger auf den Gerätekontext. Der Gerätetreiber verwendet diesen Kontext, um Informationen zum aktuellen Energiezustand des Geräts zu speichern. Der Gerätetreiber hat diesen Zeiger im DeviceContext-Member der PO_FX_DEVICE-Struktur angegeben, die der Treiber zum Registrieren des Geräts beim Power Management Framework (PoFx) verwendet hat. Dieser Kontext ist für PoFx undurchsichtig.

[in] Component

Gibt die Komponentennummer an. Dieser Parameter ist ein Index in das Array Components in der PO_FX_DEVICE Struktur, die der Gerätetreiber zum Registrieren des Geräts bei PoFx verwendet hat. Wenn das Komponentenarray N-Elemente enthält, reichen die Komponentenindizes von 0 bis N-1.

[in] State

Gibt den neuen Fx-Energiezustand an, in den die Komponente geändert wird. Wenn dieser Parameter 0 ist, lautet der neue Zustand F0; wenn dieser Parameter eins ist, lautet der neue Zustand F1; Und so weiter.

Rückgabewert

Keine

Bemerkungen

Wenn PoFx die ComponentIdleStateCallback-Routine des Treibers aufruft, muss sich der Treiber möglicherweise auf die ausstehende Änderung des Fx-Zustands vorbereiten. Nachdem alle erforderlichen Vorbereitungen abgeschlossen sind, muss der Treiber die PoFxCompleteIdleState-Routine aufrufen, um PoFx darüber zu informieren, dass der Treiber seine Antwort auf den ComponentIdleStateCallback-Rückruf abgeschlossen hat. Der PoFxCompleteIdleState-Aufruf kann entweder vor oder nach dem Zurückgeben der ComponentIdleStateCallback-Routine erfolgen.

Wenn die Komponente von F0 zu einem Fx-Zustand mit niedriger Leistung wechseln soll, in dem das Gerät den Hardwarezustand der Komponente verliert, muss der Treiber den Hardwarezustand der Komponente speichern, bevor der Übergang zum neuen Fx-Zustand erfolgt. Wenn die Komponente von einem Fx-Zustand mit niedriger Leistung zu F0 wechseln soll und der Hardwarezustand zuvor gespeichert wurde, sollte der Treiber den Hardwarezustand wiederherstellen, nachdem die Stromversorgung der Komponente wiederhergestellt wurde.

Bei einigen Geräten kann der Energiezustand einer Komponente in der Gerätehardware gesteuert werden. Bei diesen Geräten ist der Treiber in der Regel für die Änderung des Energiezustands der Komponente verantwortlich. Bei anderen Geräten kann der Energiezustand einer Komponente durch Hardware gesteuert werden, die sich außerhalb des Geräts befindet, und der Treiber muss in der Regel poFx verwenden, um den Energiezustand der Komponente zu konfigurieren.

Wenn der Treiber für die Konfiguration des Energiezustands der Komponente verantwortlich ist, sollte der Treiber den Energiezustand als Reaktion auf den ComponentIdleStateCallback-Rückruf ändern. Für einen Übergang von F0 zu einem Fx-Zustand mit niedriger Leistung befindet sich die Komponente beim Einstieg in die ComponentIdleStateCallback-Routine in F0, und der Treiber muss die Komponente in den neuen Fx-Zustand wechseln, bevor PoFxCompleteIdleState aufgerufen wird. Für einen Übergang von einem Fx-Zustand mit niedriger Leistung zu F0 befindet sich die Komponente beim Eintritt in die ComponentIdleStateCallback-Routine im Fx-Zustand mit niedriger Leistung, und der Treiber muss die Komponente auf F0 umschalten, bevor PoFxCompleteIdleState aufgerufen wird.

Wenn der Treiber nicht für die Konfiguration des Energiezustands der Komponente verantwortlich ist, sollte der Treiber davon ausgehen, dass sich die Komponente beim Eintritt in die ComponentIdleStateCallback-Routine immer im F0-Zustand befindet. Bei einem ausstehenden Übergang von F0 zu einem Fx-Zustand mit niedriger Leistung erfolgt der Übergang zum neuen Fx-Zustand erst, nachdem der Treiber PoFxCompleteIdleState aufgerufen hat. Bei einem Übergang von einem Fx-Zustand mit niedriger Leistung zu F0 erfolgt der Übergang zu F0, bevor die ComponentIdleStateCallback-Routine aufgerufen wird.

PoFx ruft nie die ComponentIdleStateCallback-Routine auf, um direkt von einem Fx-Zustand mit niedriger Leistung in einen anderen Fx-Zustand mit niedriger Leistung zu wechseln. Beispielsweise muss PoFx eine Komponente als Reaktion auf einen Aufruf der PoFxSetComponentLatency-, PoFxSetComponentResidency- oder PoFxSetComponentWake-Routine von einem Fx-Zustand mit niedriger Leistung in einen anderen wechseln. In diesem Fall ruft PoFx zuerst die ComponentIdleStateCallback-Routine auf, um vom alten Fx-Zustand zu F0 zu wechseln, und ruft dann ein zweites Mal die ComponentIdleStateCallback-Routine auf, um von F0 in den neuen Fx-Zustand zu wechseln.

Beispiele

Um eine ComponentIdleStateCallback-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückrufroutine identifiziert. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine ComponentIdleStateCallback-Rückrufroutine mit dem Namen MyComponentIdleStateCallbackzu definieren, verwenden Sie den typ PO_FX_COMPONENT_IDLE_STATE_CALLBACK, wie in diesem Codebeispiel gezeigt:

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

Der PO_FX_COMPONENT_IDLE_STATE_CALLBACK Funktionstyp ist in der Headerdatei Wdm.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den PO_FX_COMPONENT_IDLE_STATE_CALLBACK Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Annotating Function Behavior.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Wird in Windows 8 und höheren Versionen von Windows unterstützt.
Zielplattform	Desktop
Kopfzeile	wdm.h (include Wudfwdm.h)
IRQL	Wird unter IRQL <= DISPATCH_LEVEL aufgerufen.