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 回调函数未遇到任何错误，则必须返回NT_SUCCESS (状态) 等于 TRUE 的STATUS_SUCCESS或其他状态值。 否则，它必须返回NT_SUCCESS (状态) 等于 FALSE 的状态值。 不要返回STATUS_NOT_SUPPORTED。

如果NT_SUCCESS (状态) 等于 FALSE，框架将调用驱动程序的 EvtDeviceReleaseHardware 回调函数。

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

注解

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

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

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

EvtDevicePrepareHardware 回调函数使用它收到的 ResourcesRaw 和 ResourcesTranslated 句柄访问设备的原始和翻译的硬件资源。 回调函数可以调用 WdfCmResourceListGetCount 和 WdfCmResourceListGetDescriptor 来遍历资源列表。 此回调函数无法修改资源列表。

有关资源列表和资源出现顺序的详细信息，请参阅 原始和已转换的硬件资源。

通常，驱动程序的 EvtDevicePrepareHardware 回调函数将在必要时执行以下操作：

（可选）驱动程序的 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