HalAllocateHardwareCounters routine

The HalAllocateHardwareCounters routine allocates a set of hardware performance counters.


NTSTATUS HalAllocateHardwareCounters(
  _In_  PGROUP_AFFINITY                 GroupAffinity,
  _In_  ULONG                           GroupCount,
  _Out_ PHANDLE                         CounterSetHandle


GroupAffinity [in]

Reserved for future use. Set this parameter to NULL.

GroupCount [in]

Reserved for future use. Set this parameter to zero.

ResourceList [in]

Reserved for future use. Set this parameter to NULL.

CounterSetHandle [out]

A pointer to a location into which the routine writes a handle to the allocated counter resources. To release these resources later, the caller must pass this handle to the HalFreeHardwareCounters routine. If the requested counter resources are unavailable, HalAllocateHardwareCounters sets *CounterSetHandle = NULL and returns STATUS_INSUFFICIENT_RESOURCES.

Return value

HalAllocateHardwareCounters returns STATUS_SUCCESS if the call was successful. Possible error return values include the following status codes.

Return codeDescription

The requested counter resources are currently unavailable.


The caller specified an invalid parameter value.



Most processors have performance monitor units (PMUs) that contain a number of hardware counters. Software tools use these counters to monitor various aspects of system performance. Typically, such a tool consists of a custom kernel-mode driver to program the counters and a user-mode application that communicates with the driver.

If more than one such tool is installed on a computer, the associated drivers must avoid trying to use the same hardware counters simultaneously. To avoid such resource conflicts, all drivers that use counter resources should use the HalAllocateHardwareCounters and HalFreeHardwareCounters routines to coordinate their sharing of these resources.

A counter resource is a single hardware counter, a block of contiguous counters, or a counter overflow interrupt in a PMU.

Before configuring the counters, a driver can call the HalAllocateHardwareCounters routine to acquire exclusive access to a set of counter resources. After the driver no longer needs these resources, it must free the resources by calling the HalFreeHardwareCounters routine.

In Windows 8 and Windows 7, a successful call to HalAllocateHardwareCounters grants the caller exclusive access to all counter resources in the performance monitor unit of a single-processor system. In a multiprocessor system, a successful call grants the caller exclusive access to all counter resources in all processors in the system. Future versions of this routine might provide more fine-grained allocation of counter resources.

Virtualization software typically does not virtualize hardware performance counters. Thus, these counters might not be available in a virtual machine, regardless of whether HalAllocateHardwareCounters returns a status code of STATUS_SUCCESS. For example, hardware performance counters are not available in a Hyper-V virtual machine, but HalAllocateHardwareCounters might still return STATUS_SUCCESS.


Target platform



Available starting with Windows 7.


Ntddk.h (include Ntddk.h or Ntifs.h)







See also




Send comments about this topic to Microsoft