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 루틴을 사용하여 이러한 리소스의 공유를 조정해야 합니다.

카운터 리소스는 단일 하드웨어 카운터, 연속 카운터 블록, 카운터 오버플로 인터럽트 또는 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

추가 정보

GROUP_AFFINITY

HalFreeHardwareCounters

PHYSICAL_COUNTER_RESOURCE_LIST