HalAllocateHardwareCounters routine

The HalAllocateHardwareCounters routine allocates a set of hardware performance counters.

Syntax


NTSTATUS HalAllocateHardwareCounters(
  _In_   PGROUP_AFFINITY GroupAffinity,
  _In_   ULONG GroupCount,
  _In_   PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList,
  _Out_  PHANDLE CounterSetHandle
);

Parameters

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
STATUS_INSUFFICIENT_RESOURCES

The requested counter resources are currently unavailable.

STATUS_INVALID_PARAMETER

The caller specified an invalid parameter value.

 

Remarks

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.

Requirements

Version

Available starting with Windows 7.

Header

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

Library

Hal.lib

IRQL

PASSIVE_LEVEL

See also

GROUP_AFFINITY
HalFreeHardwareCounters
PHYSICAL_COUNTER_RESOURCE_LIST

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft