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。 可能的錯誤傳回值包括下列狀態代碼。

傳回碼 Description
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 開始提供。
目標平台 Universal
標頭 ntddk.h (包含 Ntddk.h、Ntifs.h)
程式庫 Hal.lib
Dll Hal.dll
IRQL PASSIVE_LEVEL

另請參閱

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST