KeSetHardwareCounterConfiguration 函式 (ntddk.h)

KeSetHardwareCounterConfiguration 例程會指定要用於線程分析的硬體計數器清單。

語法

NTSTATUS KeSetHardwareCounterConfiguration(
  [in] PHARDWARE_COUNTER CounterArray,
  [in] ULONG             Count
);

參數

[in] CounterArray

HARDWARE_COUNTER數位的指標，描述用於線程分析的硬體計數器組態。 每個數位元素都是描述硬體計數器的結構。 例程傳回之前，它會將此數位的內容複製到其內部數據結構。

[in] Count

指定 CounterArray 參數所指向之陣列中的項目數目。

傳回值

如果呼叫成功，KeSetHardwareCounterConfiguration 會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列各項：

傳回碼	Description
STATUS_INVALID_PARAMETER	Count 參數的值超過MAX_HW_COUNTERS常數所指定的計數器數目上限，這個計數器定義於 Ntddk.h 頭檔中。
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 開始提供。
目標平台	Universal
標頭	ntddk.h (包含 Ntddk.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= APC_LEVEL

另請參閱

硬體計數器分析參考

HARDWARE_COUNTER

HalAllocateHardwareCounters

HalFreeHardwareCounters

KeQueryHardwareCounterConfiguration