GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS Rückruffunktion (gpioclx.h)

Artikel
08/07/2023

Die CLIENT_QueryEnabledInterrupts Ereignisrückruffunktion fragt den Zustand einer Reihe von GPIO-Pins (General Purpose E/O) ab, um zu bestimmen, welche Pins sowohl als Interrupteingaben konfiguriert und für Interrupts 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 aufruferseitig zugeordnete GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS-Struktur . Vor dem Aufrufen dieser Funktion schreibt der Aufrufer eine Bank-ID in das BankId-Mitglied dieser Struktur, um anzugeben, welche Bank von GPIO-Pins abfragt werden soll. Bei erfolgreicher Ausführung schreibt die Funktion einen Maskenwert in den EnabledMask-Member dieser Struktur, um anzugeben, welche Interrupts 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.

Hinweise

Ab Windows 8.1 kann der GPIO-Controllertreiber optional eine CLIENT_QueryEnabledInterrupts Rückruffunktion implementieren. Bei Implementierung wird diese Funktion von der GPIO-Frameworkerweiterung (GpioClx) aufgerufen, um zu bestimmen, welche Interrupts in einer Bank mit GPIO-Pins aktiviert sind.

Der QueryEnabledParameters-Parameter verweist auf eine aufruferseitig zugewiesene GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS-Struktur . Der Aufrufer legt den Wert des BankId-Members dieser Struktur fest. Die CLIENT_QueryEnabledInterrupts-Funktion schreibt in das EnabledMask-Element der -Struktur.

Um die CLIENT_QueryEnabledInterrupts Rückruffunktion Ihres Treibers zu registrieren, rufen Sie die GPIO_CLX_RegisterClient-Methode auf. 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 Ihr Treiber diese Funktion nicht implementiert, legen Sie den CLIENT_QueryEnabledInterrupts Member der GPIO_CLIENT_REGISTRATION_PACKET-Struktur auf NULL fest.

Wenn die CLIENT_QueryEnabledInterrupts-Funktion implementiert ist, verwendet GpioClx diese Funktion, um die Zuverlässigkeit des Treibers und die Diagnose zu verbessern. GpioClx ruft diese Funktion auf, um zu überprüfen, ob der Satz von Interrupts, die auf dem GPIO-Controller aktiviert sind, mit den Erwartungen von GpioClx übereinstimmt. In der Regel weist eine Nichtübereinstimmung auf einen Treiberfehler hin, der möglicherweise einen Unterbrechungssturm verursachen kann. GpioClx verwendet diese Funktion, um eine umfangreichere Zustandsüberprüfung in überprüften Builds (Debug) durchzuführen, und reduziert die Anzahl der Aufrufe dieser Funktion in kostenlosen (Einzelhandels-)Builds, um Auswirkungen auf die Leistung zu vermeiden. Wenn diese Funktion implementiert ist, muss diese Funktion direkt den Hardwarezustand lesen, anstatt eine zwischengespeicherte oder von Software verwaltete Version des Zustands zu lesen.

GpioClx ruft die CLIENT_QueryEnabledInterrupts Rückruffunktion entweder bei PASSIVE_LEVEL oder DIRQL auf, abhängig von den Geräteinformationen, die die CLIENT_QueryControllerBasicInformation Rückruffunktion an 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, d. h. die IRQL, unter der der ISR in GpioClx ausgeführt wird. Andernfalls wird diese Funktion bei PASSIVE_LEVEL aufgerufen. Weitere Informationen zu diesem Flagbit finden Sie unter Optionale und erforderliche GPIO-Rückruffunktionen.

Beispiele

Um eine CLIENT_QueryEnabledInterrupts Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der von Ihnen definierten Rückruffunktion angibt. 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 CLIENT_QueryEnabledInterrupts Rückruffunktion namens MyEvtGpioQueryEnabledInterruptszu definieren, verwenden Sie den GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS-Funktionstyp, wie in diesem Codebeispiel gezeigt:

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

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

Der GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS Funktionstyp ist in der Headerdatei Gpioclx.h definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzu. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS 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 KMDF-Treiber. Weitere Informationen zu Use_decl_annotations finden Sie unter Verhalten von Funktionen mit Anmerkungen.