Installation Instructions

Questions? Problems?  send mail to dheller@scl.ameslab.gov

Your kernel should be configured to accept a loadable module
(User Misc. Modules, in the character devices configuration).
For example, /proc/modules and /proc/ksyms should be present.

You should not have added any kernel patches which manipulate
the Intel Pentium-family Performance-Monitoring Counters.

If you previously installed an older version of this software,
then
  rm /dev/pmc
The default minor device number has been changed from 200 to 240.

Obtain pmc-1.14.tar.gz from the web pages
(http://www.scl.ameslab.gov/Projects/Rabbit/index.html).

  This version has been tested for Linux 2.[024].x kernels.
  It is unsafe on a multiprocessor system, because the counters
  are not normally part of the process state, but an SMP kernel
  on a single processor is ok.

  This version has been tested with Intel processors (Pentium,
  Pentium/MMX, Pentium Pro/II/III) and the AMD Athlon (but here
  the 2.[24].x kernels only); it is unlikely to work properly with
  other x86 configurations without some rewriting.

  The library links properly with C programs using the GNU
  compiler; it is unlikely to work properly with any other
  compiler family, and has not been tested with C++.

  If you would like to help overcome these limitations, please
  contact the author.

As any user:
Check the kernel version:
  uname -s
  (should be Linux)
  uname -r
  (should be 2.0.x or 2.2.x or 2.4.x)
  uname -m
  (should be i586 or i686)
Check the processor version:
  cat /proc/cpuinfo
  (should be one processor, GenuineIntel, 586 or 686, MMX or not,
  or AuthenticAMD, AMD Athlon(tm) Processor)
Check the kernel version, SMP or not:
  cat /proc/interrupts
  (if you see IPI, Interprocessor Interrupts, this is an SMP kernel)

As root:
Make the target directories, if they do not already exist:
  mkdir /usr/local/src
  mkdir /usr/local/man
  mkdir /usr/local/include
  mkdir /usr/local/bin
  mkdir /usr/local/lib
Check the permissions, to verify the settings:
  ls -l /usr/local

As any user or as root, depending on your local administration:
Unpack the source code:
  mv pmc-1.14.tar.gz /usr/local/src
  cd /usr/local/src
  gunzip pmc-1.14.tar
  tar xvf pmc-1.14.tar
  rm pmc-1.14.tar
  cd pmc-1.14
Read these files:
  Instructions	(this file; #pragma once :-)
  README	(credits, disclaimers, old installation instructions)
  Bug_reports	(problems you might need to know about)
  pmc_options.h	(explanation of compiler options and defined constants)
  Makefile
Choose the options appropriate for the current system, and
Choose the target directories (/usr/local/bin and so on):
  vi Makefile
  (there is more information in the Makefile itself - please read it)

When root, always first use 'make -n' to see what will happen.

To specify the system, you can either edit the Makefile to change the
default, or use the PROC and MHZ options:
  make PROC=pentium-II MHZ=450 ...
If you think you will eventually forget to use these options, then it
would be better to set the proper defaults now.

Compile the code, create /dev/pmc, install the module:
  make fresh
The same operations, step by step:
  Compile the code:
    make module rabbit
  Compile the examples:  (some of these are Pentium Pro/II/III only)
    make sample menu
  Create /dev/pmc (do this once only as root):
    make node
  Create the target directories (do this once only):
    make directories
  Copy to the target directories:
    make install
  Install the kernel module:
    make load
  Remove the kernel module:
    make unload

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

  If 'make module' gives a response like this

    /usr/include/asm/smp.h: In function `hard_smp_processor_id':
    ...

  or if 'make load' gives a response like this

    /sbin/insmod /usr/local/lib/pmc_dev.o
    apic_reg undefined
    Loading failed! The module symbols (from linux-2.0.27)
	don't match your linux-2.0.27

  then you should compile without -D__SMP__ (in the Makefile, see MODULE_FLAGS).

  If 'make load' gives a response like this

    /sbin/insmod /usr/local/lib/pmc_dev.o
    misc_register undefined
    misc_deregister undefined
    Loading failed! The module symbols (from linux-2.0.30)
	don't match your linux-2.0.30

  you will need to rebuild the kernel to accept a loadable misc module.

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

As any user:
Check the installation:
  ls -l /dev/pmc
  /sbin/lsmod
  cat /proc/pmc
  pmc_query
Test the program:
  rabbit -v
  (compare the actual processor type and the library version)
  (do not proceed until they agree)
  (you might need to go back and edit the Makefile again)
Test the program:
  rabbit -v
  (you might need to run pmc_enable)
Test the program:
  rabbit -mhz 0
  (estimate the MHz rating of the processor)
  (you might need to go back and edit the Makefile again)
Check the installation:
  pmc_query
  pmc_enable
Test the program:
  rabbit -g 0 date
Test the /proc/pmc interface:
  cat /proc/pmc
  rabbit -g 0 sleep 1 & cat /proc/pmc

As root:
It should not be necessary, but you could reboot the system:
  /sbin/shutdown -r now
Recompile the code, reinstall the module:
  make refresh

As root:
Put this into the system startup file:
  pmc_load		# /sbin/insmod /usr/local/lib/pmc_dev.o
  pmc_enable		# enable rdpmc instruction from user mode
Otherwise, you will need to do this every time you reboot the system.
In some situations, it might be better to install the module only as
needed.

As any user:
The compiler options that should be used with user code:
  pmc_options
For example:
  gcc `pmc_options` example.c -lm -lpmc
Please note: the back-quote ` is used here.

As root:
Delete non-essential files:
  make clean
Delete all files that can be rebuilt:
  make Clean
If you were really curious and compiled the .s files:
  make CLEAN

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

Last revised 1 February 2001