PCL - The Performance Counter Library
Version 2.2, January 2003

A performance counter is that part of a modern microprocessor that measures and gathers performance-relevant events of the microprocessor without affecting the performance of a program. For example, one performance counter might count the number of level 1 data cache misses while another performance counter might count the number of data reads or data writes. PCL - the Performance Counter Library - is a software library to access hardware performance counters on many microprocessors through a uniform interface and with low overhead. Language bindings exist for C, C++, Fortran, and Java. See here for some usage examples. PCL is intended to be used by the expert application programmer who wishes to do detailed analysis on program performance, and it is intended to be used by tool writers which need a common platform to base their work on. The application interface supports: PCL is available in source. See the copyright notice.

Supported Systems

-
Processor Operating System uses
Intel Pentium / Pentium MMX / PPro / Pentium II / Pentium III / Pentium 4 Linux 2.x.x (kernel patch by Mikael Pettersson)
AMD Athlon / Duron Linux 2.x.x (kernel patch by Mikael Pettersson)
PowerPC 604, 604e, POWER3, POWER3-II AIX 4.3 and above PMapi (included in AIX 5.x: For AIX 4.x contact laderose@us.ibm.com)
Alpha 21164, Alpha 21264 Tru64 (aka Digital Unix) -
Alpha 21164 CRAY Unicos/mk on T3E's -
R10000, R12000 SGI IRIX 6.x and above -
UltraSPARC I/II/III Solaris 2.x and above -

Changes

These are the main changes compared to version 2.1:
  • added Intel Pentium 4 support
  • added AMD Athlon/Duron support
  • added option for generic multithreading support (pthreads) in configure script
  • added two macros PCL_EVENT_IS_INT(event) and PCL_EVENT_IS_RATE(event) to determine whether an event result is int64/fp64 and count/rate
These are the main changes compared to version 2.0:
  • added support for UltraSPARC III
  • support for Linux kernels 2.4.x
  • additional WWW site: http://berrendorf.inf.h-brs.de/PCL/
These are the main changes compared to version 1.3:
  • more thread-safe
  • modified call interface (because of point 1)
  • automatic configuration
  • public low-level hardware interface
  • added PCLesecond() to get elapsed time
These are the main changes compared to version 1.2:
  • R12000 support
  • We use SIGVTALRM (again) to avoid counter overflows.
These are the main changes compared to version 1.1:
  • The full PCL package is now free software with a BSD-style copyright
  • Modified call interface to PLCread and PCLstop to support floating point result values. Please check you programs!
  • New homepage: http://www.fz-juelich.de/zam/PCL/
  • Support for more processors (Pentium III, DEC Alpha 21264)
  • hpm program for command line access to performance counters (a la "time a.out")
  • A Java interface has been included (with a Java-class PCL).
  • more event types
  • Reduced overhead

Browse Documentation

A report for the current version with a detailed description on PCL as well as on performance counters on different microprocessors is available as Postscript, or PDF, or HTML.

Examples

We have included examples in C, Fortran, and Java.

This is an example how to use PCL in C:

The first example is a simple example in C. First, after setting some PCL-related variables, PCLquery is called to ask if the requested events (count floating point instructions and cycles) can be measured on the system the program is running on. Then PCLstart is called to start countinh these two events. After the piece of code for which the events should be counted, PCLstop is called returning in the array result the requested numbers.
#include < pcl.h>

int
main(int argc, char **argv)
{
  PCL_CNT_TYPE i_result[2];
  PCL_FP_CNT_TYPE fp_result[2];
  int counter_list[2], res;
  unsigned int flags;
  PCL_DESCR_TYPE descr;

  if(PCLinit(&descr) != PCL_SUCCESS)
    printf("unable to allocate PCL handle\n");

  /* define events to be measured 
     (Floating point instructions and cycles)
   */
  counter_list[0] = PCL_FP_INSTR;
  counter_list[1] = PCL_CYCLES;

  /* define in what mode to count (only user mode) */
  flags = PCL_MODE_USER;

  /* query for functionality */
  if ((res = PCLquery(descr, counter_list, 2, flags)) != PCL_SUCCESS)
    printf("these two events are not available on this system\n");
  else
    {
      /* start counting */
      if ((res = PCLstart(descr, counter_list, 2, flags)) != PCL_SUCCESS)
	{
	  printf("problem with starting two events\n");
	  exit(1);
	}

      /* do work */
      /* you should include here your piece of code to measure */

      /* stop counting */
      if ((res = PCLstop(descr, i_result, fp_result, 2)) != PCL_SUCCESS)
	printf("problem with stopping two events\n");
      else
	printf("%15.0f FP-instructions in %15.0f cycles\n",
	       (double) i_result[0], (double) i_result[1]);
    }

  if(PCLexit(descr) != PCL_SUCCESS)
    printf("unable to deallocate PCL handle\n");

  return 0;
}

This is an example how to use PCL in a Fortran:

      PROGRAM PCL_test
C*** declarations
      INCLUDE 'pclh.f'
      INTEGER counter_list(1), flags, res
      INTEGER*8 i_result, descr
      REAL*8 fp_result
      INTEGER PCLquery, PCLstart, PCLstop
      EXTERNAL PCLquery, PCLstart, PCLstop

      res = PCLinit(descr)
      IF(res .NE. PCL_SUCCESS) WRITE(*,*) 'error in PCLinit'

C*** count for user mode
      flags = PCL_MODE_USER
C*** count cycles
      counter_list(1) = PCL_CYCLES
C***  check if event is available
      res = PCLquery(descr, counter_list, 1, flags)
      IF(res .EQ. PCL_SUCCESS) THEN

C***     start counting
         IF(PCLstart(descr, counter_list, 1, flags) .NE. PCL_SUCCESS) THEN
            WRITE(*,*) 'problem with starting event ',counter_list(1)
         ENDIF

C***     do some work

C***     stop counting
         IF(PCLstop(descr, i_result,fp_result,1) .NE. PCL_SUCCESS) THEN
            WRITE(*,*) 'problem with stopping event ',counter_list(1)
         ELSE
            WRITE(*,*) 'result: ', i_result
         ENDIF

      ELSE
C***     event not supported
         WRITE(*,1001) counter_list(1), res
      ENDIF

      res = PCLexit(descr)
      IF(res .NE. PCL_SUCCESS) WRITE(*,*) 'error in PCLexit'

      STOP
      END

This is an example how to use PCL in a Java:

// import PCL class description
import PCL;

public class pcl_jtest
{
   // main program
   public static void main(String[] args)
   {
     int i;
     PCL pcl = new PCL();                // instantiate PCL
     int mode = pcl.PCL_MODE_USER_SYSTEM;// count mode
     int[] events = new int[1];          // events; array required
     long[] result = new long[1];        // int results; array required
     double[] fp_result = new double[1]; // fp results; array required	
     long descr = 0;

     if(pcl.PCLinit(descr) != pcl.PCL_SUCCESS)
       System.out.println("problem with PCLinit");

     events[0] = pcl.PCL_ELAPSED_CYCLES;
     if(pcl.PCLquery(descr, events, 1, mode) == pcl.PCL_SUCCESS)
      {
	// start counting
	if(pcl.PCLstart(descr, events, 1, mode) != pcl.PCL_SUCCESS)
	    System.out.println("problem with starting event");
			
	// here comes your code to measure

	// stop counting
	if(pcl.PCLstop(descr, i_result,fp_result,1) != pcl.PCL_SUCCESS)
	    System.out.println("problem with stopping event");

	// print result for event i
	System.out.println(pcl.PCLeventname(events[0])
                           + ":" + i_result[0]);
     }

    if(pcl.PCLexit(descr) != pcl.PCL_SUCCESS)
      System.out.println("problem with PCLexit");
   }
}

Copyright for PCL

Copyright © 1998, 1999, 2000 Forschungszentrum Juelich GmbH, Federal Republic of Germany. All rights reserved.
Copyright © 2001,2002 University of Applied Sciences Bonn-Rhein-Sieg, Federal Republic of Germany. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  • Any publications that result from the use of this software shall reasonably refer to the Research Centre's development.
  • All advertising materials mentioning features or use of this software must display the following acknowledgement:
    • This product includes software developed by Forschungszentrum Juelich GmbH, Federal Republic of Germany.
  • Forschungszentrum Juelich GmbH is not obligated to provide the user with any support, consulting, training or assistance of any kind with regard to the use, operation and performance of this software or to provide the user with any updates, revisions or new versions.
THIS SOFTWARE IS PROVIDED BY FORSCHUNGSZENTRUM JUELICH GMBH "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL FORSCHUNGSZENTRUM JUELICH GMBH BE LIABLE FOR ANY SPECIAL, DIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE ACCESS, USE OR PERFORMANCE OF THIS SOFTWARE.

Download PCL

The full package including source and documentation is available as gzipped tar-file or as tar-file. The current version as well as older versions are available here:
Version Release Date pcl.tar pcl.tar.gz
PCL v2.2 Jan. 2003 tar-file gzipped tar-file
PCL v2.1 Feb. 2002 tar-file gzipped tar-file
PCL v2.0 Sep. 2000 tar-file gzipped tar-file
PCL v1.3 Nov. 1999 tar-file gzipped tar-file
PCL v1.2 Jul. 1999 tar-file gzipped tar-file
PCL v1.1 Oct. 1998 tar-file gzipped tar-file

Suscribe to Email-List

We have established a mailing list as a forum for discussions and questions of common interest. At any time, you may add or remove your name from the mailing list.
To subscribe to the mailing list, send a mail with the body "subscribe pcl" to majordomo@fz-juelich.de. To unsubscribe, send a mail to majordomo@fz-juelich.de with the body "unsubscibe pcl". To get a list of possible commands for majordomo, send an email with the body "help" to majordomo@fz-juelich.de.

Contact Authors

PCL was developed by Rudolf Berrendorf (University of Applied Sciences Bonn-Rhein-Sieg), Heinz Ziegler, and Bernd Mohr at the Central Institute for Applied Mathematics (ZAM) at the Research Centre Juelich , Germany.

Projects Using PCL

If you have an interesting project based on or using PCL, send us an email with a short description and a URL.

TOPAS

TOPAS is a tool for an SGI/CRAY T3E developed at Research Centre Juelich/ZAM to gather statistics about all programs running on a T3E system. One collected data item is the MFLOPS-rate of a program which is calculated automatically using PCL.

Tuning and Analysis Utilities: TAU

TAU is a program and performance analysis tool framework being developed for the DOE 2000 and ASCI initiatives at Los Alamos National Laboratory. TAU provides a suite of static and dynamic tools that provide graphical user interaction and interoperation to form an integrated analysis environment for parallel C++ applications. In particular, a robust performance profiling facility availble in TAU has been applied extensively in the ACTS toolkit. Also, recent advancements in TAU's code analysis capabilities have allowed new static tools to be developed, such as an automatic instrumentation tool. TAU is being developed jointly by the University of Oregon, Los Alamos National Laboratory, and Research Centre Jülich, ZAM, Germany.

autopcl

Hardware performance counters are hardware features in modern ILP processors that permit you catching and counting some basic events by the processors. Such events could be the cache L1 miss rate, MFLOP, CPI, ...etc. Autopcl permit you catch in events of a certain region of your application in orger to get real value of performance. PCL is a high level library that invoke hardware performance counters. autopcl is a tool that automaticly insert calls to PCL in your source language. This version of autopcl permit you counting only ONE event at time in a Fortran code section. It use Sage+ to instrument fortran files by introducing calls to PCL.

Information on Performance Counters

Non-system specific

System specific

Compaq/DEC

IBM

Intel

Linux (mostly on Intel processors)

SGI/MIPS

SUN/SPARC