PoFxRegisterComponentPerfStates 函数 (wdm.h)

  • 项目

PoFxRegisterComponentPerfStates 例程注册设备组件，以便通过电源管理框架 (PoFx) 进行性能状态管理。

语法

NTSTATUS PoFxRegisterComponentPerfStates(
  [in]  POHANDLE                             Handle,
  [in]  ULONG                                Component,
  [in]  ULONGLONG                            Flags,
  [in]  PPO_FX_COMPONENT_PERF_STATE_CALLBACK ComponentPerfStateCallback,
  [in]  PPO_FX_COMPONENT_PERF_INFO           InputStateInfo,
  [out] PPO_FX_COMPONENT_PERF_INFO           *OutputStateInfo
);

参数

[in] Handle

表示向 PoFx 注册设备的句柄。 设备驱动程序以前从 PoFxRegisterDevice 例程收到此句柄。

[in] Component

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

[in] Flags

修改性能状态注册行为的标志。 将此成员设置为零或设置为以下标志之一 PO_FX_FLAG_PERF_XXX 位：

值 含义
PO_FX_FLAG_PERF_PEP_OPTIONAL
0x1
 指示驱动程序无需平台扩展插件 (PEP) 的帮助即可更改性能状态，或者驱动程序将性能状态注册到 PoFx 仅用于日志记录目的。 如果设置了此标志，则如果 PEP 不支持组件的性能状态， 则 PoFxRegisterComponentPerfStates 调用仍将成功。
PO_FX_FLAG_PERF_QUERY_ON_F0
0x2
 对于某些设备，PEP 可能需要将组件的性能状态集置于某个性能状态中， (在组件空闲时) 称为 名义性能状态 。 如果组件包含名义性能状态，驱动程序将设置此标志，在这种情况下，PoFx 将查询 PEP 以确定组件转换为 F0 时的当前性能状态。
PO_FX_FLAG_PERF_QUERY_ON_ALL_IDLE_STATES
0x4
 对于某些设备，PEP 可能需要将组件的性能状态集置于某个性能状态中， (在空闲状态之间转换组件时称为 名义性能状态) 。 如果此组件包含名义性能状态，驱动程序将设置此标志，在这种情况下，PoFx 将查询 PEP 以确定组件在空闲状态之间转换时的当前性能状态。

[in] ComponentPerfStateCallback

指向 ComponentPerfStateCallback 例程的指针。 当 PoFx 完成日志记录并通知 PEP 有关由驱动程序调用 PoFxIssueComponentPerfStateChange 或 PoFxIssueComponentPerfStateChangeMultiple 启动的性能状态转换时，将调用此例程。 对于所有组件和所有设备，此回调可能相同;PoFx 在每个完成调用中提供设备句柄和组件索引。

[in] InputStateInfo

如果驱动程序提供性能状态信息，则此参数包含指向分配 PO_FX_COMPONENT_PERF_INFO 结构的驱动程序的指针，该结构向 PoFx 提供性能状态信息。 如果驱动程序需要 PEP 中的性能状态信息，则必须将此参数设置为 NULL。

[out] OutputStateInfo

如果驱动程序需要 PEP 中的性能状态信息，则成功注册后，此参数包含指向 PO_FX_COMPONENT_PERF_INFO 结构的指针，该结构提供 PEP 定义的性能状态信息。 如果驱动程序提供性能状态信息，则必须将此参数设置为 NULL。

为此参数分配的内存由 PoFx 管理，删除设备时驱动程序不应释放此内存。 此内存的生存期保证超过包含这些性能状态集的 PoFx 组件的生存期。

返回值

如果 PoFx 接受设备的性能状态注册，则 PoFxRegisterComponentPerfStates 返回STATUS_SUCCESS。 如果未提供任何必要信息或信息不正确，注册将失败，返回 代码不是STATUS_SUCCESS。 可能的错误返回值包括以下状态代码。

返回代码 说明
STATUS_NOT_IMPLEMENTED
 Flags 参数不包括 PO_FX_FLAG_PERF_PEP_OPTIONAL 标志，PEP 无法为此设备提供性能状态管理。
STATUS_INVALID_PARAMETER
 InputStateInfo 和 OutputStateInfo 均为 NULL，或者这两个参数都不为 NULL，或者PO_FX_COMPONENT_PERF_INFO结构中没有分配给 InputStateInfo 参数的性能状态集。

注解

请注意，PoFx 将设备的结构深层复制到其内存中。

驱动程序或平台扩展插件 (PEP) 可能会提供有关每个组件支持的性能状态的信息：

  • 如果驱动程序提供性能状态信息，则驱动程序必须将 InputStateInfo 参数设置为指向包含性能状态信息的 PO_FX_COMPONENT_PERF_INFO 结构的指针。 否则，驱动程序必须将此参数设置为 NULL。
  • 如果 PEP 提供性能状态信息，驱动程序必须将 OutputStateInfo 参数设置为指向接收性能状态信息的 PO_FX_COMPONENT_PERF_INFO 结构的有效指针。 否则，驱动程序必须将此参数设置为 NULL。
如果 PEP 不支持性能状态，驱动程序可能仅出于日志记录目的向 PoFx 注册性能状态支持。

如果驱动程序注册性能状态支持仅用于日志记录目的，或者如果驱动程序可以使用或不使用 PEP 支持性能状态管理正常运行，则驱动程序必须在 Flags 参数中设置PO_FX_FLAG_PERF_PEP_OPTIONAL标志。 如果设置了 标志，即使 PEP 不提供对性能状态的支持，注册调用也会成功。

如果驱动程序要求 PEP 提供性能状态信息，则驱动程序无法在 Flags 参数中设置PO_FX_FLAG_PERF_PEP_OPTIONAL标志。

要求

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

另请参阅

ComponentPerfStateCallback

设备性能状态管理

PO_FX_COMPONENT_PERF_INFO

PoFxRegisterDevice