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

Статья
02/26/2024

[Относится к KMDF и UMDF]

Функция обратного вызова события EvtDevicePrepareHardware драйвера выполняет все операции, необходимые для обеспечения доступности устройства для драйвера.

Синтаксис

EVT_WDF_DEVICE_PREPARE_HARDWARE EvtWdfDevicePrepareHardware;

NTSTATUS EvtWdfDevicePrepareHardware(
  [in] WDFDEVICE Device,
  [in] WDFCMRESLIST ResourcesRaw,
  [in] WDFCMRESLIST ResourcesTranslated
)
{...}

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] ResourcesRaw

Дескриптор объекта списка ресурсов платформы, который идентифицирует необработанные аппаратные ресурсы, назначенные диспетчером Plug and Play устройству.

[in] ResourcesTranslated

Дескриптор объекта списка ресурсов платформы, который идентифицирует преобразованные аппаратные ресурсы, назначенные диспетчером Plug and Play устройству.

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

Если функция обратного вызова EvtDevicePrepareHardware не обнаруживает ошибок, она должна возвращать STATUS_SUCCESS или другое значение состояния, для которого NT_SUCCESS(status) равно TRUE. В противном случае он должен возвращать значение состояния, для которого NT_SUCCESS(status) равно FALSE. Не возвращайте STATUS_NOT_SUPPORTED.

Если NT_SUCCESS(status) равно FALSE, платформа вызывает функцию обратного вызова EvtDeviceReleaseHardware драйвера.

Дополнительные сведения о возвращаемых значениях этой функции обратного вызова см. в разделе Отчеты о сбоях устройств.

Если драйвер зарегистрировал функцию обратного вызова EvtDevicePrepareHardware для устройства, платформа вызывает функцию после того, как диспетчер Plug and Play назначил аппаратные ресурсы устройству и после того, как устройство перейдет в неинициализированное состояние D0. (Диспетчер Plug and Play всегда запускает родительское устройство перед запуском дочерних устройств этого устройства.)

Платформа вызывает функцию обратного вызова EvtDevicePrepareHardware драйвера перед вызовом функции обратного вызова EvtDeviceD0Entry драйвера.

Функция обратного вызова EvtDevicePrepareHardware обращается к необработанным и преобразованным аппаратным ресурсам устройства с помощью получаемых дескрипторов ResourcesRaw и ResourcesTranslated . Функция обратного вызова может вызывать WdfCmResourceListGetCount и WdfCmResourceListGetDescriptor для обхода списков ресурсов. Эта функция обратного вызова не может изменять списки ресурсов.

Дополнительные сведения о списках ресурсов и порядке их отображения см. в статье Необработанные и преобразованные аппаратные ресурсы.

Как правило, функция обратного вызова EvtDevicePrepareHardware вашего драйвера при необходимости выполняет следующие действия:

Сопоставляет адреса физической памяти с виртуальными адресами, чтобы драйвер смог получить доступ к памяти, назначенной устройству
Определяет номер редакции устройства.
Настройка USB-устройств
Получает определяемые драйвером интерфейсы из других драйверов.

При необходимости функция обратного вызова EvtDevicePrepareHardware драйвера может ставить рабочий элемент в очередь для выполнения любых других задач настройки, требующих большого времени. Использование рабочего элемента для таких операций может гарантировать, что время запуска устройства не увеличит время загрузки системы. Дополнительные сведения см. в разделе Использование рабочих элементов платформы.

Как правило, все остальные операции инициализации оборудования, включая загрузку встроенного ПО, должны выполняться каждый раз, когда устройство переходит в рабочее (D0) состояние, и, следовательно, должны выполняться в функции обратного вызова EvtDeviceD0Entry драйвера.

Дескриптора ResourcesRaw и ResourcesTranslated , которые получает функция обратного вызова EvtDevicePrepareHardware , остаются действительными до тех пор, пока не вернется функция обратного вызова EvtDeviceReleaseHardware драйвера.

Дополнительные сведения об аппаратных ресурсах см. в разделе Аппаратные ресурсы для драйверов Framework-Based.

Дополнительные сведения о том, когда платформа вызывает эту функцию обратного вызова, см. в статье Сценарии PnP и управления питанием.

Дополнительные сведения о драйверах, которые предоставляют эту функцию обратного вызова, см. в разделе Поддержка PnP и управления питанием в драйверах функций.

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfdevice.h (включая Wdf.h)
IRQL	PASSIVE_LEVEL

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

EvtDeviceReleaseHardware