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 の場合は 0 を指定します。
[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 ルーチンを使用して、これらのリソースの共有を調整する必要があります。
カウンター リソースは、1 つのハードウェア カウンター、連続したカウンターのブロック、カウンター オーバーフロー割り込み、または PMU 内のイベント バッファー構成です。
カウンターを構成する前に、ドライバーは HalAllocateHardwareCounters ルーチンを呼び出して、カウンター リソースのセットへの排他的アクセスを取得できます。 ドライバーでこれらのリソースが不要になった後は、 HalFreeHardwareCounters ルーチンを呼び出してリソースを解放する必要があります。
バージョン 1903 Windows 10 より前のバージョンの Windows では、HalAllocateHardwareCounters を正常に呼び出すと、単一プロセッサ システムのパフォーマンス モニター ユニット内のすべてのカウンター リソースへの呼び出し元の排他的アクセスが許可されます。 マルチプロセッサ システムでは、呼び出しが成功すると、呼び出し元に、システム内のすべてのプロセッサ内のすべてのカウンター リソースへの排他的アクセスが許可されます。 GroupAffinity と ResourceList は NULL 、GroupCount は 0 である必要があります。
Windows 10 バージョン 1903 以降では、提供されるリソース リストとグループ アフィニティに基づいてカウンター リソースを割り当てることができます。
仮想化ソフトウェアは、通常、ハードウェア パフォーマンス カウンターを仮想化しません。 したがって、 HalAllocateHardwareCounters が STATUS_SUCCESS の状態コードを返すかどうかに関係なく、これらのカウンターを仮想マシンで使用できない場合があります。 たとえば、ハードウェア パフォーマンス カウンターは Hyper-V 仮想マシンでは使用できませんが、 HalAllocateHardwareCounters は引き続きSTATUS_SUCCESS返す場合があります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 7 以降で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntddk.h、Ntifs.h を含む) |
| Library | Hal.lib |
| [DLL] | Hal.dll |
| IRQL | PASSIVE_LEVEL |