GPIO_CLIENT_MASK_INTERRUPTS Rückruffunktion (gpioclx.h)

Artikel
02/07/2025

Die CLIENT_MaskInterrupts Ereignisrückruffunktionsmasken unterbrechen eine Reihe von allgemeinen I/O-Pins (GPIO), 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 beim Einstieg die GPIO-Interrupt-Pins zum Maskieren beschreibt und beim Beenden den Status des Maskenvorgangs enthält.

Rückgabewert

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

Bemerkungen

Diese Rückruffunktion wird vom GPIO-Controllertreiber implementiert. Die GPIO-Framework-Erweiterung (GpioClx) ruft diese Funktion auf, um Unterbrechungen für GPIO-Pins zu maskieren, die als Interruptanforderungseingaben konfiguriert sind. Weitere Informationen finden Sie unter GPIO Interrupt Masken.

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

Die CLIENT_MaskInterrupts-Funktion wird aus der Unterbrechungsdienstroutine (Interrupt Service Routine, ISR) in GpioClx aufgerufen. Dieser ISR wird entweder bei PASSIVE_LEVEL oder DIRQL ausgeführt, 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, wird der GPioClx ISR bei DIRQL ausgeführt und ruft die CLIENT_MaskInterrupts-Funktion bei DIRQL auf. Andernfalls wird der ISR bei PASSIVE_LEVEL ausgeführt und ruft die Funktion bei PASSIVE_LEVEL auf. Weitere Informationen zu diesem Flagbit finden Sie unter Optional und Required GPIO Callback Functions.

Ein CLIENT_MaskInterrupts Aufruf, der die Unterbrechungsmaske nicht auf den angeforderten Wert festlegen kann, muss das FailedMask Member der GPIO_MASK_INTERRUPT_PARAMETERS-Struktur auf einen Wert ungleich Null festlegen und einen entsprechenden Fehlerstatuscode zurückgeben. Die CLIENT_MaskInterrupts-Funktion für einen speicherzuordnungen GPIO-Controller wird erwartet, dass es immer erfolgreich ist, die Unterbrechungsmaske auf den angeforderten Wert festzulegen. 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 schlägt möglicherweise fehl. Wenn die Anforderung das Maskenformat nicht festlegen kann, muss die Funktion diesen Fehler im Wert angeben, den sie in das FailedMask Member schreibt.

Beispiele

Um eine CLIENT_MaskInterrupts 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_MaskInterrupts Rückruffunktion zu definieren, die MyEvtGpioMaskInterruptsbenannt ist, verwenden Sie den funktionstyp GPIO_CLIENT_MASK_INTERRUPTS, wie in diesem Codebeispiel gezeigt:

GPIO_CLIENT_MASK_INTERRUPTS MyEvtGpioMaskInterrupts;

Implementieren Sie dann die Rückruffunktion wie folgt:

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

Der GPIO_CLIENT_MASK_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_MASK_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.