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

Статья
08/07/2023

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

Синтаксис

GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION GpioClientControllerSpecificFunction;

NTSTATUS GpioClientControllerSpecificFunction(
  [in]      PVOID Context,
  [in, out] PGPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS Parameters
)
{...}

Параметры

[in] Context

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

[in, out] Parameters

Указатель на структуру GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS , содержащую входные и выходные буферы для конкретной операции контроллера.

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

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

Код возврата	Описание
STATUS_NOT_SUPPORTED	Контроллер GPIO не поддерживает операцию, заданную входными параметрами.
STATUS_BUFFER_TOO_SMALL	Размер входного или выходного буфера слишком мал.

Как вариант, драйвер контроллера GPIO может поддерживать IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION запросы. Этот тип запроса управления вводом-выводом (IOCTL) выполняет операции, относящиеся к контроллеру, в интересах драйверов периферийных устройств, которым требуются эти операции. Для поддержки этого IOCTL драйвер контроллера GPIO реализует функцию CLIENT_ControllerSpecificFunction .

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

Как правило, функция CLIENT_ControllerSpecificFunction программирует контроллер GPIO для выполнения аппаратной операции с набором контактов GPIO. Входные и выходные параметры для этой операции определяются разработчиком для драйвера контроллера GPIO. Только драйвер периферийных устройств, который знает о конкретных операциях, реализованных драйвером контроллера GPIO, может запрашивать эти операции.

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

Если GpioClx получает запрос IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION , а драйвер контроллера GPIO не реализует функцию CLIENT_ControllerSpecificFunction , GpioClx завершает IOCTL с кодом ошибки STATUS_NOT_IMPLEMENTED.

Примеры

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

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

GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION MyEvtGpioControllerSpecificFunction;

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

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioControllerSpecificFunction(
    PVOID Context,
    PGPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS Parameters
    )
{ ... }

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

Требования

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

См. также раздел

GPIO_CLIENT_CONTROLLER_SPECIFIC_FUNCTION_PARAMETERS

IOCTL_GPIO_CONTROLLER_SPECIFIC_FUNCTION

Поделиться через