PCL - The Performance Counter Library
Version 1.2, July 1999

A performance counter is that part of a modern microprocessor that measures and gathers performance-relevant events of the microprocessor without effecting 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
Alpha 21164, Alpha 21264 True 64 (aka Digital Unix) -
Alpha 21164 CRAY Unicos/mk on T3E's -
R10000 SGI IRIX 6.x -
UltraSPARC I/II Solaris 2.x, Solaris 7 perfmon (SPARC) from Richard Enbody
PowerPC 604e AIX 4.2 IBM PMapi
Pentium / Pentium MMX / PPro / Pentium II / Pentium III Linux 2.0.x, 2.1.x, 2.2.x msr from Stephan Meyer

Changes

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 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;


  /* 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(counter_list, 2, flags)) != PCL_SUCCESS)
    printf("these two events are not available on this system\n");
  else
    {
      /* start counting */
      if ((res = PCLstart(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(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) fp_result[1]);
    }

  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
      REAL*8 fp_result
      INTEGER PCLquery, PCLstart, PCLstop
      EXTERNAL PCLquery, PCLstart, PCLstop

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(counter_list, 1, flags)
      IF(res .EQ. PCL_SUCCESS) THEN

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

C***     do some work

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

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

      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	

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

	// stop counting
	if(pcl.PCLstop(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]);
     }
   }
}

Copyright for PCL

Copyright © 1998, 1999, Forschungszentrum Juelich GmbH, 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.

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 and Heinz Ziegler 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 FZ 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.

Information on Performance Counters

Non-system specific

System specific

Compaq/DEC

IBM

Intel

Linux (mostly on Intel processors)

SGI/MIPS

SUN/SPARC