GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS função de retorno de chamada (gpioclx.h)

Artigo
02/07/2025

A função de retorno de chamada de evento CLIENT_QueryEnabledInterrupts consulta o estado de um conjunto de pinos de E/S de uso geral (GPIO) para determinar quais pinos estão configurados como entradas de interrupção e habilitados para interrupções.

Sintaxe

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS GpioClientQueryEnabledInterrupts;

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

Parâmetros

[in] Context

Um ponteiro para o contexto do dispositivo do driver gpio.

[in] QueryEnabledParameters

Um ponteiro para uma estrutura de GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS alocada pelo chamador. Antes de chamar essa função, o chamador grava uma ID bancária no BankId membro dessa estrutura para especificar qual banco de pinos gpio consultar. Se bem-sucedida, a função gravará um valor de máscara no enabledMask membro dessa estrutura para indicar quais interrupções estão habilitadas no banco especificado.

Valor de retorno

A função CLIENT_QueryEnabledInterrupts retornará STATUS_SUCCESS se a chamada for bem-sucedida. Caso contrário, ele retornará um código de erro apropriado.

Observações

A partir do Windows 8.1, o driver do controlador GPIO pode, como opção, implementar uma função de retorno de chamada CLIENT_QueryEnabledInterrupts. Se implementada, essa função será chamada pela extensão da estrutura GPIO (GpioClx) para determinar quais interrupções são habilitadas em um banco de pinos GPIO.

O parâmetro QueryEnabledParameters aponta para uma estrutura de GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS alocada pelo chamador. O chamador define o valor do BankId membro dessa estrutura. A função CLIENT_QueryEnabledInterrupts grava no membro EnabledMask da estrutura.

Para registrar a função de retorno de chamada CLIENT_QueryEnabledInterrupts do driver, chame o método GPIO_CLX_RegisterClient. Esse método aceita, como um parâmetro de entrada, um ponteiro para uma estrutura GPIO_CLIENT_REGISTRATION_PACKET que contém um ponteiro de função CLIENT_QueryEnabledInterrupts.

A função CLIENT_QueryEnabledInterrupts é opcional. Se o driver não implementar essa função, defina o membro CLIENT_QueryEnabledInterrupts da estrutura GPIO_CLIENT_REGISTRATION_PACKET para NULL.

Se a função CLIENT_QueryEnabledInterrupts for implementada, o GpioClx usará essa função para melhorar a confiabilidade e o diagnóstico do driver. GpioClx chama essa função para verificar se o conjunto de interrupções habilitados no controlador GPIO corresponde ao que o GpioClx espera. Normalmente, uma incompatibilidade indica um bug de driver que pode causar uma tempestade de interrupção. O GpioClx usa essa função para fazer uma validação de estado mais abrangente em builds verificados (depuração) e reduz o número de chamadas para essa função em builds gratuitos (varejo) para evitar afetar o desempenho. Se implementada, essa função deve ler diretamente o estado do hardware em vez de ler uma versão em cache ou mantida por software do estado.

GpioClx chama a função de retorno de chamada CLIENT_QueryEnabledInterrupts em PASSIVE_LEVEL ou DIRQL, dependendo das informações do dispositivo que a função de retorno de chamada CLIENT_QueryControllerBasicInformation fornece ao GpioClx. A função CLIENT_QueryControllerBasicInformation fornece informações do dispositivo na forma de uma estrutura CLIENT_CONTROLLER_BASIC_INFORMATION. Se o MemoryMappedController bit de sinalizador for definido no Flags membro dessa estrutura, GpioClx chamará a função CLIENT_QueryEnabledInterrupts no DIRQL, que é o IRQL no qual o ISR no GpioClx é executado. Caso contrário, essa função será chamada em PASSIVE_LEVEL. Para obter mais informações sobre esse bit de sinalizador, consulte funções de retorno de chamada de GPIO opcionais e necessárias.

Exemplos

Para definir uma função de retorno de chamada CLIENT_QueryEnabledInterrupts, primeiro você deve fornecer uma declaração de função que identifique o tipo de função de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a análise de código para drivers, SDV (Verificador de Driver Estático) e outras ferramentas de verificação encontram erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma função de retorno de chamada CLIENT_QueryEnabledInterrupts chamada MyEvtGpioQueryEnabledInterrupts, use o tipo de função GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS, conforme mostrado neste exemplo de código:

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

Em seguida, implemente sua função de retorno de chamada da seguinte maneira:

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

O tipo de função GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS é definido no arquivo de cabeçalho Gpioclx.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a anotação Use_decl_annotations à sua definição de função. A anotação Use_decl_annotations garante que as anotações aplicadas ao tipo de função GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers KMDF. Para obter mais informações sobre Use_decl_annotations, consulte Anotando o comportamento da função.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Com suporte a partir do Windows 8.1.
da Plataforma de Destino	Área de trabalho
cabeçalho	gpioclx.h
IRQL	Consulte Comentários.