Using Hardware Performance Counters on Windows

March 12, 2009

Abstract This paper describes how drivers can safely use hardware performance counters on Windows® 7 platforms. This information applies for the Windows 7 operating system. References and resources discussed here are listed at the end of this paper. For the latest information, see: http://www.microsoft.com/whdc/system/sysperf/HW_Perf_Counters.mspx Disclaimer: This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

Microsoft and Windows are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Document History Date Change March 12, 2009 First publication

Contents Using Hardware Performance Counters on Windows - 3

Introduction Today’s processors expose hardware performance counters that count many different events. Performance tools—the typical consumers of these events—use these counters to measure retired instructions, cache misses, and other hardware events. However, other tools and applications sometimes also use the same hardware performance counters. Such counters are a finite, global system resource. If multiple tools and applications use these counters at the same time, unpredictable behavior can sometimes occur. Windows® 7 provides the following new functions for kernel-mode drivers to coordinate the use of hardware performance counters: HalAllocateHardwareCounters HalFreeHardwareCounters A driver that allocates the counters typically exposes an interface for user-mode tools and applications that use the counters. This paper describes how to safely use hardware performance counters on Windows 7 platforms.

Use of Counter Resources Device drivers that require the use of hardware performance counters must request resources by calling the HalAllocateHardwareCounters function. A counter resource is a single hardware counter, a block of contiguous counters, or a counter overflow interrupt in a performance monitor unit (PMU). HalAllocateHardwareCounters accepts a list of required resources and returns a handle to the resources if another component has not already requested them. Upon successful return, the driver can freely configure the requested resources. This function has the following prototype:

NTSTATUS HalAllocateHardwareCounters( __in PGROUP_AFFINITY GroupAffinity , __in ULONG GroupCount , __in PPHYSICAL_COUNTER_RESOURCE_LIST ResourceList , __out PHANDLE CounterSetHandle ); In Windows 7, the first three parameters are unused. The CounterSetHandle parameter receives a handle to the allocated resources. When the driver finishes with the resources, it must call HalFreeHardwareCounters and pass the handle to the resources. This function has the following prototype:

NTSTATUS HalFreeHardwareCounters( __in HANDLE CounterSetHandle ); HalFreeHardwareCounters releases the handle and makes the resources available to other consumers.

March 12, 2009 © 2009 Microsoft Corporation. All rights reserved. Counter Resource Ownership All kernel-mode drivers should use HalAllocateHardwareCounters and HalFreeHardwareCounters to request and release performance counter resources so that the system can coordinate the use of the counters. However, other components can enable the counters without the knowledge of these routines: System firmware might enable counters before Windows initializes. Legacy drivers might enable counters through some other mechanism. Drivers must recognize that even a successful return from HalAllocateHardwareCounters does not guarantee ownership under these circumstances. After the driver allocates a counter resource, it must verify that another consumer has not already programmed the counter. It can do this by testing whether the enable bit is set in the counter’s configuration register. Conversely, before the driver frees counter resources by using HalFreeHardwareCounters, it must disable the counter so that other clients that follow this protocol can use the counter.

Hardware Performance Counters on Virtualized Systems Typically, virtual machines do not expose counter resources to guest operating systems. When a driver runs in a Hyper-V enabled environment, HalAllocateHardwareCounters always returns FALSE.

Counter Configuration Windows 7 provides services only to allocate counter resources. It does not provide services to configure or enable counting events. Drivers are responsible for discovering which events the platform supports and how to configure counters for those events. In Windows 7, the implementation does not recognize platform differences and therefore cannot allocate individual counters. Consequently, regardless of the allocation size or affinity, a driver that successfully allocates counter resources owns all the system’s counter resources. Therefore, if two clients try to allocate counter resources or if a single client tries to make multiple allocations of disjoint resources, one such allocation fails. If future versions of Windows have additional information about the resources that the hardware offers, finer grained allocations might then be available. The Windows 7 implementation lets future clients that use finer grained allocations continue to work on earlier versions. Currently, however, clients should treat the GroupAffinity and ResourceList parameters to HalAllocateHardwareCounters as reserved. Using Hardware Performance Counters on Windows - 5

Summary Follow these guidelines for the use of counter resources in Windows 7: Use the new counter resource allocation routines. Verify that counters have not been enabled by another component that does not use these routines. Disable counters before the call to HalFreeHardwareCounters. Return resources immediately after they are used.

Resources

Windows Driver Kit (WDK) HAL Library Routines http://msdn.microsoft.com/en-us/library/aa490448.aspx