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 位:
[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。 可能的错误返回值包括以下状态代码。
返回代码 | 说明 |
---|---|
|
Flags 参数不包括 PO_FX_FLAG_PERF_PEP_OPTIONAL 标志,PEP 无法为此设备提供性能状态管理。 |
|
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 支持性能状态管理正常运行,则驱动程序必须在 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 |