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） |
| 库 | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |