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 結構數目，如果 groupAffinityNULL，則為零。
[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 （include Ntddk.h， Ntifs.h） |
| 連結庫 | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |