KeSetHardwareCounterConfiguration 関数 (ntddk.h)

  • [アーティクル]

KeSetHardwareCounterConfiguration ルーチンは、スレッド プロファイルに使用するハードウェア カウンターの一覧を指定します。

構文

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

パラメーター

[in] CounterArray

スレッド プロファイリングに使用するハードウェア カウンター構成を記述する HARDWARE_COUNTER 配列へのポインター。 各配列要素は、ハードウェア カウンターを記述する構造体です。 ルーチンが戻る前に、この配列の内容を内部データ構造にコピーします。

[in] Count

CounterArray パラメーターによって指される配列内の要素の数を指定します。

戻り値

呼び出しが成功した場合、KeSetHardwareCounterConfiguration はSTATUS_SUCCESSを返します。 考えられるエラーの戻り値は次のとおりです。

リターン コード 説明
STATUS_INVALID_PARAMETER Count パラメーターの値が、Ntddk.h ヘッダー ファイルで定義されているMAX_HW_COUNTERS定数で指定されたカウンターの最大数を超えています。
STATUS_WMI_ALREADY_ENABLED CounterArray 配列で指定されている 1 つ以上のカウンターが既に有効になっています。
STATUS_NOT_IMPLEMENTED このルーチンは、呼び出し元が実行されているプロセッサ アーキテクチャには実装されません。

注釈

Windows 7 では、このルーチンは x86 ベース、x64 ベース、および Itanium ベースのアーキテクチャにのみ実装されます。 呼び出し元がサポートされていないプロセッサ アーキテクチャで実行されている場合、ルーチンはSTATUS_NOT_IMPLEMENTEDを返します。

このルーチンは、スレッド プロファイリングに使用するハードウェア カウンターをオペレーティング システムに指示します。 スレッド プロファイルが無効になっている場合にのみ、このルーチンを呼び出します。 CounterArray 配列で現在使用されているハードウェア カウンターが指定されている場合、ルーチンは失敗し、STATUS_WMI_ALREADY_ENABLEDを返します。

アプリケーション スレッドを使用すると、スレッド プロファイリングを有効にして、ローカル プロセッサのパフォーマンス監視ユニット (PMU) のハードウェア カウンターからパフォーマンス測定のセットを取得できます。 オペレーティング システムでは、一度に 1 つのプロファイリング アプリケーションのみがサポートされます。 スレッド プロファイル アプリケーションの同時実行インスタンスはサポートされていません。 スレッドはそれ自体に対してスレッド プロファイルを有効にできますが、他のスレッドでは有効にできません。

スレッド プロファイルが有効になっている場合、オペレーティング システムは 、KeSetHardwareCounterConfiguration の最後の呼び出しで指定されたハードウェア カウンターを使用します。 KeSetHardwareCounterConfiguration 呼び出しが成功するたびに、以前の KeSetHardwareCounterConfiguration 呼び出しで設定されていた可能性のあるハードウェア カウンター構成が置き換えられます。

空のハードウェア カウンター構成を指定するには、 Count = 0 を設定します。 この構成により、スレッド プロファイリングにハードウェア カウンターを効果的に使用できなくなります。 システムの起動後、および最初の KeSetHardwareCounterConfiguration 呼び出しの前に存在する既定のハードウェア カウンター構成は、空の構成です。

KeSetHardwareCounterConfiguration 呼び出しが成功した場合の影響はグローバルです。 プロセス内のスレッドがプロファイリングされている場合、プロファイラーは KeSetHardwareCounterConfiguration の最後の呼び出しによって設定されたハードウェア カウンター構成を使用します。 マルチプロセッサ システムでは、 KeSetHardwareCounterConfiguration 呼び出しによって、システム内のすべてのプロセッサでスレッド プロファイリングに使用するハードウェア カウンター構成が設定されますが、各プロセッサは独自のハードウェア カウンターセットを使用します。

リソースの競合を回避するには、カウンター リソースを使用するすべてのドライバーで HalAllocateHardwareCounters ルーチンと HalFreeHardwareCounters ルーチンを使用して、これらのリソースの共有を調整する必要があります。

特定のスレッドに対してスレッド プロファイルが有効になっているかどうかを確認するには、 QueryThreadProfiling 関数を呼び出します。

スレッド プロファイリングで現在有効になっているハードウェア カウンター構成をオペレーティング システムに照会するには、 KeQueryHardwareCounterConfiguration ルーチンを呼び出します。

仮想化ソフトウェアは、通常、ハードウェア パフォーマンス カウンターを仮想化しません。 したがって、仮想マシンでハードウェア パフォーマンス カウンターを使用できる可能性は低いです。

要件

要件 値
サポートされている最小のクライアント Windows 7 以降で使用できます。
対象プラットフォーム ユニバーサル
Header ntddk.h (Ntddk.h を含む)
Library NtosKrnl.lib
[DLL] NtosKrnl.exe
IRQL <= APC_LEVEL

こちらもご覧ください

ハードウェア カウンター プロファイル リファレンス

HARDWARE_COUNTER

HalAllocateHardwareCounters

HalFreeHardwareCounters

KeQueryHardwareCounterConfiguration