GPIO_CLIENT_MASK_INTERRUPTS Rückruffunktion (gpioclx.h)

Artikel
03/01/2024

Die CLIENT_MaskInterrupts Ereignisrückruffunktion maskiert Interrupts für eine Reihe von GPIO-Pins (Universelle E/A), die als Interrupteingaben konfiguriert sind.

Syntax

GPIO_CLIENT_MASK_INTERRUPTS GpioClientMaskInterrupts;

NTSTATUS GpioClientMaskInterrupts(
  [in]      PVOID Context,
  [in, out] PGPIO_MASK_INTERRUPT_PARAMETERS MaskParameters
)
{...}

Parameter

[in] Context

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

[in, out] MaskParameters

Ein Zeiger auf eine GPIO_MASK_INTERRUPT_PARAMETERS-Struktur, die bei der Eingabe die GPIO-Interruptpins zur Maskierung beschreibt und beim Beenden die status des Maskenvorgangs enthält.

Rückgabewert

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

Hinweise

Diese Rückruffunktion wird vom GPIO-Controllertreiber implementiert. Die GPIO-Frameworkerweiterung (GpioClx) ruft diese Funktion auf, um Interrupts auf GPIO-Pins zu maskieren, die als Interruptanforderungseingaben konfiguriert sind. Weitere Informationen finden Sie unter GPIO-Interruptmasken.

Um die CLIENT_MaskInterrupts 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_MaskInterrupts-Funktionszeiger enthält.

Die funktion CLIENT_MaskInterrupts wird von der Interruptdienstroutine (ISR) in GpioClx aufgerufen. Diese ISR wird entweder mit PASSIVE_LEVEL oder DIRQL ausgeführt, 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 Flagbit "MemoryMappedController " im Flags-Element dieser Struktur festgelegt ist, wird die GpioClx ISR bei DIRQL ausgeführt und die CLIENT_MaskInterrupts-Funktion bei DIRQL aufgerufen. Andernfalls wird die ISR bei PASSIVE_LEVEL ausgeführt und ruft die Funktion bei PASSIVE_LEVEL auf. Weitere Informationen zu diesem Flag-Bit finden Sie unter Optionale und erforderliche GPIO-Rückruffunktionen.

Ein CLIENT_MaskInterrupts Aufruf, bei dem die Interruptmaske nicht auf den angeforderten Wert festgelegt wird, muss das FailedMask-Element der GPIO_MASK_INTERRUPT_PARAMETERS-Struktur auf einen Wert ungleich null festlegen und einen entsprechenden Fehler status Code zurückgeben. Es wird erwartet, dass die CLIENT_MaskInterrupts-Funktion für einen speicherseitig zugeordneten GPIO-Controller immer erfolgreich die Interruptmaske auf den angeforderten Wert festlegt. Die CLIENT_MaskInterrupts-Funktion für einen Controller, der nicht im Arbeitsspeicher zugeordnet ist, muss jedoch eine E/A-Anforderung an den Controller senden, um die Maske festzulegen, und diese Anforderung kann fehlschlagen. Wenn die Anforderung die Maske nicht festlegen kann, muss die Funktion diesen Fehler in dem Wert angeben, den sie in das FailedMask-Element schreibt.

Beispiele

Um eine CLIENT_MaskInterrupts Rückruffunktion zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. 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 Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine CLIENT_MaskInterrupts Rückruffunktion mit dem Namen MyEvtGpioMaskInterruptszu definieren, verwenden Sie den Funktionstyp GPIO_CLIENT_MASK_INTERRUPTS, wie in diesem Codebeispiel gezeigt:

GPIO_CLIENT_MASK_INTERRUPTS MyEvtGpioMaskInterrupts;

Implementieren Sie dann Ihre Rückruffunktion wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioMaskInterrupts(
    PVOID Context,
    PGPIO_MASK_INTERRUPT_PARAMETERS MaskParameters
    )
{ ... }

Der GPIO_CLIENT_MASK_INTERRUPTS Funktionstyp ist in der Gpioclx.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, müssen Sie der Funktionsdefinition die anmerkung Use_decl_annotations hinzufügen. Die Use_decl_annotations-Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den funktionstyp GPIO_CLIENT_MASK_INTERRUPTS 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 Annotating Function Behavior.