poFxRegisterDevice 函数 (wdm.h)

项目
08/08/2023

PoFxRegisterDevice 例程将设备注册到电源管理框架 (PoFx) 。

语法

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

参数

[in] Pdo

指向物理设备对象的指针 (PDO) 。此参数指向表示正在注册的物理设备的 DEVICE_OBJECT 结构。调用方是设备的电源策略所有者，通常是设备的函数驱动程序。

[in] Device

指向调用方分配的PO_FX_DEVICE 结构的指针，该结构包含设备的注册信息。此结构包含指向设备驱动程序实现的一组回调例程的指针。 PoFx 调用这些例程来与驱动程序通信。

[out] Handle

指向例程在其中写入句柄的位置的指针，该句柄表示设备向 PoFx 注册。设备驱动程序将此句柄作为输入参数传递给它调用的其他 PoFxXxx 例程。驱动程序必须先调用 PoFxRegisterDevice 来注册设备，然后驱动程序才能调用任何其他 PoFxXxx 例程来管理设备。

返回值

如果例程成功注册设备，则 PoFxRegisterDevice 将返回STATUS_SUCCESS。可能的错误返回值包括以下状态代码。

返回代码	说明
STATUS_INVALID_PARAMETER	Pdo 为 NULL;或 PPO_FX_DEVICE 结构的版本号无效或组件计数为零;或为组件指定的空闲状态数为零;或空闲状态的说明无效。
STATUS_DEVICE_NOT_READY	设备未准备就绪。
STATUS_INSUFFICIENT_RESOURCES	可用资源不足，无法完成注册。

注解

设备驱动程序通常从驱动程序的 IRP_MN_START_DEVICE 请求处理程序调用此例程。在设备收到 IRP_MN_START_DEVICE 请求之前，驱动程序不得调用此例程。首次启动设备时，设备会收到第一个 IRP_MN_START_DEVICE 请求。在停止资源均衡后，每次重启设备时，设备都会收到额外的 IRP_MN_START_DEVICE 请求。用于注册已注册设备的 PoFxRegisterDevice 调用是一个严重错误，会导致检查 bug。请注意，PoFx 会将设备结构深层复制到其内存中。

在驱动程序调用 PoFxRegisterDevice 之前，设备必须满足以下条件：

设备 (即 PDO) 尚未注册到 PoFx。
设备处于 D0 (完全处于) 电源状态。
设备处于运行状态。
设备中的每个组件都处于 F0 (完全处于) 电源状态。
每个组件都处于活动状态。

通过将设备注册到 PoFx，驱动程序负责在组件正在使用和组件空闲时通知 PoFx。注册设备时，驱动程序必须调用 PoFxActivateComponent 例程才能访问组件的硬件寄存器，并且驱动程序必须调用 PoFxIdleComponent 例程，以便在驱动程序不再需要访问该组件时通知 PoFx。

驱动程序调用 PoFxRegisterDevice 将设备注册到 PoFx 后，设备中的所有组件都处于完全打开状态并处于活动状态，以便驱动程序可以完成硬件初始化。若要启动活动电源管理，驱动程序必须调用 PoFxStartDevicePowerManagement 例程。

默认情况下， PoFxStartDevicePowerManagement 将所有组件切换到空闲条件。如果驱动程序要求组件在电源管理启动后立即处于活动状态，则驱动程序必须通过调用 PoFxActivateComponent 例程显式激活该组件，并且此调用必须在 PoFxRegisterDevice 调用之后、 PoFxStartDevicePowerManagement 调用之前发生。

通常，单组件设备的 Kernel-Mode 驱动程序框架 (KMDF) 驱动程序不会调用 PoFxRegisterDevice 将设备注册到 PoFx。相反，当 KMDF 调用驱动程序的 EvtDeviceWdmPostPoFxRegisterDevice 回调函数时，此驱动程序会收到 PoFx 注册句柄。有关详细信息，请参阅支持 Single-Component 设备的多个功能电源状态。

有关多组件设备的 KMDF 驱动程序如何注册到 PoFx 的信息，请参阅支持 Multiple-Component 设备的多个功能电源状态。

要求

要求	值
最低受支持的客户端	从Windows 8开始可用。
目标平台	通用
标头	wdm.h
Library	Ntoskrnl.lib
DLL	Ntoskrnl.exe
IRQL	PASSIVE_LEVEL