GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS Rückruffunktion (gpioclx.h)

Artikel
02/07/2025

Die CLIENT_QueryEnabledInterrupts Ereignisrückruffunktion fragt den Status einer Reihe von allgemeinen I/O-Pins (GPIO) ab, um zu bestimmen, welche Pins sowohl als Interrupteingaben konfiguriert sind als auch für Unterbrechungen aktiviert sind.

Syntax

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS GpioClientQueryEnabledInterrupts;

NTSTATUS GpioClientQueryEnabledInterrupts(
  [in] PVOID Context,
  [in] PGPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS QueryEnabledParameters
)
{...}

Parameter

[in] Context

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

[in] QueryEnabledParameters

Ein Zeiger auf eine vom Aufrufer zugewiesene GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS Struktur. Vor dem Aufrufen dieser Funktion schreibt der Aufrufer eine Bank-ID in die BankId Mitglied dieser Struktur, um anzugeben, welche GPIO-Pins abfragen sollen. Bei erfolgreicher Ausführung schreibt die Funktion einen Maskenwert in die EnabledMask Member dieser Struktur, um anzugeben, welche Unterbrechungen in der angegebenen Bank aktiviert sind.

Rückgabewert

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

Bemerkungen

Ab Windows 8.1 kann der GPIO-Controllertreiber als Option eine CLIENT_QueryEnabledInterrupts Rückruffunktion implementieren. Wenn diese Funktion implementiert wird, wird diese Funktion von der GPIO-Frameworkerweiterung (GpioClx) aufgerufen, um zu bestimmen, welche Unterbrechungen in einer Bank von GPIO-Pins aktiviert sind.

Die QueryEnabledParameters Parameter verweist auf eine vom Aufrufer zugeordnete GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS Struktur. Der Aufrufer legt den Wert der BankId Mitglied dieser Struktur fest. Die CLIENT_QueryEnabledInterrupts-Funktion schreibt in das EnabledMask Element der Struktur.

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

Die CLIENT_QueryEnabledInterrupts-Funktion ist optional. Wenn Der Treiber diese Funktion nicht implementiert, legen Sie das CLIENT_QueryEnabledInterrupts Element der GPIO_CLIENT_REGISTRATION_PACKET Struktur auf NULL-fest.

Wenn die CLIENT_QueryEnabledInterrupts-Funktion implementiert ist, verwendet GpioClx diese Funktion, um die Zuverlässigkeit und Diagnose des Treibers zu verbessern. GpioClx ruft diese Funktion auf, um zu überprüfen, ob der Satz von Unterbrechungen, die auf dem GPIO-Controller aktiviert sind, dem entspricht, was GpioClx erwartet. In der Regel weist ein Konflikt auf einen Treiberfehler hin, der einen Unterbrechungssturm verursachen kann. GpioClx verwendet diese Funktion, um eine umfangreichere Zustandsüberprüfung in eingecheckten (Debug-) Builds zu erledigen, und reduziert die Anzahl der Aufrufe dieser Funktion in kostenlosen Builds (Einzelhandel), um auswirkungen auf die Leistung zu vermeiden. Wenn diese Funktion implementiert ist, muss diese Funktion den Hardwarestatus direkt lesen, anstatt eine zwischengespeicherte oder softwaregesteuerte Version des Zustands zu lesen.

GpioClx ruft die CLIENT_QueryEnabledInterrupts Rückruffunktion entweder bei PASSIVE_LEVEL oder DIRQL auf, je nachdem, welche Geräteinformationen die CLIENT_QueryControllerBasicInformation Rückruffunktion gpioClx bereitstellt. Die CLIENT_QueryControllerBasicInformation-Funktion stellt Geräteinformationen in Form einer CLIENT_CONTROLLER_BASIC_INFORMATION Struktur bereit. Wenn das MemoryMappedController- Flagbit im Flags Member dieser Struktur festgelegt ist, ruft GpioClx die CLIENT_QueryEnabledInterrupts-Funktion bei DIRQL auf, 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_QueryEnabledInterrupts 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_QueryEnabledInterrupts Rückruffunktion zu definieren, die MyEvtGpioQueryEnabledInterruptsbenannt ist, verwenden Sie den GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS Funktionstyp, wie in diesem Codebeispiel gezeigt:

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

Implementieren Sie dann die Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioQueryEnabledInterrupts(
    PVOID Context,
    PGPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS QueryEnabledParameters
    )
{ ... }

Der GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS 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_QUERY_ENABLED_INTERRUPTS 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.