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

Статья
08/07/2023

Функция обратного вызова события CLIENT_MaskInterrupts маскирует прерывания в наборе контактов ввода-вывода общего назначения (GPIO), настроенных в качестве входных данных прерывания.

Синтаксис

GPIO_CLIENT_MASK_INTERRUPTS GpioClientMaskInterrupts;

NTSTATUS GpioClientMaskInterrupts(
  [in]      PVOID Context,
  [in, out] PGPIO_MASK_INTERRUPT_PARAMETERS MaskParameters
)
{...}

Параметры

[in] Context

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

[in, out] MaskParameters

Указатель на структуру GPIO_MASK_INTERRUPT_PARAMETERS , которая в записи описывает закрепления прерываний GPIO для маски, а при выходе содержит состояние операции маски.

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

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

Эта функция обратного вызова реализуется драйвером контроллера GPIO. Расширение платформы GPIO (GpioClx) вызывает эту функцию для маскирования прерываний на контактах GPIO, настроенных в качестве входных данных запроса прерывания. Дополнительные сведения см. в разделе Маски прерываний GPIO.

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

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

Вызов CLIENT_MaskInterrupts , который не может задать для маски прерывания запрошенное значение, должен задать элемент FailedMask структуры GPIO_MASK_INTERRUPT_PARAMETERS ненулевое значение и вернуть соответствующий код состояния ошибки. Ожидается, что функция CLIENT_MaskInterrupts для контроллера GPIO, сопоставленного с памятью, всегда будет успешно задавать для маски прерывания запрошенное значение. Однако функция CLIENT_MaskInterrupts для контроллера, не сопоставленного с памятью, должна отправить контроллеру запрос ввода-вывода, чтобы задать маску, и этот запрос может завершиться ошибкой. Если запросу не удается задать маску, функция должна указать этот сбой в значении, которое она записывает в член FailedMask .

Примеры

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

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

GPIO_CLIENT_MASK_INTERRUPTS MyEvtGpioMaskInterrupts;

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

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioMaskInterrupts(
    PVOID Context,
    PGPIO_MASK_INTERRUPT_PARAMETERS MaskParameters
    )
{ ... }

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

Требования

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