GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION função de retorno de chamada (gpioclx.h)
A função de retorno de chamada de evento CLIENT_ControllerSpecificFunction executa uma operação específica a um controlador de E/S de uso geral específico (GPIO).
Sintaxe
GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION GpioClientControllerSpecificFunction;
NTSTATUS GpioClientControllerSpecificFunction(
[in] PVOID Context,
[in, out] PGPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS Parameters
)
{...}
Parâmetros
[in] Context
Um ponteiro para o contexto do dispositivo do driver gpio.
[in, out] Parameters
Um ponteiro para uma estrutura de GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS que contém os buffers de entrada e saída para a operação específica do controlador.
Valor de retorno
A função CLIENT_ControllerSpecificFunction retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os valores de retorno possíveis incluem os seguintes códigos de erro.
| Código de retorno | Descrição |
|---|---|
|
O controlador GPIO não dá suporte à operação especificada pelos parâmetros de entrada. |
|
O tamanho do buffer de entrada ou do buffer de saída é muito pequeno. |
Observações
Como opção, um driver de controlador GPIO pode dar suporte a solicitações de IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION. Esse tipo de solicitação de controle de E/S (IOCTL) executa operações específicas do controlador em benefício de drivers de dispositivo periférico que exigem essas operações. Para dar suporte a esse IOCTL, um driver de controlador gpio implementa uma função CLIENT_ControllerSpecificFunction.
A extensão da estrutura GPIO (GpioClx) dá suporte à função CLIENT_ControllerSpecificFunction para atender às necessidades específicas de determinadas plataformas de hardware. Drivers de controlador de GPIO típicos não implementam essa função. Um driver de dispositivo periférico que usa solicitações IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION para executar uma operação específica de hardware em uma plataforma corre o risco de perder a compatibilidade com outras plataformas que não dão suporte a essa operação.
Normalmente, a função CLIENT_ControllerSpecificFunction programa o controlador GPIO para executar uma operação específica de hardware em um conjunto de pinos GPIO. Os parâmetros de entrada e saída dessa operação são definidos pelo desenvolvedor para o driver do controlador GPIO. Somente um driver de dispositivo periférico que esteja ciente das operações específicas implementadas por um driver de controlador GPIO pode solicitar essas operações.
Quando o GpioClx recebe uma solicitação IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION, verifica se o driver do controlador GPIO implementou uma função de CLIENT_ControllerSpecificFunction. Nesse caso, o GpioClx copia as descrições dos buffers de entrada e saída do IOCTL para uma estrutura GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS e passa um ponteiro para essa estrutura como um parâmetro para a função CLIENT_ControllerSpecificFunction. Se os valores de parâmetro na estrutura GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS forem válidos, a função executará a operação solicitada e retornará STATUS_SUCCESS.
Se o GpioClx receber uma solicitação IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION e o driver do controlador GPIO não implementar uma função CLIENT_ControllerSpecificFunction, o GpioClx concluirá o IOCTL com o código de erro STATUS_NOT_IMPLEMENTED.
Exemplos
Para definir uma função de retorno de chamada CLIENT_ControllerSpecificFunction, 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_ControllerSpecificFunction denominada MyEvtGpioControllerSpecificFunction, use o tipo de função GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION, conforme mostrado neste exemplo de código:
GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION MyEvtGpioControllerSpecificFunction;
Em seguida, implemente sua função de retorno de chamada da seguinte maneira:
_Use_decl_annotations_
NTSTATUS
MyEvtGpioControllerSpecificFunction(
PVOID Context,
PGPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS Parameters
)
{ ... }
O tipo de função GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION é 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_CONTROLLER_SPECIFIC_FUNCTION 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. |
| da Plataforma de Destino | Área de trabalho |
| cabeçalho | gpioclx.h |
| IRQL | Chamado no PASSIVE_LEVEL. |