функция обратного вызова GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS (gpioclx.h)

Статья
08/07/2023

Функция обратного вызова события CLIENT_QueryEnabledInterrupts запрашивает состояние набора контактов ввода-вывода общего назначения (GPIO), чтобы определить, какие контакты настроены как входные данные прерывания и включены для прерываний.

Синтаксис

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS GpioClientQueryEnabledInterrupts;

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

Параметры

[in] Context

Указатель на контекст устройства драйвера контроллера GPIO.

[in] QueryEnabledParameters

Указатель на структуру GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS , выделенную вызывающим объектом. Перед вызовом этой функции вызывающий объект записывает идентификатор банка в член BankId этой структуры, чтобы указать, какой банк контактов GPIO следует запрашивать. В случае успешного выполнения функция записывает значение маски в член EnabledMask этой структуры, чтобы указать, какие прерывания включены в указанном банке.

Возвращаемое значение

Функция CLIENT_QueryEnabledInterrupts возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае возвращается соответствующий код ошибки.

Начиная с Windows 8.1 драйвер контроллера GPIO может реализовать функцию обратного вызова CLIENT_QueryEnabledInterrupts. Если эта функция реализована, эта функция вызывается расширением платформы GPIO (GpioClx), чтобы определить, какие прерывания включены в банке контактов GPIO.

Параметр QueryEnabledParameters указывает на структуру GPIO_QUERY_ENABLED_INTERRUPTS_PARAMETERS , выделенную вызывающим объектом. Вызывающий объект задает значение члена BankId этой структуры. Функция CLIENT_QueryEnabledInterrupts записывает данные в элемент EnabledMask структуры.

Чтобы зарегистрировать функцию обратного вызова CLIENT_QueryEnabledInterrupts драйвера, вызовите метод GPIO_CLX_RegisterClient . Этот метод принимает в качестве входного параметра указатель на структуру GPIO_CLIENT_REGISTRATION_PACKET , содержащую указатель CLIENT_QueryEnabledInterrupts функции.

Функция CLIENT_QueryEnabledInterrupts необязательна. Если драйвер не реализует эту функцию, задайте для элемента CLIENT_QueryEnabledInterrupts структуры GPIO_CLIENT_REGISTRATION_PACKETзначение NULL.

Если реализована функция CLIENT_QueryEnabledInterrupts, GpioClx использует эту функцию для повышения надежности драйвера и диагностика. GpioClx вызывает эту функцию, чтобы убедиться, что набор прерываний, включенных на контроллере GPIO, соответствует ожидаемому GpioClx. Как правило, несоответствие указывает на ошибку драйвера, которая потенциально может вызвать бурю прерываний. GpioClx использует эту функцию для более широкой проверки состояния в проверенных (отладочных) сборках и сокращает количество вызовов этой функции в бесплатных (розничных) сборках, чтобы избежать снижения производительности. Если эта функция реализована, эта функция должна напрямую считывать состояние оборудования, а не считывать кэшированную или поддерживаемую программным обеспечением версию состояния.

GpioClx вызывает функцию обратного вызова CLIENT_QueryEnabledInterrupts в PASSIVE_LEVEL или DIRQL в зависимости от сведений об устройстве, которые функция обратного вызова CLIENT_QueryControllerBasicInformation предоставляет GpioClx. Функция CLIENT_QueryControllerBasicInformation предоставляет сведения об устройстве в виде структуры CLIENT_CONTROLLER_BASIC_INFORMATION . Если бит флага MemoryMappedController задан в элементе Flags этой структуры, GpioClx вызывает функцию CLIENT_QueryEnabledInterrupts в DIRQL, которая является irQL, по которой выполняется ISR в GpioClx. В противном случае эта функция вызывается в PASSIVE_LEVEL. Дополнительные сведения об этом бите флага см. в разделах Необязательные и обязательные функции обратного вызова GPIO.

Примеры

Чтобы определить функцию обратного вызова CLIENT_QueryEnabledInterrupts , необходимо сначала предоставить объявление функции, определяющее тип определяемой функции обратного вызова. Windows предоставляет набор типов функций обратного вызова для драйверов. Объявление функции с помощью типов функций обратного вызова помогает анализу кода для драйверов, средству проверки статических драйверов (SDV) и другим средствам проверки находить ошибки, и это требование для написания драйверов для операционной системы Windows.

Например, чтобы определить функцию обратного вызова CLIENT_QueryEnabledInterrupts с именем MyEvtGpioQueryEnabledInterrupts, используйте тип функции GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS, как показано в следующем примере кода:

GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS MyEvtGpioQueryEnabledInterrupts;

Затем реализуйте функцию обратного вызова следующим образом:

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

Тип функции GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS определен в файле заголовка Gpioclx.h. Чтобы более точно определить ошибки при запуске средств анализа кода, не забудьте добавить заметку Use_decl_annotations в определение функции. Заметка Use_decl_annotations гарантирует использование заметок, которые применяются к типу функции GPIO_CLIENT_QUERY_ENABLED_INTERRUPTS в файле заголовка. Дополнительные сведения о требованиях к объявлениям функций см. в статье Объявление функций с помощью типов ролей функций для драйверов KMDF. Дополнительные сведения о Use_decl_annotations см. в статье О поведении функции.

Требования

Требование	Значение
Минимальная версия клиента	Поддерживается начиная с Windows 8.1.
Целевая платформа	Персональный компьютер
Верхняя часть	gpioclx.h
IRQL	См. заметки.