HalAllocateHardwareCounters 函数 (ntddk.h)

  • 项目

HalAllocateHardwareCounters 例程分配一组硬件性能计数器资源。

语法

NTHALAPI NTSTATUS HalAllocateHardwareCounters(
        PGROUP_AFFINITY                 GroupAffinty,
  [in]  ULONG                           GroupCount,
  [in]  PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
  [out] PHANDLE                         CounterSetHandle
);

参数

GroupAffinty

指向一组 GROUP_AFFINITY 结构的指针，该结构指示使用者请求哪些处理器的计数器资源。 如果此参数为 NULL，则请求指示系统中所有处理器的分配。

[in] GroupCount

提供 GroupAffinty 参数提供的GROUP_AFFINITY结构数，如果 GroupAffinity 为 NULL，则为零。

[in] ResourceList

指向包含使用者所需资源的 PHYSICAL_COUNTER_RESOURCE_LIST 的指针。 如果此参数为 NULL，则使用者请求性能监视单元的独占所有权。

[out] CounterSetHandle

指向例程向分配的计数器资源写入句柄的位置的指针。 若要稍后释放这些资源，调用方必须将此句柄传递给 HalFreeHardwareCounters 例程。 如果请求的计数器资源不可用， HalAllocateHardwareCounters 将设置 *CounterSetHandle = NULL 并返回STATUS_INSUFFICIENT_RESOURCES。

返回值

如果调用成功，HalAllocateHardwareCounters 将返回STATUS_SUCCESS。 可能的错误返回值包括以下状态代码。

返回代码 说明
STATUS_INSUFFICIENT_RESOURCES 请求的计数器资源当前不可用。
STATUS_INVALID_PARAMETER 调用方指定的参数值无效。
STATUS_NOT_SUPPORTED 调用方在资源列表中提供了当前不支持的资源。

注解

大多数处理器具有性能监视单元 (PMU) ，其中包含大量硬件计数器。 软件工具使用这些计数器来监视系统性能的各个方面。 通常，此类工具由用于对计数器进行编程的自定义内核模式驱动程序和与驱动程序通信的用户模式应用程序组成。

如果计算机上安装了多个此类工具，则关联的驱动程序必须避免尝试同时使用相同的硬件计数器。 为了避免此类资源冲突，使用计数器资源的所有驱动程序都应使用 HalAllocateHardwareCounters 和 HalFreeHardwareCounters 例程来协调它们对这些资源的共享。

计数器资源是单个硬件计数器、连续计数器块、计数器溢出中断或 PMU 中的事件缓冲区配置。

在配置计数器之前，驱动程序可以调用 HalAllocateHardwareCounters 例程来获取对一组计数器资源的独占访问权限。 驱动程序不再需要这些资源后，必须通过调用 HalFreeHardwareCounters 例程来释放资源。

在 Windows 10 版本 1903 之前的 Windows 版本中，成功调用 HalAllocateHardwareCounters 可授予调用方独占访问单处理器系统的性能监视单元中的所有计数器资源。 在多处理器系统中，成功的调用授予调用方对系统中所有处理器中的所有计数器资源的独占访问权限。 GroupAffinity 和 ResourceList 必须为 NULL，GroupCount 必须为零。

从 Windows 10 版本 1903 开始，可以根据提供的资源列表和组相关性来分配计数器资源。

虚拟化软件通常不会虚拟化硬件性能计数器。 因此，无论 HalAllocateHardwareCounters 是否返回状态代码STATUS_SUCCESS，这些计数器在虚拟机中都可能不可用。 例如，硬件性能计数器在 Hyper-V 虚拟机中不可用，但 HalAllocateHardwareCounters 可能仍返回STATUS_SUCCESS。

要求

要求 值
最低受支持的客户端 从 Windows 7 开始可用。
目标平台 通用
标头 ntddk.h (包括 Ntddk.h、Ntifs.h)
Library Hal.lib
DLL Hal.dll
IRQL PASSIVE_LEVEL

另请参阅

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST