poFxRegisterDevice 函数 (wdm.h)

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 Driver Framework (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

另请参阅

DEVICE_OBJECT

EvtDeviceWdmPostPoFxRegisterDevice

IRP_MN_START_DEVICE

PO_FX_DEVICE

PoFxActivateComponent

PoFxIdleComponent

PoFxStartDevicePowerManagement