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 调用设置硬件计数器配置,以用于跨系统的所有处理器进行线程分析,尽管每个处理器都使用自己的硬件计数器集。
为了避免资源冲突,所有使用计数器资源的驱动程序都应使用 HalAllocateHardwareCounters 和 HalFreeHardwareCounters 例程来协调这些资源的共享。
若要确定是否为给定线程启用线程分析,请调用 QueryThreadProfiling 函数。
若要在操作系统中查询当前对线程分析生效的硬件计数器配置,请调用 KeQueryHardwareCounterConfiguration 例程。
虚拟化软件通常不会虚拟化硬件性能计数器。 因此,虚拟机中不太可能提供硬件性能计数器。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | 从 Windows 7 开始可用。 |
目标平台 | 通用 |
标头 | ntddk.h (包括 Ntddk.h) |
Library | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | <= APC_LEVEL |