$Id: INSTALL,v 1.19.2.3 2009/01/23 18:37:41 mikpe Exp $

		    INSTALLATION INSTRUCTIONS

		    =========================

KERNEL

------

The kernel source code of this package consists of two parts:

the driver proper, and patches to integrate it into various

versions of the kernel.

The recommended kernel build and installation procedure is as follows:

0. Get the source code for a supported Linux kernel version.

   Let PDIR be the root directory of the unpacked perfctr package.

   A given kernel version, KVER say, is supported if and only if one

   of the following statements is true:

   a) $PDIR/patches/ contains a file "patch-kernel-$KVER"

   b) $PDIR/patches/aliases contains a line starting with $KVER

   Supported kernels include many standard www.kernel.org kernels and

   some RedHat kernels. RedHat kernels are identified by the "-redhat"

   suffix appended to their kernel versions.

   ** Any kernel version which fails the above test is by definition

   ** UNSUPPORTED.

   ** RedHat users: Please note that RedHat kernels are extensively

   ** modified compared to their baseline standard kernels, and that

   ** patches for standard kernels often do NOT work for RedHat kernels

   ** even if the version numbers are similar. If your current kernel

   ** is unsupported, then upgrading to a newer RedHat "update" kernel

   ** may be required.

1. Unpack the kernel source code. Let KDIR be its root directory.

   In your shell, `cd' to $KDIR.

   Save a copy of the .config file if it exists and you need it later.

   Then `make mrproper' (this is VERY important).

2. Apply all patches for all add-on features you want in this kernel.

   With the current directory being $KDIR, execute:

	$PDIR/update-kernel

   This will apply the patch file that matches the kernel version,

   and install the new files for the perfctr driver.

   If update-kernel does not find a matching patch file, it will fail

   with an error message. If you insist on using an unsupported kernel

   version V1, but you believe the patch file for version V2 will work,

   then you can try it as follows:

	$PDIR/update-kernel --test --patch=$V2

   This applies the patch in testing mode, without actually altering

   any files. If the patch applies cleanly without any rejects or large

   offsets, then you can force the use of this patch simply by removing

   the --test option to update-kernel. This usage mode is intended for

   experienced kernel builders only.

   Finally, edit $KDIR/Makefile and change EXTRAVERSION to include

   something unique for THIS kernel, for example by appending "-perfctr"

   (without the quotes). While not strictly necessary, this step is

   strongly recommended if you are adding the perfctr driver to

   a kernel version which is already installed on the machine.

3. If you have a saved .config file, copy it to $KDIR.

   Then configure the kernel using your favorite kernel configuration tool,

   for instance `make menuconfig', `make config', or `make oldconfig'.

   You should either configure with modules (CONFIG_MODULES=y) AND module

   versions (CONFIG_MODVERSIONS=y), or completely without modules

   (CONFIG_MODULES=n). Modules without module versions is an inherently

   unsafe configuration which is not recommended.

   You should also enable at least CONFIG_PERFCTR, CONFIG_PERFCTR_VIRTUAL,

   and CONFIG_PERFCTR_GLOBAL.

   You may also select CONFIG_PERFCTR=m to build the bulk of the driver

   as a loadable kernel module; the module will be named `perfctr'.

   Note: The perfctr kernel patch adds one word to the `thread_struct'

   type, which makes the patched kernel binary incompatible with an

   unpatched one. This is why it is important to distinguish the patched

   kernel via EXTRAVERSION and CONFIG_MODVERSIONS.

4. `make dep vmlinux modules'. This compiles the kernel and its modules.

5. As root, `make modules_install' to install the modules under /lib/modules/.

6. As root, edit /etc/lilo.conf to include a new entry for the new kernel.

   Copy an existing entry and edit the image= and label= lines to reflect

   the new kernel's name, including whatever you put in EXTRAVERSION.

   Then `make install' to install the new kernel's boot image and update

   the boot loader.

   Non-LILO users will have to adapt this step to whatever boot method

   they are using.

7. Reboot the machine.

DEVICE FILE

-----------

The kernel-side of this package is implemented as a character device

driver, which has been assigned /dev/perfctr with major number 10 and

minor number 182. This device file must exist in order for user-space

to be able to access the perfctr extensions. How the device file is

created depends on whether /dev/ is static or dynamic.

Dynamic /dev (udev)

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

These instructions are known to work on Fedora Core 4, but may need

adjustments for other Linux distributions. As root, execute:

	cp etc/perfctr.rules /etc/udev/rules.d/99-perfctr.rules

	cp etc/perfctr.rc /etc/rc.d/init.d/perfctr

	chmod 755 /etc/rc.d/init.d/perfctr

	/sbin/chkconfig --add perfctr

The first step adds a udev rule so that when the perfctr driver is

loaded into the kernel, udev will create /dev/perfctr with permissions

that allows all users to access it.

The following steps add a startup script which creates /dev/perfctr

if the driver module is not yet loaded into the kernel. This enables

the kernel to automatically load the perfctr module the first time the

device file is opened.

Static /dev (no udev)

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

The first time you install the package, a special file representing

this device must be created. As root, execute:

	mknod /dev/perfctr c 10 182

	chmod 644 /dev/perfctr

If the driver was built as a module, it will be have to be loaded

into the kernel before it can be used. This will happen automatically

if the kernel was built with support for the kernel module loader

(CONFIG_KMOD=y).

LIBRARY

-------

To build the user-space library and the example programs, simply run

	make

The source code directory of the patched kernel you built and installed

above does not have to be available when you build the library.

To install the user-space library, the include files, and the 'perfex'

application program, run

	make PREFIX=$PREFIX install

This will install binaries in $PREFIX/bin, libraries in $PREFIX/lib,

and include files in $PREFIX/include. Each of these destinations can

also be overridden individually:

	make BINDIR=$BINDIR LIBDIR=$LIBDIR INCLDIR=$INCLDIR install