This is the README file for device driver( a loadable module ) for linux
to read pentium performance counters. The driver was implemented and 
tested under Linux 2.0.1, but should run on most of the kernels
without any problems. Here is a listing of all the files in this
directory.

README		- This file
Makefile	- Makefile to make up the driver and an example program
counters.txt	- List of counters with a description
create_device*	- A simple script to create /dev/pentium device 
example.c	- An example program
libpentium.c	- A library to use device driver
libpentium.h	- Header file for libpentium.h
pentium.c	- Device driver itself ( loadable module )
pentium.h	- HEader file for device driver


INSTALLATION AND HOW TO USE?
====================================
% make clean; make all

This will make up the driver and an example program.
Now you should see the files pentium.o and example in this directory.

% insmod ./pentium.o

This loads the module into memory. If the module is sucessfully
loaded, this will display the major number with which the driver is
registered into the kernel. The default major number is 61. If the
driver cannot be registered with major 61, the system will be asked to
assign a major number and it will be displayed on the screen.
Assuming that the driver is registered with major number 61, you
should see something like

"Pentium module registered with major: 61"

on the screen. Now type

% create_device 61
to create a device called pentium with major number 61 and minor 0.

If everything goes smoothly up to this point, you can now use the
driver. Execute the example program.

% example

This is a simple example program which does 10K floating point
operations in a loop and counts them using counter 0x22. As seen from
the program source ( example.c ), the counter is initialized and the
begining by a call to "p5_init" and stoped at the end by a call to
"p5_stop". The function p5_stop dumps its output to file "Counter" in
current directory. No if you look at the file "Counter" you will see 5
fields:

First field indicates the counter being analized. In example program,
this is 22, number of floating point operations.

Second field indicates number of events which occured in kernel mode
(ring 0, 1, 2 ). In example program this is typcially 0 meaning that
no floating point operations occured in kernel mode.

Third field indicates the number of events which occured in user mode
( ring 3 ). In example program this is 10000 which is the number of
floating point operations performed.

Forurth field indicates the number of cycles that the program took to
execute. This is obtained by reading the pentium cycle counter.

Last field is a string describing the event being analyzed. In current
example this is "# Floating-point operations"


  When you are done using the driver, you can remove it from memory by
a call to rmmod:

% rmmod pentium

If succesfull you should see a message like:
Pentium counter module successfully removed.


BUGS REPORTED
======================================================

Under libc5.4.23/Linux2.1.29 you have to add:

#include <asm/uaccess.h>

in pentium.c to resolve the symbol: VERIFY_WRITE

Thanks to Mark Swanson for reporting this error.
=====================================================

Please report any errors, comments, bugs to akinlar@cs.umd.edu

