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
GroupAffinity が NULL 場合は、GroupAffinty パラメーターによって提供される GROUP_AFFINITY 構造体の数 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 ルーチン 呼び出すことによってリソースを解放する必要があります。
Windows 10 バージョン 1903 より前のバージョンの Windows では、 HalAllocateHardwareCounters を正常に呼び出すと、単一プロセッサ システムのパフォーマンス モニター ユニット内のすべてのカウンター リソースへの排他的アクセス権が呼び出し元に付与されます。 マルチプロセッサ システムでは、呼び出しが成功すると、呼び出し元は、システム内のすべてのプロセッサ内のすべてのカウンター リソースへの排他的アクセスが許可されます。 GroupAffinity と ResourceList は NULL する必要があり、GroupCount は 0 である必要があります。
Windows 10 バージョン 1903 以降では、指定されたリソース リストとグループ アフィニティに基づいてカウンター リソースを割り当てることができます。
仮想化ソフトウェアは、通常、ハードウェア パフォーマンス カウンターを仮想化しません。 したがって、 HalAllocateHardwareCounters がSTATUS_SUCCESSの状態コードを返すかどうかに関係なく、これらのカウンターを仮想マシンで使用できない可能性があります。 たとえば、ハードウェア パフォーマンス カウンターは Hyper-V 仮想マシンでは使用できませんが、 HalAllocateHardwareCounters は引き続きSTATUS_SUCCESSを返す可能性があります。
必要条件
| 要件 | 価値 |
|---|---|
| サポートされる最小クライアント | Windows 7 以降で使用できます。 |
| ターゲット プラットフォーム の | 万国 |
| ヘッダー | ntddk.h (Ntddk.h、Ntifs.h を含む) |
| ライブラリ | Hal.lib |
| DLL | Hal.dll |
| IRQL | PASSIVE_LEVEL |