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

  • Статья

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

Синтаксис

GPIO_CLIENT_PREPARE_CONTROLLER GpioClientPrepareController;

NTSTATUS GpioClientPrepareController(
  [in] WDFDEVICE Device,
  [in] PVOID Context,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

Параметры

[in] Device

Дескриптор WDFDEVICE для объекта устройства платформы, представляющего контроллер GPIO.

[in] Context

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

[in] ResourcesRaw

Дескриптор WDFCMRESLIST для коллекции объектов ресурсов платформы. Эта коллекция идентифицирует необработанные (относительно шины) аппаратные ресурсы, назначенные диспетчером Plug and Play (PnP) устройству контроллера GPIO.

[in] ResourcesTranslated

Дескриптор WDFCMRESLIST для коллекции объектов ресурсов платформы. Эта коллекция идентифицирует преобразованные (системно-физические) аппаратные ресурсы, назначенные диспетчером PnP устройству контроллера GPIO.

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

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

Комментарии

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

Параметры ResourcesRaw и ResourcesTranslated являются дескрипторами для списков необработанных и переведенных ресурсов. Эти списки описывают аппаратные ресурсы, назначенные диспетчером PnP устройству контроллера GPIO, заданному параметром Device . Дополнительные сведения см. в разделе Необработанные и переведенные ресурсы.

Во время обратного вызова CLIENT_PrepareController драйвер контроллера GPIO может получить необходимые аппаратные ресурсы из списка ResourcesRaw или ResourcesTranslated . Если устройство контроллера GPIO сопоставлено с памятью, драйвер должен сопоставить диапазон адресов памяти относительно шины или диапазоны, назначенные аппаратным регистрам устройства, с системными виртуальными адресами. Дополнительные сведения см. в статье Сопоставление Bus-Relative адресов с виртуальными адресами.

Если контроллер GPIO не сопоставлен с памятью, аппаратные ресурсы драйвера содержат идентификатор подключения вместо диапазона памяти. Драйвер использует этот идентификатор для открытия логического подключения к контроллеру GPIO и отправляет запросы ввода-вывода через это подключение для доступа к регистрам контроллера.

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

Функция обратного вызова события CLIENT_ReleaseController выполняет операции, необходимые, когда устройство контроллера GPIO больше не доступно. Во время этого обратного вызова драйвер контроллера GPIO должен освободить все аппаратные ресурсы, полученные во время предыдущего обратного вызова CLIENT_PrepareController .

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

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

Примеры

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

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

GPIO_CLIENT_PREPARE_CONTROLLER MyEvtGpioPrepareController;

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

_Use_decl_annotations_
NTSTATUS
  MyEvtGpioPrepareController(
    WDFDEVICE Device,
    PVOID Context,
    WDFCMRESLIST ResourcesRaw,
    WDFCMRESLIST ResourcesTranslated
)
{ ... }

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

Требования

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

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

CLIENT_ReleaseController

GPIO_CLIENT_REGISTRATION_PACKET

GPIO_CLX_RegisterClient