	    x86 Performance-Monitoring Counters for Linux
		by Mikael Pettersson <mikpe@csd.uu.se>
		       [Last update 1999-11-14]
========================================================================


Latest Updates
--------------
1999-11-14
- Version 0.8 with support for Linux kernels 2.3.28 and 2.2.13.
- Major updates to reduce the overhead of maintaining virtual
  performance-monitoring counters:
    - The control registers are cached and updated lazily.
    - The counter registers are no longer written to.
    - Unused counters are no longer manipulated at all.
      (This matters especially for the AMD K7.)
- Reduced the process scheduling overhead for processes not
  using performance-monitoring counters.
- Minor code cleanups and bug fixes, and documentation updates.


Overview
--------
This package adds support to the Linux kernel for using the
Performance-Monitoring Counters (PMCs) found in many modern
x86-class processors. Supported processors are:
- All Intel family 5 and 6 processors, i.e. Pentium, Pentium MMX,
  Pentium Pro, Pentium II, Celeron, and Pentium III.
- AMD K7 Athlon. (Note: the K6 family has no PMCs.)
- Cyrix 6x86MX and MII.
- WinChip C6, 2, and 2A.

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 by compiler writers, runtime system
developers, and kernel developers, to identify code sections
exhibiting low-level performance problems, and to validate
code changes intended to improve performance.


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 40 or 48-bit PMCs. Each process also has a virtual
Time-Stamp Counter (TSC).

To use the PMCs, a process makes system calls to set up, sample,
stop, and remove the counters. On most machines, the PMCs can be
sampled entirely in user-space without incurring the overhead of
a system call. The user-space library takes care of these details.

In addition to controlling its own PMCs, a process may also "attach"
itself to another process (given appropriate permissions) in order
to control and monitor that process' PMCs.


Status
------
The current release is version 0.8 for Linux 2.3.28/2.2.13.
This and previous versions have been tested on Intel Pentium,
Pentium MMX, Pentium II, Pentium III, and AMD K7 processors.

This and future versions of this package can be downloaded from
http://www.csd.uu.se/~mikpe/linux/perfctr/.


Limitations
-----------
- Almost no documentation. "Use the source, Luke."
- Neither the kernel driver nor the user-space library attempt
  to hide any processor-specific details from the user.
  The user has to know _all_ processor-specific details related
  to the performance-monitoring registers and the model-specific
  registers used to control them.
- Counter overflow interrupts via the local APIC are not yet
  implemented.
- Global-mode counters, used when profiling the kernel itself,
  are not yet implemented.
- This package makes it possible to compute aggregate event and
  cycle counts for larger 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 (URL below) for more information.
- Remote-control commands (CONTROL, STOP, UNLINK) are not "immediate".
  Instead the command is recorded and then executed by the target
  process itself the next time it is scheduled to run. This should
  be good enough for most uses, and it simplifies the kernel-side
  implementation immensely. Users who need immediate commands can
  run the target process under ptrace() control.


Related packages
----------------
(Incomplete URLs. Sorry about that.)

msr (by Stephan.Meyer@pobox.com)
	http://pobox.com/~smeyer/msr.html [page seems dead now]
	Supports kernels up to 2.2.6. No longer actively developed.
	Adds /dev/msr as a raw interface to the CPUs MSRs.
	No virtual PMCs.

proc_sr (by bosch@lri.fr)
	Patch for kernel 2.0.27.
	Adds a bunch of files under /proc/Intel/, which allow
	global access to MSRs and control registers.
	No virtual PMCs.

vtimer (by dadkins@mit.edu and bsong@supertech.lcs.mit.edu)
	Patch for kernel 2.3.6.
	Adds per-process virtual TSC support.

msr_patch-2.1.126 (by Harald Hoyer, HarryH@Royal.Net)
	Patch for kernel 2.1.126.
	Adds /proc/<pid>/msr text file with read/write
	access to per-process PMC MSRs
	Only supports the Intel P5MMX.
	Does not handle counter overflow.

Using hardware performance counters with Linux (by David Mentr)
	http://www.irisa.fr/prive/mentre/linux-counters/
	A page with info and links.

hardcntr-2 (by David.Mentre@irisa.fr)
	http://www.irisa.fr/prive/mentre/linux-counters/hardctr-2.patch
	Patch for kernel 2.1.65.
	Adds some text files under /proc/<pid>/hardcntr/, which
	allow read/write access for per-process PMC MSRs.
	Only supports the Intel P6.
	Does not handle counter overflow.
	Deprecated by author.

perf-0.7 (by Erik Hendriks, hendriks@cesdis.gsfc.nasa.gov)
	Patches for kernels 2.0.36, 2.2.2, and 2.2.9.
	Does support both per-process and global PMCs.
	Does handle counter overflow.
	No virtual TSC.
	Only supports Intel P6.

msr-patch-2.3.1 (by Richard Gooch, http://www.atnf.csiro.au/~rgooch/linux/)
	Adds /dev/<cpu>/perfmon with access to per-CPU PMCs.
	Does not implement virtual-mode PMCs.
	Does not handle counter overflow.
	Part of bigger package (MSRs, requires devfs).

pperf/libpperf (by M. Patrick Goda, http://qso.lanl.gov/~mpg/pperf.html)
	Based on Stephan Meyer's msr patch, and shares its limitations.
	Emphasis on user-space tools.

pcl	(by Rudolf Berrendorf and Heinz Ziegler,
	 http://www.fz-juelich.de/zam/PCL/)
	User-space tools, based on libpperf.

pmc-1.02 (by Don Heller, dheller@scl.ameslab.gov)
	http://www.scl.ameslab.gov/Projects/Rabbit/index.html
	Derived from pperf by M. Patrick Goda and Michael S. Warren.
	Global-mode counters access via /dev/pmc.
	Supports Intel P5 and P6 via compiler option.
	No virtual counters.
	Emphasis on user-space tools.

Compaq Continuous Profiling Infrastructure Project
	http://www.research.digital.com/SRC/dcpi/
	Cool stuff, but only for Compaq-supported operating systems.
