$Id: README,v 1.46.2.7 2010/01/30 11:50:30 mikpe Exp $

	   Linux Performance-Monitoring Counters Driver

		Mikael Pettersson <mikpe@it.uu.se>

========================================================================

Overview

--------

This package adds support to the Linux kernel (2.6.0 or newer)

for using the Performance-Monitoring Counters (PMCs) found in

many modern processors. Supported processors are:

- All Intel x86 family 5, 6, and 15 processors, i.e., Pentium,

  Pentium MMX, Pentium Pro, Pentium II, Pentium III, Pentium M,

  Pentium 4, Core, Core 2, Atom, and Core i7, including Celeron and Xeon versions.

- The AMD K7, K8, Family 10h, and Family 11h processor families.

- Cyrix 6x86MX, MII, and III.

- VIA C3 (Cyrix III).

- Centaur WinChip C6/2/3.

- PowerPC 604, 7xx, and 74xx processors.

- Intel XScale 1 and 2 processors (ARM).

PMCs are "event counters" capable of recording any of a large

number of performance-related events during execution.

These events typically include instructions executed, cache

misses, TLB misses, stalls, and other events specific to

the microarchitecture of the processor being used.

PMCs are primarily used to identify low-level performance problems,

and to validate code changes intended to improve performance.

Limited support is available for generic x86 processors with

a Time-Stamp Counter but no PMCs, such as the AMD K6 family.

For these processors, only TSC-based cycle-count measurements

are possible. However, all high-level facilities implemented

by the driver are still available.

Features

--------

Each Linux process has its own set of "virtual" PMCs. That is,

to a process the PMCs appear to be private and unrelated to the

activities of other processes in the system. The virtual PMCs

have 64-bit precision, even though current processors only

implement 32, 40, or 48-bit PMCs. Each process also has a virtual

Time-Stamp Counter (TSC). On most machines, the virtual PMCs can

be sampled entirely in user-space without incurring the overhead

of a system call.

A process accesses its virtual PMCs by opening /dev/perfctr

and issuing system calls on the resulting file descriptor. A

user-space library is included which provides a more high-level

interface.

The driver also supports global-mode or system-wide PMCs.

In this mode, each PMC on each processor can be controlled

and read. The PMCs and TSC on active processors are sampled

periodically and the accumulated sums have 64-bit precision.

Global-mode PMCs are accessed via the /dev/perfctr device file;

the user-space library provides a more high-level interface.

The user-space library is accompanied by several example programs

that illustrate how the driver and the library can be used.

Support for performance-counter overflow interrupts is provided

where such support exists in the processors.

Limitations

-----------

- Kernels older than 2.6.0 are not supported.

- The performance counter interrupt facility on x86 requires SMP or

  uniprocessor APIC support. In the latter case, the BIOS must be

  reasonably non-buggy. Unfortunately, this is often not the case.

- Almost no documentation. "Use the source, Luke."

- Neither the kernel driver nor the sample user-space library

  attempt to hide any processor-specific details from the user.

- This package makes it possible to compute aggregate event and

  cycle counts for sections of code. Since many x86-type processors

  use out-of-order execution, it is impossible to attribute exact

  event or cycle counts to individual instructions.

  See the "Continuous Profiling" and "ProfileMe" papers at Compaq's

  DCPI web site for more information on this issue. (The URL is

  listed in the OTHERS file.)

- Centaur WinChip C6/2/3 support requires that the TSC is disabled.

  See linux/drivers/perfctr/x86.c for further information.

Availability

------------

This and future versions of this package can be downloaded from

<http://user.it.uu.se/~mikpe/linux/perfctr/>.

The perfctr-devel mailing list is an open forum for driver update

announcements and general discussions about the perfctr driver

and its usage. To subscribe to perfctr-devel, visit

<http://lists.sourceforge.net/lists/listinfo/perfctr-devel>.

Licensing

---------

Copyright (C) 1999-2010  Mikael Pettersson <mikpe@it.uu.se>

This library is free software; you can redistribute it and/or

modify it under the terms of the GNU Lesser General Public

License as published by the Free Software Foundation; either

version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public

License along with this library; if not, write to the Free Software

Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA