通过

EVT_WDF_DEVICE_PREPARE_HARDWARE回调函数 （wdfdevice.h）

  • 项目

[适用于 KMDF 和 UMDF]

驱动程序的 EvtDevicePrepareHardware 事件回调函数执行使设备可供驱动程序访问所需的任何作。

语法

EVT_WDF_DEVICE_PREPARE_HARDWARE EvtWdfDevicePrepareHardware;

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

参数

[in] Device

框架设备对象的句柄。

[in] ResourcesRaw

框架资源列表对象的句柄，用于标识即插即用管理器分配给设备的原始硬件资源。

[in] ResourcesTranslated

框架资源列表对象的句柄，用于标识即插即用管理器分配给设备的已转换的硬件资源。

返回值

如果 EvtDevicePrepareHardware 回调函数遇到任何错误，则它必须返回STATUS_SUCCESS或其他状态值，NT_SUCCESS（状态）等于 TRUE。 否则，它必须返回一个状态值，NT_SUCCESS（状态）等于 FALSE。 不要返回STATUS_NOT_SUPPORTED。

如果 NT_SUCCESS（status） 等于 FALSE，则框架将调用驱动程序的 EvtDeviceReleaseHardware 回调函数。

有关此回调函数的返回值的详细信息，请参阅 报告设备故障。

言论

若要注册 EvtDevicePrepareHardware 回调函数，驱动程序必须调用 WdfDeviceInitSetPnpPowerEventCallbacks。

如果驱动程序为设备注册了 EvtDevicePrepareHardware 回调函数，则框架会在即插即用管理器向设备分配硬件资源以及设备进入未初始化的 D0 状态后调用该函数。 （即插即用管理器始终在启动该设备的子设备之前启动父设备。

框架在调用驱动程序的 EvtDeviceD0Entry 回调函数之前调用驱动程序的 EvtDevicePrepareHardware 回调函数。

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