GPIO_CLIENT_MASK_INTERRUPTS funzione di callback (gpioclx.h)

Articolo
02/29/2024

La funzione di callback degli eventi CLIENT_MaskInterrupts interrompe gli interruzioni in un set di pin di I/O (GPIO) di utilizzo generico configurati come input di interruzione.

Sintassi

GPIO_CLIENT_MASK_INTERRUPTS GpioClientMaskInterrupts;

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

Parametri

[in] Context

Puntatore al contesto del dispositivo del controller GPIO.

[in, out] MaskParameters

Puntatore a una struttura GPIO_MASK_INTERRUPT_PARAMETERS che, nella voce, descrive i pin di interruzione GPIO per mascherare e, all'uscita, contiene lo stato dell'operazione maschera.

Valore restituito

La funzione CLIENT_MaskInterrupts restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, restituisce un codice di errore appropriato.

Commenti

Questa funzione di callback viene implementata dal driver del controller GPIO. L'estensione del framework GPIO (GpioClx) chiama questa funzione per mascherare gli interruzioni nei pin GPIO configurati come input della richiesta di interruzione. Per altre informazioni, vedere Maschera di interruzione GPIO.

Per registrare la funzione di callback CLIENT_MaskInterrupts del driver, chiamare il metodo GPIO_CLX_RegisterClient . Questo metodo accetta, come parametro di input, un puntatore a una struttura GPIO_CLIENT_REGISTRATION_PACKET che contiene un puntatore alla funzione CLIENT_MaskInterrupts .

La funzione CLIENT_MaskInterrupts viene chiamata dalla routine del servizio di interruzione (ISR) in GpioClx. Questo ISR viene eseguito in PASSIVE_LEVEL o DIRQL, a seconda delle informazioni sul dispositivo fornite dalla funzione di callback CLIENT_QueryControllerBasicInformation a GpioClx. La funzione CLIENT_QueryControllerBasicInformation fornisce informazioni sul dispositivo sotto forma di una struttura CLIENT_CONTROLLER_BASIC_INFORMATION . Se il bit del flag MemoryMappedController è impostato nel membro Flags di questa struttura, GpioClx ISR viene eseguito in DIRQL e chiama la funzione di CLIENT_MaskInterrupts in DIRQL. In caso contrario, l'ISR viene eseguito in PASSIVE_LEVEL e chiama la funzione in PASSIVE_LEVEL. Per altre informazioni su questo bit di flag, vedere Funzioni di callback facoltativo e obbligatorio per GPIO.

Una chiamata CLIENT_MaskInterrupts che non riesce a impostare la maschera di interruzione sul valore richiesto deve impostare il membro FailedMaskdella strutturaGPIO_MASK_INTERRUPT_PARAMETERS su un valore diverso da zero e restituire un codice di stato di errore appropriato. La funzione CLIENT_MaskInterrupts per un controller GPIO mappato alla memoria dovrebbe avere sempre esito positivo nell'impostazione della maschera di interruzione sul valore richiesto. Tuttavia, la funzione CLIENT_MaskInterrupts per un controller che non è mappata alla memoria deve inviare una richiesta di I/O al controller per impostare la maschera e questa richiesta potrebbe non riuscire. Se la richiesta non riesce a impostare la maschera, la funzione deve indicare questo errore nel valore che scrive nel membro FailedMask .

Esempio

Per definire una funzione di callback CLIENT_MaskInterrupts , è prima necessario specificare una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione usando i tipi di funzione callback consente l'analisi del codice per i driver, il verifica driver statico (SDV) e altri strumenti di verifica trovano errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una funzione di callback CLIENT_MaskInterrupts denominata MyEvtGpioMaskInterrupts, usare il tipo di funzione GPIO_CLIENT_MASK_INTERRUPTS, come illustrato in questo esempio di codice:

GPIO_CLIENT_MASK_INTERRUPTS MyEvtGpioMaskInterrupts;

Implementare quindi la funzione di callback come indicato di seguito:

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

Il tipo di funzione GPIO_CLIENT_MASK_INTERRUPTS è definito nel file di intestazione Gpioclx.h. Per identificare in modo più accurato gli errori durante l'esecuzione degli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano usate le annotazioni applicate al tipo di funzione GPIO_CLIENT_MASK_INTERRUPTS nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo per i driver KMDF. Per altre informazioni su Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Supportato a partire da Windows 8.
Piattaforma di destinazione	Desktop
Intestazione	gpioclx.h
IRQL	Vedere la sezione Osservazioni.