GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS funzione di callback (gpioclx.h)

Articolo
02/26/2024

La funzione di callback degli eventi CLIENT_QueryEnabledInterrupts esegue una query sullo stato di un set di pin di I/O (GPIO) per determinare quali pin sono configurati come input di interruzione e abilitati per gli interruzioni.

Sintassi

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS GpioClientQueryEnabledInterrupts;

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

Parametri

[in] Context

Puntatore al contesto del dispositivo del controller GPIO.

[in] QueryEnabledParameters

Puntatore a una struttura GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS allocata dal chiamante. Prima di chiamare questa funzione, il chiamante scrive un ID bancario nel membro BankId di questa struttura per specificare quale banca di pin GPIO aggiungere alla query. Se ha esito positivo, la funzione scrive un valore mask nel membro EnabledMask di questa struttura per indicare quali interruzioni sono abilitate nella banca specificata.

Valore restituito

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

Commenti

A partire da Windows 8.1, il driver del controller GPIO può, come opzione, implementare una funzione di callback CLIENT_QueryEnabledInterrupts. Se implementata, questa funzione viene chiamata dall'estensione del framework GPIO (GpioClx) per determinare quali interruzioni sono abilitate in una banca di pin GPIO.

Il parametro QueryEnabledParameters punta a una struttura GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS allocata dal chiamante. Il chiamante imposta il valore del membro BankId di questa struttura. La funzione CLIENT_QueryEnabledInterrupts scrive nel membro EnabledMask della struttura.

Per registrare la funzione di callback CLIENT_QueryEnabledInterrupts 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_QueryEnabledInterrupts .

La funzione CLIENT_QueryEnabledInterrupts è facoltativa. Se il driver non implementa questa funzione, impostare il membro CLIENT_QueryEnabledInterrupts della strutturaGPIO_CLIENT_REGISTRATION_PACKET su NULL.

Se la funzione CLIENT_QueryEnabledInterrupts viene implementata, GpioClx usa questa funzione per migliorare l'affidabilità e la diagnostica del driver. GpioClx chiama questa funzione per verificare che il set di interruzioni abilitato nel controller GPIO corrisponda a quello previsto da GpioClx. In genere, una mancata corrispondenza indica un bug del driver che può potenzialmente causare una tempesta di interruzioni. GpioClx usa questa funzione per eseguire una convalida dello stato più estesa nelle build controllate (debug) e riduce il numero di chiamate a questa funzione nelle build gratuite (retail) per evitare un impatto sulle prestazioni. Se implementata, questa funzione deve leggere direttamente lo stato hardware anziché leggere una versione memorizzata nella cache o gestita dal software dello stato.

GpioClx chiama la funzione di callbackCLIENT_QueryEnabledInterrupts 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 flag MemoryMappedController è impostato nel membro Flags di questa struttura, GpioClx chiama la funzione CLIENT_QueryEnabledInterrupts in DIRQL, ovvero IRQL in corrispondenza del quale viene eseguito l'ISR in GpioClx. In caso contrario, questa funzione viene chiamata in PASSIVE_LEVEL. Per altre informazioni su questo bit di flag, vedere Funzioni di callback facoltativo e obbligatorio per GPIO.

Esempio

Per definire una funzione di callback CLIENT_QueryEnabledInterrupts , è 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_QueryEnabledInterrupts denominata MyEvtGpioQueryEnabledInterrupts, usare il tipo di funzione GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS, come illustrato in questo esempio di codice:

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

Implementare quindi la funzione di callback come indicato di seguito:

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

Il tipo di funzione GPIO_CLIENT_QUERY_ENABLED_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_QUERY_ENABLED_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.1.
Piattaforma di destinazione	Desktop
Intestazione	gpioclx.h
IRQL	Vedere la sezione Osservazioni.