PO_FX_COMPONENT_IDLE_STATE_CALLBACK Rückruffunktion (wdm.h)

Artikel
02/07/2025

Die ComponentIdleStateCallback- Rückrufroutine benachrichtigt den Treiber einer ausstehenden Änderung an den Fx-Leistungsstatus 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, mit der der Treiber das Gerät mit dem Power Management Framework (PoFx) registriert hat. Dieser Kontext ist undurchsichtig für PoFx.

[in] Component

Gibt die Komponentennummer an. Dieser Parameter ist ein Index im Components Array in der PO_FX_DEVICE Struktur, mit der der Gerätetreiber das Gerät bei PoFx registriert hat. Wenn das Components Array N-Elemente enthält, reichen Komponentenindizes von 0 bis N-1.

[in] State

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

Rückgabewert

Nichts

Bemerkungen

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

Wenn die Komponente von F0 in einen Fx-Zustand mit niedriger Leistung wechselt, 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 eintritt. 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 der Strom in der Komponente wiederhergestellt wurde.

Bei einigen Geräten kann der Energiezustand einer Komponente in der Gerätehardware gesteuert werden. Für diese Geräte ist der Treiber in der Regel für das Ändern 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 auf PoFx angewiesen sein, 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 in F0 beim Eintrag in die ComponentIdleStateCallback Routine, und der Treiber muss die Komponente in den neuen Fx-Zustand wechseln, bevor PoFxCompleteIdleStateaufgerufen wird. Bei einem Übergang von einem Fx-Zustand mit geringem Strom zu F0 befindet sich die Komponente beim Einstieg in die ComponentIdleStateCallback Routine im Niedrigstrom-Fx-Zustand, und der Treiber muss die Komponente auf F0 umstellen, bevor PoFxCompleteIdleStateaufgerufen wird.

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

PoFx ruft niemals die ComponentIdleStateCallback- Routine auf, um direkt von einem Fx-Zustand mit niedrigem Strom zu einem anderen Fx-Zustand mit niedriger Leistung zu wechseln. Beispielsweise muss PoFx als Reaktion auf einen Aufruf der PoFxSetComponentLatency, PoFxSetComponentResidencyoder PoFxSetComponentWake Eine Komponente von einem Low-Power Fx-Zustand zu einem anderen wechseln. In diesem Fall ruft PoFx zuerst die ComponentIdleStateCallback Routine auf, um vom alten Fx-Zustand zu F0 zu wechseln, und ruft dann die ComponentIdleStateCallback- Routine ein zweites Mal auf, um von F0 zum neuen Fx-Zustand zu wechseln.

Beispiele

Um eine ComponentIdleStateCallback Callbackroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückrufroutinen identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Wenn Sie beispielsweise eine ComponentIdleStateCallback- Rückrufroutine definieren möchten, die MyComponentIdleStateCallbackheißt, verwenden Sie den PO_FX_COMPONENT_IDLE_STATE_CALLBACK Typ, 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 wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die _Use_decl_annotations_ Anmerkung hinzufügen. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp PO_FX_COMPONENT_IDLE_STATE_CALLBACK in der Headerdatei angewendet werden, verwendet 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
mindestens unterstützte Client-	Unterstützt in Windows 8 und höheren Versionen von Windows.
Zielplattform-	Desktop
Header-	wdm.h (include Wudfwdm.h)
IRQL-	Wird bei IRQL <= DISPATCH_LEVEL aufgerufen.