GPIO_CLIENT_RESTORE_BANK_HARDWARE_CONTEXT Rückruffunktion (gpioclx.h)

Artikel
02/07/2025

Die CLIENT_RestoreBankHardwareContext Ereignisrückruffunktion stellt den Hardwarekontext einer Bank mit allgemeinen I/O-Pins (GPIO) wieder her.

Syntax

GPIO_CLIENT_RESTORE_BANK_HARDWARE_CONTEXT GpioClientRestoreBankHardwareContext;

void GpioClientRestoreBankHardwareContext(
  [in] PVOID Context,
  [in] PGPIO_SAVE_RESTORE_BANK_HARDWARE_CONTEXT_PARAMETERS Parameters
)
{...}

Parameter

[in] Context

Ein Zeiger auf den Gerätekontext des GPIO-Controllertreibers.

[in] Parameters

Ein Zeiger auf eine GPIO_SAVE_RESTORE_BANK_HARDWARE_CONTEXT_PARAMETERS Struktur, die die Bank der GPIO-Pins zum Wiederherstellen beschreibt.

Rückgabewert

Nichts

Bemerkungen

Die CLIENT_RestoreBankHardwareContext-Funktion gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls wird ein entsprechender Fehlerstatuscode zurückgegeben.

Wenn eine Bank von GPIO-Pins das Energiemanagement auf Komponentenebene unterstützt, kann GpioClx die Bank in einen Fx-Zustand mit niedriger Leistung wechseln, wenn die Bank im Leerlauf ist. Wenn die GPIO-Controllerbank ihren Hardwarekontext im Fx-Zustand verliert, muss der GPIO-Controllertreiber diesen Kontext vor dem Übergang von F0-to-Fx speichern und später den Kontext nach dem Fx-to-F0-Übergang wiederherstellen. Derzeit ist F1 der einzige Low-Power-Zustand, der für GPIO-Controller definiert ist, die GpioClx verwenden.

GpioClx ruft die CLIENT_RestoreBankHardwareContext-Funktion auf, um den zuvor gespeicherten Hardwarekontext der Bank wiederherzustellen. Der Hardwarekontext wurde zuvor von der CLIENT_SaveBankHardwareContext Ereignisrückruffunktion gespeichert.

Einige GPIO-Controllergeräte ermöglichen es ausgewählten Pins, unabhängig von anderen Banken auf demselben Gerät ein- und ausgeschaltet zu werden. So kann Energie gespart werden, indem eine Bank deaktiviert wird, die im Leerlauf ist.

Rufen Sie die GPIO_CLX_RegisterClient Methode auf, um die CLIENT_RestoreBankHardwareContext Rückruffunktion ihres Treibers zu registrieren. Diese Methode akzeptiert als Eingabeparameter einen Zeiger auf eine GPIO_CLIENT_REGISTRATION_PACKET Struktur, die einen CLIENT_RestoreBankHardwareContext Funktionszeiger enthält.

GpioClx ruft die CLIENT_RestoreBankHardwareContext Rückruffunktion entweder bei PASSIVE_LEVEL oder DIRQL auf, abhängig von den Geräteinformationen, die die CLIENT_QueryControllerBasicInformation Rückruffunktion für GpioClx bereitstellt. Die CLIENT_QueryControllerBasicInformation-Funktion stellt Geräteinformationen in Form einer CLIENT_CONTROLLER_BASIC_INFORMATION Struktur bereit. Wenn das MemoryMappedController- Flagbit im Flags Mitglied dieser Struktur festgelegt ist, ruft GpioClx die CLIENT_RestoreBankHardwareContext-Funktion bei DIRQL auf, d. h. die IRQL, bei der der ISR in GpioClx ausgeführt wird. Andernfalls wird diese Funktion bei PASSIVE_LEVEL aufgerufen. Weitere Informationen zu diesem Flagbit finden Sie unter Optional und Required GPIO Callback Functions.

Beispiele

Um eine CLIENT_RestoreBankHardwareContext Rückruffunktion zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der rückruffunktion 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.

Um beispielsweise eine CLIENT_RestoreBankHardwareContext Rückruffunktion zu definieren, die MyEvtGpioRestoreBankHardwareContextbenannt ist, verwenden Sie den funktionstyp GPIO_CLIENT_RESTORE_BANK_HARDWARE_CONTEXT, wie in diesem Codebeispiel gezeigt:

GPIO_CLIENT_RESTORE_BANK_HARDWARE_CONTEXT MyEvtGpioRestoreBankHardwareContext;</pre>

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioRestoreBankHardwareContext(
    PVOID Context,
    PGPIO_SAVE_RESTORE_BANK_HARDWARE_CONTEXT_PARAMETERS Parameters
    )
{ ... }

Der GPIO_CLIENT_RESTORE_BANK_HARDWARE_CONTEXT Funktionstyp wird in der Headerdatei "Gpioclx.h" 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 GPIO_CLIENT_RESTORE_BANK_HARDWARE_CONTEXT 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 KMDF-Treiber. Weitere Informationen zu Use_decl_annotationsfinden Sie unter Annotating Function Behavior.