PoFxActivateComponent 函数 (wdm.h)

  • 项目

PoFxActivateComponent 例程递增指定组件的激活引用计数。

语法

void PoFxActivateComponent(
  [in] POHANDLE Handle,
  [in] ULONG    Component,
  [in] ULONG    Flags
);

参数

[in] Handle

一个句柄，表示设备在 PoFx) (电源管理框架的注册。 设备驱动程序以前从 PoFxRegisterDevice 例程收到此句柄。

[in] Component

标识组件的索引。 此参数是设备驱动程序用于将设备注册到 PoFx 的 PO_FX_DEVICE 结构中的 Components 数组的索引。 如果 Components 数组包含 N 个元素，则组件索引的范围为 0 到 N–1。

[in] Flags

激活操作的标志。 将此成员设置为零或设置为以下标志PO_FX_FLAG_XXX 位之一：

这两个标志位是互斥的。 有关详细信息，请参阅“备注”。

值 含义
PO_FX_FLAG_BLOCKING
0x1
 使条件更改同步。 如果设置了此标志，则请求条件更改的例程不会将控制权返回到调用驱动程序，直到组件硬件完成到新条件的转换。 仅当调用方在 IRQL < DISPATCH_LEVEL 运行时，才能使用此标志。
PO_FX_FLAG_ASYNC_ONLY
0x2
 使条件更改完全异步。 如果设置了此标志，则从调用请求条件更改的例程的线程以外的线程调用调用驱动程序的回调例程。 因此，请求条件更改的例程始终以异步方式返回，而无需等待回调完成。

返回值

无

备注

在设备驱动程序可以访问设备中的组件之前，驱动程序必须先调用 PoFxActivateComponent 以获取对组件的激活引用。 如果组件尚未处于活动状态，则此调用将启动从空闲条件到活动条件的转换。 完成此转换后，PoFx 会调用驱动程序的 ComponentActiveConditionCallback 例程来通知驱动程序。 仅当组件处于活动状态时，驱动程序才能访问组件中的硬件寄存器。

如果在调用 PoFxActivateComponent 时组件已处于活动状态，则无需转换，并且不调用 ComponentActiveConditionCallback 例程。

组件进入活动条件后，只要驱动程序对该组件保留一个或多个激活引用，它就一直处于活动状态。 若要释放激活引用，驱动程序会调用 PoFxIdleComponent 例程。 当驱动程序在组件上释放最后一个激活引用时， PoFxIdleComponent 会启动从活动条件到空闲条件的转换。 处于空闲状态的组件可能会进入低功耗 Fx 状态。

如果 标志 = PO_FX_FLAG_BLOCKING， 则 PoFxActivateComponent 调用是同步的。 如果组件已处于活动状态，则调用会递增激活引用计数并返回 ，而无需等待。 否则， PoFxActivateComponent 将等待返回，直到组件完成到活动条件的转换。 在这种情况下，如果发生调用时组件尚未处于 F0 状态， 则 PoFxActivateComponent 调用驱动程序的 ComponentIdleStateCallback 例程以启动到 F0 的转换。 组件进入 F0 状态后， PoFxActivateComponent 调用驱动程序的 ComponentActiveConditionCallback 例程，以通知驱动程序组件处于活动状态。 这些回调与调用 PoFxActivateComponent 在同一线程中发生， PoFxActivateComponent 仅在 ComponentActiveConditionCallback 回调返回后返回。

如果 标志 = PO_FX_FLAG_ASYNC_ONLY， 则 PoFxActivateComponent 调用是异步的。 如果组件已处于活动状态，则 调用将递增激活引用计数并返回 。 否则， PoFxActivateComponent 会根据需要将 ComponentIdleStateCallback (安排在另一个线程中) 和 ComponentActiveConditionCallback 回调，然后返回 ，而无需等待任一回调发生。 回调可以在 PoFxActivateComponent 返回之前或之后发生。 驱动程序依赖于 ComponentActiveConditionCallback 回调来确定组件何时完成到活动条件的转换。

驱动程序可以设置 Flags = 0 以指示它不关心 PoFxActivateComponent 调用是同步调用还是异步调用。 在这种情况下，PoFx 决定是使调用同步还是异步。

同一驱动程序中的两个或多个代码路径可能需要同时访问特定组件。 PoFxActivateComponent 和 PoFxIdleComponent 例程使用激活引用计数，使驱动程序的各个部分能够独立维护对组件的访问，而无需驱动程序集中管理对组件的访问。

PoFx 维护设备中每个组件的激活引用计数。 PoFxActivateComponent 调用会将此计数递增 1，而 PoFxIdleComponent 调用会将计数递减一。 当计数为非零时，组件要么处于活动状态，要么正在切换到活动条件。 计数为零的组件处于空闲状态，或者正在切换到空闲条件。

当 PoFxActivateComponent 调用导致激活引用计数从 0 增加到 1 时， PoFxActivateComponent 启动从空闲条件到活动条件的转换。 当 PoFxIdleComponent 调用导致计数从 1 减为 0 时， PoFxIdleComponent 启动从活动条件到空闲条件的转换。

在活动条件与空闲条件之间发生转换时，PoFx 会通知驱动程序。 ComponentActiveConditionCallback 回调通知驱动程序转换到活动条件，ComponentIdleConditionCallback 回调通知驱动程序转换到空闲条件。 当 PoFxActivateComponent 或 PoFxIdleComponent 调用只是递增或递减激活引用计数而不导致此类转换时，驱动程序不会收到通知。

要求

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

另请参阅

ComponentActiveConditionCallback

ComponentIdleStateCallback

PO_FX_DEVICE

PoFxIdleComponent

PoFxRegisterDevice