KeSetHardwareCounterConfiguration 函数 (ntddk.h)

KeSetHardwareCounterConfiguration 例程指定要用于线程分析的硬件计数器列表。

语法

NTSTATUS KeSetHardwareCounterConfiguration(
  [in] PHARDWARE_COUNTER CounterArray,
  [in] ULONG             Count
);

参数

[in] CounterArray

指向 HARDWARE_COUNTER数组的 指针,该数组描述要用于线程分析的硬件计数器配置。 每个数组元素都是描述硬件计数器的结构。 在例程返回之前,它将此数组的内容复制到其内部数据结构中。

[in] Count

指定 CounterArray 参数指向的数组中的元素数。

返回值

如果调用成功,KeSetHardwareCounterConfiguration 将返回STATUS_SUCCESS。 可能的错误返回值包括:

返回代码 说明
STATUS_INVALID_PARAMETER Count 参数的值超过了 ntddk.h 头文件中定义的MAX_HW_COUNTERS常量指定的最大计数器数。
STATUS_WMI_ALREADY_ENABLED 已启用 CounterArray 数组中指定的一个或多个计数器。
STATUS_NOT_IMPLEMENTED 此例程不是针对调用方运行的处理器体系结构实现的。

注解

在 Windows 7 中,此例程仅针对基于 x86、基于 x64 和基于 Itanium 的体系结构实现。 如果调用方在不支持的处理器体系结构上运行,则例程返回STATUS_NOT_IMPLEMENTED。

此例程告知操作系统要使用哪些硬件计数器进行线程分析。 仅在禁用线程分析时调用此例程。 如果 CounterArray 数组指定当前正在使用的任何硬件计数器,则例程将失败并返回STATUS_WMI_ALREADY_ENABLED。

应用程序线程可以启用线程分析,以便从本地处理器的性能监视单元 (PMU) 中的硬件计数器获取一组性能度量值。 操作系统一次仅支持一个分析应用程序。 不支持线程分析应用程序的并发实例。 线程可以为自身启用线程分析,但不能为其他线程启用线程分析。

启用线程分析后,操作系统将使用上次调用 KeSetHardwareCounterConfiguration 中指定的硬件计数器。 每次成功的 KeSetHardwareCounterConfiguration 调用都会替换可能在以前的 KeSetHardwareCounterConfiguration 调用中设置的任何硬件计数器配置。

Count = 0 设置为指定空的硬件计数器配置。 此配置有效地防止使用硬件计数器进行线程分析。 在系统启动后和初始 KeSetHardwareCounterConfiguration 调用之前存在的默认硬件计数器配置是空配置。

成功的 KeSetHardwareCounterConfiguration 调用的效果是全局性的。 如果分析任何进程中的线程,探查器将使用最后一次调用 KeSetHardwareCounterConfiguration 设置的硬件计数器配置。 在多处理器系统中, KeSetHardwareCounterConfiguration 调用设置硬件计数器配置,以用于跨系统的所有处理器进行线程分析,尽管每个处理器都使用自己的硬件计数器集。

为了避免资源冲突,所有使用计数器资源的驱动程序都应使用 HalAllocateHardwareCountersHalFreeHardwareCounters 例程来协调这些资源的共享。

若要确定是否为给定线程启用线程分析,请调用 QueryThreadProfiling 函数。

若要在操作系统中查询当前对线程分析生效的硬件计数器配置,请调用 KeQueryHardwareCounterConfiguration 例程。

虚拟化软件通常不会虚拟化硬件性能计数器。 因此,虚拟机中不太可能提供硬件性能计数器。

要求

要求
最低受支持的客户端 从 Windows 7 开始可用。
目标平台 通用
标头 ntddk.h (包括 Ntddk.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= APC_LEVEL

另请参阅

硬件计数器分析参考

HARDWARE_COUNTER

HalAllocateHardwareCounters

HalFreeHardwareCounters

KeQueryHardwareCounterConfiguration