GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS función de devolución de llamada (gpioclx.h)

Artículo
08/07/2023

La función de devolución de llamada de evento CLIENT_QueryEnabledInterrupts consulta el estado de un conjunto de patillas de E/S de uso general (GPIO) para determinar qué patillas están configuradas como entradas de interrupción y habilitadas para las interrupciones.

Sintaxis

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS GpioClientQueryEnabledInterrupts;

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

Parámetros

[in] Context

Puntero al contexto del dispositivo del controlador GPIO.

[in] QueryEnabledParameters

Puntero a una estructura de GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS asignada por el autor de la llamada. Antes de llamar a esta función, el autor de la llamada escribe un identificador de banco en el miembro BankId de esta estructura para especificar qué banco de GPIO ancla a la consulta. Si se ejecuta correctamente, la función escribe un valor de máscara en el miembro EnabledMask de esta estructura para indicar qué interrupciones están habilitadas en el banco especificado.

Valor devuelto

La función CLIENT_QueryEnabledInterrupts devuelve STATUS_SUCCESS si la llamada es correcta. De lo contrario, devuelve un código de error adecuado.

Comentarios

A partir de Windows 8.1, el controlador de controlador GPIO puede, como opción, implementar una función de devolución de llamada CLIENT_QueryEnabledInterrupts. Si se implementa, la extensión de marco GPIO (GpioClx) llama a esta función para determinar qué interrupciones están habilitadas en un banco de patillas GPIO.

El parámetro QueryEnabledParameters apunta a una estructura de GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS asignada por el autor de la llamada. El autor de la llamada establece el valor del miembro BankId de esta estructura. La función CLIENT_QueryEnabledInterrupts escribe en el miembro EnabledMask de la estructura.

Para registrar la función de devolución de llamada CLIENT_QueryEnabledInterrupts del controlador, llame al método GPIO_CLX_RegisterClient . Este método acepta, como parámetro de entrada, un puntero a una estructura de GPIO_CLIENT_REGISTRATION_PACKET que contiene un puntero de función CLIENT_QueryEnabledInterrupts .

La función CLIENT_QueryEnabledInterrupts es opcional. Si el controlador no implementa esta función, establezca el miembro CLIENT_QueryEnabledInterrupts de la estructura de GPIO_CLIENT_REGISTRATION_PACKET en NULL.

Si se implementa la función CLIENT_QueryEnabledInterrupts , GpioClx usa esta función para mejorar la confiabilidad y el diagnóstico del controlador. GpioClx llama a esta función para comprobar que el conjunto de interrupciones habilitadas en el controlador GPIO coincide con lo que GpioClx espera. Normalmente, una discrepancia indica un error de controlador que puede provocar una tormenta de interrupción. GpioClx usa esta función para realizar una validación de estado más extensa en compilaciones activadas (depurar) y reduce el número de llamadas a esta función en compilaciones gratuitas (comerciales) para evitar que afecte al rendimiento. Si se implementa, esta función debe leer directamente el estado de hardware en lugar de leer una versión almacenada en caché o mantenida por software del estado.

GpioClx llama a la función de devolución de llamada CLIENT_QueryEnabledInterrupts en PASSIVE_LEVEL o DIRQL, en función de la información del dispositivo que la función de devolución de llamada CLIENT_QueryControllerBasicInformation proporciona a GpioClx. La función CLIENT_QueryControllerBasicInformation proporciona información del dispositivo en forma de una estructura de CLIENT_CONTROLLER_BASIC_INFORMATION . Si el bit de marca MemoryMappedController se establece en el miembro Flags de esta estructura, GpioClx llama a la función CLIENT_QueryEnabledInterrupts en DIRQL, que es el IRQL en el que se ejecuta el ISR en GpioClx. De lo contrario, se llama a esta función en PASSIVE_LEVEL. Para obtener más información sobre este bit de marca, vea Funciones de devolución de llamada GPIO opcionales y necesarias.

Ejemplos

Para definir una función de devolución de llamada CLIENT_QueryEnabledInterrupts , primero debe proporcionar una declaración de función que identifique el tipo de función de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una función de devolución de llamada CLIENT_QueryEnabledInterrupts denominada MyEvtGpioQueryEnabledInterrupts, use el tipo de función GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS, como se muestra en este ejemplo de código:

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

A continuación, implemente la función de devolución de llamada de la siguiente manera:

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

El tipo de función GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS se define en el archivo de encabezado Gpioclx.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación Use_decl_annotations a la definición de función. La anotación Use_decl_annotations garantiza que se usen las anotaciones que se aplican al tipo de función GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, consulte Declaración de funciones mediante tipos de roles de función para controladores KMDF. Para obtener más información sobre Use_decl_annotations, consulte Anotación del comportamiento de la función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Se admite a partir de Windows 8.1.
Plataforma de destino	Escritorio
Encabezado	gpioclx.h
IRQL	Vea la sección Comentarios.