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

Статья
08/07/2023

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

Синтаксис

GPIO_CLIENT_START_CONTROLLER GpioClientStartController;

NTSTATUS GpioClientStartController(
  [in] PVOID Context,
  [in] BOOLEAN RestoreContext,
  [in] WDF_POWER_DEVICE_STATE PreviousPowerState
)
{...}

Параметры

[in] Context

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

[in] RestoreContext

Указывает, должен ли драйвер клиента восстанавливать контроллер GPIO в ранее сохраненный аппаратный контекст. Если задано значение TRUE, необходимо восстановить аппаратный контекст. Если задано значение FALSE, не следует восстанавливать аппаратный контекст. Дополнительные сведения см. в подразделе "Примечания".

[in] PreviousPowerState

Предыдущее состояние питания устройства. Этот параметр представляет собой значение перечисления WDF_POWER_DEVICE_STATE, указывающее состояние с низким энергопотреблением, из которого устройство перейдет в состояние питания D0. Драйвер контроллера GPIO может использовать эти сведения, чтобы определить, как настроить устройство контроллера таким образом, чтобы оно было готово к использованию.

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

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

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

Как правило, функция обратного вызова CLIENT_StartController присваивает всем контактам GPIO состояние по умолчанию.

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

Хотя функция обратного вызова CLIENT_StartController вызывается в irQL = PASSIVE_LEVEL, не следует делать эту функцию страничной. Обратный вызов CLIENT_StartController находится в критическом временном пути для восстановления питания устройств на аппаратной платформе и по соображениям производительности не должен задерживаться из-за ошибок страницы.

Примеры

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

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

GPIO_CLIENT_START_CONTROLLER MyEvtGpioStartController;

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

_Use_decl_annotations_
VOID
  MyEvtGpioStartController(
    PVOID Context,
    BOOLEAN RestoreContext,
    WDF_POWER_DEVICE_STATE PreviousPowerState
    )
{ ... }

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

Требования

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

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

GPIO_CLIENT_REGISTRATION_PACKET

GPIO_CLX_RegisterClient

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